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

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.

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"
}