Skip to main content

Update Application Form

Description​

Update an existing application form within your Bold Penguin tenant. Specify question codes from the Master Question Set or your Broker Question Set to update their answers. You do not need to specify every question from the original form, only those with updated values.

The endpoint returns an application form ID. It may also return a redirect_url to retrieve the application in your Consumer Portal if you have one configured.

Endpoint​

Staging​

https://partner-engine-uat.beta.boldpenguin.com/tenants/<tenant_id>/application_forms/<application_form_id>

Production​

https://partner-engine.boldpenguin.com/tenants/<tenant_id>/application_forms/<application_form_id>

Authentication​

This endpoint requires an access_token from the authentication endpoint in the same environment. Include it as a bearer token in an Authorization header for the request.

Authorization: Bearer <access_token>

Methods​

PATCH / POST

Request Syntax​

PATCH /tenants/<tenant_id>/application_forms/<application_form_id>

Request Payload​

The body of the request contains an application_form consisting of one or more answer values to update in JSON format.

{
  "application_form": {
    "answer_values": [
      {
        "code": "<string>",
        "answer": "<string>"
      },
      {
        "code": "<string>",
        "answer": "<string>"
      },
      {
        "code": "<string>",
        "answer": "<string>"
      },
      ...
    ]
  }
}

Request Parameters​

URL Parameters​

  • tenant_id
    • You will be assigned a unique tenant_id for each of our environments.
    • Type: String
    • Required: Yes

JSON Parameters​

Your JSON payload may contain an application_form object with the following properties:

  • answer_values
    • One or more questions and answers to prepopulate in the form
    • Type: JSON object (An array of code and answer tuples)
    • Required: No

NOTE: answer_values is an optional property used to prepopulate questions in the application form. This is useful if the consumer has already selected a product or provided contact information. You may use any of the pre-defined question codes for your tenant.

NOTE: Applications you intend to send to the Bold Penguin Exchange must include the mqs_phone question code with a unique phone number as the answer.

Response Syntax​

{
  "id": "<UUID>",
  "reference_id": "<string>",
  "redirect_url": null -or- "https://[url]?token_type=guest&token=[guest-user-auth-token]&token_id=[application-form-token-id]"
}

Response Elements​

  • id
    • A globally unique ID for this instance of the application form within the tenant. It may change as the form is updated
    • Type: UUID
  • reference_id
    • This ID will remain constant throughout the life of the application form
    • Type: String (Format: XXX-XXX-XXX)
  • redirect_url
    • A single use URL for displaying the form for the consumer. Only populated on consumer forms when a Consumer Portal is configured. Typically null for update responses
    • Type: URL String
    • Default: null

Response Payload - With Validation Errors​

If an application form cannot be persisted or updated due to an answer's value not satisfying the question's validation, the Quote Start API will now provide a response that includes all validation errors encountered.

Posting to the update endpoint with the following payload:

{
  "application_form": {
    "answer_values": [
      {
        "code": "mqs_zipcode",
        "answer": "5547888"
      },
      {
        "code": "mqs_phone",
        "answer": "1719555555x123"
      }
    ]
  }
}

Will result in the following response:

{
  "errors": {
    "answers": [
      "mqs_zipcode is too long (maximum is 5 characters)",
      "mqs_zipcode is invalid",
      "mqs_phone is too long (maximum is 10 characters)",
      "mqs_phone is invalid"
    ]
  }
}

NOTE: Only answers that are included in the answer_values array will be validated. Some answers can result in a question_code is invalid message without additional explanation. For example, posting a zip code as 4321e would result in an error, but would not provide any additional details as to the nature of the error. In this case, the error would be that zip codes can only contain numbers. The update_application_form endpoint is similar to the create_application_form endpoint, but does not include the last is invalid message in the answer array.

Status Codes​

  • 201 Success
  • 401 Unauthorized: The necessary authentication credentials are not present in the request or are incorrect.
  • 422 Parameter validation failure (verify the request body)

Examples​

Example Request​

curl --request PATCH \
  --url https://partner-engine.boldpenguin.com/tenants/<tenant_id>/application_forms/<application_form_id> \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "application_form": {
    "answer_values": [
      {
        "code": "[tenant-code]_zipcode",
        "answer": "43215"
      },
      {
        "code": "[tenant-code]_coverage_types",
        "answer": "Business Owners Policy"
      }
    ]
  }
}'

Example Responses​

{
  "id": "f4d6130e-bd39-4789-a625-5612835ebf51",
  "reference_id": "8JL-NC2-GD3",
  "redirect_url": null
}
{
  "id": "1234a690-2be4-4e95-8516-31cda41f311a",
  "reference_id": "3JL-NX2-XD9",
  "redirect_url": "https://[domain]-portal.boldpenguin.com/auth/callback?token_type=guest&token=[application-form-auth-token]&token_id=[application-form-token-id]"
}