Skip to main content

Get Consumer Application Form (Consumer Flow)

Description

This API is to assist consumers with retrieving an existing application form to view in a Consumer Portal. For programmatic access or to view applications in the Partner Portal, see Get Latest Application Form.

The endpoint returns an application form ID and a one-time-use redirect_url to continue the application in your Consumer Portal.

Prerequisites

Consumers are authenticated as guest users. Because of this, they must supply the following pieces of information to retrieve a previously started application:

  • Reference ID of the application form (XXX-XXX-XXX)
  • Zip code supplied in the application form
  • Last name supplied in the application form

Endpoint

Staging

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

Production

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

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.

Methods

POST

Request Syntax

POST /tenants/<tenant_id>/application_forms/search

Request Payload

{
"application_form": {
"create_guest_token": true,
"reference_id": "<string>",
"answer_values": [
{
"code": "mqs_zipcode",
"answer": "<string>"
},
{
"code": "mqs_last_name",
"answer": "<string>"
}
]
}
}

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 must include 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
  • reference_id
    • A unique ID visible to the consumer in the Consumer Portal. The consumer must supply this as part of the search request.
    • Type: String (Format: XXX-XXX-XXX)
    • Required: Yes
  • answer_values
    • An array containing the mqs_zipcode and mqs_last_name question codes along with the answers supplied in the original form (see NOTE below)
    • Type: JSON object
    • Required: No

Response Payload

{
"id": "<UUID>",
"redirect_url": "https://[url]?token_type=guest&token=[guest-user-auth-token]&token_id=[application-form-token-id]",
"reference_id": "12A-BC3-45D",
}

Response Elements

  • id
    • The unique ID for this application form within the tenant
    • Type: String
  • redirect_url
    • A one-time-use URL for displaying the form to the consumer. Only populated if create_guest_user was true in the request and a Consumer Portal exists.
    • Type: URL String
    • Default: null
  • reference_id
    • A unique ID visible to the consumer in the Consumer Portal.
    • Type: String (Format: XXX-XXX-XXX)

Status Codes

  • 200 Success
  • 204 No Content (Application Form not found)
  • 401 Unauthorized: The necessary authentication credentials are not present in the request or are incorrect.
  • 403 Forbidden (Application Form is being worked on by an agent)

Examples

Example Request

curl --request POST \
--url https://partner-engine.boldpenguin.com/tenants/<tenant_id>/application_forms/search \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
"application_form": {
"create_guest_token": true,
"reference_id": "XXX-XXX-XXX",
"answer_values": [
{
"code": "mqs_zipcode",
"answer": "XXXXX"
},
{
"code": "mqs_last_name",
"answer": "XXXXXXXXXX"
}
]
}
}'

Example Response: Success

{
"id": "1234a690-2be4-4e95-8516-31cda41f311a",
"redirect_url": "https://<domain>-portal.boldpenguin.com/auth/callback?token_type=guest&token=<application-form-auth-token>&token_id=<application-form-token-id>",
"reference_id": "12A-BC3-45D",
}

NOTE: domain will be your unique domain provided during on-boarding.

Example Response: 403

{
"id": "1234a690-2be4-4e95-8516-31cda41f311a"
"redirect_url": nil,
"reference_id": "12A-BC3-45D",
"error": "Application is being worked on by agent"
}