Legacy schema — superseded by the Entity API. New programs integrate via the Entity API. This schema remains the supported path for file-integrated programs that have not yet migrated.
Complete Customer Files are required to be sent for all customers on creation as well as on update. Partial updates are not supported. Please do not submit “no-op” changes to customers.
For optional fields where you do not plan to pass through data, please include the header and an empty value.
| Field | Description | Required | Data Type |
|---|---|---|---|
| client_customer_id | The unique ID for this customer in your system. Limit of 64 characters. | Required | string |
| customer_type | Type of customer. | Required | enum: individualbusinesssole_prop |
| intended_roles | Intended role(s) of the customer. These can be used to synchronously validate eligibility of customers for specific roles. Refer to Data Requirements for Intended Roles for more details. | Optional | array of enum:authorized_userauthorized_signeraccount_holder For customer_type = individual, all of authorized_user, authorized_signer, account_holder allowedFor customer_type = sole_prop, only account_holder is allowed.For customer_type = business, only account_holder is allowed. |
| first_name | Legal first name. | Required if customer_type = individual | string |
| preferred_first_name | Preferred first name. | Optional | string |
| middle_name | Middle name. | Optional | string |
| last_name | Legal last name. Must be at least 2 alphanumeric characters. | Required if customer_type = individual | string |
| date_of_birth | Date of birth. | Optional | dateYYYY-MM-DD |
| occupation | Occupation or job. | Optional | string |
| business_type | Business types based on customer_types | Required if customer_type = business, sole_prop | enum:corporationpartnershipsole_propllctrustcooperativeotherindividual = N/A business = corporation, partnership, sole_prop, llc, trust, cooperative, othersole_prop = sole_prop |
| business_name | Legal name of the business. Must be at least 2 characters. | Required if customer_type = business, sole_prop | string |
| doing_business_as | Business name if the business operates under a different name. | Optional | string |
| website | The website of the business. | Optional | url:http:// https:// |
| business_gross _annual_revenue | Business gross revenue for prior fiscal year. | Optional | decimal(M, 2) |
| business_gross _annual_revenue_currency | A three-letter currency code as defined in ISO 4217. | Optional | ISO 4217 |
| industry | NAICS codes for the applicable industries. 2-6 digits of NAICS codes are accepted. | Required if customer_type = business, sole_prop | array of enum [11, 111140] |
| Primary email address of the customer. | ONE of email or phone_number is required | string | |
| phone_number | Primary phone number of the customer. | ONE of email or phone_number is required | E.123 phone number format. Example for US: +1 123 456 7890 |
| physical_address _line_1 | Address line 1. Physical addresses must not be P.O. boxes, registered agent addresses or in prohibited countries. | Required if any of the physical_address fields are present | string |
| physical_address _line_2 | Address line 2. | Optional | string |
| physical_address _city | City. | Required if any of the physical_address fields are present | string |
| physical_address _postal_code | Postal Code, required for US addresses. | Required if physical_address_country = us | string Follow this format: US: ^\d5(?:-\d4)?$ CN: ^\d6$, GB: ^[A-Z]2d[A-Z0-9]? ?d[A-Z]2$ JP: ^\d3-\d4$ |
| physical_address _state | State. | Required if physical_address_country = us | string: 2-letter state code |
| physical_address _country | ISO3166-1 Alpha-2 country code. | Required if any of the physical_address fields are present | string: ISO 3166-1-alpha-2 |
| mailing_address _line_1 | Address line 1. | Required if any of the mailing_address fields are present | string |
| mailing_address _line_2 | Address line 2. | Optional. | string |
| mailing_address _city | City. | Required if any of the mailing_address fields are present | string |
| mailing_address _postal_code | Postal Code, required for US addresses. | Required if mailing_address_country = us | string Follow this format: US: ^\d5(?:-\d4)?$ CN: ^\d6$, GB: ^[A-Z]2d[A-Z0-9]? ?d[A-Z]2$ JP: ^\d3-\d4$ |
| mailing_address _state | State. | Required if mailing_address_country = us | string: 2-letter state code |
| mailing_address _country | ISO3166-1 Alpha-2 country code. | Required if any of the mailing_address fields are present | string: ISO 3166-1-alpha-2 |
| other_addresses | Other addresses for the customer. | Optional. | ”line_1”: “string” (required) “line_2”: “string” (optional) “city”: “string” (required) “postal_code”: “string” (required if country = us) “state”: “string; 2 character code” (required if country= us) “country”: “string; ISO3166-1 Alpha-2 country code” (required) |
| is_us_entity | Customer is considered US entity if they have US tax identification. For US Entities: Full KYC (needed for Account Holder and Authorized Signer roles), US tax identification number as well as other available government-verified identification documents are required. For non-US Entities: Government-verified identification documents are required | Required | boolean |
| us_tax_id_type | The entity’s US tax identification type. | Required if any of the us_tax_id fields are present | enum:ssneinitin If customer_type = individual, ssn or itin is required.If customer_type = business, ein is required.If customer_type = sole_prop, ssn, ein or itin is required. |
| us_tax_id_value | The customer’s US tax identification number. Must be 9 digits (e.g. XXXXXXXXX). ssn must not start with a 9.ein must begin with a number between 00 and 99. itin must begin with a 9 | Required if any of the us_tax_id fields are present | string |
| identification_documents | For US Entities Available government-verified identification documents are required. For non-US Entities Government-verified identification documents are required. client_document_id: Client document ID for the identification document. type: Customer’s government-verified identification document type. This will apply for identification types other than US tax identification. description: Description about the identification document. Required if identification document type is other.identification_number: Unique identification number on the identification document.expiration_date: Expiration date of the identification document. issuing_state: Issuing state of the identification document. Must be 2 character code (e.g. NY). issuing_country: Issuing country of the identification document. ISO3166-1 Alpha-2 country code. | Optional | identification_documents: “client\_document\_id”: “string” (optional) “type”: “enum” (required) “description”: “string” (required if type = other) “identification\_number”: “string” (required) “expiration\_date”: “datetime” (optional) “issuing\_state”: “string” (optional) “issuing\_country”: “string” (required) Possible type for different customers are the following: For individual customer, possible type are: drivers_licensestate_or_provincial_idpassportpermanent_residency_idmilitary_idnational_idmatriculate_idotherNote that national_id and matriculate_id are not applicable for us_entity. For business customer, possible type are: tax_certificatetax_returnspartnership_agreementcertificate_of_good_standingformation_documentproof_of_place_on_stock_exchangeother For sole_prop customer, possible type are: tax_certificatetax_returnsname_certificatedrivers_licensestate_or_provincial_idpassportpermanent_residency_idmilitary_idnational_idmatriculate_idotherNote that national_id and matriculate_id are not applicable for us_entity. Suggested Document Naming Format:<Date><UniqueIdentifier><DocumentType>_<Version>.<FileExtension> |
| additional_documents | Additional non-government documents being provided to verify customer.client_document_id: Client document ID for the identification document. This should be the full file name of the document delivered in the SFTP directory.type: Customer’s type of additional documents (non identification document) for customer verification.description: Description about the identification document. Required if additional document type is other. | Optional | additional_documents: “client_document_id”: “string” (optional) “type”: “enum” (required) “description”: “string” (required if document_type = other) Possible values for type are:bank_statementutility_billsproof_of_addressinvestigation_reportfinancial_statementpublic_recordsadverse_mediaid_selfieotherSuggested Document Naming Format: <Date><UniqueIdentifier><DocumentType>_<Version>.<FileExtension> |
| risk_score | The customer’s risk score, mapped to Lead by the client. Client should have provided risk score mapping to Lead. | Optional | enum:lowmediumhigh |
| rfi_result | Result of request for information with the end customer. Leave blank if RFI has not been sent to the customer. | Required if any of the RFI fields are present | enum:requestedcompleted |
| rfi_requested_at | Date time RFI is requested at. | Required if any of the RFI fields are present | datetime ISO8601 |
| ofac_result | OFAC result. | Required if any of the ofac fields are present | enumpendingpassedfailed |
| ofac_screened_at | Date time OFAC screen is screened at. | Required if any of the ofac fields are present | datetime ISO8601 |
| kyc_result | KYC result. | Required if any of the kyc fields are present | enumpendingpassedfailed |
| kyc_screened_at | Datetime KYC screen is performed. | Required if any of the kyc fields are present | datetime ISO8601 |
| credit_pulled_at | Date time credit is pulled at. | Required if any of the credit fields are present | datetime ISO8601 |
| credit_score | Credit score given by the credit bureau. Cannot be above 850. Mutually exclusive with credit_report_non_score_value. | Required if any of the credit fields are present and credit_report_non_score_value is not provided | number integer |
| credit_report_non_score_value | Indicates the state of a credit file when a numeric score is not available. Mutually exclusive with credit_score. | Required if any of the credit fields are present and credit_score is not provided | enumunestablishedfrozen |
| credit_report_source | The name of the credit bureau. | Required if any of the credit fields are present | enumequifaxexperiantransunion |
| generated_at | The day this file is generated. This should always be the date the file is sent to Lead Bank. | Required | datetime ISO8601 |
| effective_at | The timestamp of when the related object(s) were polled to collect the information for this record. | Required | datetime ISO8601 |