Guides
Postman collections ↗Bud Console ↗

API: Initiating and managing applications

Suggest Edits

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.

With Assess, there are two ways you can create these application links:

  1. Manually, via the dashboard (as detailed here).
  2. By API, allowing for seamless integration into your own processes.

The steps to achieve the latter are broken down below.

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 an 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...)

🚧

Looking for creating applications via Dashboard?

To walk you through that, use the alternative guide, which explain how to create applications directly in the dashboard.

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.

❗️

If you intend to use the Assess dashboard in sync with the API, it is crucial that you follow these steps. Customers created in other ways will not appear in the dashboard, and you will miss out on other capabilities that are available via the API.

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, and the visibility and relevance of each is determined by the configuration of your client's dashboard. For example, clients can choose to disable/hide the application_id.

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

📘

Important note on the Application ID in the Dashboard

In the dashboard, you are given the option to provide an Application ID on creation. This is not the application_id that is generated: it is purely a piece of metadata to allow you to easily filter by user-defined IDs. You can achieve this via API in the same way illustrated above with product_type:

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": {
    "application_id": "app1234"
  }
}
'

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.

Updated over 1 year ago