Credit Applications

The Application API is used to collect applicants' data used for the credit application decision process. As a fintech processes a credit application, they must update the content and status of the application. The application status must be in state 'CREDIT_ACCEPTED_BY_CUSTOMER' before a credit account can be created. Credit account type include LINE_OF_CREDIT, CHARGE_SECURED, and CHARGE_UNSECURED.

A credit application consists of a primary applicant, with an option to add one or more co-applicant(s), application status, the account type the application is associated with, and the purpose of this application, which ranges from account opening to account management post issuance. The Credit Application spec includes more standardized information on applicants to help fintechs record the lifecycle of a credit application from initial submission to the resulting outcome, and share it with their sponsoring bank. That includes if credit was extended or not; if extended credit was accepted or declined by the client; once extended, what data information is used for the decisioning process; and, if the application is declined, what adverse action reasons were sent.

The application processing is a multi-step process. The following diagram illustrates all the states the application could be in. Upon creation of the credit application, the status is APPLICATION_SUBMITTED and can flow to other states as seen in the following diagram.

Once the application is in CREDIT_ACCEPTED_BY_CUSTOMER state, a credit account is now allowed to be created.

If the application is in the CREDIT_DENIED state, the fintech is required to provide an adverse action notice to the customer. This requirement is primarily for retail consumers, but may also be applicable to certain business customers. Please confirm with your sponsor bank's compliance policy. This requirement is applicable for KYC failure, credit decision rejection, and incomplete application.

If credit scores were pulled and utilized for credit decisions during application, please follow the examples here to record the scores and link to the related applications.

Examples

1a. Application Submitted - Create an Application - POST /v1/applications

curl -X POST \
  -H 'Authorization: Bearer $apikey' \
  -H 'Content-Type: application/json' \
  -d '
  {
      "account_type": "LINE_OF_CREDIT",
      "applicants": [
        {
          "customer_id": "4a666a01-d23a-47b1-8c20-2eb5a923da35",
          "is_primary": true
        }
      ],
      "purpose": "ACCOUNT_OPENING",
      "status": "SUBMITTED",
      "type": "CREDIT"
    }' $baseurl/v1/applications

Sample response body:

{
  "account_type": "LINE_OF_CREDIT",
  "applicants": [
    {
      "customer_id": "4a666a01-d23a-47b1-8c20-2eb5a923da35",
      "is_primary": true
    }
  ],
  "purpose": "ACCOUNT_OPENING",
  "status": "SUBMITTED",
  "type": "CREDIT",
  "creation_time": "2022-10-26T19:14:45.861687Z",
  "id": "ebda67f0-e0a7-41e2-98ed-0617a1e815a6",
  "last_updated_time": "2023-09-20T00:31:10.255042Z"
}

1b-i. Application Submitted, with credit scores used - Create a credit score record - POST /v1/credit_scores

curl -X POST \
  -H 'Authorization: Bearer $apikey' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "customer_id": "6a7ed697-4e8c-481c-b8e9-cfadde31342e",
    "score": 725,
    "score_requested_time": "2020-01-01T00:00:00Z",
    "source_of_score": "ACCOUNT_OPENING",
    "type": "FICO",
    "vendor_name": "EQUIFAX",
    "version": "8"
    }' $baseurl/v1/credit_scores

Sample response body:

{
  "customer_id": "6a7ed697-4e8c-481c-b8e9-cfadde31342e",
  "score": 725,
  "score_requested_time": "2020-01-01T00:00:00Z",
  "source_of_score": "ACCOUNT_OPENING",
  "type": "FICO",
  "vendor_name": "EQUIFAX",
  "version": "8",
  "creation_time": "2023-10-03T22:35:01.415125Z",
  "id": "9534eebb-7d37-4d07-b219-8133d26e6fee",
  "last_updated_time": "2023-10-03T22:35:01.415125Z"
}

1b-ii. Application Submitted, with credit scores used - Create an Application - POST /v1/applications

curl -X POST \
  -H 'Authorization: Bearer $apikey' \
  -H 'Content-Type: application/json' \
  -d '
  {
   COMING SOON
    }' $baseurl/v1/applications

Sample response body:

{
  COMING SOON
}

2a. Credit Approved - Update the application - PATCH /v1/applications/{APPLICATION_UUID}

 curl -X PATCH \
     -H 'Authorization: Bearer $apikey' \
     -H 'Content-Type: application/json' \
     -d '
     {
         "status": "CREDIT_APPROVED"
     }' $baseurl/v1/applications/{APPLICATION_UUID}

Sample response body:

{
  "account_type": "LINE_OF_CREDIT",
  "applicants": [
    {
      "customer_id": "4a666a01-d23a-47b1-8c20-2eb5a923da35",
      "is_primary": true
    }
  ],
  "purpose": "ACCOUNT_OPENING",
  "status": "CREDIT_APPROVED",
  "type": "CREDIT",
  "creation_time": "2022-10-26T19:14:45.861687Z",
  "id": "ebda67f0-e0a7-41e2-98ed-0617a1e815a6",
  "last_updated_time": "2023-09-20T00:31:10.255042Z"
}

3a. Customer accepts the credit offered - Update the application - PATCH /v1/applications/{APPLICATION_UUID}

curl -X PATCH \
    -H 'Authorization: Bearer $apikey' \
    -H 'Content-Type: application/json' \
    -d '
    {
        "status": "CREDIT_ACCEPTED_BY_CUSTOMER"
    }' $baseurl/v1/applications/{APPLICATION_UUID}

Sample response body:

 {
  "account_type": "LINE_OF_CREDIT",
  "applicants": [
    {
      "customer_id": "4a666a01-d23a-47b1-8c20-2eb5a923da35",
      "is_primary": true
    }
  ],
  "purpose": "ACCOUNT_OPENING",
  "status": "CREDIT_ACCEPTED_BY_CUSTOMER",
  "type": "CREDIT",
  "creation_time": "2022-10-26T19:14:45.861687Z",
  "id": "ebda67f0-e0a7-41e2-98ed-0617a1e815a6",
  "last_updated_time": "2023-09-20T00:31:10.255042Z"
}

Alternative Flows

2b. After Application Submitted, Credit is Denied - Fintech sends an Adverse Action Notice to Applicant - POST /v1/adverse_actions

curl -X POST \
    -H 'Authorization: Bearer $apikey' \
    -H 'Content-Type: application/json' \
    -d '
     {
     "notification_time": "2020-05-19T21:14:27.434964Z",
     "purpose": "ACCOUNT_OPENING",
     "reasons": [
       "TOO_MANY_INQUIRIES",
       "INSUFFICIENT_CREDIT_HISTORY"
     ],
     "related_resource_id": "9337a443-fa03-471c-ab05-b138c41dbd17",
     "related_resource_type": "CUSTOMER"
   }' $baseurl/v1/adverse_actions

Sample respones body:

{
   "notification_time": "2020-05-19T21:14:27.434964Z",
   "purpose": "ACCOUNT_OPENING",
   "reasons": [
     "TOO_MANY_INQUIRIES",
     "INSUFFICIENT_CREDIT_HISTORY"
   ],
   "related_resource_id": "9337a443-fa03-471c-ab05-b138c41dbd17",
   "related_resource_type": "CUSTOMER",
   "creation_time": "2023-09-19T15:48:24.10184Z",
   "id": "2fb2858b-f859-4dc8-9ad2-2a4e596fed89",
   "last_updated_time": "2023-09-19T15:48:24.10184Z"
 }

3b. After Application Submitted, Credit is Denied - Update the application - PATCH /v1/applications/{APPLICATION_UUID}

curl -X PATCH \
    -H 'Authorization: Bearer $apikey' \
    -H 'Content-Type: application/json' \
    -d '
    {
        "status": "CREDIT_DENIED",
        "adverse_action_id": "2fb2858b-f859-4dc8-9ad2-2a4e596fed89"
    }' $baseurl/v1/applications/{APPLICATION_UUID}

Sample response body:

  {
  "account_type": "LINE_OF_CREDIT",
  "applicants": [
    {
      "customer_id": "4a666a01-d23a-47b1-8c20-2eb5a923da35",
      "is_primary": true
    }
  ],
  "purpose": "ACCOUNT_OPENING",
  "status": "CREDIT_DENIED",
  "type": "CREDIT",
  "adverse_action_id": "2fb2858b-f859-4dc8-9ad2-2a4e596fed89",
  "creation_time": "2022-10-26T19:14:45.861687Z",
  "id": "ebda67f0-e0a7-41e2-98ed-0617a1e815a6",
  "last_updated_time": "2023-09-20T00:31:10.255042Z"
}