> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lead.bank/llms.txt
> Use this file to discover all available pages before exploring further.
# Customer File Schema
> Field-level reference for the Customer file, including individual and business customer identification, tax IDs, addresses, and KYC requirements.
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:
`individual`
`business`
`sole_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](/api-integrations/entity/roles) for more details. | Optional | array of enum:
`authorized_user`
`authorized_signer`
`account_holder` For customer\_type = individual, all of `authorized_user`, `authorized_signer`, `account_holder` allowed
For 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 | date
`YYYY-MM-DD` |
| occupation | Occupation or job. | Optional | string |
| business\_type | Business types based on `customer_types` | Required if `customer_type` = `business`, `sole_prop` | enum:
`corporation`
`partnership`
`sole_prop`
`llc`
`trust`
`cooperative`
`otherindividual` = N/A `business` = `corporation`, `partnership`, `sole_prop`, `llc`, `trust`, `cooperative`, `other`
`sole_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](https://www.census.gov/naics/?58967?yearbck=2022) for the applicable industries. 2-6 digits of NAICS codes are accepted. | Required if `customer_type` = `business`, `sole_prop` | array of enum
\[11, 111140] |
| email | 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](https://en.wikipedia.org/wiki/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:
`ssn`
`ein`
`itin` 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_license`
`state_or_provincial_id`
`passport`
`permanent_residency_id`
`military_id`
`national_id`
`matriculate_id`
`other`
Note that `national_id` and `matriculate_id` are not applicable for us\_entity.
For `business` customer, possible `type` are:
`tax_certificate`
`tax_returns`
`partnership_agreement`
`certificate_of_good_standing`
`formation_document`
`proof_of_place_on_stock_exchange`
`other` For `sole_prop` customer, possible `type` are:
`tax_certificate`
`tax_returns`
`name_certificate`
`drivers_license`
`state_or_provincial_id`
`passport`
`permanent_residency_id`
`military_id`
`national_id`
`matriculate_id`
`other`
Note that `national_id` and `matriculate_id` are not applicable for us\_entity. **Suggested Document Naming Format:**
\*\*\\_\.\ |
| 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_statement`
`utility_bills`
`proof_of_address`
`investigation_report`
`financial_statement`
`public_records`
`adverse_media`
`id_selfie`
`other`
**Suggested Document Naming Format:**
\*\*\\_\.\ |
| risk\_score | The customer's risk score, mapped to Lead by the client. Client should have provided risk score mapping to Lead. | Optional | enum:
`low`
`medium`
`high` |
| 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:
`requested`
`completed` |
| 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 | enum
`pending`
`passed`
`failed` |
| 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 | enum
`pending`
`passed`
`failed` |
| 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 | enum
`unestablished`
`frozen` |
| credit\_report\_source | The name of the credit bureau. | Required if any of the credit fields are present | enum
`equifax`
`experian`
`transunion` |
| 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 |