Get Required Documents

GET

customers

required-documents

curl --request GET \
  --url https://sandbox.api.fin.com/v2/customers/required-documents \
  --header 'Authorization: Bearer <token>'

const url = 'https://sandbox.api.fin.com/v2/customers/required-documents';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "https://sandbox.api.fin.com/v2/customers/required-documents"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.api.fin.com/v2/customers/required-documents"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "data": {
    "requirements": [
      {
        "customer_type": "INDIVIDUAL",
        "documents": [
          {
            "category": "identifying_documents",
            "requirement": "ONE_OF",
            "document_types": [
              "PASSPORT",
              "NATIONAL_ID",
              "DRIVERS_LICENSE",
              "RESIDENCE_PERMIT"
            ],
            "front_and_back_required": [
              "NATIONAL_ID",
              "DRIVERS_LICENSE",
              "RESIDENCE_PERMIT"
            ]
          },
          {
            "category": "address_documents",
            "requirement": "ONE_OF",
            "document_types": [
              "UTILITY_BILL",
              "GOVERNMENT_LETTER",
              "BANK_STATEMENT"
            ]
          }
        ]
      }
    ]
  }
}

Use this endpoint to find out which documents to collect before you call the attach document endpoints. It describes the onboarding rules, not the progress of a specific customer, and it reads from the same rules the attach endpoints enforce. All three query parameters are optional. Leave them out to get every customer type in one response. Send all three when you know them to get a single, exact checklist.

Reading the response

Each entry in requirements covers one customer type (and, for businesses, one entity type). documents lists the customer’s own document groups. associated_party_documents lists what each director or owner must provide, and appears only for businesses.

Field	Meaning
`category`	The group the documents belong to, such as `identifying_documents` or `formation_documents`.
`requirement`	`ONE_OF`: upload any one document from the list. `ALL_OF`: upload every document in the list.
`document_types`	The accepted document types.
`front_and_back_required`	Document types that need both a front and a back image.
`required_when`	Shown only on a conditional group. See below.

How `country_of_incorporation` changes the response

Only CORPORATION, LIMITED_LIABILITY_COMPANY and PUBLICLY_LISTED_COMPANY have a country dependent document (EVIDENCE_OF_DIRECTORS_AND_CONTROLLERS).

You send	Response
No country	A separate `formation_documents` group with `required_when: "country_of_incorporation is not USA"`.
`USA`	The document is omitted.
Any other country, e.g. `GBR`	The document is merged into the main `formation_documents` group, with no `required_when`.

entity_type and country_of_incorporation only apply to businesses. Sending either with customer_type=INDIVIDUAL returns 422. Parameter values are case insensitive, and countries must be ISO 3166-1 alpha-3 (GBR, not UK).

Authorizations

Authorization

string

header

required

Bearer token authentication. Obtain token from Issue a Token endpoint

Query Parameters

customer_type

enum<string>

Filter by customer type. Case insensitive. Omit to return every customer type.

Available options:

INDIVIDUAL,

BUSINESS

entity_type

enum<string>

Filter by business entity type. Case insensitive. Only valid when customer_type is BUSINESS (or omitted).

Available options:

CHARITY,

CORPORATION,

LIMITED_LIABILITY_COMPANY,

NONPROFIT_ORGANIZATION,

PARTNERSHIP,

PRIVATE_FOUNDATION,

PUBLICLY_LISTED_COMPANY,

PUBLIC_AGENCY_OR_AUTHORITY,

SOLE_PROPRIETOR,

TRUST

country_of_incorporation

string

Country where the business is registered, ISO 3166-1 alpha-3. Only valid when customer_type is BUSINESS (or omitted). Resolves country dependent documents into a single exact checklist.

Pattern: ^[A-Za-z]{3}$

Response

Required documents retrieved successfully

data

object

Show child attributes

⌘I

Get Required Documents

curl --request GET \
  --url https://sandbox.api.fin.com/v2/customers/required-documents \
  --header 'Authorization: Bearer <token>'

const url = 'https://sandbox.api.fin.com/v2/customers/required-documents';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "https://sandbox.api.fin.com/v2/customers/required-documents"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.api.fin.com/v2/customers/required-documents"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "data": {
    "requirements": [
      {
        "customer_type": "INDIVIDUAL",
        "documents": [
          {
            "category": "identifying_documents",
            "requirement": "ONE_OF",
            "document_types": [
              "PASSPORT",
              "NATIONAL_ID",
              "DRIVERS_LICENSE",
              "RESIDENCE_PERMIT"
            ],
            "front_and_back_required": [
              "NATIONAL_ID",
              "DRIVERS_LICENSE",
              "RESIDENCE_PERMIT"
            ]
          },
          {
            "category": "address_documents",
            "requirement": "ONE_OF",
            "document_types": [
              "UTILITY_BILL",
              "GOVERNMENT_LETTER",
              "BANK_STATEMENT"
            ]
          }
        ]
      }
    ]
  }
}

Authentication

Customers

Beneficiaries

Virtual Accounts

Transactions

Balances

Fees & FX Rates

Catalogue

Crypto Orchestration

Webhooks

Get Required Documents

Reading the response

How `country_of_incorporation` changes the response

Authorizations

Query Parameters

Response

​Reading the response

​How country_of_incorporation changes the response

Authorizations

Query Parameters

Response

Reading the response

How `country_of_incorporation` changes the response