Skip to main content

Create Application Form

Description​

Create an application form within your Bold Penguin tenant. You can optionally prepopulate the form with question codes and answers from the Master Question Set or your Broker Question Set.

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/

Production​

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

NOTE: that the tenant_id will be different between environments.

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​

POST

Request Syntax​

POST /tenants/<tenant_id>/application_forms

Request Payload​

The body of the request may contain an optional application_form consisting of one or more answer values in JSON format.

{
  "application_form": {
    "create_guest_user": true,
    "mark_in_progress": true,
    "autocomplete": true,
    "storefront_code": "<string>",
    "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:

  • create_guest_user
    • Set this to true to generate a redirect URL for consumers. This requires a configured Consumer Portal for your terminal
    • Type: Boolean
    • Required: No
  • mark_in_progress
    • Set this to true when submitting an application form with pre-filled answer values
    • Type: Boolean
    • Required: No
  • autocomplete
    • If answer_values are sent, set this to true to automatically mark `question_sets`` eligible for completion to completed.
    • Type: Boolean
    • Required: No
  • storefront_code
    • When using the Storefront product you can pre-populate answers for your own Storefront using the API. This code is provided by Bold Penguin.
    • Type: String
    • Required: No
  • 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 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 create 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",
      "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.

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 if create_guest_user was true in the request and a Consumer Portal exists
    • Type: URL String
    • Default: null

NOTE: You will need the id of this application form later to get the latest form or to clone this application to the Bold Penguin Exchange.

Status Codes​

  • 201 Created
  • 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 POST \
  --url https://partner-engine.boldpenguin.com/tenants/<tenant_id>/application_forms \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "application_form": {
    "create_guest_user": true,
    "mark_in_progress": true,
    "autocomplete": true,
    "storefront_code": "<string>",
    "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]"
}