Credit Terms Service Methods

This section highlights the different methods that can be used to create and retrieve credit terms resources through the DeepIDV API.

Table of Contents

• Create and Send a Credit Terms Request
• Fetch Credit Terms
• Fetch Credit Terms by External ID
• Fetch Credit Terms by ID
• Error Status Reference

Create and Send a Credit Terms Request

POST /credit-terms

Parameters

Headers

Type	Params	Values	Description
HEADER	x-api-key*	string	The users API Key

Body Parameters

Type	Params	Values	Description
BODY	businessEmail*	string	The end business email where the request will be sent to
BODY	firstName*	string	The end users first name
BODY	lastName*	string	The end users last name
BODY	businessName*	string	The end business name
BODY	businessAddress*	string	The end business address
BODY	requestedCreditAmount *	number	The total amount of requested credit from the applicant
BODY	externalId	string	A unique identifier that can be used to retrieve the generated statement session
BODY	requestedCreditPeriod	string	The period (in months) of a bank statement to reuqest (DEFAULT: 30) VALUES(30, 60, 90)
BODY	sendEmailInvite	boolean	Send an email to the applicant (DEFAULT: true)

Example Request

{
  "businessEmail": "applicant@example.com",
  "businessName": "Example Corp",
  "businessAddress": "123 Example St, City, Country",
  "firstName": "John",
  "lastName": "Doe",
  "externalId": "external-123",
  "period": "60",
  "requestedCreditAmount": 50000,
  "sendEmailInvite": true
}

Response

Success (200)

{
  "creditTermsId": "<credit_terms_id>",
  "creditTermsUrl": "<credit_terms_url>",
  "externalId": "<external_id>",
  "links": "<links>"
}

Response Fields

Field	Type	Description
credit_terms_id	string	The unique id for the created credit terms session
credit_terms_url	string	The link created to complete the credit terms ssession
external_id	string	The externalId that was passed as a parameter
links	array	A list of discoverable URLs for related resources

Best Practices

• Always validate required fields before sending requests
• Store the id and externalId for future reference
• Handle error responses appropriately in your application

Fetch Credit Terms

Request to fetch all credit terms sessions under the authenticated organization

Request

GET /credit-terms

Parameters

Headers

Type	Params	Values	Description
HEADER	x-api-key*	string	The users API Key

Query Parameters

Type	Params	Values	Description
QUERY	nextToken	string	To retrieve the next page of sessions, provided the limit of 500 was reached in a previous call

Response

Success (200)

{
  "creditTerms": [
    {
      "id": "<credit_terms_id>",
      "externalId": "<external_id>",
      "status": "<status>",
      "type": "<statement_type>",
      "createdAt": "<created_at>",
      "updatedAt": "<updated_at>",
      "senderUserId": "<sender_user_id>",
      "Config": "<config>"
    }
  ],
  "nextToken": "<next_token>"
}

Response Fields

Field	Type	Description
credit_terms_id	string	The unique id for a credit terms
external_id	string	The externalId for a credit terms
status	string	The status of a bank statement
statement_type	string	Type of the bank statement VALUES: (upload, request)
created_at	string	The date stamp of when a session was created
updated_at	string	The date stamp of when a session was updated
sender_user_id	string	ID of the user that sent out the request
config	object	The configuration for the bank statement
next_token	string	The token to get the next page of statements (if limit of 500 was reached)

Status Values

The status field can have one of the following values:

• PENDING: Session has not been started
• IN_PROGRESS: Sataement is processing
• COMPLETED: Statement and analysis has completed

Config Values

• period: The period in months of the requested bank statement (VALUES: 30, 60, 90)
• name: Name of the business requesting the credit
• address: Address of the business requesting the credit
• requestedAmount: The total amount of credit requested

Fetch Credit Terms by External Id

Request to fetch all credit terms session by its external ID

Request

GET /credit-terms/externalId/{external_id}

Parameters

Headers

Type	Params	Values	Description
HEADER	x-api-key*	string	The users API Key

Response

Success (200)

{
  "creditTerms": [
    {
      "id": "<credit_terms_id>",
      "externalId": "<external_id>",
      "status": "<status>",
      "type": "<statement_type>",
      "createdAt": "<created_at>",
      "updatedAt": "<updated_at>",
      "senderUserId": "<sender_user_id>",
      "Config": "<config>"
    }
  ],
  "nextToken": "<next_token>"
}

Response Fields

Field	Type	Description
credit_terms_id	string	The unique id for a credit terms
external_id	string	The externalId for a credit terms
status	string	The status of a bank statement
statement_type	string	Type of the bank statement VALUES: (upload, request)
created_at	string	The date stamp of when a session was created
updated_at	string	The date stamp of when a session was updated
sender_user_id	string	ID of the user that sent out the request
config	object	The configuration for the bank statement
next_token	string	The token to get the next page of statements (if limit of 500 was reached)

Status Values

The status field can have one of the following values:

• PENDING: Session has not been started
• IN_PROGRESS: Sataement is processing
• COMPLETED: Statement and analysis has completed

Config Values

• period: The period in months of the requested bank statement (VALUES: 30, 60, 90)
• name: Name of the business requesting the credit
• address: Address of the business requesting the credit
• requestedAmount: The total amount of credit requested

Fetch Credit Terms by ID

Fetches a credit terms by credit terms ID

Request

GET /credit-terms/{credit_terms_id}

Parameters

Headers

Type	Params	Values	Description
HEADER	x-api-key*	string	The users API Key

Response

Success (200)

{
  "id": "<credit_terms_id>",
  "externalId": "<external_id>",
  "status": "<status>",
  "type": "<statement_type>",
  "createdAt": "<created_at>",
  "updatedAt": "<updated_at>",
  "senderUserId": "<sender_user_id>",
  "Config": "<config>"
}

Response Fields

Field	Type	Description
credit_terms_id	string	The unique id for a credit terms
external_id	string	The externalId for a credit terms
status	string	The status of a bank statement
statement_type	string	Type of the bank statement VALUES: (upload, request)
created_at	string	The date stamp of when a session was created
updated_at	string	The date stamp of when a session was updated
sender_user_id	string	ID of the user that sent out the request
config	object	The configuration for the bank statement

Status Values

The status field can have one of the following values:

• PENDING: Session has not been started
• IN_PROGRESS: Sataement is processing
• COMPLETED: Statement and analysis has completed

Config Values

• period: The period in months of the requested bank statement (VALUES: 30, 60, 90)
• name: Name of the business requesting the credit
• address: Address of the business requesting the credit
• requestedAmount: The total amount of credit requested

Error Status Reference

The DeepIDV API uses standard HTTP status codes to indicate the success or failure of requests. The following table describes the possible error responses you may encounter:

Status Code	Error Message	Description
400	{"error": "Invalid Input."}	The request parameters are invalid or missing required fields
401	{"error": "Invalid API key."}	The provided API key is invalid or expired
402	{"error": "Insufficient funds or subscription."}	Unauthorized - Payment required
403	{"error": "API key is missing."}	No API key was provided in the request
429	{"error": "Rate limit exceeded."}	Too many requests have been made in a short period
500	{"error": "Something went wrong."}	An unexpected error occurred on the server

Best Practices for Error Handling

• Always validate required fields before sending requests
• Implement retry logic with exponential backoff for rate limit errors (429)
• Store error logs for debugging and monitoring purposes
• Display user-friendly error messages in your application