Initiating and managing applications

Summary

Most applications in Assess start with a link that's created and sent to your customer. Once they access that link, the user is able to submit their financial data through what we call the Connect flow. You can read more about that here.

Pre-requisites

You’ll need a valid OAuth access token - for further details on how to authenticate to Bud’s APIs please see this guide
It's advisable to get a base understanding of a customer entity given an Assess application combines it with additional data that is used in the context of affordability assessments (e.g. customer first/last name, email address, etc...)

Create an application

First, you need to create the customer application in Bud. This step is necessary so that non-financial data (like the name, email address, etc) can be stored and associated with an application in Assess.

To do that call this endpoint: POST assess/v1/customer-applications (here).

The primary_applicant field is required in order to be able to create an application, but all other fields are optional.
By default, the assessment_date field will be set to the current day as of the application creation, but a different date can be provided if relevant.
All metadata fields are optional.

You can see a breakdown of all fields below:

curl --request POST \
  --url https://api-sandbox.thisisbud.com/assess/v1/customer-applications \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Client-ID: <client_id>' \
  --data '{
  "primary_applicant": {
    "first_name": "string",
    "last_name": "string"
  },
  "secondary_applicants": [
    {
      "first_name": "string",
      "last_name": "string"
    }
  ],
  "assessment_date": "2022-05-11",
  "metadata": {
    "application_id": "string",
    "customer_id": "string",
    "advisor_name": "string",
    "account_connection_initiator": "customer",
    "property1": "string",
    "property2": "string"
  }
}
'

Successful responses will return the application_id and the expiry_date for that application, which is a configurable value. You can see an example response below:

{
  "operation_id": "v1_customer_applications_post",
  "data": {
    "application_id": "48ac72d0-a829-4896-a067-dcb1c2b0f30c",
    "expires_at": "2022-05-11T15:30:39Z"
  }
}

For example, suppose that you are assessing your customers for 3 different possible financial products: a credit_card, a mortgage or insurance. You can use the metadata to add this information on creation:

curl --request POST \
  --url https://api-sandbox.thisisbud.com/assess/v1/customer-applications \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Client-ID: <client_id>' \
  --data '{
  "primary_applicant": {
    "first_name": "Jim",
    "last_name": "Flarsky"
  },
  "metadata": {
    "product_type": "credit_card"
  }
}
'

Then when you want to find all of the credit_card applications, you can use the GET /assess/v1/customer-applications/{application_id} endpoint (here) to list only the credit card applications using the query parameter metadata.product_type=credit_card:

curl --request GET \
  --url 'https://api-sandbox.thisisbud.com/assess/v1/customer-applications?metadata.product_type=credit_card' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'X-Client-ID: <client_id>'

{
  "operation_id": "v1_customer_applications_get",
  "data": [
    {
      "application_id": "94c67222-bb34-4b5d-be0f-bd76bcadc9c9",
      "customer_id": "49d49c31-ef6a-4ca4-97ff-488b31216ac1",
      "creation_date": "2023-08-14T13:45:03Z",
      "deletion_date": "2023-08-15T13:45:03Z",
      "accounts_connected": 0,
      "metadata": {
        "product_type": "credit_card"
      },
      "assessment_date": "2023-08-14T13:45:02Z",
      "primary_applicant": {
        "first_name": "Jim",
        "last_name": "Flarsky"
      },
      "secondary_applicants": null,
      "initiator_id": "",
      "customer_link": null,
      "review_status": ""
    }
  ],
  "metadata": {
    "results": 1
  }
}

Viewing a Customer's Application

Each application has a generated UUID, which is seen under the application_id property. You can retrieve an individual customer's application using the GET /assess/v1/customer-applications/{application_id} endpoint (here) with this ID:

curl --request GET \
  --url 'https://api-sandbox.thisisbud.com/assess/v1/customer-applications/<application_id>' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'X-Client-ID: <client_id>'

{
  "operation_id": "v1_customer_application_get",
  "data": {
    "application_id": "<application_id>",
    "customer_id": "<customer_id>",
    "creation_date": "2023-08-14T13:45:03Z",
    "deletion_date": "2023-08-15T13:45:03Z",
    "accounts_connected": 0,
    "metadata": {
      "product_type": "credit_card"
    },
    "assessment_date": "2023-08-14T13:45:02Z",
    "primary_applicant": {
      "first_name": "Jim",
      "last_name": "Flarsky"
    },
    "secondary_applicants": null,
    "initiator_id": "",
    "customer_link": {
      "created_at": "2023-08-14T14:02:48Z",
      "url": "<customer_link>",
      "finished_connecting_accounts": false,
      "expired": false,
      "status": "requested"
    },
    "review_status": ""
  }
}

Create the connection link

Once you've created your application, you can use the application_id to create an application link, which your customer will use to access the Connect flow to connect up their accounts and submit their financial data.

To do that, use POST assess/v1/customer-applications/{application_id}/customer-links (here), passing in the relevant application_id.

If successful, you'll get the connection link back in a response which will look like the below:

{
  "operation_id": "v1_customer_applications_customer_links_post",
  "data": {
    "link": "https://url-to-customer-dashboard.thisisbud.com/connect-accounts/1674af1a-96ce-4517-97c4-6937592b0807"
  },
  "metadata": {
    "connection_id": "1674af1a-96ce-4517-97c4-6937592b0807"
  }
}

{
  "operation_id": "v1_customer_applications_customer_links_post",
  "data": {
    "link": "<link_to_follow>"
  },
  "metadata": {
    "connection_id": "<connection_id>"
  }
}

Sending the link directly to the customer

👍
Want to automatically send the application?
Follow this additional step detailed below.

While you're free to distribute the connection link however you wish, you can also opt to have the link distributed directly to your customer. To do that, you just need to provide the destination email address in the payload of your call above in the send_to field, as below:

{
  "send_to": "[email protected]"
}

If you provide an email address in this way, Bud will send a templated email to the user inviting them to complete their loan application. By default, that email looks like the below, but your client name, logo, and privacy policy will be inserted - as per what you provide when configuring the user experience of Assess:

Deletion of applications

The deletion_date property on the customer application indicates the date by which it will be removed from the platform automatically.

If you want to delete an application before then however, you can use the DELETE /assess/v1/customer-applications/{application_id} endpoint (here):

curl --request DELETE \
  --url 'https://api-sandbox.thisisbud.com/assess/v1/customer-applications/<application_id>' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'X-Client-ID: <client_id>'

This permanently removes the application (making it no longer accessible via dashboard or API) and deletes all financial data associated with the customer.

Deletion via purging

Assess also has functionality that supports the automatic purging of applications after a period of time you define. This auto-purge functionality is configured when onboarding with Bud, so please prepare to discuss this with us.

If you have any questions, please contact us via the chatbot (bottom-right of screen 👉) or via a support request or check our FAQs.

Summary

Create an application

Viewing a Customer's Application

Create the connection link

Sending the link directly to the customer

👍Want to automatically send the application?

Deletion of applications

Deletion via purging

👍
Want to automatically send the application?