--- title: "Create an entity" method: POST path: "/v2/entities" tags: ["Entity"] --- # Create an entity `POST /v2/entities` ## Request - Base URL: `https://api.sandbox.lead.bank` - URL: `https://api.sandbox.lead.bank/v2/entities` - Auth: HTTP bearer Create an `individual`, `business`, or `sole_prop` Entity. `lead` and `partner` Entities are provisioned by Lead and cannot be created, so a `POST` with either type returns `422 parameters_invalid`. Each entry in `identification_documents` and `additional_documents` takes a `file_id` from `POST /v2/files` or a declared `type`, not both. ## Headers - `Idempotency-Key` string, required ## Request body - union - CreateAnIndividualEntityRequestBodyV2: Lead ignores fields not listed here. - `type` string, required: Type of entity = individual. - `intended_eligibility` EligibilityRelationshipType[]: The relationship types you intend this entity to hold. When you send it, Lead checks the entity's data against every listed type and rejects the request with `422 parameters_invalid` if any fails. The check is all or nothing, and the error returns every failing check, not just the first. Listing fewer types than the entity qualifies for still succeeds, and `eligibility` shows everything it qualifies for. If the check passes, Lead saves the list and returns it on the entity. On a `PATCH`, Lead checks the entity as it would be after the update, against the list you send or, if you leave the field out, the saved list. Send an empty array to clear the saved list; no check runs. - `risk_score` 'low' | 'medium' | 'high': The entity's risk score, mapped to Lead by the client. Client should have provided risk score mapping to Lead. - `individual_details` IndividualDetailsV2, required: Details for the individual entity. An `authorized_user` requires only `first_name`, `last_name`, a contact method, and `identification_details.type`. Other relationship types require more; see [Eligibility](https://docs.lead.bank/v2/products/entity/eligibility). - `first_name` string, required: Legal first name, as your customer gave it. Non-Latin characters are accepted. - `preferred_first_name` string: Preferred first name. - `middle_name` string: Middle name. - `last_name` string, required: Legal last name, as your customer gave it. Non-Latin characters are accepted. - `date_of_birth` string, date: Date of birth, in YYYY-MM-DD format. `account_holder` and `authorized_signer` require age 18 or older. `minor_account_holder` requires age 16 or 17. - `occupation` string: Occupation / job. - `contact_methods` ContactMethod[] - union - object - `type` string, required: ContactMethodType = email. - `email` string, required: Must be a valid email address in the form `local-part@domain.tld`. The domain must contain at least one dot. Addresses using `localhost`, IP literals (e.g., user@[127.0.0.1]), or quoted local parts (e.g., "user"@example.com) are not accepted. Only common, real-world email formats are supported. - object - `type` string, required: ContactMethodType = phone_number. Conforms to E.123 standard - `phone_number` string, required: Primary phone number of the entity. Must follow E.123 format. - `address_details` AddressDetails - `physical_address` Address - `line_1` string, required: Address line 1 is the required primary street-address field. It must contain the full base address needed to identify the physical location, such as the street number and street name together, or the closest local equivalent in countries where addresses do not use that exact structure. Use address line 1 for all core location details that describe the main property or thoroughfare. Regardless of how each component of an address is collected from your end-users, they must be combined into address line 1 before sending to Lead. Do not: - split the primary street address across line 1 and line 2 - put only the street number in line 1 and the street name in line 2 - pad line 1 with false or altered data just to satisfy validation - `line_2` string: Address line 2 is optional and should be used only for secondary or sub-premise information, such as: - apartment - unit - suite - floor - building - care-of / attention If there is no secondary or sub-premise information, address line 2 should be blank. Do not use address line 2 for any part of the primary street address. - `city` string, required: City. - `postal_code` string: Postal Code, required for US addresses. Please follow the following format: US: ^\d5(?:-\d4)?$, CN: ^\d6$, GB: ^[A-Z]{1,2}d[A-Z0-9]? ?d[A-Z]{2}$, JP: ^\d3-\d4$ - `state` string: State. required for US addresses in 2 character code (e.g. NY). - `country` string, required: ISO3166-1 Alpha-2 country code. - `mailing_address` Address - `line_1` string, required: Address line 1 is the required primary street-address field. It must contain the full base address needed to identify the physical location, such as the street number and street name together, or the closest local equivalent in countries where addresses do not use that exact structure. Use address line 1 for all core location details that describe the main property or thoroughfare. Regardless of how each component of an address is collected from your end-users, they must be combined into address line 1 before sending to Lead. Do not: - split the primary street address across line 1 and line 2 - put only the street number in line 1 and the street name in line 2 - pad line 1 with false or altered data just to satisfy validation - `line_2` string: Address line 2 is optional and should be used only for secondary or sub-premise information, such as: - apartment - unit - suite - floor - building - care-of / attention If there is no secondary or sub-premise information, address line 2 should be blank. Do not use address line 2 for any part of the primary street address. - `city` string, required: City. - `postal_code` string: Postal Code, required for US addresses. Please follow the following format: US: ^\d5(?:-\d4)?$, CN: ^\d6$, GB: ^[A-Z]{1,2}d[A-Z0-9]? ?d[A-Z]{2}$, JP: ^\d3-\d4$ - `state` string: State. required for US addresses in 2 character code (e.g. NY). - `country` string, required: ISO3166-1 Alpha-2 country code. - `other_addresses` Address[]: Other addresses for the entity. - `line_1` string, required: Address line 1 is the required primary street-address field. It must contain the full base address needed to identify the physical location, such as the street number and street name together, or the closest local equivalent in countries where addresses do not use that exact structure. Use address line 1 for all core location details that describe the main property or thoroughfare. Regardless of how each component of an address is collected from your end-users, they must be combined into address line 1 before sending to Lead. Do not: - split the primary street address across line 1 and line 2 - put only the street number in line 1 and the street name in line 2 - pad line 1 with false or altered data just to satisfy validation - `line_2` string: Address line 2 is optional and should be used only for secondary or sub-premise information, such as: - apartment - unit - suite - floor - building - care-of / attention If there is no secondary or sub-premise information, address line 2 should be blank. Do not use address line 2 for any part of the primary street address. - `city` string, required: City. - `postal_code` string: Postal Code, required for US addresses. Please follow the following format: US: ^\d5(?:-\d4)?$, CN: ^\d6$, GB: ^[A-Z]{1,2}d[A-Z0-9]? ?d[A-Z]{2}$, JP: ^\d3-\d4$ - `state` string: State. required for US addresses in 2 character code (e.g. NY). - `country` string, required: ISO3166-1 Alpha-2 country code. - `identification_details` union, required: Required on every individual; only `type` is required inside it. `tax_identification` is required for a `us_entity` holding the `account_holder`, `minor_account_holder`, or `authorized_signer` relationship type, and for beneficial owners, control persons, and sole proprietors. It is not required for an `authorized_user`. A `non_us_entity` needs at least one `identification_documents` entry for the same relationship types; on an entity created on v0, `legacy_identification_documents` entries count. - object - `type` string, required: Use `us_entity` for an entity with US tax identification, including one you have not collected yet. `tax_identification` is required for an `account_holder`, `minor_account_holder`, or `authorized_signer`, and for beneficial owners, control persons, and sole proprietors. It is not required for an `authorized_user`. Include other government-verified identification documents in `identification_documents` when collected. - `tax_identification` TaxIdentification: The entity's own US tax identification. Do not submit another person's SSN or ITIN (e.g. a parent's for a minor). If you have not collected it, omit `tax_identification`; `type` without a valid `value` is rejected. See https://docs.lead.bank/products/entity/entity-object#identification-for-us-and-non-us-entities. - `type` 'ssn' | 'itin' | 'ein', required: The entity's US tax identification type: `ssn`, `itin`, or `ein`. - For `individual` entity, use SSN or ITIN. - For `business` entity, use EIN. For single-member LLC entities where no EIN is available, SSN or ITIN may be used. - For `sole_prop` entity, use SSN, ITIN, or EIN. - `value` string, required: The entity's US tax identification number. Must be 9 digits (e.g. XXXXXXXXX). An SSN must not start with 9. An EIN must begin with a number between 00 and 99. An ITIN must begin with 9. Required whenever `tax_identification` is sent; omit the whole object if you have not collected the tax identification. - `identification_documents` IdentificationDocumentV2[]: Government-issued identification, one entry per document. Each entry takes `file_id` or `type`, not both. A supplied array replaces the whole array, and Lead re-checks every `file_id` in it. Changing documents does not need a new KYC attestation. - `file_id` string: A file ID from `POST /v2/files`. Send `file_id` or `type`, not both. When you send only a `file_id`, Lead determines the document type from the file. Retrieve that type with `GET /v2/files/{id}`. The file must exist, belong to your program, and have a type this entry accepts. Send each `file_id` only once per entity. You can still link several files of the same type, and link one file to other entities. - `type` 'drivers_license' | 'state_id' | 'provincial_id' | 'passport' | 'permanent_residency_id' | 'national_id' | 'consular_id' | 'military_id' | 'tax_certificate' | 'tax_return' | 'partnership_agreement' | 'certificate_of_good_standing' | 'formation_document' | 'proof_of_place_on_stock_exchange' | 'name_certificate': The identification document type, when you do not link a file. Send `file_id` or `type`, not both. - For an `individual`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`. - For a `business`: `tax_certificate`, `tax_return`, `partnership_agreement`, `certificate_of_good_standing`, `formation_document`, `proof_of_place_on_stock_exchange`. - For a `sole_prop`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`, `tax_certificate`, `tax_return`, `name_certificate`. - `identification_number` string, required: The number on the document. - `issuing_country` string, required: Issuing country, as an ISO 3166-1 alpha-2 code. - `issuing_state` string: Issuing state, as a two-letter code. When `issuing_country` is `US`, it must be a valid US state. - `expiration_date` string, date: Expiration date, in YYYY-MM-DD format. Cannot be in the past when you create the entity. - object - `type` string, required: Use `non_us_entity` for an entity without US tax identification. At least one government-verified document in `identification_documents` is required for an `account_holder`, `minor_account_holder`, or `authorized_signer`, and for beneficial owners, control persons, and sole proprietors. It is not required for an `authorized_user`. - `identification_documents` IdentificationDocumentV2[]: Government-issued identification, one entry per document. Each entry takes `file_id` or `type`, not both. A supplied array replaces the whole array, and Lead re-checks every `file_id` in it. Changing documents does not need a new KYC attestation. - `file_id` string: A file ID from `POST /v2/files`. Send `file_id` or `type`, not both. When you send only a `file_id`, Lead determines the document type from the file. Retrieve that type with `GET /v2/files/{id}`. The file must exist, belong to your program, and have a type this entry accepts. Send each `file_id` only once per entity. You can still link several files of the same type, and link one file to other entities. - `type` 'drivers_license' | 'state_id' | 'provincial_id' | 'passport' | 'permanent_residency_id' | 'national_id' | 'consular_id' | 'military_id' | 'tax_certificate' | 'tax_return' | 'partnership_agreement' | 'certificate_of_good_standing' | 'formation_document' | 'proof_of_place_on_stock_exchange' | 'name_certificate': The identification document type, when you do not link a file. Send `file_id` or `type`, not both. - For an `individual`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`. - For a `business`: `tax_certificate`, `tax_return`, `partnership_agreement`, `certificate_of_good_standing`, `formation_document`, `proof_of_place_on_stock_exchange`. - For a `sole_prop`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`, `tax_certificate`, `tax_return`, `name_certificate`. - `identification_number` string, required: The number on the document. - `issuing_country` string, required: Issuing country, as an ISO 3166-1 alpha-2 code. - `issuing_state` string: Issuing state, as a two-letter code. When `issuing_country` is `US`, it must be a valid US state. - `expiration_date` string, date: Expiration date, in YYYY-MM-DD format. Cannot be in the past when you create the entity. - `additional_documents` AdditionalDocumentV2[]: Supporting documents, one entry per document. Each entry takes `file_id` or `type`, not both. A supplied array replaces the whole array, and Lead re-checks every `file_id` in it. Changing documents does not need a new KYC attestation. - `file_id` string: A file ID from `POST /v2/files`. Send `file_id` or `type`, not both. When you send only a `file_id`, Lead determines the document type from the file. Retrieve that type with `GET /v2/files/{id}`. The file must exist, belong to your program, and have a type this entry accepts. Send each `file_id` only once per entity. You can still link several files of the same type, and link one file to other entities. - `type` 'proof_of_address' | 'investigation_report' | 'financial_statement' | 'public_record' | 'adverse_media' | 'id_selfie' | 'source_of_wealth' | 'social_security_card': The supporting document type, when you do not link a file. Send `file_id` or `type`, not both. - `rfi_details` RfiDetails - `result` 'requested' | 'completed', required: Result of request for information with the end customer. Leave blank if RFI has not been sent to the customer. - `requested_at` string, date-time, required: Date time RFI is requested at. - `ofac_details` OfacDetails: Details on OFAC on the entity. - `result` 'pending' | 'passed' | 'failed', required: OFAC result. Possible values: pending | passed | failed. - `screened_at` string, date-time, required: Date time OFAC screen is screened at. - `kyc_details` KycDetails: Details on KYC on the entity. - `result` 'pending' | 'passed' | 'failed', required: KYC result. Possible values: pending | passed | failed. - `screened_at` string, date-time, required: Date time KYC screen is screened at. - `credit_details` CreditDetails[] - `credit_score` string: Credit score given by the credit bureau. Cannot be above 850. Mutually exclusive with `credit_report_non_score_value`. - `credit_report_non_score_value` 'unestablished' | 'frozen': Indicates the state of a credit file when a numeric score is not available. - `credit_report_source` 'equifax' | 'experian' | 'transunion', required: The name of the credit bureau. - `credit_pulled_at` string, date-time, required: Date time credit is pulled at. - `metadata` Metadata: A set of key-value pairs that can be used to store additional information related to this object. - CreateABusinessEntityRequestBodyV2: Lead ignores fields not listed here. - `type` string, required: Type of entity = business. - `intended_eligibility` EligibilityRelationshipType[]: The relationship types you intend this entity to hold. When you send it, Lead checks the entity's data against every listed type and rejects the request with `422 parameters_invalid` if any fails. The check is all or nothing, and the error returns every failing check, not just the first. Listing fewer types than the entity qualifies for still succeeds, and `eligibility` shows everything it qualifies for. If the check passes, Lead saves the list and returns it on the entity. On a `PATCH`, Lead checks the entity as it would be after the update, against the list you send or, if you leave the field out, the saved list. Send an empty array to clear the saved list; no check runs. - `risk_score` 'low' | 'medium' | 'high': The entity's risk score, mapped to Lead by the client. Client should have provided risk score mapping to Lead. - `business_details` BusinessDetailsV2, required: Details for the business entity. - `type` 'corporation' | 'partnership' | 'sole_prop' | 'llc' | 'trust' | 'cooperative' | 'other': Business Types. Possible business types are `corporation`, `partnership`, `sole_prop`, `llc`, `trust`, `cooperative`, `other`. - For business entity, cannot use `sole_prop` as business type. - For sole_prop entity, must use `sole_prop` as business type. - `name` string, required: Legal name of the business. Must be at least 2 characters. - `gross_annual_revenue` string: Business gross revenue for prior fiscal year. - `currency_code` string: A three-letter currency code as defined in ISO 4217. - `industry` string[]: NAICS code(s) for the applicable industries. 2-6 digits of NAICS code(s) are accepted and valid NAICS codes can be found on naics.com/search. Please refer to 2022 NAICS Reference Files. - `doing_business_as` string: Business name if the business operates under a different name. - `website` string: The website of the business. Must start with http:// or https://. - `contact_methods` ContactMethod[] - union - object - `type` string, required: ContactMethodType = email. - `email` string, required: Must be a valid email address in the form `local-part@domain.tld`. The domain must contain at least one dot. Addresses using `localhost`, IP literals (e.g., user@[127.0.0.1]), or quoted local parts (e.g., "user"@example.com) are not accepted. Only common, real-world email formats are supported. - object - `type` string, required: ContactMethodType = phone_number. Conforms to E.123 standard - `phone_number` string, required: Primary phone number of the entity. Must follow E.123 format. - `address_details` AddressDetails, required - `physical_address` Address - `line_1` string, required: Address line 1 is the required primary street-address field. It must contain the full base address needed to identify the physical location, such as the street number and street name together, or the closest local equivalent in countries where addresses do not use that exact structure. Use address line 1 for all core location details that describe the main property or thoroughfare. Regardless of how each component of an address is collected from your end-users, they must be combined into address line 1 before sending to Lead. Do not: - split the primary street address across line 1 and line 2 - put only the street number in line 1 and the street name in line 2 - pad line 1 with false or altered data just to satisfy validation - `line_2` string: Address line 2 is optional and should be used only for secondary or sub-premise information, such as: - apartment - unit - suite - floor - building - care-of / attention If there is no secondary or sub-premise information, address line 2 should be blank. Do not use address line 2 for any part of the primary street address. - `city` string, required: City. - `postal_code` string: Postal Code, required for US addresses. Please follow the following format: US: ^\d5(?:-\d4)?$, CN: ^\d6$, GB: ^[A-Z]{1,2}d[A-Z0-9]? ?d[A-Z]{2}$, JP: ^\d3-\d4$ - `state` string: State. required for US addresses in 2 character code (e.g. NY). - `country` string, required: ISO3166-1 Alpha-2 country code. - `mailing_address` Address - `line_1` string, required: Address line 1 is the required primary street-address field. It must contain the full base address needed to identify the physical location, such as the street number and street name together, or the closest local equivalent in countries where addresses do not use that exact structure. Use address line 1 for all core location details that describe the main property or thoroughfare. Regardless of how each component of an address is collected from your end-users, they must be combined into address line 1 before sending to Lead. Do not: - split the primary street address across line 1 and line 2 - put only the street number in line 1 and the street name in line 2 - pad line 1 with false or altered data just to satisfy validation - `line_2` string: Address line 2 is optional and should be used only for secondary or sub-premise information, such as: - apartment - unit - suite - floor - building - care-of / attention If there is no secondary or sub-premise information, address line 2 should be blank. Do not use address line 2 for any part of the primary street address. - `city` string, required: City. - `postal_code` string: Postal Code, required for US addresses. Please follow the following format: US: ^\d5(?:-\d4)?$, CN: ^\d6$, GB: ^[A-Z]{1,2}d[A-Z0-9]? ?d[A-Z]{2}$, JP: ^\d3-\d4$ - `state` string: State. required for US addresses in 2 character code (e.g. NY). - `country` string, required: ISO3166-1 Alpha-2 country code. - `other_addresses` Address[]: Other addresses for the entity. - `line_1` string, required: Address line 1 is the required primary street-address field. It must contain the full base address needed to identify the physical location, such as the street number and street name together, or the closest local equivalent in countries where addresses do not use that exact structure. Use address line 1 for all core location details that describe the main property or thoroughfare. Regardless of how each component of an address is collected from your end-users, they must be combined into address line 1 before sending to Lead. Do not: - split the primary street address across line 1 and line 2 - put only the street number in line 1 and the street name in line 2 - pad line 1 with false or altered data just to satisfy validation - `line_2` string: Address line 2 is optional and should be used only for secondary or sub-premise information, such as: - apartment - unit - suite - floor - building - care-of / attention If there is no secondary or sub-premise information, address line 2 should be blank. Do not use address line 2 for any part of the primary street address. - `city` string, required: City. - `postal_code` string: Postal Code, required for US addresses. Please follow the following format: US: ^\d5(?:-\d4)?$, CN: ^\d6$, GB: ^[A-Z]{1,2}d[A-Z0-9]? ?d[A-Z]{2}$, JP: ^\d3-\d4$ - `state` string: State. required for US addresses in 2 character code (e.g. NY). - `country` string, required: ISO3166-1 Alpha-2 country code. - `identification_details` union, required - object - `type` string, required: Use `us_entity` for an entity with US tax identification, including one you have not collected yet. `tax_identification` is required for an `account_holder`, `minor_account_holder`, or `authorized_signer`, and for beneficial owners, control persons, and sole proprietors. It is not required for an `authorized_user`. Include other government-verified identification documents in `identification_documents` when collected. - `tax_identification` TaxIdentification: The entity's own US tax identification. Do not submit another person's SSN or ITIN (e.g. a parent's for a minor). If you have not collected it, omit `tax_identification`; `type` without a valid `value` is rejected. See https://docs.lead.bank/products/entity/entity-object#identification-for-us-and-non-us-entities. - `type` 'ssn' | 'itin' | 'ein', required: The entity's US tax identification type: `ssn`, `itin`, or `ein`. - For `individual` entity, use SSN or ITIN. - For `business` entity, use EIN. For single-member LLC entities where no EIN is available, SSN or ITIN may be used. - For `sole_prop` entity, use SSN, ITIN, or EIN. - `value` string, required: The entity's US tax identification number. Must be 9 digits (e.g. XXXXXXXXX). An SSN must not start with 9. An EIN must begin with a number between 00 and 99. An ITIN must begin with 9. Required whenever `tax_identification` is sent; omit the whole object if you have not collected the tax identification. - `identification_documents` IdentificationDocumentV2[]: Government-issued identification, one entry per document. Each entry takes `file_id` or `type`, not both. A supplied array replaces the whole array, and Lead re-checks every `file_id` in it. Changing documents does not need a new KYC attestation. - `file_id` string: A file ID from `POST /v2/files`. Send `file_id` or `type`, not both. When you send only a `file_id`, Lead determines the document type from the file. Retrieve that type with `GET /v2/files/{id}`. The file must exist, belong to your program, and have a type this entry accepts. Send each `file_id` only once per entity. You can still link several files of the same type, and link one file to other entities. - `type` 'drivers_license' | 'state_id' | 'provincial_id' | 'passport' | 'permanent_residency_id' | 'national_id' | 'consular_id' | 'military_id' | 'tax_certificate' | 'tax_return' | 'partnership_agreement' | 'certificate_of_good_standing' | 'formation_document' | 'proof_of_place_on_stock_exchange' | 'name_certificate': The identification document type, when you do not link a file. Send `file_id` or `type`, not both. - For an `individual`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`. - For a `business`: `tax_certificate`, `tax_return`, `partnership_agreement`, `certificate_of_good_standing`, `formation_document`, `proof_of_place_on_stock_exchange`. - For a `sole_prop`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`, `tax_certificate`, `tax_return`, `name_certificate`. - `identification_number` string, required: The number on the document. - `issuing_country` string, required: Issuing country, as an ISO 3166-1 alpha-2 code. - `issuing_state` string: Issuing state, as a two-letter code. When `issuing_country` is `US`, it must be a valid US state. - `expiration_date` string, date: Expiration date, in YYYY-MM-DD format. Cannot be in the past when you create the entity. - object - `type` string, required: Use `non_us_entity` for an entity without US tax identification. At least one government-verified document in `identification_documents` is required for an `account_holder`, `minor_account_holder`, or `authorized_signer`, and for beneficial owners, control persons, and sole proprietors. It is not required for an `authorized_user`. - `identification_documents` IdentificationDocumentV2[]: Government-issued identification, one entry per document. Each entry takes `file_id` or `type`, not both. A supplied array replaces the whole array, and Lead re-checks every `file_id` in it. Changing documents does not need a new KYC attestation. - `file_id` string: A file ID from `POST /v2/files`. Send `file_id` or `type`, not both. When you send only a `file_id`, Lead determines the document type from the file. Retrieve that type with `GET /v2/files/{id}`. The file must exist, belong to your program, and have a type this entry accepts. Send each `file_id` only once per entity. You can still link several files of the same type, and link one file to other entities. - `type` 'drivers_license' | 'state_id' | 'provincial_id' | 'passport' | 'permanent_residency_id' | 'national_id' | 'consular_id' | 'military_id' | 'tax_certificate' | 'tax_return' | 'partnership_agreement' | 'certificate_of_good_standing' | 'formation_document' | 'proof_of_place_on_stock_exchange' | 'name_certificate': The identification document type, when you do not link a file. Send `file_id` or `type`, not both. - For an `individual`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`. - For a `business`: `tax_certificate`, `tax_return`, `partnership_agreement`, `certificate_of_good_standing`, `formation_document`, `proof_of_place_on_stock_exchange`. - For a `sole_prop`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`, `tax_certificate`, `tax_return`, `name_certificate`. - `identification_number` string, required: The number on the document. - `issuing_country` string, required: Issuing country, as an ISO 3166-1 alpha-2 code. - `issuing_state` string: Issuing state, as a two-letter code. When `issuing_country` is `US`, it must be a valid US state. - `expiration_date` string, date: Expiration date, in YYYY-MM-DD format. Cannot be in the past when you create the entity. - `additional_documents` AdditionalDocumentV2[]: Supporting documents, one entry per document. Each entry takes `file_id` or `type`, not both. A supplied array replaces the whole array, and Lead re-checks every `file_id` in it. Changing documents does not need a new KYC attestation. - `file_id` string: A file ID from `POST /v2/files`. Send `file_id` or `type`, not both. When you send only a `file_id`, Lead determines the document type from the file. Retrieve that type with `GET /v2/files/{id}`. The file must exist, belong to your program, and have a type this entry accepts. Send each `file_id` only once per entity. You can still link several files of the same type, and link one file to other entities. - `type` 'proof_of_address' | 'investigation_report' | 'financial_statement' | 'public_record' | 'adverse_media' | 'id_selfie' | 'source_of_wealth' | 'social_security_card': The supporting document type, when you do not link a file. Send `file_id` or `type`, not both. - `beneficial_owners` BeneficialOwnersV2[] - `entity_id` string, required: The `entity_id` of the individual entity for this beneficial owner. Data requirements for beneficial owners match those of an `authorized_signer`. - `ownership_percentage` string: Percentage of the business this person owns, from 0 to 100 with up to two decimal places. For example, `25.5` means 25.5%. The percentages of all beneficial owners must add up to 100 or less. - `relationship_established_at` string, date: The date the relationship was established. - `control_persons` ControlPersons[] - `entity_id` string, required: Individual entity_id created for the control person. Data requirements for control persons match those of an `authorized_signer`. - `title` string, required: The title of this control person. - `relationship_established_at` string, date: The date the relationship was established. - `rfi_details` RfiDetails - `result` 'requested' | 'completed', required: Result of request for information with the end customer. Leave blank if RFI has not been sent to the customer. - `requested_at` string, date-time, required: Date time RFI is requested at. - `ofac_details` OfacDetails: Details on OFAC on the entity. - `result` 'pending' | 'passed' | 'failed', required: OFAC result. Possible values: pending | passed | failed. - `screened_at` string, date-time, required: Date time OFAC screen is screened at. - `kyc_details` KycDetails: Details on KYC on the entity. - `result` 'pending' | 'passed' | 'failed', required: KYC result. Possible values: pending | passed | failed. - `screened_at` string, date-time, required: Date time KYC screen is screened at. - `credit_details` CreditDetails[] - `credit_score` string: Credit score given by the credit bureau. Cannot be above 850. Mutually exclusive with `credit_report_non_score_value`. - `credit_report_non_score_value` 'unestablished' | 'frozen': Indicates the state of a credit file when a numeric score is not available. - `credit_report_source` 'equifax' | 'experian' | 'transunion', required: The name of the credit bureau. - `credit_pulled_at` string, date-time, required: Date time credit is pulled at. - `metadata` Metadata: A set of key-value pairs that can be used to store additional information related to this object. - CreateASolePropEntityRequestBodyV2: Lead ignores fields not listed here. - `type` string, required: Type of entity = sole_prop. - `intended_eligibility` EligibilityRelationshipType[]: The relationship types you intend this entity to hold. When you send it, Lead checks the entity's data against every listed type and rejects the request with `422 parameters_invalid` if any fails. The check is all or nothing, and the error returns every failing check, not just the first. Listing fewer types than the entity qualifies for still succeeds, and `eligibility` shows everything it qualifies for. If the check passes, Lead saves the list and returns it on the entity. On a `PATCH`, Lead checks the entity as it would be after the update, against the list you send or, if you leave the field out, the saved list. Send an empty array to clear the saved list; no check runs. - `risk_score` 'low' | 'medium' | 'high': The entity's risk score, mapped to Lead by the client. Client should have provided risk score mapping to Lead. - `business_details` BusinessDetailsV2, required: Details for the business entity. - `type` 'corporation' | 'partnership' | 'sole_prop' | 'llc' | 'trust' | 'cooperative' | 'other': Business Types. Possible business types are `corporation`, `partnership`, `sole_prop`, `llc`, `trust`, `cooperative`, `other`. - For business entity, cannot use `sole_prop` as business type. - For sole_prop entity, must use `sole_prop` as business type. - `name` string, required: Legal name of the business. Must be at least 2 characters. - `gross_annual_revenue` string: Business gross revenue for prior fiscal year. - `currency_code` string: A three-letter currency code as defined in ISO 4217. - `industry` string[]: NAICS code(s) for the applicable industries. 2-6 digits of NAICS code(s) are accepted and valid NAICS codes can be found on naics.com/search. Please refer to 2022 NAICS Reference Files. - `doing_business_as` string: Business name if the business operates under a different name. - `website` string: The website of the business. Must start with http:// or https://. - `contact_methods` ContactMethod[] - union - object - `type` string, required: ContactMethodType = email. - `email` string, required: Must be a valid email address in the form `local-part@domain.tld`. The domain must contain at least one dot. Addresses using `localhost`, IP literals (e.g., user@[127.0.0.1]), or quoted local parts (e.g., "user"@example.com) are not accepted. Only common, real-world email formats are supported. - object - `type` string, required: ContactMethodType = phone_number. Conforms to E.123 standard - `phone_number` string, required: Primary phone number of the entity. Must follow E.123 format. - `address_details` AddressDetails, required - `physical_address` Address - `line_1` string, required: Address line 1 is the required primary street-address field. It must contain the full base address needed to identify the physical location, such as the street number and street name together, or the closest local equivalent in countries where addresses do not use that exact structure. Use address line 1 for all core location details that describe the main property or thoroughfare. Regardless of how each component of an address is collected from your end-users, they must be combined into address line 1 before sending to Lead. Do not: - split the primary street address across line 1 and line 2 - put only the street number in line 1 and the street name in line 2 - pad line 1 with false or altered data just to satisfy validation - `line_2` string: Address line 2 is optional and should be used only for secondary or sub-premise information, such as: - apartment - unit - suite - floor - building - care-of / attention If there is no secondary or sub-premise information, address line 2 should be blank. Do not use address line 2 for any part of the primary street address. - `city` string, required: City. - `postal_code` string: Postal Code, required for US addresses. Please follow the following format: US: ^\d5(?:-\d4)?$, CN: ^\d6$, GB: ^[A-Z]{1,2}d[A-Z0-9]? ?d[A-Z]{2}$, JP: ^\d3-\d4$ - `state` string: State. required for US addresses in 2 character code (e.g. NY). - `country` string, required: ISO3166-1 Alpha-2 country code. - `mailing_address` Address - `line_1` string, required: Address line 1 is the required primary street-address field. It must contain the full base address needed to identify the physical location, such as the street number and street name together, or the closest local equivalent in countries where addresses do not use that exact structure. Use address line 1 for all core location details that describe the main property or thoroughfare. Regardless of how each component of an address is collected from your end-users, they must be combined into address line 1 before sending to Lead. Do not: - split the primary street address across line 1 and line 2 - put only the street number in line 1 and the street name in line 2 - pad line 1 with false or altered data just to satisfy validation - `line_2` string: Address line 2 is optional and should be used only for secondary or sub-premise information, such as: - apartment - unit - suite - floor - building - care-of / attention If there is no secondary or sub-premise information, address line 2 should be blank. Do not use address line 2 for any part of the primary street address. - `city` string, required: City. - `postal_code` string: Postal Code, required for US addresses. Please follow the following format: US: ^\d5(?:-\d4)?$, CN: ^\d6$, GB: ^[A-Z]{1,2}d[A-Z0-9]? ?d[A-Z]{2}$, JP: ^\d3-\d4$ - `state` string: State. required for US addresses in 2 character code (e.g. NY). - `country` string, required: ISO3166-1 Alpha-2 country code. - `other_addresses` Address[]: Other addresses for the entity. - `line_1` string, required: Address line 1 is the required primary street-address field. It must contain the full base address needed to identify the physical location, such as the street number and street name together, or the closest local equivalent in countries where addresses do not use that exact structure. Use address line 1 for all core location details that describe the main property or thoroughfare. Regardless of how each component of an address is collected from your end-users, they must be combined into address line 1 before sending to Lead. Do not: - split the primary street address across line 1 and line 2 - put only the street number in line 1 and the street name in line 2 - pad line 1 with false or altered data just to satisfy validation - `line_2` string: Address line 2 is optional and should be used only for secondary or sub-premise information, such as: - apartment - unit - suite - floor - building - care-of / attention If there is no secondary or sub-premise information, address line 2 should be blank. Do not use address line 2 for any part of the primary street address. - `city` string, required: City. - `postal_code` string: Postal Code, required for US addresses. Please follow the following format: US: ^\d5(?:-\d4)?$, CN: ^\d6$, GB: ^[A-Z]{1,2}d[A-Z0-9]? ?d[A-Z]{2}$, JP: ^\d3-\d4$ - `state` string: State. required for US addresses in 2 character code (e.g. NY). - `country` string, required: ISO3166-1 Alpha-2 country code. - `identification_details` union, required - object - `type` string, required: Use `us_entity` for an entity with US tax identification, including one you have not collected yet. `tax_identification` is required for an `account_holder`, `minor_account_holder`, or `authorized_signer`, and for beneficial owners, control persons, and sole proprietors. It is not required for an `authorized_user`. Include other government-verified identification documents in `identification_documents` when collected. - `tax_identification` TaxIdentification: The entity's own US tax identification. Do not submit another person's SSN or ITIN (e.g. a parent's for a minor). If you have not collected it, omit `tax_identification`; `type` without a valid `value` is rejected. See https://docs.lead.bank/products/entity/entity-object#identification-for-us-and-non-us-entities. - `type` 'ssn' | 'itin' | 'ein', required: The entity's US tax identification type: `ssn`, `itin`, or `ein`. - For `individual` entity, use SSN or ITIN. - For `business` entity, use EIN. For single-member LLC entities where no EIN is available, SSN or ITIN may be used. - For `sole_prop` entity, use SSN, ITIN, or EIN. - `value` string, required: The entity's US tax identification number. Must be 9 digits (e.g. XXXXXXXXX). An SSN must not start with 9. An EIN must begin with a number between 00 and 99. An ITIN must begin with 9. Required whenever `tax_identification` is sent; omit the whole object if you have not collected the tax identification. - `identification_documents` IdentificationDocumentV2[]: Government-issued identification, one entry per document. Each entry takes `file_id` or `type`, not both. A supplied array replaces the whole array, and Lead re-checks every `file_id` in it. Changing documents does not need a new KYC attestation. - `file_id` string: A file ID from `POST /v2/files`. Send `file_id` or `type`, not both. When you send only a `file_id`, Lead determines the document type from the file. Retrieve that type with `GET /v2/files/{id}`. The file must exist, belong to your program, and have a type this entry accepts. Send each `file_id` only once per entity. You can still link several files of the same type, and link one file to other entities. - `type` 'drivers_license' | 'state_id' | 'provincial_id' | 'passport' | 'permanent_residency_id' | 'national_id' | 'consular_id' | 'military_id' | 'tax_certificate' | 'tax_return' | 'partnership_agreement' | 'certificate_of_good_standing' | 'formation_document' | 'proof_of_place_on_stock_exchange' | 'name_certificate': The identification document type, when you do not link a file. Send `file_id` or `type`, not both. - For an `individual`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`. - For a `business`: `tax_certificate`, `tax_return`, `partnership_agreement`, `certificate_of_good_standing`, `formation_document`, `proof_of_place_on_stock_exchange`. - For a `sole_prop`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`, `tax_certificate`, `tax_return`, `name_certificate`. - `identification_number` string, required: The number on the document. - `issuing_country` string, required: Issuing country, as an ISO 3166-1 alpha-2 code. - `issuing_state` string: Issuing state, as a two-letter code. When `issuing_country` is `US`, it must be a valid US state. - `expiration_date` string, date: Expiration date, in YYYY-MM-DD format. Cannot be in the past when you create the entity. - object - `type` string, required: Use `non_us_entity` for an entity without US tax identification. At least one government-verified document in `identification_documents` is required for an `account_holder`, `minor_account_holder`, or `authorized_signer`, and for beneficial owners, control persons, and sole proprietors. It is not required for an `authorized_user`. - `identification_documents` IdentificationDocumentV2[]: Government-issued identification, one entry per document. Each entry takes `file_id` or `type`, not both. A supplied array replaces the whole array, and Lead re-checks every `file_id` in it. Changing documents does not need a new KYC attestation. - `file_id` string: A file ID from `POST /v2/files`. Send `file_id` or `type`, not both. When you send only a `file_id`, Lead determines the document type from the file. Retrieve that type with `GET /v2/files/{id}`. The file must exist, belong to your program, and have a type this entry accepts. Send each `file_id` only once per entity. You can still link several files of the same type, and link one file to other entities. - `type` 'drivers_license' | 'state_id' | 'provincial_id' | 'passport' | 'permanent_residency_id' | 'national_id' | 'consular_id' | 'military_id' | 'tax_certificate' | 'tax_return' | 'partnership_agreement' | 'certificate_of_good_standing' | 'formation_document' | 'proof_of_place_on_stock_exchange' | 'name_certificate': The identification document type, when you do not link a file. Send `file_id` or `type`, not both. - For an `individual`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`. - For a `business`: `tax_certificate`, `tax_return`, `partnership_agreement`, `certificate_of_good_standing`, `formation_document`, `proof_of_place_on_stock_exchange`. - For a `sole_prop`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`, `tax_certificate`, `tax_return`, `name_certificate`. - `identification_number` string, required: The number on the document. - `issuing_country` string, required: Issuing country, as an ISO 3166-1 alpha-2 code. - `issuing_state` string: Issuing state, as a two-letter code. When `issuing_country` is `US`, it must be a valid US state. - `expiration_date` string, date: Expiration date, in YYYY-MM-DD format. Cannot be in the past when you create the entity. - `additional_documents` AdditionalDocumentV2[]: Supporting documents, one entry per document. Each entry takes `file_id` or `type`, not both. A supplied array replaces the whole array, and Lead re-checks every `file_id` in it. Changing documents does not need a new KYC attestation. - `file_id` string: A file ID from `POST /v2/files`. Send `file_id` or `type`, not both. When you send only a `file_id`, Lead determines the document type from the file. Retrieve that type with `GET /v2/files/{id}`. The file must exist, belong to your program, and have a type this entry accepts. Send each `file_id` only once per entity. You can still link several files of the same type, and link one file to other entities. - `type` 'proof_of_address' | 'investigation_report' | 'financial_statement' | 'public_record' | 'adverse_media' | 'id_selfie' | 'source_of_wealth' | 'social_security_card': The supporting document type, when you do not link a file. Send `file_id` or `type`, not both. - `sole_proprietor` SoleProprietor, required - `entity_id` string, required: Individual entity_id created for the sole proprietor. Data requirements for sole proprietors match those of an `authorized_signer`. - `rfi_details` RfiDetails - `result` 'requested' | 'completed', required: Result of request for information with the end customer. Leave blank if RFI has not been sent to the customer. - `requested_at` string, date-time, required: Date time RFI is requested at. - `ofac_details` OfacDetails: Details on OFAC on the entity. - `result` 'pending' | 'passed' | 'failed', required: OFAC result. Possible values: pending | passed | failed. - `screened_at` string, date-time, required: Date time OFAC screen is screened at. - `kyc_details` KycDetails: Details on KYC on the entity. - `result` 'pending' | 'passed' | 'failed', required: KYC result. Possible values: pending | passed | failed. - `screened_at` string, date-time, required: Date time KYC screen is screened at. - `credit_details` CreditDetails[] - `credit_score` string: Credit score given by the credit bureau. Cannot be above 850. Mutually exclusive with `credit_report_non_score_value`. - `credit_report_non_score_value` 'unestablished' | 'frozen': Indicates the state of a credit file when a numeric score is not available. - `credit_report_source` 'equifax' | 'experian' | 'transunion', required: The name of the credit bureau. - `credit_pulled_at` string, date-time, required: Date time credit is pulled at. - `metadata` Metadata: A set of key-value pairs that can be used to store additional information related to this object. ## Response `200` Entity object created. - union - IndividualEntityV2 - `id` string, required: The ID of your entity. - `client_customer_id` string: Your customer ID, on entities created through Customer files. Response only. Lead ignores it if sent, and does not return it on entities created with `POST /v2/entities`. - `created_at` string, date-time, required: Timestamp at which the entity object is created. - `updated_at` string, date-time, required: Timestamp at which the entity object was last updated. - `type` string, required: Type of entity = individual. - `risk_score` 'low' | 'medium' | 'high': The entity's risk score, mapped to Lead by the client. Client should have provided risk score mapping to Lead. - `individual_details` IndividualDetailsResponseV2, required: Details for the individual entity. An `authorized_user` requires only `first_name`, `last_name`, a contact method, and `identification_details.type`. Other relationship types require more; see [Eligibility](https://docs.lead.bank/v2/products/entity/eligibility). - `first_name` string, required: Legal first name, as your customer gave it. Non-Latin characters are accepted. - `preferred_first_name` string: Preferred first name. - `middle_name` string: Middle name. - `last_name` string, required: Legal last name, as your customer gave it. Non-Latin characters are accepted. - `date_of_birth` string, date: Date of birth, in YYYY-MM-DD format. `account_holder` and `authorized_signer` require age 18 or older. `minor_account_holder` requires age 16 or 17. - `occupation` string: Occupation / job. - `contact_methods` ContactMethod[] - union - object - `type` string, required: ContactMethodType = email. - `email` string, required: Must be a valid email address in the form `local-part@domain.tld`. The domain must contain at least one dot. Addresses using `localhost`, IP literals (e.g., user@[127.0.0.1]), or quoted local parts (e.g., "user"@example.com) are not accepted. Only common, real-world email formats are supported. - object - `type` string, required: ContactMethodType = phone_number. Conforms to E.123 standard - `phone_number` string, required: Primary phone number of the entity. Must follow E.123 format. - `address_details` AddressDetails - `physical_address` Address - `line_1` string, required: Address line 1 is the required primary street-address field. It must contain the full base address needed to identify the physical location, such as the street number and street name together, or the closest local equivalent in countries where addresses do not use that exact structure. Use address line 1 for all core location details that describe the main property or thoroughfare. Regardless of how each component of an address is collected from your end-users, they must be combined into address line 1 before sending to Lead. Do not: - split the primary street address across line 1 and line 2 - put only the street number in line 1 and the street name in line 2 - pad line 1 with false or altered data just to satisfy validation - `line_2` string: Address line 2 is optional and should be used only for secondary or sub-premise information, such as: - apartment - unit - suite - floor - building - care-of / attention If there is no secondary or sub-premise information, address line 2 should be blank. Do not use address line 2 for any part of the primary street address. - `city` string, required: City. - `postal_code` string: Postal Code, required for US addresses. Please follow the following format: US: ^\d5(?:-\d4)?$, CN: ^\d6$, GB: ^[A-Z]{1,2}d[A-Z0-9]? ?d[A-Z]{2}$, JP: ^\d3-\d4$ - `state` string: State. required for US addresses in 2 character code (e.g. NY). - `country` string, required: ISO3166-1 Alpha-2 country code. - `mailing_address` Address - `line_1` string, required: Address line 1 is the required primary street-address field. It must contain the full base address needed to identify the physical location, such as the street number and street name together, or the closest local equivalent in countries where addresses do not use that exact structure. Use address line 1 for all core location details that describe the main property or thoroughfare. Regardless of how each component of an address is collected from your end-users, they must be combined into address line 1 before sending to Lead. Do not: - split the primary street address across line 1 and line 2 - put only the street number in line 1 and the street name in line 2 - pad line 1 with false or altered data just to satisfy validation - `line_2` string: Address line 2 is optional and should be used only for secondary or sub-premise information, such as: - apartment - unit - suite - floor - building - care-of / attention If there is no secondary or sub-premise information, address line 2 should be blank. Do not use address line 2 for any part of the primary street address. - `city` string, required: City. - `postal_code` string: Postal Code, required for US addresses. Please follow the following format: US: ^\d5(?:-\d4)?$, CN: ^\d6$, GB: ^[A-Z]{1,2}d[A-Z0-9]? ?d[A-Z]{2}$, JP: ^\d3-\d4$ - `state` string: State. required for US addresses in 2 character code (e.g. NY). - `country` string, required: ISO3166-1 Alpha-2 country code. - `other_addresses` Address[]: Other addresses for the entity. - `line_1` string, required: Address line 1 is the required primary street-address field. It must contain the full base address needed to identify the physical location, such as the street number and street name together, or the closest local equivalent in countries where addresses do not use that exact structure. Use address line 1 for all core location details that describe the main property or thoroughfare. Regardless of how each component of an address is collected from your end-users, they must be combined into address line 1 before sending to Lead. Do not: - split the primary street address across line 1 and line 2 - put only the street number in line 1 and the street name in line 2 - pad line 1 with false or altered data just to satisfy validation - `line_2` string: Address line 2 is optional and should be used only for secondary or sub-premise information, such as: - apartment - unit - suite - floor - building - care-of / attention If there is no secondary or sub-premise information, address line 2 should be blank. Do not use address line 2 for any part of the primary street address. - `city` string, required: City. - `postal_code` string: Postal Code, required for US addresses. Please follow the following format: US: ^\d5(?:-\d4)?$, CN: ^\d6$, GB: ^[A-Z]{1,2}d[A-Z0-9]? ?d[A-Z]{2}$, JP: ^\d3-\d4$ - `state` string: State. required for US addresses in 2 character code (e.g. NY). - `country` string, required: ISO3166-1 Alpha-2 country code. - `identification_details` union, required: Required on every individual; only `type` is required inside it. `tax_identification` is required for a `us_entity` holding the `account_holder`, `minor_account_holder`, or `authorized_signer` relationship type, and for beneficial owners, control persons, and sole proprietors. It is not required for an `authorized_user`. A `non_us_entity` needs at least one `identification_documents` entry for the same relationship types; on an entity created on v0, `legacy_identification_documents` entries count. - object - `type` string, required: Use `us_entity` for an entity with US tax identification, including one you have not collected yet. `tax_identification` is required for an `account_holder`, `minor_account_holder`, or `authorized_signer`, and for beneficial owners, control persons, and sole proprietors. It is not required for an `authorized_user`. Include other government-verified identification documents in `identification_documents` when collected. - `tax_identification` TaxIdentification: The entity's own US tax identification. Do not submit another person's SSN or ITIN (e.g. a parent's for a minor). If you have not collected it, omit `tax_identification`; `type` without a valid `value` is rejected. See https://docs.lead.bank/products/entity/entity-object#identification-for-us-and-non-us-entities. - `type` 'ssn' | 'itin' | 'ein', required: The entity's US tax identification type: `ssn`, `itin`, or `ein`. - For `individual` entity, use SSN or ITIN. - For `business` entity, use EIN. For single-member LLC entities where no EIN is available, SSN or ITIN may be used. - For `sole_prop` entity, use SSN, ITIN, or EIN. - `value` string, required: The entity's US tax identification number. Must be 9 digits (e.g. XXXXXXXXX). An SSN must not start with 9. An EIN must begin with a number between 00 and 99. An ITIN must begin with 9. Required whenever `tax_identification` is sent; omit the whole object if you have not collected the tax identification. - `identification_documents` IdentificationDocumentV2[]: Government-issued identification, one entry per document. Each entry takes `file_id` or `type`, not both. A supplied array replaces the whole array, and Lead re-checks every `file_id` in it. Changing documents does not need a new KYC attestation. - `file_id` string: A file ID from `POST /v2/files`. Send `file_id` or `type`, not both. When you send only a `file_id`, Lead determines the document type from the file. Retrieve that type with `GET /v2/files/{id}`. The file must exist, belong to your program, and have a type this entry accepts. Send each `file_id` only once per entity. You can still link several files of the same type, and link one file to other entities. - `type` 'drivers_license' | 'state_id' | 'provincial_id' | 'passport' | 'permanent_residency_id' | 'national_id' | 'consular_id' | 'military_id' | 'tax_certificate' | 'tax_return' | 'partnership_agreement' | 'certificate_of_good_standing' | 'formation_document' | 'proof_of_place_on_stock_exchange' | 'name_certificate': The identification document type, when you do not link a file. Send `file_id` or `type`, not both. - For an `individual`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`. - For a `business`: `tax_certificate`, `tax_return`, `partnership_agreement`, `certificate_of_good_standing`, `formation_document`, `proof_of_place_on_stock_exchange`. - For a `sole_prop`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`, `tax_certificate`, `tax_return`, `name_certificate`. - `identification_number` string, required: The number on the document. - `issuing_country` string, required: Issuing country, as an ISO 3166-1 alpha-2 code. - `issuing_state` string: Issuing state, as a two-letter code. When `issuing_country` is `US`, it must be a valid US state. - `expiration_date` string, date: Expiration date, in YYYY-MM-DD format. Cannot be in the past when you create the entity. - `legacy_identification_documents` IdentificationDocument[]: Identification document entries created on v0 Entities, returned exactly as sent. Read only: ignored if included on a POST or PATCH. - `client_document_id` string: Client document ID for the identification document. - `type` 'drivers_license' | 'state_or_provincial_id' | 'passport' | 'permanent_residency_id' | 'military_id' | 'national_id' | 'matriculate_id' | 'other' | 'tax_certificate' | 'tax_returns' | 'partnership_agreement' | 'certificate_of_good_standing' | 'formation_document' | 'proof_of_place_on_stock_exchange' | 'name_certificate', required: The entity's government-verified identification document type. This will apply for identification types other than US tax identification. - For `individual` entity, possible types 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` entity, possible types are: `tax_certificate`, `tax_returns`, `partnership_agreement`, `certificate_of_good_standing`, `formation_document`, `proof_of_place_on_stock_exchange`, `other`. - For `sole_prop` entity, possible types 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`. - `description` string: Description about the identification document. Required if identification document type is `other`. - `identification_number` string, required: Unique identification number on the identification document. - `expiration_date` string, date: Expiration date of the identification document. - `issuing_state` string: Issuing state of the identification document. Must be 2 character code (e.g. NY). If the issuing country is US, this value must be a valid US State. - `issuing_country` string, required: Issuing country of the identification document. ISO3166-1 Alpha-2 country code. - object - `type` string, required: Use `non_us_entity` for an entity without US tax identification. At least one government-verified document in `identification_documents` is required for an `account_holder`, `minor_account_holder`, or `authorized_signer`, and for beneficial owners, control persons, and sole proprietors. It is not required for an `authorized_user`. - `identification_documents` IdentificationDocumentV2[]: Government-issued identification, one entry per document. Each entry takes `file_id` or `type`, not both. A supplied array replaces the whole array, and Lead re-checks every `file_id` in it. Changing documents does not need a new KYC attestation. - `file_id` string: A file ID from `POST /v2/files`. Send `file_id` or `type`, not both. When you send only a `file_id`, Lead determines the document type from the file. Retrieve that type with `GET /v2/files/{id}`. The file must exist, belong to your program, and have a type this entry accepts. Send each `file_id` only once per entity. You can still link several files of the same type, and link one file to other entities. - `type` 'drivers_license' | 'state_id' | 'provincial_id' | 'passport' | 'permanent_residency_id' | 'national_id' | 'consular_id' | 'military_id' | 'tax_certificate' | 'tax_return' | 'partnership_agreement' | 'certificate_of_good_standing' | 'formation_document' | 'proof_of_place_on_stock_exchange' | 'name_certificate': The identification document type, when you do not link a file. Send `file_id` or `type`, not both. - For an `individual`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`. - For a `business`: `tax_certificate`, `tax_return`, `partnership_agreement`, `certificate_of_good_standing`, `formation_document`, `proof_of_place_on_stock_exchange`. - For a `sole_prop`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`, `tax_certificate`, `tax_return`, `name_certificate`. - `identification_number` string, required: The number on the document. - `issuing_country` string, required: Issuing country, as an ISO 3166-1 alpha-2 code. - `issuing_state` string: Issuing state, as a two-letter code. When `issuing_country` is `US`, it must be a valid US state. - `expiration_date` string, date: Expiration date, in YYYY-MM-DD format. Cannot be in the past when you create the entity. - `legacy_identification_documents` IdentificationDocument[]: Identification document entries created on v0 Entities, returned exactly as sent. Read only: ignored if included on a POST or PATCH. - `client_document_id` string: Client document ID for the identification document. - `type` 'drivers_license' | 'state_or_provincial_id' | 'passport' | 'permanent_residency_id' | 'military_id' | 'national_id' | 'matriculate_id' | 'other' | 'tax_certificate' | 'tax_returns' | 'partnership_agreement' | 'certificate_of_good_standing' | 'formation_document' | 'proof_of_place_on_stock_exchange' | 'name_certificate', required: The entity's government-verified identification document type. This will apply for identification types other than US tax identification. - For `individual` entity, possible types 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` entity, possible types are: `tax_certificate`, `tax_returns`, `partnership_agreement`, `certificate_of_good_standing`, `formation_document`, `proof_of_place_on_stock_exchange`, `other`. - For `sole_prop` entity, possible types 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`. - `description` string: Description about the identification document. Required if identification document type is `other`. - `identification_number` string, required: Unique identification number on the identification document. - `expiration_date` string, date: Expiration date of the identification document. - `issuing_state` string: Issuing state of the identification document. Must be 2 character code (e.g. NY). If the issuing country is US, this value must be a valid US State. - `issuing_country` string, required: Issuing country of the identification document. ISO3166-1 Alpha-2 country code. - `additional_documents` AdditionalDocumentV2[]: Supporting documents, one entry per document. Each entry takes `file_id` or `type`, not both. A supplied array replaces the whole array, and Lead re-checks every `file_id` in it. Changing documents does not need a new KYC attestation. - `file_id` string: A file ID from `POST /v2/files`. Send `file_id` or `type`, not both. When you send only a `file_id`, Lead determines the document type from the file. Retrieve that type with `GET /v2/files/{id}`. The file must exist, belong to your program, and have a type this entry accepts. Send each `file_id` only once per entity. You can still link several files of the same type, and link one file to other entities. - `type` 'proof_of_address' | 'investigation_report' | 'financial_statement' | 'public_record' | 'adverse_media' | 'id_selfie' | 'source_of_wealth' | 'social_security_card': The supporting document type, when you do not link a file. Send `file_id` or `type`, not both. - `legacy_additional_documents` AdditionalDocument[]: Additional document entries created on v0 Entities, returned exactly as sent. Read only: ignored if included on a POST or PATCH. - `client_document_id` string: Client document ID for the additional document. - `type` 'bank_statement' | 'utility_bills' | 'proof_of_address' | 'investigation_report' | 'financial_statement' | 'public_records' | 'adverse_media' | 'id_selfie' | 'other', required: Type of additional non-government documents being provided to verify entity. Possible values are `bank_statement`, `utility_bills`, `proof_of_address`, `investigation_report`, `financial_statement`, `public_records`, `adverse_media`, `id_selfie`, `other`. - `description` string: Description about the identification document. Required if additional document type is `other`. - `rfi_details` RfiDetails - `result` 'requested' | 'completed', required: Result of request for information with the end customer. Leave blank if RFI has not been sent to the customer. - `requested_at` string, date-time, required: Date time RFI is requested at. - `ofac_details` OfacDetails: Details on OFAC on the entity. - `result` 'pending' | 'passed' | 'failed', required: OFAC result. Possible values: pending | passed | failed. - `screened_at` string, date-time, required: Date time OFAC screen is screened at. - `kyc_details` KycDetails: Details on KYC on the entity. - `result` 'pending' | 'passed' | 'failed', required: KYC result. Possible values: pending | passed | failed. - `screened_at` string, date-time, required: Date time KYC screen is screened at. - `credit_details` CreditDetails[] - `credit_score` string: Credit score given by the credit bureau. Cannot be above 850. Mutually exclusive with `credit_report_non_score_value`. - `credit_report_non_score_value` 'unestablished' | 'frozen': Indicates the state of a credit file when a numeric score is not available. - `credit_report_source` 'equifax' | 'experian' | 'transunion', required: The name of the credit bureau. - `credit_pulled_at` string, date-time, required: Date time credit is pulled at. - `intended_eligibility` EligibilityRelationshipType[]: The relationship types you intend this entity to hold. When you send it, Lead checks the entity's data against every listed type and rejects the request with `422 parameters_invalid` if any fails. The check is all or nothing, and the error returns every failing check, not just the first. Listing fewer types than the entity qualifies for still succeeds, and `eligibility` shows everything it qualifies for. If the check passes, Lead saves the list and returns it on the entity. On a `PATCH`, Lead checks the entity as it would be after the update, against the list you send or, if you leave the field out, the saved list. Send an empty array to clear the saved list; no check runs. - `eligibility` EligibilityV2, required: Whether the entity's current data qualifies it for each relationship type, with the failing checks. Response only. Lead computes it from current data on every read and never stores it. All four keys are always present. On a program that does not offer minor account holders, `minor_account_holder` is `ineligible` for every entity. - `account_holder` EligibilityRelationshipV2, required - `status` 'eligible' | 'ineligible', required: Whether the entity's current data qualifies it for the relationship type. - `failed_checks` EligibilityFailedCheck[], required: The checks the entity fails for this relationship type. Empty when `status` is `eligible`. - `check` string, required: The name of the failing check. The same names appear in `422` errors for a failed `intended_eligibility` assertion. Lead may add checks, so handle names you do not recognize. Current checks: - Identity and contact: `check_first_name`, `check_last_name`, `check_date_of_birth`, `check_date_of_birth_missing`, `check_date_of_birth_below_minimum`, `check_date_of_birth_above_maximum`, `check_phone_or_email`, `check_physical_address`, `check_government_id`. - Business: `check_business_name`, `check_business_type`, `check_business_industry`, `check_control_person_exists`, `check_child_entity_not_found`. - Screening and risk: `check_kyc_status`, `check_ofac`, `check_risk_score`, `check_manual_review_status` (a manual review of the entity is pending). - Relationship type: `check_individual_entity` (only individuals can hold `minor_account_holder`, `authorized_signer`, and `authorized_user`), `check_minor_account_holder_enabled` (your program is not approved for minor account holders). - Stored data: `invalid_entity` (the entity's stored data fails Lead's current validations, which can happen to an older entity when rules change). See [Eligibility](https://docs.lead.bank/v2/products/entity/eligibility). - `entity_id` string, required: The ID of your entity. - `reason` string, required: A human-readable explanation of the failure and how to fix it. Not part of the API contract, so do not parse it. It may change without notice. - `minor_account_holder` EligibilityRelationshipV2, required - `status` 'eligible' | 'ineligible', required: Whether the entity's current data qualifies it for the relationship type. - `failed_checks` EligibilityFailedCheck[], required: The checks the entity fails for this relationship type. Empty when `status` is `eligible`. - `check` string, required: The name of the failing check. The same names appear in `422` errors for a failed `intended_eligibility` assertion. Lead may add checks, so handle names you do not recognize. Current checks: - Identity and contact: `check_first_name`, `check_last_name`, `check_date_of_birth`, `check_date_of_birth_missing`, `check_date_of_birth_below_minimum`, `check_date_of_birth_above_maximum`, `check_phone_or_email`, `check_physical_address`, `check_government_id`. - Business: `check_business_name`, `check_business_type`, `check_business_industry`, `check_control_person_exists`, `check_child_entity_not_found`. - Screening and risk: `check_kyc_status`, `check_ofac`, `check_risk_score`, `check_manual_review_status` (a manual review of the entity is pending). - Relationship type: `check_individual_entity` (only individuals can hold `minor_account_holder`, `authorized_signer`, and `authorized_user`), `check_minor_account_holder_enabled` (your program is not approved for minor account holders). - Stored data: `invalid_entity` (the entity's stored data fails Lead's current validations, which can happen to an older entity when rules change). See [Eligibility](https://docs.lead.bank/v2/products/entity/eligibility). - `entity_id` string, required: The ID of your entity. - `reason` string, required: A human-readable explanation of the failure and how to fix it. Not part of the API contract, so do not parse it. It may change without notice. - `authorized_signer` EligibilityRelationshipV2, required - `status` 'eligible' | 'ineligible', required: Whether the entity's current data qualifies it for the relationship type. - `failed_checks` EligibilityFailedCheck[], required: The checks the entity fails for this relationship type. Empty when `status` is `eligible`. - `check` string, required: The name of the failing check. The same names appear in `422` errors for a failed `intended_eligibility` assertion. Lead may add checks, so handle names you do not recognize. Current checks: - Identity and contact: `check_first_name`, `check_last_name`, `check_date_of_birth`, `check_date_of_birth_missing`, `check_date_of_birth_below_minimum`, `check_date_of_birth_above_maximum`, `check_phone_or_email`, `check_physical_address`, `check_government_id`. - Business: `check_business_name`, `check_business_type`, `check_business_industry`, `check_control_person_exists`, `check_child_entity_not_found`. - Screening and risk: `check_kyc_status`, `check_ofac`, `check_risk_score`, `check_manual_review_status` (a manual review of the entity is pending). - Relationship type: `check_individual_entity` (only individuals can hold `minor_account_holder`, `authorized_signer`, and `authorized_user`), `check_minor_account_holder_enabled` (your program is not approved for minor account holders). - Stored data: `invalid_entity` (the entity's stored data fails Lead's current validations, which can happen to an older entity when rules change). See [Eligibility](https://docs.lead.bank/v2/products/entity/eligibility). - `entity_id` string, required: The ID of your entity. - `reason` string, required: A human-readable explanation of the failure and how to fix it. Not part of the API contract, so do not parse it. It may change without notice. - `authorized_user` EligibilityRelationshipV2, required - `status` 'eligible' | 'ineligible', required: Whether the entity's current data qualifies it for the relationship type. - `failed_checks` EligibilityFailedCheck[], required: The checks the entity fails for this relationship type. Empty when `status` is `eligible`. - `check` string, required: The name of the failing check. The same names appear in `422` errors for a failed `intended_eligibility` assertion. Lead may add checks, so handle names you do not recognize. Current checks: - Identity and contact: `check_first_name`, `check_last_name`, `check_date_of_birth`, `check_date_of_birth_missing`, `check_date_of_birth_below_minimum`, `check_date_of_birth_above_maximum`, `check_phone_or_email`, `check_physical_address`, `check_government_id`. - Business: `check_business_name`, `check_business_type`, `check_business_industry`, `check_control_person_exists`, `check_child_entity_not_found`. - Screening and risk: `check_kyc_status`, `check_ofac`, `check_risk_score`, `check_manual_review_status` (a manual review of the entity is pending). - Relationship type: `check_individual_entity` (only individuals can hold `minor_account_holder`, `authorized_signer`, and `authorized_user`), `check_minor_account_holder_enabled` (your program is not approved for minor account holders). - Stored data: `invalid_entity` (the entity's stored data fails Lead's current validations, which can happen to an older entity when rules change). See [Eligibility](https://docs.lead.bank/v2/products/entity/eligibility). - `entity_id` string, required: The ID of your entity. - `reason` string, required: A human-readable explanation of the failure and how to fix it. Not part of the API contract, so do not parse it. It may change without notice. - `metadata` Metadata: A set of key-value pairs that can be used to store additional information related to this object. - BusinessEntityV2 - `id` string, required: The ID of your entity. - `client_customer_id` string: Your customer ID, on entities created through Customer files. Response only. Lead ignores it if sent, and does not return it on entities created with `POST /v2/entities`. - `created_at` string, date-time, required: Timestamp at which the entity object is created. - `updated_at` string, date-time, required: Timestamp at which the entity object was last updated. - `type` string, required: Type of entity = business. - `risk_score` 'low' | 'medium' | 'high': The entity's risk score, mapped to Lead by the client. Client should have provided risk score mapping to Lead. - `business_details` BusinessDetailsResponseV2, required: Details for the business entity. - `type` 'corporation' | 'partnership' | 'sole_prop' | 'llc' | 'trust' | 'cooperative' | 'other': Business Types. Possible business types are `corporation`, `partnership`, `sole_prop`, `llc`, `trust`, `cooperative`, `other`. - For business entity, cannot use `sole_prop` as business type. - For sole_prop entity, must use `sole_prop` as business type. - `name` string, required: Legal name of the business. Must be at least 2 characters. - `gross_annual_revenue` string: Business gross revenue for prior fiscal year. - `currency_code` string: A three-letter currency code as defined in ISO 4217. - `industry` string[]: NAICS code(s) for the applicable industries. 2-6 digits of NAICS code(s) are accepted and valid NAICS codes can be found on naics.com/search. Please refer to 2022 NAICS Reference Files. - `doing_business_as` string: Business name if the business operates under a different name. - `website` string: The website of the business. Must start with http:// or https://. - `contact_methods` ContactMethod[] - union - object - `type` string, required: ContactMethodType = email. - `email` string, required: Must be a valid email address in the form `local-part@domain.tld`. The domain must contain at least one dot. Addresses using `localhost`, IP literals (e.g., user@[127.0.0.1]), or quoted local parts (e.g., "user"@example.com) are not accepted. Only common, real-world email formats are supported. - object - `type` string, required: ContactMethodType = phone_number. Conforms to E.123 standard - `phone_number` string, required: Primary phone number of the entity. Must follow E.123 format. - `address_details` AddressDetails, required - `physical_address` Address - `line_1` string, required: Address line 1 is the required primary street-address field. It must contain the full base address needed to identify the physical location, such as the street number and street name together, or the closest local equivalent in countries where addresses do not use that exact structure. Use address line 1 for all core location details that describe the main property or thoroughfare. Regardless of how each component of an address is collected from your end-users, they must be combined into address line 1 before sending to Lead. Do not: - split the primary street address across line 1 and line 2 - put only the street number in line 1 and the street name in line 2 - pad line 1 with false or altered data just to satisfy validation - `line_2` string: Address line 2 is optional and should be used only for secondary or sub-premise information, such as: - apartment - unit - suite - floor - building - care-of / attention If there is no secondary or sub-premise information, address line 2 should be blank. Do not use address line 2 for any part of the primary street address. - `city` string, required: City. - `postal_code` string: Postal Code, required for US addresses. Please follow the following format: US: ^\d5(?:-\d4)?$, CN: ^\d6$, GB: ^[A-Z]{1,2}d[A-Z0-9]? ?d[A-Z]{2}$, JP: ^\d3-\d4$ - `state` string: State. required for US addresses in 2 character code (e.g. NY). - `country` string, required: ISO3166-1 Alpha-2 country code. - `mailing_address` Address - `line_1` string, required: Address line 1 is the required primary street-address field. It must contain the full base address needed to identify the physical location, such as the street number and street name together, or the closest local equivalent in countries where addresses do not use that exact structure. Use address line 1 for all core location details that describe the main property or thoroughfare. Regardless of how each component of an address is collected from your end-users, they must be combined into address line 1 before sending to Lead. Do not: - split the primary street address across line 1 and line 2 - put only the street number in line 1 and the street name in line 2 - pad line 1 with false or altered data just to satisfy validation - `line_2` string: Address line 2 is optional and should be used only for secondary or sub-premise information, such as: - apartment - unit - suite - floor - building - care-of / attention If there is no secondary or sub-premise information, address line 2 should be blank. Do not use address line 2 for any part of the primary street address. - `city` string, required: City. - `postal_code` string: Postal Code, required for US addresses. Please follow the following format: US: ^\d5(?:-\d4)?$, CN: ^\d6$, GB: ^[A-Z]{1,2}d[A-Z0-9]? ?d[A-Z]{2}$, JP: ^\d3-\d4$ - `state` string: State. required for US addresses in 2 character code (e.g. NY). - `country` string, required: ISO3166-1 Alpha-2 country code. - `other_addresses` Address[]: Other addresses for the entity. - `line_1` string, required: Address line 1 is the required primary street-address field. It must contain the full base address needed to identify the physical location, such as the street number and street name together, or the closest local equivalent in countries where addresses do not use that exact structure. Use address line 1 for all core location details that describe the main property or thoroughfare. Regardless of how each component of an address is collected from your end-users, they must be combined into address line 1 before sending to Lead. Do not: - split the primary street address across line 1 and line 2 - put only the street number in line 1 and the street name in line 2 - pad line 1 with false or altered data just to satisfy validation - `line_2` string: Address line 2 is optional and should be used only for secondary or sub-premise information, such as: - apartment - unit - suite - floor - building - care-of / attention If there is no secondary or sub-premise information, address line 2 should be blank. Do not use address line 2 for any part of the primary street address. - `city` string, required: City. - `postal_code` string: Postal Code, required for US addresses. Please follow the following format: US: ^\d5(?:-\d4)?$, CN: ^\d6$, GB: ^[A-Z]{1,2}d[A-Z0-9]? ?d[A-Z]{2}$, JP: ^\d3-\d4$ - `state` string: State. required for US addresses in 2 character code (e.g. NY). - `country` string, required: ISO3166-1 Alpha-2 country code. - `identification_details` union, required - object - `type` string, required: Use `us_entity` for an entity with US tax identification, including one you have not collected yet. `tax_identification` is required for an `account_holder`, `minor_account_holder`, or `authorized_signer`, and for beneficial owners, control persons, and sole proprietors. It is not required for an `authorized_user`. Include other government-verified identification documents in `identification_documents` when collected. - `tax_identification` TaxIdentification: The entity's own US tax identification. Do not submit another person's SSN or ITIN (e.g. a parent's for a minor). If you have not collected it, omit `tax_identification`; `type` without a valid `value` is rejected. See https://docs.lead.bank/products/entity/entity-object#identification-for-us-and-non-us-entities. - `type` 'ssn' | 'itin' | 'ein', required: The entity's US tax identification type: `ssn`, `itin`, or `ein`. - For `individual` entity, use SSN or ITIN. - For `business` entity, use EIN. For single-member LLC entities where no EIN is available, SSN or ITIN may be used. - For `sole_prop` entity, use SSN, ITIN, or EIN. - `value` string, required: The entity's US tax identification number. Must be 9 digits (e.g. XXXXXXXXX). An SSN must not start with 9. An EIN must begin with a number between 00 and 99. An ITIN must begin with 9. Required whenever `tax_identification` is sent; omit the whole object if you have not collected the tax identification. - `identification_documents` IdentificationDocumentV2[]: Government-issued identification, one entry per document. Each entry takes `file_id` or `type`, not both. A supplied array replaces the whole array, and Lead re-checks every `file_id` in it. Changing documents does not need a new KYC attestation. - `file_id` string: A file ID from `POST /v2/files`. Send `file_id` or `type`, not both. When you send only a `file_id`, Lead determines the document type from the file. Retrieve that type with `GET /v2/files/{id}`. The file must exist, belong to your program, and have a type this entry accepts. Send each `file_id` only once per entity. You can still link several files of the same type, and link one file to other entities. - `type` 'drivers_license' | 'state_id' | 'provincial_id' | 'passport' | 'permanent_residency_id' | 'national_id' | 'consular_id' | 'military_id' | 'tax_certificate' | 'tax_return' | 'partnership_agreement' | 'certificate_of_good_standing' | 'formation_document' | 'proof_of_place_on_stock_exchange' | 'name_certificate': The identification document type, when you do not link a file. Send `file_id` or `type`, not both. - For an `individual`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`. - For a `business`: `tax_certificate`, `tax_return`, `partnership_agreement`, `certificate_of_good_standing`, `formation_document`, `proof_of_place_on_stock_exchange`. - For a `sole_prop`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`, `tax_certificate`, `tax_return`, `name_certificate`. - `identification_number` string, required: The number on the document. - `issuing_country` string, required: Issuing country, as an ISO 3166-1 alpha-2 code. - `issuing_state` string: Issuing state, as a two-letter code. When `issuing_country` is `US`, it must be a valid US state. - `expiration_date` string, date: Expiration date, in YYYY-MM-DD format. Cannot be in the past when you create the entity. - `legacy_identification_documents` IdentificationDocument[]: Identification document entries created on v0 Entities, returned exactly as sent. Read only: ignored if included on a POST or PATCH. - `client_document_id` string: Client document ID for the identification document. - `type` 'drivers_license' | 'state_or_provincial_id' | 'passport' | 'permanent_residency_id' | 'military_id' | 'national_id' | 'matriculate_id' | 'other' | 'tax_certificate' | 'tax_returns' | 'partnership_agreement' | 'certificate_of_good_standing' | 'formation_document' | 'proof_of_place_on_stock_exchange' | 'name_certificate', required: The entity's government-verified identification document type. This will apply for identification types other than US tax identification. - For `individual` entity, possible types 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` entity, possible types are: `tax_certificate`, `tax_returns`, `partnership_agreement`, `certificate_of_good_standing`, `formation_document`, `proof_of_place_on_stock_exchange`, `other`. - For `sole_prop` entity, possible types 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`. - `description` string: Description about the identification document. Required if identification document type is `other`. - `identification_number` string, required: Unique identification number on the identification document. - `expiration_date` string, date: Expiration date of the identification document. - `issuing_state` string: Issuing state of the identification document. Must be 2 character code (e.g. NY). If the issuing country is US, this value must be a valid US State. - `issuing_country` string, required: Issuing country of the identification document. ISO3166-1 Alpha-2 country code. - object - `type` string, required: Use `non_us_entity` for an entity without US tax identification. At least one government-verified document in `identification_documents` is required for an `account_holder`, `minor_account_holder`, or `authorized_signer`, and for beneficial owners, control persons, and sole proprietors. It is not required for an `authorized_user`. - `identification_documents` IdentificationDocumentV2[]: Government-issued identification, one entry per document. Each entry takes `file_id` or `type`, not both. A supplied array replaces the whole array, and Lead re-checks every `file_id` in it. Changing documents does not need a new KYC attestation. - `file_id` string: A file ID from `POST /v2/files`. Send `file_id` or `type`, not both. When you send only a `file_id`, Lead determines the document type from the file. Retrieve that type with `GET /v2/files/{id}`. The file must exist, belong to your program, and have a type this entry accepts. Send each `file_id` only once per entity. You can still link several files of the same type, and link one file to other entities. - `type` 'drivers_license' | 'state_id' | 'provincial_id' | 'passport' | 'permanent_residency_id' | 'national_id' | 'consular_id' | 'military_id' | 'tax_certificate' | 'tax_return' | 'partnership_agreement' | 'certificate_of_good_standing' | 'formation_document' | 'proof_of_place_on_stock_exchange' | 'name_certificate': The identification document type, when you do not link a file. Send `file_id` or `type`, not both. - For an `individual`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`. - For a `business`: `tax_certificate`, `tax_return`, `partnership_agreement`, `certificate_of_good_standing`, `formation_document`, `proof_of_place_on_stock_exchange`. - For a `sole_prop`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`, `tax_certificate`, `tax_return`, `name_certificate`. - `identification_number` string, required: The number on the document. - `issuing_country` string, required: Issuing country, as an ISO 3166-1 alpha-2 code. - `issuing_state` string: Issuing state, as a two-letter code. When `issuing_country` is `US`, it must be a valid US state. - `expiration_date` string, date: Expiration date, in YYYY-MM-DD format. Cannot be in the past when you create the entity. - `legacy_identification_documents` IdentificationDocument[]: Identification document entries created on v0 Entities, returned exactly as sent. Read only: ignored if included on a POST or PATCH. - `client_document_id` string: Client document ID for the identification document. - `type` 'drivers_license' | 'state_or_provincial_id' | 'passport' | 'permanent_residency_id' | 'military_id' | 'national_id' | 'matriculate_id' | 'other' | 'tax_certificate' | 'tax_returns' | 'partnership_agreement' | 'certificate_of_good_standing' | 'formation_document' | 'proof_of_place_on_stock_exchange' | 'name_certificate', required: The entity's government-verified identification document type. This will apply for identification types other than US tax identification. - For `individual` entity, possible types 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` entity, possible types are: `tax_certificate`, `tax_returns`, `partnership_agreement`, `certificate_of_good_standing`, `formation_document`, `proof_of_place_on_stock_exchange`, `other`. - For `sole_prop` entity, possible types 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`. - `description` string: Description about the identification document. Required if identification document type is `other`. - `identification_number` string, required: Unique identification number on the identification document. - `expiration_date` string, date: Expiration date of the identification document. - `issuing_state` string: Issuing state of the identification document. Must be 2 character code (e.g. NY). If the issuing country is US, this value must be a valid US State. - `issuing_country` string, required: Issuing country of the identification document. ISO3166-1 Alpha-2 country code. - `additional_documents` AdditionalDocumentV2[]: Supporting documents, one entry per document. Each entry takes `file_id` or `type`, not both. A supplied array replaces the whole array, and Lead re-checks every `file_id` in it. Changing documents does not need a new KYC attestation. - `file_id` string: A file ID from `POST /v2/files`. Send `file_id` or `type`, not both. When you send only a `file_id`, Lead determines the document type from the file. Retrieve that type with `GET /v2/files/{id}`. The file must exist, belong to your program, and have a type this entry accepts. Send each `file_id` only once per entity. You can still link several files of the same type, and link one file to other entities. - `type` 'proof_of_address' | 'investigation_report' | 'financial_statement' | 'public_record' | 'adverse_media' | 'id_selfie' | 'source_of_wealth' | 'social_security_card': The supporting document type, when you do not link a file. Send `file_id` or `type`, not both. - `legacy_additional_documents` AdditionalDocument[]: Additional document entries created on v0 Entities, returned exactly as sent. Read only: ignored if included on a POST or PATCH. - `client_document_id` string: Client document ID for the additional document. - `type` 'bank_statement' | 'utility_bills' | 'proof_of_address' | 'investigation_report' | 'financial_statement' | 'public_records' | 'adverse_media' | 'id_selfie' | 'other', required: Type of additional non-government documents being provided to verify entity. Possible values are `bank_statement`, `utility_bills`, `proof_of_address`, `investigation_report`, `financial_statement`, `public_records`, `adverse_media`, `id_selfie`, `other`. - `description` string: Description about the identification document. Required if additional document type is `other`. - `beneficial_owners` BeneficialOwnersV2[] - `entity_id` string, required: The `entity_id` of the individual entity for this beneficial owner. Data requirements for beneficial owners match those of an `authorized_signer`. - `ownership_percentage` string: Percentage of the business this person owns, from 0 to 100 with up to two decimal places. For example, `25.5` means 25.5%. The percentages of all beneficial owners must add up to 100 or less. - `relationship_established_at` string, date: The date the relationship was established. - `control_persons` ControlPersons[] - `entity_id` string, required: Individual entity_id created for the control person. Data requirements for control persons match those of an `authorized_signer`. - `title` string, required: The title of this control person. - `relationship_established_at` string, date: The date the relationship was established. - `rfi_details` RfiDetails - `result` 'requested' | 'completed', required: Result of request for information with the end customer. Leave blank if RFI has not been sent to the customer. - `requested_at` string, date-time, required: Date time RFI is requested at. - `ofac_details` OfacDetails: Details on OFAC on the entity. - `result` 'pending' | 'passed' | 'failed', required: OFAC result. Possible values: pending | passed | failed. - `screened_at` string, date-time, required: Date time OFAC screen is screened at. - `kyc_details` KycDetails: Details on KYC on the entity. - `result` 'pending' | 'passed' | 'failed', required: KYC result. Possible values: pending | passed | failed. - `screened_at` string, date-time, required: Date time KYC screen is screened at. - `credit_details` CreditDetails[] - `credit_score` string: Credit score given by the credit bureau. Cannot be above 850. Mutually exclusive with `credit_report_non_score_value`. - `credit_report_non_score_value` 'unestablished' | 'frozen': Indicates the state of a credit file when a numeric score is not available. - `credit_report_source` 'equifax' | 'experian' | 'transunion', required: The name of the credit bureau. - `credit_pulled_at` string, date-time, required: Date time credit is pulled at. - `intended_eligibility` EligibilityRelationshipType[]: The relationship types you intend this entity to hold. When you send it, Lead checks the entity's data against every listed type and rejects the request with `422 parameters_invalid` if any fails. The check is all or nothing, and the error returns every failing check, not just the first. Listing fewer types than the entity qualifies for still succeeds, and `eligibility` shows everything it qualifies for. If the check passes, Lead saves the list and returns it on the entity. On a `PATCH`, Lead checks the entity as it would be after the update, against the list you send or, if you leave the field out, the saved list. Send an empty array to clear the saved list; no check runs. - `eligibility` EligibilityV2, required: Whether the entity's current data qualifies it for each relationship type, with the failing checks. Response only. Lead computes it from current data on every read and never stores it. All four keys are always present. On a program that does not offer minor account holders, `minor_account_holder` is `ineligible` for every entity. - `account_holder` EligibilityRelationshipV2, required - `status` 'eligible' | 'ineligible', required: Whether the entity's current data qualifies it for the relationship type. - `failed_checks` EligibilityFailedCheck[], required: The checks the entity fails for this relationship type. Empty when `status` is `eligible`. - `check` string, required: The name of the failing check. The same names appear in `422` errors for a failed `intended_eligibility` assertion. Lead may add checks, so handle names you do not recognize. Current checks: - Identity and contact: `check_first_name`, `check_last_name`, `check_date_of_birth`, `check_date_of_birth_missing`, `check_date_of_birth_below_minimum`, `check_date_of_birth_above_maximum`, `check_phone_or_email`, `check_physical_address`, `check_government_id`. - Business: `check_business_name`, `check_business_type`, `check_business_industry`, `check_control_person_exists`, `check_child_entity_not_found`. - Screening and risk: `check_kyc_status`, `check_ofac`, `check_risk_score`, `check_manual_review_status` (a manual review of the entity is pending). - Relationship type: `check_individual_entity` (only individuals can hold `minor_account_holder`, `authorized_signer`, and `authorized_user`), `check_minor_account_holder_enabled` (your program is not approved for minor account holders). - Stored data: `invalid_entity` (the entity's stored data fails Lead's current validations, which can happen to an older entity when rules change). See [Eligibility](https://docs.lead.bank/v2/products/entity/eligibility). - `entity_id` string, required: The ID of your entity. - `reason` string, required: A human-readable explanation of the failure and how to fix it. Not part of the API contract, so do not parse it. It may change without notice. - `minor_account_holder` EligibilityRelationshipV2, required - `status` 'eligible' | 'ineligible', required: Whether the entity's current data qualifies it for the relationship type. - `failed_checks` EligibilityFailedCheck[], required: The checks the entity fails for this relationship type. Empty when `status` is `eligible`. - `check` string, required: The name of the failing check. The same names appear in `422` errors for a failed `intended_eligibility` assertion. Lead may add checks, so handle names you do not recognize. Current checks: - Identity and contact: `check_first_name`, `check_last_name`, `check_date_of_birth`, `check_date_of_birth_missing`, `check_date_of_birth_below_minimum`, `check_date_of_birth_above_maximum`, `check_phone_or_email`, `check_physical_address`, `check_government_id`. - Business: `check_business_name`, `check_business_type`, `check_business_industry`, `check_control_person_exists`, `check_child_entity_not_found`. - Screening and risk: `check_kyc_status`, `check_ofac`, `check_risk_score`, `check_manual_review_status` (a manual review of the entity is pending). - Relationship type: `check_individual_entity` (only individuals can hold `minor_account_holder`, `authorized_signer`, and `authorized_user`), `check_minor_account_holder_enabled` (your program is not approved for minor account holders). - Stored data: `invalid_entity` (the entity's stored data fails Lead's current validations, which can happen to an older entity when rules change). See [Eligibility](https://docs.lead.bank/v2/products/entity/eligibility). - `entity_id` string, required: The ID of your entity. - `reason` string, required: A human-readable explanation of the failure and how to fix it. Not part of the API contract, so do not parse it. It may change without notice. - `authorized_signer` EligibilityRelationshipV2, required - `status` 'eligible' | 'ineligible', required: Whether the entity's current data qualifies it for the relationship type. - `failed_checks` EligibilityFailedCheck[], required: The checks the entity fails for this relationship type. Empty when `status` is `eligible`. - `check` string, required: The name of the failing check. The same names appear in `422` errors for a failed `intended_eligibility` assertion. Lead may add checks, so handle names you do not recognize. Current checks: - Identity and contact: `check_first_name`, `check_last_name`, `check_date_of_birth`, `check_date_of_birth_missing`, `check_date_of_birth_below_minimum`, `check_date_of_birth_above_maximum`, `check_phone_or_email`, `check_physical_address`, `check_government_id`. - Business: `check_business_name`, `check_business_type`, `check_business_industry`, `check_control_person_exists`, `check_child_entity_not_found`. - Screening and risk: `check_kyc_status`, `check_ofac`, `check_risk_score`, `check_manual_review_status` (a manual review of the entity is pending). - Relationship type: `check_individual_entity` (only individuals can hold `minor_account_holder`, `authorized_signer`, and `authorized_user`), `check_minor_account_holder_enabled` (your program is not approved for minor account holders). - Stored data: `invalid_entity` (the entity's stored data fails Lead's current validations, which can happen to an older entity when rules change). See [Eligibility](https://docs.lead.bank/v2/products/entity/eligibility). - `entity_id` string, required: The ID of your entity. - `reason` string, required: A human-readable explanation of the failure and how to fix it. Not part of the API contract, so do not parse it. It may change without notice. - `authorized_user` EligibilityRelationshipV2, required - `status` 'eligible' | 'ineligible', required: Whether the entity's current data qualifies it for the relationship type. - `failed_checks` EligibilityFailedCheck[], required: The checks the entity fails for this relationship type. Empty when `status` is `eligible`. - `check` string, required: The name of the failing check. The same names appear in `422` errors for a failed `intended_eligibility` assertion. Lead may add checks, so handle names you do not recognize. Current checks: - Identity and contact: `check_first_name`, `check_last_name`, `check_date_of_birth`, `check_date_of_birth_missing`, `check_date_of_birth_below_minimum`, `check_date_of_birth_above_maximum`, `check_phone_or_email`, `check_physical_address`, `check_government_id`. - Business: `check_business_name`, `check_business_type`, `check_business_industry`, `check_control_person_exists`, `check_child_entity_not_found`. - Screening and risk: `check_kyc_status`, `check_ofac`, `check_risk_score`, `check_manual_review_status` (a manual review of the entity is pending). - Relationship type: `check_individual_entity` (only individuals can hold `minor_account_holder`, `authorized_signer`, and `authorized_user`), `check_minor_account_holder_enabled` (your program is not approved for minor account holders). - Stored data: `invalid_entity` (the entity's stored data fails Lead's current validations, which can happen to an older entity when rules change). See [Eligibility](https://docs.lead.bank/v2/products/entity/eligibility). - `entity_id` string, required: The ID of your entity. - `reason` string, required: A human-readable explanation of the failure and how to fix it. Not part of the API contract, so do not parse it. It may change without notice. - `metadata` Metadata: A set of key-value pairs that can be used to store additional information related to this object. - SolePropEntityV2 - `id` string, required: The ID of your entity. - `client_customer_id` string: Your customer ID, on entities created through Customer files. Response only. Lead ignores it if sent, and does not return it on entities created with `POST /v2/entities`. - `created_at` string, date-time, required: Timestamp at which the entity object is created. - `updated_at` string, date-time, required: Timestamp at which the entity object was last updated. - `type` string, required: Type of entity = sole_prop. - `risk_score` 'low' | 'medium' | 'high': The entity's risk score, mapped to Lead by the client. Client should have provided risk score mapping to Lead. - `business_details` BusinessDetailsResponseV2, required: Details for the business entity. - `type` 'corporation' | 'partnership' | 'sole_prop' | 'llc' | 'trust' | 'cooperative' | 'other': Business Types. Possible business types are `corporation`, `partnership`, `sole_prop`, `llc`, `trust`, `cooperative`, `other`. - For business entity, cannot use `sole_prop` as business type. - For sole_prop entity, must use `sole_prop` as business type. - `name` string, required: Legal name of the business. Must be at least 2 characters. - `gross_annual_revenue` string: Business gross revenue for prior fiscal year. - `currency_code` string: A three-letter currency code as defined in ISO 4217. - `industry` string[]: NAICS code(s) for the applicable industries. 2-6 digits of NAICS code(s) are accepted and valid NAICS codes can be found on naics.com/search. Please refer to 2022 NAICS Reference Files. - `doing_business_as` string: Business name if the business operates under a different name. - `website` string: The website of the business. Must start with http:// or https://. - `contact_methods` ContactMethod[] - union - object - `type` string, required: ContactMethodType = email. - `email` string, required: Must be a valid email address in the form `local-part@domain.tld`. The domain must contain at least one dot. Addresses using `localhost`, IP literals (e.g., user@[127.0.0.1]), or quoted local parts (e.g., "user"@example.com) are not accepted. Only common, real-world email formats are supported. - object - `type` string, required: ContactMethodType = phone_number. Conforms to E.123 standard - `phone_number` string, required: Primary phone number of the entity. Must follow E.123 format. - `address_details` AddressDetails, required - `physical_address` Address - `line_1` string, required: Address line 1 is the required primary street-address field. It must contain the full base address needed to identify the physical location, such as the street number and street name together, or the closest local equivalent in countries where addresses do not use that exact structure. Use address line 1 for all core location details that describe the main property or thoroughfare. Regardless of how each component of an address is collected from your end-users, they must be combined into address line 1 before sending to Lead. Do not: - split the primary street address across line 1 and line 2 - put only the street number in line 1 and the street name in line 2 - pad line 1 with false or altered data just to satisfy validation - `line_2` string: Address line 2 is optional and should be used only for secondary or sub-premise information, such as: - apartment - unit - suite - floor - building - care-of / attention If there is no secondary or sub-premise information, address line 2 should be blank. Do not use address line 2 for any part of the primary street address. - `city` string, required: City. - `postal_code` string: Postal Code, required for US addresses. Please follow the following format: US: ^\d5(?:-\d4)?$, CN: ^\d6$, GB: ^[A-Z]{1,2}d[A-Z0-9]? ?d[A-Z]{2}$, JP: ^\d3-\d4$ - `state` string: State. required for US addresses in 2 character code (e.g. NY). - `country` string, required: ISO3166-1 Alpha-2 country code. - `mailing_address` Address - `line_1` string, required: Address line 1 is the required primary street-address field. It must contain the full base address needed to identify the physical location, such as the street number and street name together, or the closest local equivalent in countries where addresses do not use that exact structure. Use address line 1 for all core location details that describe the main property or thoroughfare. Regardless of how each component of an address is collected from your end-users, they must be combined into address line 1 before sending to Lead. Do not: - split the primary street address across line 1 and line 2 - put only the street number in line 1 and the street name in line 2 - pad line 1 with false or altered data just to satisfy validation - `line_2` string: Address line 2 is optional and should be used only for secondary or sub-premise information, such as: - apartment - unit - suite - floor - building - care-of / attention If there is no secondary or sub-premise information, address line 2 should be blank. Do not use address line 2 for any part of the primary street address. - `city` string, required: City. - `postal_code` string: Postal Code, required for US addresses. Please follow the following format: US: ^\d5(?:-\d4)?$, CN: ^\d6$, GB: ^[A-Z]{1,2}d[A-Z0-9]? ?d[A-Z]{2}$, JP: ^\d3-\d4$ - `state` string: State. required for US addresses in 2 character code (e.g. NY). - `country` string, required: ISO3166-1 Alpha-2 country code. - `other_addresses` Address[]: Other addresses for the entity. - `line_1` string, required: Address line 1 is the required primary street-address field. It must contain the full base address needed to identify the physical location, such as the street number and street name together, or the closest local equivalent in countries where addresses do not use that exact structure. Use address line 1 for all core location details that describe the main property or thoroughfare. Regardless of how each component of an address is collected from your end-users, they must be combined into address line 1 before sending to Lead. Do not: - split the primary street address across line 1 and line 2 - put only the street number in line 1 and the street name in line 2 - pad line 1 with false or altered data just to satisfy validation - `line_2` string: Address line 2 is optional and should be used only for secondary or sub-premise information, such as: - apartment - unit - suite - floor - building - care-of / attention If there is no secondary or sub-premise information, address line 2 should be blank. Do not use address line 2 for any part of the primary street address. - `city` string, required: City. - `postal_code` string: Postal Code, required for US addresses. Please follow the following format: US: ^\d5(?:-\d4)?$, CN: ^\d6$, GB: ^[A-Z]{1,2}d[A-Z0-9]? ?d[A-Z]{2}$, JP: ^\d3-\d4$ - `state` string: State. required for US addresses in 2 character code (e.g. NY). - `country` string, required: ISO3166-1 Alpha-2 country code. - `identification_details` union, required - object - `type` string, required: Use `us_entity` for an entity with US tax identification, including one you have not collected yet. `tax_identification` is required for an `account_holder`, `minor_account_holder`, or `authorized_signer`, and for beneficial owners, control persons, and sole proprietors. It is not required for an `authorized_user`. Include other government-verified identification documents in `identification_documents` when collected. - `tax_identification` TaxIdentification: The entity's own US tax identification. Do not submit another person's SSN or ITIN (e.g. a parent's for a minor). If you have not collected it, omit `tax_identification`; `type` without a valid `value` is rejected. See https://docs.lead.bank/products/entity/entity-object#identification-for-us-and-non-us-entities. - `type` 'ssn' | 'itin' | 'ein', required: The entity's US tax identification type: `ssn`, `itin`, or `ein`. - For `individual` entity, use SSN or ITIN. - For `business` entity, use EIN. For single-member LLC entities where no EIN is available, SSN or ITIN may be used. - For `sole_prop` entity, use SSN, ITIN, or EIN. - `value` string, required: The entity's US tax identification number. Must be 9 digits (e.g. XXXXXXXXX). An SSN must not start with 9. An EIN must begin with a number between 00 and 99. An ITIN must begin with 9. Required whenever `tax_identification` is sent; omit the whole object if you have not collected the tax identification. - `identification_documents` IdentificationDocumentV2[]: Government-issued identification, one entry per document. Each entry takes `file_id` or `type`, not both. A supplied array replaces the whole array, and Lead re-checks every `file_id` in it. Changing documents does not need a new KYC attestation. - `file_id` string: A file ID from `POST /v2/files`. Send `file_id` or `type`, not both. When you send only a `file_id`, Lead determines the document type from the file. Retrieve that type with `GET /v2/files/{id}`. The file must exist, belong to your program, and have a type this entry accepts. Send each `file_id` only once per entity. You can still link several files of the same type, and link one file to other entities. - `type` 'drivers_license' | 'state_id' | 'provincial_id' | 'passport' | 'permanent_residency_id' | 'national_id' | 'consular_id' | 'military_id' | 'tax_certificate' | 'tax_return' | 'partnership_agreement' | 'certificate_of_good_standing' | 'formation_document' | 'proof_of_place_on_stock_exchange' | 'name_certificate': The identification document type, when you do not link a file. Send `file_id` or `type`, not both. - For an `individual`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`. - For a `business`: `tax_certificate`, `tax_return`, `partnership_agreement`, `certificate_of_good_standing`, `formation_document`, `proof_of_place_on_stock_exchange`. - For a `sole_prop`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`, `tax_certificate`, `tax_return`, `name_certificate`. - `identification_number` string, required: The number on the document. - `issuing_country` string, required: Issuing country, as an ISO 3166-1 alpha-2 code. - `issuing_state` string: Issuing state, as a two-letter code. When `issuing_country` is `US`, it must be a valid US state. - `expiration_date` string, date: Expiration date, in YYYY-MM-DD format. Cannot be in the past when you create the entity. - `legacy_identification_documents` IdentificationDocument[]: Identification document entries created on v0 Entities, returned exactly as sent. Read only: ignored if included on a POST or PATCH. - `client_document_id` string: Client document ID for the identification document. - `type` 'drivers_license' | 'state_or_provincial_id' | 'passport' | 'permanent_residency_id' | 'military_id' | 'national_id' | 'matriculate_id' | 'other' | 'tax_certificate' | 'tax_returns' | 'partnership_agreement' | 'certificate_of_good_standing' | 'formation_document' | 'proof_of_place_on_stock_exchange' | 'name_certificate', required: The entity's government-verified identification document type. This will apply for identification types other than US tax identification. - For `individual` entity, possible types 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` entity, possible types are: `tax_certificate`, `tax_returns`, `partnership_agreement`, `certificate_of_good_standing`, `formation_document`, `proof_of_place_on_stock_exchange`, `other`. - For `sole_prop` entity, possible types 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`. - `description` string: Description about the identification document. Required if identification document type is `other`. - `identification_number` string, required: Unique identification number on the identification document. - `expiration_date` string, date: Expiration date of the identification document. - `issuing_state` string: Issuing state of the identification document. Must be 2 character code (e.g. NY). If the issuing country is US, this value must be a valid US State. - `issuing_country` string, required: Issuing country of the identification document. ISO3166-1 Alpha-2 country code. - object - `type` string, required: Use `non_us_entity` for an entity without US tax identification. At least one government-verified document in `identification_documents` is required for an `account_holder`, `minor_account_holder`, or `authorized_signer`, and for beneficial owners, control persons, and sole proprietors. It is not required for an `authorized_user`. - `identification_documents` IdentificationDocumentV2[]: Government-issued identification, one entry per document. Each entry takes `file_id` or `type`, not both. A supplied array replaces the whole array, and Lead re-checks every `file_id` in it. Changing documents does not need a new KYC attestation. - `file_id` string: A file ID from `POST /v2/files`. Send `file_id` or `type`, not both. When you send only a `file_id`, Lead determines the document type from the file. Retrieve that type with `GET /v2/files/{id}`. The file must exist, belong to your program, and have a type this entry accepts. Send each `file_id` only once per entity. You can still link several files of the same type, and link one file to other entities. - `type` 'drivers_license' | 'state_id' | 'provincial_id' | 'passport' | 'permanent_residency_id' | 'national_id' | 'consular_id' | 'military_id' | 'tax_certificate' | 'tax_return' | 'partnership_agreement' | 'certificate_of_good_standing' | 'formation_document' | 'proof_of_place_on_stock_exchange' | 'name_certificate': The identification document type, when you do not link a file. Send `file_id` or `type`, not both. - For an `individual`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`. - For a `business`: `tax_certificate`, `tax_return`, `partnership_agreement`, `certificate_of_good_standing`, `formation_document`, `proof_of_place_on_stock_exchange`. - For a `sole_prop`: `drivers_license`, `state_id`, `provincial_id`, `passport`, `permanent_residency_id`, `national_id`, `consular_id`, `military_id`, `tax_certificate`, `tax_return`, `name_certificate`. - `identification_number` string, required: The number on the document. - `issuing_country` string, required: Issuing country, as an ISO 3166-1 alpha-2 code. - `issuing_state` string: Issuing state, as a two-letter code. When `issuing_country` is `US`, it must be a valid US state. - `expiration_date` string, date: Expiration date, in YYYY-MM-DD format. Cannot be in the past when you create the entity. - `legacy_identification_documents` IdentificationDocument[]: Identification document entries created on v0 Entities, returned exactly as sent. Read only: ignored if included on a POST or PATCH. - `client_document_id` string: Client document ID for the identification document. - `type` 'drivers_license' | 'state_or_provincial_id' | 'passport' | 'permanent_residency_id' | 'military_id' | 'national_id' | 'matriculate_id' | 'other' | 'tax_certificate' | 'tax_returns' | 'partnership_agreement' | 'certificate_of_good_standing' | 'formation_document' | 'proof_of_place_on_stock_exchange' | 'name_certificate', required: The entity's government-verified identification document type. This will apply for identification types other than US tax identification. - For `individual` entity, possible types 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` entity, possible types are: `tax_certificate`, `tax_returns`, `partnership_agreement`, `certificate_of_good_standing`, `formation_document`, `proof_of_place_on_stock_exchange`, `other`. - For `sole_prop` entity, possible types 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`. - `description` string: Description about the identification document. Required if identification document type is `other`. - `identification_number` string, required: Unique identification number on the identification document. - `expiration_date` string, date: Expiration date of the identification document. - `issuing_state` string: Issuing state of the identification document. Must be 2 character code (e.g. NY). If the issuing country is US, this value must be a valid US State. - `issuing_country` string, required: Issuing country of the identification document. ISO3166-1 Alpha-2 country code. - `additional_documents` AdditionalDocumentV2[]: Supporting documents, one entry per document. Each entry takes `file_id` or `type`, not both. A supplied array replaces the whole array, and Lead re-checks every `file_id` in it. Changing documents does not need a new KYC attestation. - `file_id` string: A file ID from `POST /v2/files`. Send `file_id` or `type`, not both. When you send only a `file_id`, Lead determines the document type from the file. Retrieve that type with `GET /v2/files/{id}`. The file must exist, belong to your program, and have a type this entry accepts. Send each `file_id` only once per entity. You can still link several files of the same type, and link one file to other entities. - `type` 'proof_of_address' | 'investigation_report' | 'financial_statement' | 'public_record' | 'adverse_media' | 'id_selfie' | 'source_of_wealth' | 'social_security_card': The supporting document type, when you do not link a file. Send `file_id` or `type`, not both. - `legacy_additional_documents` AdditionalDocument[]: Additional document entries created on v0 Entities, returned exactly as sent. Read only: ignored if included on a POST or PATCH. - `client_document_id` string: Client document ID for the additional document. - `type` 'bank_statement' | 'utility_bills' | 'proof_of_address' | 'investigation_report' | 'financial_statement' | 'public_records' | 'adverse_media' | 'id_selfie' | 'other', required: Type of additional non-government documents being provided to verify entity. Possible values are `bank_statement`, `utility_bills`, `proof_of_address`, `investigation_report`, `financial_statement`, `public_records`, `adverse_media`, `id_selfie`, `other`. - `description` string: Description about the identification document. Required if additional document type is `other`. - `sole_proprietor` SoleProprietor, required - `entity_id` string, required: Individual entity_id created for the sole proprietor. Data requirements for sole proprietors match those of an `authorized_signer`. - `rfi_details` RfiDetails - `result` 'requested' | 'completed', required: Result of request for information with the end customer. Leave blank if RFI has not been sent to the customer. - `requested_at` string, date-time, required: Date time RFI is requested at. - `ofac_details` OfacDetails: Details on OFAC on the entity. - `result` 'pending' | 'passed' | 'failed', required: OFAC result. Possible values: pending | passed | failed. - `screened_at` string, date-time, required: Date time OFAC screen is screened at. - `kyc_details` KycDetails: Details on KYC on the entity. - `result` 'pending' | 'passed' | 'failed', required: KYC result. Possible values: pending | passed | failed. - `screened_at` string, date-time, required: Date time KYC screen is screened at. - `credit_details` CreditDetails[] - `credit_score` string: Credit score given by the credit bureau. Cannot be above 850. Mutually exclusive with `credit_report_non_score_value`. - `credit_report_non_score_value` 'unestablished' | 'frozen': Indicates the state of a credit file when a numeric score is not available. - `credit_report_source` 'equifax' | 'experian' | 'transunion', required: The name of the credit bureau. - `credit_pulled_at` string, date-time, required: Date time credit is pulled at. - `intended_eligibility` EligibilityRelationshipType[]: The relationship types you intend this entity to hold. When you send it, Lead checks the entity's data against every listed type and rejects the request with `422 parameters_invalid` if any fails. The check is all or nothing, and the error returns every failing check, not just the first. Listing fewer types than the entity qualifies for still succeeds, and `eligibility` shows everything it qualifies for. If the check passes, Lead saves the list and returns it on the entity. On a `PATCH`, Lead checks the entity as it would be after the update, against the list you send or, if you leave the field out, the saved list. Send an empty array to clear the saved list; no check runs. - `eligibility` EligibilityV2, required: Whether the entity's current data qualifies it for each relationship type, with the failing checks. Response only. Lead computes it from current data on every read and never stores it. All four keys are always present. On a program that does not offer minor account holders, `minor_account_holder` is `ineligible` for every entity. - `account_holder` EligibilityRelationshipV2, required - `status` 'eligible' | 'ineligible', required: Whether the entity's current data qualifies it for the relationship type. - `failed_checks` EligibilityFailedCheck[], required: The checks the entity fails for this relationship type. Empty when `status` is `eligible`. - `check` string, required: The name of the failing check. The same names appear in `422` errors for a failed `intended_eligibility` assertion. Lead may add checks, so handle names you do not recognize. Current checks: - Identity and contact: `check_first_name`, `check_last_name`, `check_date_of_birth`, `check_date_of_birth_missing`, `check_date_of_birth_below_minimum`, `check_date_of_birth_above_maximum`, `check_phone_or_email`, `check_physical_address`, `check_government_id`. - Business: `check_business_name`, `check_business_type`, `check_business_industry`, `check_control_person_exists`, `check_child_entity_not_found`. - Screening and risk: `check_kyc_status`, `check_ofac`, `check_risk_score`, `check_manual_review_status` (a manual review of the entity is pending). - Relationship type: `check_individual_entity` (only individuals can hold `minor_account_holder`, `authorized_signer`, and `authorized_user`), `check_minor_account_holder_enabled` (your program is not approved for minor account holders). - Stored data: `invalid_entity` (the entity's stored data fails Lead's current validations, which can happen to an older entity when rules change). See [Eligibility](https://docs.lead.bank/v2/products/entity/eligibility). - `entity_id` string, required: The ID of your entity. - `reason` string, required: A human-readable explanation of the failure and how to fix it. Not part of the API contract, so do not parse it. It may change without notice. - `minor_account_holder` EligibilityRelationshipV2, required - `status` 'eligible' | 'ineligible', required: Whether the entity's current data qualifies it for the relationship type. - `failed_checks` EligibilityFailedCheck[], required: The checks the entity fails for this relationship type. Empty when `status` is `eligible`. - `check` string, required: The name of the failing check. The same names appear in `422` errors for a failed `intended_eligibility` assertion. Lead may add checks, so handle names you do not recognize. Current checks: - Identity and contact: `check_first_name`, `check_last_name`, `check_date_of_birth`, `check_date_of_birth_missing`, `check_date_of_birth_below_minimum`, `check_date_of_birth_above_maximum`, `check_phone_or_email`, `check_physical_address`, `check_government_id`. - Business: `check_business_name`, `check_business_type`, `check_business_industry`, `check_control_person_exists`, `check_child_entity_not_found`. - Screening and risk: `check_kyc_status`, `check_ofac`, `check_risk_score`, `check_manual_review_status` (a manual review of the entity is pending). - Relationship type: `check_individual_entity` (only individuals can hold `minor_account_holder`, `authorized_signer`, and `authorized_user`), `check_minor_account_holder_enabled` (your program is not approved for minor account holders). - Stored data: `invalid_entity` (the entity's stored data fails Lead's current validations, which can happen to an older entity when rules change). See [Eligibility](https://docs.lead.bank/v2/products/entity/eligibility). - `entity_id` string, required: The ID of your entity. - `reason` string, required: A human-readable explanation of the failure and how to fix it. Not part of the API contract, so do not parse it. It may change without notice. - `authorized_signer` EligibilityRelationshipV2, required - `status` 'eligible' | 'ineligible', required: Whether the entity's current data qualifies it for the relationship type. - `failed_checks` EligibilityFailedCheck[], required: The checks the entity fails for this relationship type. Empty when `status` is `eligible`. - `check` string, required: The name of the failing check. The same names appear in `422` errors for a failed `intended_eligibility` assertion. Lead may add checks, so handle names you do not recognize. Current checks: - Identity and contact: `check_first_name`, `check_last_name`, `check_date_of_birth`, `check_date_of_birth_missing`, `check_date_of_birth_below_minimum`, `check_date_of_birth_above_maximum`, `check_phone_or_email`, `check_physical_address`, `check_government_id`. - Business: `check_business_name`, `check_business_type`, `check_business_industry`, `check_control_person_exists`, `check_child_entity_not_found`. - Screening and risk: `check_kyc_status`, `check_ofac`, `check_risk_score`, `check_manual_review_status` (a manual review of the entity is pending). - Relationship type: `check_individual_entity` (only individuals can hold `minor_account_holder`, `authorized_signer`, and `authorized_user`), `check_minor_account_holder_enabled` (your program is not approved for minor account holders). - Stored data: `invalid_entity` (the entity's stored data fails Lead's current validations, which can happen to an older entity when rules change). See [Eligibility](https://docs.lead.bank/v2/products/entity/eligibility). - `entity_id` string, required: The ID of your entity. - `reason` string, required: A human-readable explanation of the failure and how to fix it. Not part of the API contract, so do not parse it. It may change without notice. - `authorized_user` EligibilityRelationshipV2, required - `status` 'eligible' | 'ineligible', required: Whether the entity's current data qualifies it for the relationship type. - `failed_checks` EligibilityFailedCheck[], required: The checks the entity fails for this relationship type. Empty when `status` is `eligible`. - `check` string, required: The name of the failing check. The same names appear in `422` errors for a failed `intended_eligibility` assertion. Lead may add checks, so handle names you do not recognize. Current checks: - Identity and contact: `check_first_name`, `check_last_name`, `check_date_of_birth`, `check_date_of_birth_missing`, `check_date_of_birth_below_minimum`, `check_date_of_birth_above_maximum`, `check_phone_or_email`, `check_physical_address`, `check_government_id`. - Business: `check_business_name`, `check_business_type`, `check_business_industry`, `check_control_person_exists`, `check_child_entity_not_found`. - Screening and risk: `check_kyc_status`, `check_ofac`, `check_risk_score`, `check_manual_review_status` (a manual review of the entity is pending). - Relationship type: `check_individual_entity` (only individuals can hold `minor_account_holder`, `authorized_signer`, and `authorized_user`), `check_minor_account_holder_enabled` (your program is not approved for minor account holders). - Stored data: `invalid_entity` (the entity's stored data fails Lead's current validations, which can happen to an older entity when rules change). See [Eligibility](https://docs.lead.bank/v2/products/entity/eligibility). - `entity_id` string, required: The ID of your entity. - `reason` string, required: A human-readable explanation of the failure and how to fix it. Not part of the API contract, so do not parse it. It may change without notice. - `metadata` Metadata: A set of key-value pairs that can be used to store additional information related to this object. ## Other responses - `400`: `code` is one of: `request_malformed` (the body is missing or is not JSON; `errors[].code` is `body_malformed`), `headers_invalid` (the `Idempotency-Key` header is missing, sent more than once, or longer than 255 characters; `errors[].code` is `idempotency_key_invalid`). - `403`: `code` is one of: `authentication_missing` (the request has no credentials), `token_invalid` (the bearer token is missing, expired, or invalid, or does not grant `entity/read_write`), `source_ip_not_permitted` (the request came from an IP address that is not on your program's allowlist). - `409`: A concurrent request with the same `Idempotency-Key` is still in flight. - `415`: The request has a body and its `Content-Type` header is not `application/json` (`unsupported_media_type`; `errors[].code` is `content_type_invalid`). A missing or too long `Idempotency-Key`, or an empty body, is reported first as a `400`. - `422`: The request was parsed but cannot be processed. `code` is one of: `parameters_invalid` (a field is missing or invalid, including a malformed value (`value_malformed`) or one outside its allowed list, like a country, NAICS or currency code (`value_not_permitted`); `type` is `lead` or `partner` (`schema_violation`); a field that another field requires is missing, like `state` and `postal_code` on a US address, or a physical address on a business (`dependent_parameter_required`), or two fields don't fit together, like an `ein` tax ID on an individual (`dependent_parameter_invalid`); `tax_identification` has a `type` without a `value`, or a `value` without a `type` (`parameter_group_incomplete`); a document entry has neither `file_id` nor `type`, or a `credit_details` entry has neither a score nor a non-score value (`parameter_group_empty`), or either has both (`parameters_mutually_exclusive`); the beneficial owners' `ownership_percentage` values add up to more than 100 (`parameter_bound_exceeded`); a `file_id` appears more than once on the entity, or `intended_eligibility` lists a relationship type twice (`parameter_duplicated`); a screening or credit timestamp, or the date of birth, is in the future (`future_date_not_permitted`); an identification document has already expired (`past_date_not_permitted`); or the entity fails a check for a relationship type listed in `intended_eligibility`, where each failed check is an `errors[]` entry whose `code` is the check name. All failures are returned at once), `related_object_invalid` (a linked beneficial owner, control person, or sole proprietor, or a `file_id`, does not exist or belongs to another program; `errors[].code` is `reference_not_found`), `related_object_incompatible` (a linked beneficial owner, control person, or sole proprietor is not an individual entity, or a file's type is not allowed on that document entry; `errors[].code` is `reference_type_mismatched`), `lead_control_restricted` (your program is not enabled for Entity v2, or only allows individual entities and the request creates a `business` or `sole_prop`; `errors[].code` is `feature_not_enabled`), `idempotency_request_mismatched` (this `Idempotency-Key` was used with a different request body). - `429`: Rate limit exceeded. - `500`: Internal server error. Retry with the same `Idempotency-Key`. - `503`: The service or endpoint is temporarily unavailable. Retry after a delay. - `504`: An upstream system did not respond in time. Retry with backoff, and with the same `Idempotency-Key` on a `POST` or `PATCH`. ## Changes - **2026-11-03** `2c659854496e`: 1 info - endpoint added [Operation history](https://skmtc.dev/lead/apis/lead-bank/changes/v2/entities/post.md) --- [API](https://skmtc.dev/lead/apis/lead-bank.md) - [All operations](https://skmtc.dev/lead/apis/lead-bank/llms.txt) - [OpenAPI document](https://skmtc.dev/lead/apis/lead-bank/revisions/2c659854496e?raw)