Financial Service Methods

This section highlights the different methods that can be used to create and retrieve bank statement request resources through the DeepIDV API.

Table of Contents

• Create and Send a Bank Statement Request
• Fetch Bank Statements
• Fetch Bank Statements by External ID
• Fetch Bank Statements by ID
• Error Status Reference

Create and Send a Bank Statement Request

Request to create and send a bank satement request to an applicant

Request

POST /financial

Parameters

Headers

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

Body Parameters

Type	Params	Values	Description
BODY	email*	string	The end users email (Bank Statement session will be sent to this email)
BODY	firstName*	string	The end users first name
BODY	lastName*	string	The end users last name
BODY	phone*	string	The end users phone number (with country code) Example: +15192223333
BODY	externalId	string	A unique identifier that can be used to retrieve the generated statement session
BODY	period	string	The period (in months) of a bank statement to reuqest (DEFAULT: 3) VALUES(3, 6, 9)
BODY	sendEmailInvite	boolean	Send an email to the applicant (DEFAULT: true)
BODY	sendPhoneInvite	boolean	Send an SMS to the applicant (DEFAULT: true)

Example Request

{
  "email": "applicant@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+15192223333",
  "externalId": "external-123",
  "period": "6",
  "sendEmailInvite": true,
  "sendPhoneInvite": true
}

Response

Success (200)

{
  "bankStatementId": "<bank_statement_id>",
  "bankStatementUrl": "<bank_statement_url>",
  "externalId": "<external_id>",
  "links": "<links>"
}

Response Fields

Field	Type	Description
bank_statement_id	string	The unique id for the created bank statement session
bank_statement_url	string	The link created to complete the bank statement session
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 Bank Statements

Request to fetch all bank statement sessions under the authenticated organization.

Request

GET /financial

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)

{
  "bankStatements": [
    {
      "id": "<bank_statement_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
bank_statement_id	string	The unique id for an bank statement
external_id	string	The externalId for an bank statement
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: 3, 6, 9)

Fetch Bank Statements by External ID

Get all bank statements by external ID

Request

GET /financial/externalId/{external_id}

Parameters

Headers

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

Response

Success (200)

{
  "bankStatements": [
    {
      "id": "<bank_statement_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
bank_statement_id	string	The unique id for an bank statement
external_id	string	The externalId for an bank statement
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: 3, 6, 9)

Fetch Bank Statements by ID

Fetches a bank statement by bank statement ID

Request

GET /financial/{bank_statement_id}

Parameters

Headers

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

Response

Success (200)

{
  "id": "<bank_statement_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
bank_statement_id	string	The unique id for an bank statement
external_id	string	The externalId for an bank statement
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: 3, 6, 9)

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