Retrieve Application Form (Consumer Flow)

Description

This API is to assist consumers with retrieving an existing application form to view in a Consumer Portal. To view applications in the Partner Portal, see Retrieve Application Form (Partner Flow).

The endpoint returns an application form ID and a 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
  • 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. The token must come from the the same environment, and be presented 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

NOTE: This request uses question codes from the Master Question Set rather than the tenant specific question codes used when creating an application form.

Response Payload

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

Response Elements

  • id
    • The unique ID for this application form within the tenant
    • Type: String
  • 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

Status Codes

  • 201 Success
  • 401 Unauthorized (verify bearer token from authentication)
  • 422 Parameter validation failure (verify answers supplied match an application form for your tenant)
  • 500 Internal server error

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

{
  "id": "1234a690-2be4-4e95-8516-31cda41f311a",
  "redirect_url": "https://[domain]-portal.boldpenguin.com/auth/callback?token=[application-form-auth-token]&token_id=[application-form-token-id]"
}

results matching ""

    No results matching ""