Create (Start) Credit Application

An introduction to the Create Credit Application endpoint.

📘
Early Access
Credit API endpoints are currently being finalised as part of ongoing product development. While we do not anticipate significant changes, some interfaces, behaviours, and documentation may be refined before general availability.

The Create (Start) Credit Application endpoint enables you to create a new credit application for a customer and send it to Thredd. Thredd can then create the customer record and start processing the application. This forms the start of the credit application flow and is part of the wider origination process.

📘
More Information
For more information about the application process, see: Credit Applications and Origination.

Prerequisites

To integrate calls to the Create (Start) Credit Application endpoint and implement an application process, ensure the following prerequisites are met:

Your own user interface, such as a mobile app or web page, to capture applicant information and display updates about the application status to a user.
Call the Get Application Metadata endpoint to retrieve the list of financial products available to you, along with their IDs. Pass the productId from this response when submitting a credit application.
Consider whether an application requires approval or is pre-approved. For applications that require decisioning, use this endpoint. For pre-approved applications, where you must first complete the necessary diligence checks, use the Submit Pre-Approved Application endpoint instead.
A subscription to Thredd webhooks so that you can receive updates about the application status and communicate them to an applicant via your user interface.

Example Request

Submit a credit application by making a POST request to the Create Credit Application endpoint.

POST {{baseUrl}}/api/v1/credit/applications

Example Payload

The following examples show the payload for the Create Credit Application endpoint.

{
  "productId": "string",
  "title": "string",
  "firstName": "string",
  "middleName": "string",
  "lastName": "string",
  "nameSuffix": "NONE | JR | SR | II | III | IV | V | VI | VII | VIII | IX",
  "dateOfBirth": {
    "year": 0,
    "month": 0,
    "day": 0
  },
  "nationalId": {
    "idNumber": "string",
    "idType": "SSN"
  },
  "customerType": "INDIVIDUAL",
  "gender": "UNKNOWN | FEMALE | MALE",
  "email": "string",
  "residentialAddress": {
    "houseNumber": "string",
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "state": "string",
    "zipCode": "string",
    "county": "string",
    "country": "US"
  },
  "mailingAddress": {
    "houseNumber": "string",
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "state": "string",
    "zipCode": "string",
    "county": "string",
    "country": "US"
  },
  "phoneNumbers": {
    "mobile": "string",
    "work": "string",
    "home": "string",
    "primaryContact": "MOBILE | WORK | HOME | PHONE_TYPE_UNSPECIFIED",
    "secondaryContact": "MOBILE | WORK | HOME | PHONE_TYPE_UNSPECIFIED"
  },
  "employmentStatus": "EMPLOYED | SELF_EMPLOYED | RETIRED | STUDENT | UNEMPLOYED | OTHER",
  "occupation": "string",
  "totalAnnualIncome": 0,
  "monthlyRentOrMortgage": 0,
  "bankAccounts": "CHECKING_AND_SAVINGS | CHECKING_ONLY | SAVINGS_ONLY | NONE",
  "usCitizen": true,
  "dualCitizenship": false,
  "consent": true,
  "ipAddress": "string",
  "employerName": "string"
}

{
  "productId": "prod_123456",
  "title": "Ms",
  "firstName": "Known",
  "middleName": "Lee",
  "lastName": "Person",
  "nameSuffix": "JR",
  "dateOfBirth": {
    "year": 1990,
    "month": 4,
    "day": 15
  },
  "nationalId": {
    "idNumber": "123-45-6789",
    "idType": "SSN"
  },
  "customerType": "INDIVIDUAL",
  "gender": "FEMALE",
  "email": "[email protected]",
  "residentialAddress": {
    "addressLine1": "1234 Test St",
    "city": "Any Town",
    "state": "TX",
    "zipCode": "73301",
    "country": "US"
  },
  "mailingAddress": {
    "addressLine1": "321 Main St",
    "city": "Another Town",
    "state": "TX",
    "zipCode": "10337",
    "country": "US"
  },
  "phoneNumbers": {
    "mobile": "+14155552671",
    "primaryContact": "MOBILE"
  },
  "employmentStatus": "EMPLOYED",
  "occupation": "Administrator",
  "totalAnnualIncome": 72000,
  "monthlyRentOrMortgage": 1200,
  "bankAccounts": "CHECKING_AND_SAVINGS",
  "usCitizen": true,
  "dualCitizenship": false,
  "consent": true,
  "ipAddress": "10.0.0.0",
  "employerName": "Acme Corp"
}

Application Object

Attribute	Description
`productId`	string. Required. The unique ID of the credit product.
`title`	string. Required. The title of the applicant.
`firstName`	string. Required. The first name of the applicant. Used in application and customer records, verification checks, correspondence with the applicant, and as the name on the front of the card. Maximum length is 50 characters.
`middleName`	string. Optional. The middle name of the applicant, if applicable. Used in application and customer records, verification checks, and correspondence with the applicant. Maximum length is 50 characters.
`lastName`	string. Required. The last name of the applicant. Used in application and customer records, verification checks, and correspondence with the applicant. Maximum length is 50 characters.
`nameSuffix`	string. Required. The suffix of the applicant. Possible values: `NONE`, `JR`, `SR`, `II`, `III`, `IV`, `V`, `VI`, `VII`, `VIII`, `IX`.
`dateOfBirth`	object. Required. The date of birth of the applicant, used in identity and verification checks and applicant records. Fields: `year` (integer), `month` (integer), `day` (integer). For `month`, the value is the month number in a calendar year; for example, `1` represents January and `12` represents December.
`nationalId`	object. Required. The national identification details of the applicant, used in identity and verification checks and applicant records. Fields: `idNumber` (string) — the format depends on the `idType`; only digits and hyphens are allowed. `idType` (string) — possible values: `SSN`. An `idType` of `SSN` requires a corresponding `idNumber` of nine digits, in the format: `###-##-####`.
`customerType`	string. Required. The customer type of the applicant. Possible values: `INDIVIDUAL`.
`gender`	string. Optional. The gender of the applicant. Defaults to `UNKNOWN` if not specified. Possible values: `UNKNOWN`, `FEMALE`, `MALE`.
`email`	string. Required. The primary email address of the applicant. Used in applicant records and as the contact address for all email communications and notifications.
`residentialAddress`	object. Required. The primary residence or home address of the applicant. Fields: `addressLine1` (required, string), `city` (required, string), `zipCode` (required, string), `country` (required, string), `houseNumber` (optional, string), `addressLine2` (optional, string), `state` (optional, string), `county` (optional, string). The `country` field must be a two-letter ISO 3166 alpha-2 country code. Accepted values: `US`.
`mailingAddress`	object. Optional. The mailing address of the applicant. If included, must follow the same format as `residentialAddress`.
`phoneNumbers`	object. Required. The phone numbers of the applicant, for use in applicant records. Fields: `mobile` (required, string) — acts as the contact number for all SMS functionality; `work` (optional, string); `home` (optional, string); `primaryContact` (optional, string) — specifies which number is the primary contact, possible values: `MOBILE`, `WORK`, `HOME`, `PHONE_TYPE_UNSPECIFIED`; `secondaryContact` (optional, string) — possible values: `MOBILE`, `WORK`, `HOME`, `PHONE_TYPE_UNSPECIFIED`. Phone numbers must be in E.164 format: a plus sign (`+`), followed by the country code and subscriber number, with a maximum of 15 digits total. For example: `+14155552671`.
`employmentStatus`	string. Required. The employment status of the applicant. Possible values: `EMPLOYED`, `SELF_EMPLOYED`, `RETIRED`, `STUDENT`, `UNEMPLOYED`, `OTHER`.
`occupation`	string. Required. The occupation of the applicant.
`totalAnnualIncome`	integer. Required. The total annual income of the applicant.
`monthlyRentOrMortgage`	integer. Required. The amount the applicant pays for their monthly rent or mortgage.
`bankAccounts`	string. Required. The type of bank account that the applicant holds. Possible values: `CHECKING_AND_SAVINGS`, `CHECKING_ONLY`, `SAVINGS_ONLY`, `NONE`.
`usCitizen`	boolean. Required. Whether the applicant is a U.S. citizen. Possible values: `true`, `false`.
`dualCitizenship`	boolean. Required. Whether the applicant is a legal citizen of more than one country. Possible values: `true`, `false`.
`consent`	boolean. Required. Whether the applicant consents to submitting the application. Possible values: `true`, `false`.
`ipAddress`	string. Optional. The IP address of the applicant, used to aid fraud detection.
`employerName`	string. Optional. The name of the applicant's employer.

Example Response

A successful request returns a 200 HTTP code. The response confirms that the credit application has been created successfully.

📘
Note
If the request contains invalid data or is incomplete, the system returns a 422 HTTP error and details of the validation failure.

{
  "applicationType": "standard_review",
  "applicationId": "app_123456",
  "accountHolderId": "ah_123456",
  "accountId": null,
  "status": "PENDED",
  "productId": "prod_123456",
  "title": "Ms",
  "firstName": "Known",
  "middleName": "Lee",
  "lastName": "Person",
  "nameSuffix": "JR",
  "dateOfBirth": {
    "year": 1990,
    "month": 4,
    "day": 15
  },
  "nationalId": {
    "idNumber": "123-45-6789",
    "idType": "SSN"
  },
  "customerType": "INDIVIDUAL",
  "gender": "FEMALE",
  "email": "[email protected]",
  "residentialAddress": {
    "addressLine1": "1234 Test St",
    "city": "Any Town",
    "state": "TX",
    "zipCode": "73301",
    "country": "US"
  },
  "mailingAddress": {
    "addressLine1": "321 Main St",
    "city": "Another Town",
    "state": "TX",
    "zipCode": "10337",
    "country": "US"
  },
  "phoneNumbers": {
    "mobile": "+14155552671",
    "primaryContact": "MOBILE"
  },
  "employmentStatus": "EMPLOYED",
  "occupation": "Administrator",
  "totalAnnualIncome": 72000,
  "monthlyRentOrMortgage": 1200,
  "bankAccounts": "CHECKING_AND_SAVINGS",
  "usCitizen": true,
  "dualCitizenship": false,
  "consent": true,
  "ipAddress": "10.0.0.0",
  "createdAt": 1736238041798277,
  "updatedAt": 1736238041798277,
  "clientAssignedId": 12345,
  "clientAssignedLocId": 67890,
  "employerName": "Acme Corp"
}

{
  "detail": [
    {
      "loc": ["body", "consent"],
      "msg": "Applicant must provide consent",
      "type": "consent_required"
    }
  ]
}

{
  "detail": [
    {
      "loc": ["body", "consent"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Response Fields

A successful response echoes back the submitted application object and includes the following additional fields:

Attribute	Description
`applicationType`	string. Always `standard_review` for this endpoint.
`applicationId`	string. The unique ID of the application.
`accountHolderId`	string. The unique ID of the account holder created for this applicant.
`accountId`	string or null. The unique ID of the account. `null` until an account is created.
`status`	string. The current status of the application.
`createdAt`	integer. Unix timestamp in microseconds when the application was created.
`updatedAt`	integer. Unix timestamp in microseconds when the application was last updated.
`clientAssignedId`	integer. The ID assigned to the customer in the loan management system.
`clientAssignedLocId`	integer. The ID assigned to the line of credit in the loan management system.

Application Status

When an application is first created, the status is initially set to PENDED. The status changes throughout the lifecycle of the application.

Status	Description
`PENDED`	The application is under review, pending identity verification or manual review checks.

Error Messages

If there is a problem with the request, the response returns a 422 HTTP error containing details of the validation failure. Possible reasons include (this is not a complete list):

A required field or its value is missing from the application object
Incorrect formatting for a field value, such as the national ID number, phone number, or email address
An invalid value in the application object, such as an unsupported country code
An invalid structure in the application object, such as for an address field
An application for this customer already exists, based on the identification details provided

📘
More Information
For more information about the application process, see: Credit Applications and Origination.

Updated 4 days ago

What’s Next

Get Credit Application Timeline

Did this page help you?