> ## Documentation Index > Fetch the complete documentation index at: https://docs.lead.bank/llms.txt > Use this file to discover all available pages before exploring further. # Update an Entity > Update an `individual`, `business`, or `sole_prop` Entity. Some changes need a fresh KYC attestation. See [Create and update](/v2/products/entity/entity-object#create-and-update) for which changes need one and how `PATCH` handles each field. ## OpenAPI ````yaml PATCH /v2/entities/{id} openapi: 3.0.1 info: title: Lead Bank description: Lead Bank's APIs version: v1.0 servers: - url: https://api.sandbox.lead.bank - url: https://api.lead.bank security: - bearerAuth: [] tags: - name: ACH - name: Account Number - name: OAuth - name: Events - name: Instant Payments - name: Lending - name: Simulation - name: Internal Transfer - name: Disbursement - name: Entity - name: Wire - name: Originator - name: Funding - name: Receivable Sale - name: Balances - name: Compliance - name: Application - name: User Account - name: Blockchain Payment - name: Core Account - name: Core Balance - name: Core Transaction - name: Event Subscription - name: Receivable - name: User Credit Transaction - name: Files paths: /v2/entities/{id}: patch: tags: - Entity summary: Update an entity description: >- Update an `individual`, `business`, or `sole_prop` Entity. Some changes need a fresh KYC attestation. See [Create and update](/v2/products/entity/entity-object#create-and-update) for which changes need one and how `PATCH` handles each field. operationId: update-an-entity-v2 parameters: - name: id in: path required: true schema: $ref: '#/components/schemas/EntityID' - name: Idempotency-Key in: header description: >- A unique key for this request, up to 255 characters. Retrying with the same key and body returns the original response without applying the update twice. See [Idempotency](https://docs.lead.bank/api-reference/using-the-api/idempotency-v2). required: true schema: type: string maxLength: 255 example: 3f1c9a52-7d4e-4b8a-9c21-6e0f5d2a8b14 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAnEntityRequestBodyV2' responses: '200': description: Entity object updated. content: application/json: schema: $ref: '#/components/schemas/UpdateAnEntitySuccessResponseV2' '400': description: >- The request could not be parsed (`request_malformed`), or the `Idempotency-Key` header is missing (`idempotency_key_missing`). content: application/json: schema: $ref: '#/components/schemas/Error' example: code: request_malformed message: The request is invalid and cannot be parsed by the server. errors: - code: body_malformed message: The request body is missing or isn't JSON. '403': description: >- `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_allowed` (the request came from an IP address that is not on your program's allowlist). content: application/json: schema: $ref: '#/components/schemas/Error' example: code: token_invalid message: The bearer token is missing, expired, malformed, or invalid. '404': description: No entity exists with this ID, or it is not visible to your program. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: object_not_found message: >- No object exists at the requested ID, or it is not visible to this caller. '409': description: >- `code` is one of: `idempotency_key_in_use` (a concurrent request with the same `Idempotency-Key` is still in flight), `object_modified_concurrently` (another request changed the entity while this one was processing; fetch it and retry). content: application/json: schema: $ref: '#/components/schemas/Error' example: code: idempotency_key_in_use message: >- A concurrent request using this Idempotency-Key is still in flight. '422': description: >- 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` does not match the entity, or a business switches between `us_entity` and `non_us_entity` (`parameter_immutable`); a field that another field requires is missing, like `state` and `postal_code` on a US address, or a later `kyc_details.screened_at` when a name, date of birth, tax ID, or business name or type changes (`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`); `kyc_details.screened_at` is not later than the stored one (`parameter_sequence_invalid`); the request clears a stored KYC or OFAC `result` or `screened_at` (`parameter_not_removable`); or the updated 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_conflict` (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; `errors[].code` is `feature_not_enabled`), `operation_invalid` (the entity is a `lead` or `partner` entity, which cannot be updated; `errors[].code` is `object_lead_managed`; a body whose `type` is `lead` or `partner` returns `parameters_invalid` (`schema_violation`) instead, because the body is validated first), `idempotency_request_inconsistent` (this `Idempotency-Key` was used with a different request body). content: application/json: schema: $ref: '#/components/schemas/Error' example: code: parameters_invalid message: One or more parameters are invalid. errors: - code: check_date_of_birth message: >- entity_xyz123 is not eligible for account_holder. The entity must be 18 or older. parameters: - intended_eligibility '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: rate_limit_exceeded message: >- You have exceeded the rate limit for this endpoint. Retry with backoff. '500': description: Internal server error. Retry with the same `Idempotency-Key`. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: internal_server_error message: >- Something went wrong on our end. Contact Lead with the Request-Id if this persists. '503': description: >- The service or endpoint is temporarily unavailable. Retry after a delay. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: service_unavailable message: >- The service is temporarily unavailable. Retry after the indicated delay. '504': description: >- An upstream system did not respond in time. Retry with backoff, and with the same `Idempotency-Key` on a `POST` or `PATCH`. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: gateway_timeout message: An upstream system timed out. Retry with backoff. components: schemas: EntityID: type: string description: The ID of your entity. example: entity_xyz123 pattern: ^entity_[^\s]{1,33}$ UpdateAnEntityRequestBodyV2: oneOf: - $ref: '#/components/schemas/UpdateAnIndividualEntityRequestBodyV2' - $ref: '#/components/schemas/UpdateABusinessEntityRequestBodyV2' - $ref: '#/components/schemas/UpdateASolePropEntityRequestBodyV2' discriminator: propertyName: type mapping: individual: '#/components/schemas/UpdateAnIndividualEntityRequestBodyV2' business: '#/components/schemas/UpdateABusinessEntityRequestBodyV2' sole_prop: '#/components/schemas/UpdateASolePropEntityRequestBodyV2' UpdateAnEntitySuccessResponseV2: oneOf: - $ref: '#/components/schemas/IndividualEntityV2' - $ref: '#/components/schemas/BusinessEntityV2' - $ref: '#/components/schemas/SolePropEntityV2' discriminator: propertyName: type mapping: individual: '#/components/schemas/IndividualEntityV2' business: '#/components/schemas/BusinessEntityV2' sole_prop: '#/components/schemas/SolePropEntityV2' Error: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: >- A human-readable description of the error family. Identical for every occurrence of a given `code`; carries no request-specific detail. example: One or more parameters are invalid. errors: type: array description: >- Zero or more specific errors within this family. Always present for validation errors, one entry per failing field. items: $ref: '#/components/schemas/ErrorItem' UpdateAnIndividualEntityRequestBodyV2: title: Individual type: object required: - type description: Lead ignores fields not listed here. properties: type: $ref: '#/components/schemas/EntityTypeIndividual' intended_eligibility: $ref: '#/components/schemas/IntendedEligibilityV2' risk_score: $ref: '#/components/schemas/EntityRiskScoreEnum' individual_details: $ref: '#/components/schemas/UpdateIndividualDetailsV2' rfi_details: $ref: '#/components/schemas/RfiDetails' ofac_details: $ref: '#/components/schemas/OfacDetails' kyc_details: $ref: '#/components/schemas/KycDetails' credit_details: type: array items: $ref: '#/components/schemas/CreditDetails' metadata: $ref: '#/components/schemas/Metadata' UpdateABusinessEntityRequestBodyV2: title: Business type: object required: - type description: Lead ignores fields not listed here. properties: type: $ref: '#/components/schemas/EntityTypeBusiness' intended_eligibility: $ref: '#/components/schemas/IntendedEligibilityV2' risk_score: $ref: '#/components/schemas/EntityRiskScoreEnum' business_details: $ref: '#/components/schemas/UpdateBusinessDetailsV2' beneficial_owners: type: array items: $ref: '#/components/schemas/BeneficialOwners' control_persons: type: array items: $ref: '#/components/schemas/ControlPersons' rfi_details: $ref: '#/components/schemas/RfiDetails' ofac_details: $ref: '#/components/schemas/OfacDetails' kyc_details: $ref: '#/components/schemas/KycDetails' credit_details: type: array items: $ref: '#/components/schemas/CreditDetails' metadata: $ref: '#/components/schemas/Metadata' UpdateASolePropEntityRequestBodyV2: title: Sole Prop type: object required: - type description: Lead ignores fields not listed here. properties: type: $ref: '#/components/schemas/EntityTypeSoleProp' intended_eligibility: $ref: '#/components/schemas/IntendedEligibilityV2' risk_score: $ref: '#/components/schemas/EntityRiskScoreEnum' business_details: $ref: '#/components/schemas/UpdateBusinessDetailsV2' sole_proprietor: $ref: '#/components/schemas/SoleProprietor' rfi_details: $ref: '#/components/schemas/RfiDetails' ofac_details: $ref: '#/components/schemas/OfacDetails' kyc_details: $ref: '#/components/schemas/KycDetails' credit_details: type: array items: $ref: '#/components/schemas/CreditDetails' metadata: $ref: '#/components/schemas/Metadata' IndividualEntityV2: title: Individual type: object required: - id - type - individual_details - eligibility - created_at - updated_at properties: id: $ref: '#/components/schemas/EntityID' description: Unique ID for the Entity object. client_customer_id: type: string description: >- Your customer ID, on entities created on v0 or through Entity files. Response only. Lead ignores it if sent, and does not return it on other entities. created_at: type: string format: date-time description: Timestamp at which the entity object is created. updated_at: type: string format: date-time description: Timestamp at which the entity object was last updated. type: $ref: '#/components/schemas/EntityTypeIndividual' risk_score: $ref: '#/components/schemas/EntityRiskScoreEnum' individual_details: $ref: '#/components/schemas/IndividualDetailsResponseV2' rfi_details: $ref: '#/components/schemas/RfiDetails' ofac_details: $ref: '#/components/schemas/OfacDetails' kyc_details: $ref: '#/components/schemas/KycDetails' credit_details: type: array items: $ref: '#/components/schemas/CreditDetails' intended_eligibility: $ref: '#/components/schemas/IntendedEligibilityV2' eligibility: $ref: '#/components/schemas/EligibilityV2' metadata: $ref: '#/components/schemas/Metadata' BusinessEntityV2: title: Business type: object required: - id - type - business_details - eligibility - created_at - updated_at properties: id: $ref: '#/components/schemas/EntityID' description: Unique ID for the Entity object. client_customer_id: type: string description: >- Your customer ID, on entities created on v0 or through Entity files. Response only. Lead ignores it if sent, and does not return it on other entities. created_at: type: string format: date-time description: Timestamp at which the entity object is created. updated_at: type: string format: date-time description: Timestamp at which the entity object was last updated. type: $ref: '#/components/schemas/EntityTypeBusiness' risk_score: $ref: '#/components/schemas/EntityRiskScoreEnum' business_details: $ref: '#/components/schemas/BusinessDetailsResponseV2' beneficial_owners: type: array items: $ref: '#/components/schemas/BeneficialOwners' control_persons: type: array items: $ref: '#/components/schemas/ControlPersons' rfi_details: $ref: '#/components/schemas/RfiDetails' ofac_details: $ref: '#/components/schemas/OfacDetails' kyc_details: $ref: '#/components/schemas/KycDetails' credit_details: type: array items: $ref: '#/components/schemas/CreditDetails' intended_eligibility: $ref: '#/components/schemas/IntendedEligibilityV2' eligibility: $ref: '#/components/schemas/EligibilityV2' metadata: $ref: '#/components/schemas/Metadata' SolePropEntityV2: title: Sole Prop type: object required: - id - type - business_details - sole_proprietor - eligibility - created_at - updated_at properties: id: $ref: '#/components/schemas/EntityID' description: Unique ID for the Entity object. client_customer_id: type: string description: >- Your customer ID, on entities created on v0 or through Entity files. Response only. Lead ignores it if sent, and does not return it on other entities. created_at: type: string format: date-time description: Timestamp at which the entity object is created. updated_at: type: string format: date-time description: Timestamp at which the entity object was last updated. type: $ref: '#/components/schemas/EntityTypeSoleProp' risk_score: $ref: '#/components/schemas/EntityRiskScoreEnum' business_details: $ref: '#/components/schemas/BusinessDetailsResponseV2' sole_proprietor: $ref: '#/components/schemas/SoleProprietor' rfi_details: $ref: '#/components/schemas/RfiDetails' ofac_details: $ref: '#/components/schemas/OfacDetails' kyc_details: $ref: '#/components/schemas/KycDetails' credit_details: type: array items: $ref: '#/components/schemas/CreditDetails' intended_eligibility: $ref: '#/components/schemas/IntendedEligibilityV2' eligibility: $ref: '#/components/schemas/EligibilityV2' metadata: $ref: '#/components/schemas/Metadata' ErrorCode: type: string description: >- A snake_case code identifying the error family — the stable, machine-readable value partners branch on, together with the HTTP status. example: parameters_invalid enum: - request_malformed - content_too_large - idempotency_key_missing - authentication_missing - token_invalid - source_ip_not_allowed - url_invalid - object_not_found - method_not_allowed - idempotency_key_in_use - idempotency_request_inconsistent - rate_limit_exceeded - internal_server_error - service_unavailable - endpoint_disabled - gateway_timeout - unclassified - parameters_invalid - related_object_invalid - related_object_not_ready - related_object_conflict - limit_exceeded - client_control_restricted - lead_control_restricted - object_state_conflict - object_modified_concurrently - operation_invalid ErrorItem: type: object required: - code - message properties: code: type: string description: A snake_case code naming the specific error or sub-category. example: required message: type: string description: >- A human-readable description of this specific error, with interpolated values where relevant. example: account_number_id is required. parameters: type: array description: >- The request fields this error implicates, in dot notation for nested fields. Present for validation errors. items: type: string example: - account_number_id EntityTypeIndividual: type: string pattern: ^individual$ default: individual description: Type of entity = individual. IntendedEligibilityV2: type: array items: $ref: '#/components/schemas/EligibilityRelationshipType' example: - account_holder description: > 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. EntityRiskScoreEnum: type: string enum: - low - medium - high example: low description: >- The entity's risk score, mapped to Lead by the client. Client should have provided risk score mapping to Lead. UpdateIndividualDetailsV2: type: object properties: first_name: type: string description: >- Legal first name, as your customer gave it. Non-Latin characters are accepted. example: Lucy preferred_first_name: type: string description: Preferred first name. example: Lu middle_name: type: string description: Middle name. example: Reginald last_name: type: string description: >- Legal last name, as your customer gave it. Non-Latin characters are accepted. example: Collins date_of_birth: type: string format: date description: >- 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. example: '2002-02-15' occupation: type: string description: Occupation / job. example: Author contact_methods: type: array items: $ref: '#/components/schemas/ContactMethod' address_details: $ref: '#/components/schemas/UpdateAddressDetails' identification_details: $ref: '#/components/schemas/IdentificationDetailsIndividualV2' additional_documents: $ref: '#/components/schemas/AdditionalDocumentsV2' description: Details for the individual entity. RfiDetails: type: object required: - result - requested_at properties: result: $ref: '#/components/schemas/RfiDetailsResultEnum' requested_at: type: string format: date-time description: Date time RFI is requested at. OfacDetails: type: object required: - result - screened_at properties: result: $ref: '#/components/schemas/OfacDetailsResultEnum' screened_at: type: string format: date-time description: Date time OFAC screen is screened at. description: Details on OFAC on the entity. KycDetails: type: object required: - result - screened_at properties: result: $ref: '#/components/schemas/KycDetailsResultEnum' screened_at: type: string format: date-time description: Date time KYC screen is screened at. description: Details on KYC on the entity. CreditDetails: type: object required: - credit_report_source - credit_pulled_at properties: credit_score: type: string description: >- Credit score given by the credit bureau. Cannot be above 850. Mutually exclusive with `credit_report_non_score_value`. credit_report_non_score_value: $ref: '#/components/schemas/CreditReportNonScoreValueEnum' credit_report_source: $ref: '#/components/schemas/CreditReportSourceEnum' credit_pulled_at: type: string format: date-time description: Date time credit is pulled at. description: >- Details on credit data from credit bureaus on the entity. Exactly one of `credit_score` or `credit_report_non_score_value` must be provided. Metadata: type: object additionalProperties: type: string description: >- A set of key-value pairs that can be used to store additional information related to this object. EntityTypeBusiness: type: string pattern: ^business$ default: business description: Type of entity = business. UpdateBusinessDetailsV2: type: object properties: type: $ref: '#/components/schemas/BusinessTypeEnum' name: type: string description: Legal name of the business. Must be at least 2 characters. gross_annual_revenue: type: string description: Business gross revenue for prior fiscal year. currency_code: type: string description: A three-letter currency code as defined in ISO 4217. industry: type: array items: type: string description: >- 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: type: string description: Business name if the business operates under a different name. website: type: string description: The website of the business. Must start with http:// or https://. contact_methods: type: array items: $ref: '#/components/schemas/ContactMethod' address_details: $ref: '#/components/schemas/UpdateAddressDetails' identification_details: $ref: '#/components/schemas/IdentificationDetailsBusinessV2' additional_documents: $ref: '#/components/schemas/AdditionalDocumentsV2' description: Details for the business entity. BeneficialOwners: type: object required: - entity_id properties: entity_id: type: string description: >- Individual entity_id created for the beneficial owner. Data requirements for beneficial owners match those of an `authorized_signer`. ownership_percentage: type: string description: >- Percentage ownership (0-100.00 or 0-1.00 for decimal representation). pattern: ^(0(\.\d{1,2})?|[1-9]\d{0,1}(\.\d{1,2})?|100(\.0{1,2})?)$ relationship_established_at: type: string format: date description: The date the relationship was established. ControlPersons: type: object required: - entity_id - title properties: entity_id: type: string description: >- Individual entity_id created for the control person. Data requirements for control persons match those of an `authorized_signer`. title: type: string description: The title of this control person. relationship_established_at: type: string format: date description: The date the relationship was established. EntityTypeSoleProp: type: string pattern: ^sole_prop$ default: sole_prop description: Type of entity = sole_prop. SoleProprietor: type: object required: - entity_id properties: entity_id: type: string minLength: 1 description: >- Individual entity_id created for the sole proprietor. Data requirements for sole proprietors match those of an `authorized_signer`. IndividualDetailsResponseV2: type: object required: - first_name - last_name - identification_details properties: first_name: type: string description: >- Legal first name, as your customer gave it. Non-Latin characters are accepted. preferred_first_name: type: string description: Preferred first name. middle_name: type: string description: Middle name. last_name: type: string description: >- Legal last name, as your customer gave it. Non-Latin characters are accepted. date_of_birth: type: string format: date description: >- 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. example: '2002-02-15' occupation: type: string description: Occupation / job. contact_methods: type: array items: $ref: '#/components/schemas/ContactMethod' address_details: $ref: '#/components/schemas/AddressDetails' identification_details: $ref: '#/components/schemas/IdentificationDetailsIndividualResponseV2' additional_documents: $ref: '#/components/schemas/AdditionalDocumentsV2' legacy_additional_documents: $ref: '#/components/schemas/LegacyAdditionalDocumentsV2' description: >- 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). EligibilityV2: type: object description: >- 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. required: - account_holder - minor_account_holder - authorized_signer - authorized_user properties: account_holder: $ref: '#/components/schemas/EligibilityRelationshipV2' minor_account_holder: $ref: '#/components/schemas/EligibilityRelationshipV2' authorized_signer: $ref: '#/components/schemas/EligibilityRelationshipV2' authorized_user: $ref: '#/components/schemas/EligibilityRelationshipV2' example: account_holder: status: eligible failed_checks: [] minor_account_holder: status: ineligible failed_checks: - check: check_date_of_birth_above_maximum entity_id: entity_xyz123 reason: The entity exceeds the maximum age for minor_account_holder. authorized_signer: status: eligible failed_checks: [] authorized_user: status: eligible failed_checks: [] BusinessDetailsResponseV2: type: object required: - name - identification_details - address_details properties: type: $ref: '#/components/schemas/BusinessTypeEnum' name: type: string description: Legal name of the business. Must be at least 2 characters. gross_annual_revenue: type: string description: Business gross revenue for prior fiscal year. currency_code: type: string description: A three-letter currency code as defined in ISO 4217. industry: type: array items: type: string description: >- 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: type: string description: Business name if the business operates under a different name. website: type: string description: The website of the business. Must start with http:// or https://. contact_methods: type: array items: $ref: '#/components/schemas/ContactMethod' address_details: $ref: '#/components/schemas/AddressDetails' identification_details: $ref: '#/components/schemas/IdentificationDetailsBusinessResponseV2' additional_documents: $ref: '#/components/schemas/AdditionalDocumentsV2' legacy_additional_documents: $ref: '#/components/schemas/LegacyAdditionalDocumentsV2' description: Details for the business entity. EligibilityRelationshipType: type: string enum: - account_holder - minor_account_holder - authorized_signer - authorized_user example: account_holder description: > A relationship type an entity can hold. * `account_holder`: Full control of, and legal responsibility for, the account. * `minor_account_holder`: An individual aged 16 or 17 with account holder eligibility. * `authorized_signer`: An individual allowed to sign on behalf of the account holder, without legal responsibility. * `authorized_user`: An individual with restricted access to the account, without legal responsibility. ContactMethod: type: object oneOf: - $ref: '#/components/schemas/ContactMethodEmail' - $ref: '#/components/schemas/ContactMethodPhone' discriminator: propertyName: type mapping: email: '#/components/schemas/ContactMethodEmail' phone_number: '#/components/schemas/ContactMethodPhone' UpdateAddressDetails: type: object properties: physical_address: $ref: '#/components/schemas/UpdateAddress' description: >- Physical address for the entity. Physical addresses must not be P.O. boxes, registered agent addresses or in prohibited countries. mailing_address: $ref: '#/components/schemas/UpdateAddress' description: Mailing address for the entity. other_addresses: type: array description: Other addresses for the entity. items: $ref: '#/components/schemas/Address' IdentificationDetailsIndividualV2: type: object description: >- 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. oneOf: - $ref: '#/components/schemas/UsEntityV2' - $ref: '#/components/schemas/NonUsEntityV2' discriminator: propertyName: type mapping: us_entity: '#/components/schemas/UsEntityV2' non_us_entity: '#/components/schemas/NonUsEntityV2' AdditionalDocumentsV2: type: array example: - file_id: file_X5jD8hN2sQ6yFb1Gt9Ka - type: financial_statement description: >- Supporting documents. 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. items: $ref: '#/components/schemas/AdditionalDocumentV2' RfiDetailsResultEnum: type: string enum: - requested - completed example: completed description: >- Result of request for information with the end customer. Leave blank if RFI has not been sent to the customer. OfacDetailsResultEnum: type: string enum: - pending - passed - failed example: passed description: 'OFAC result. Possible values: pending | passed | failed. ' KycDetailsResultEnum: type: string enum: - pending - passed - failed example: passed description: 'KYC result. Possible values: pending | passed | failed. ' CreditReportNonScoreValueEnum: type: string enum: - unestablished - frozen example: unestablished description: >- Indicates the state of a credit file when a numeric score is not available. CreditReportSourceEnum: type: string enum: - equifax - experian - transunion example: equifax description: The name of the credit bureau. BusinessTypeEnum: type: string enum: - corporation - partnership - sole_prop - llc - trust - cooperative - other example: llc description: > 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. IdentificationDetailsBusinessV2: type: object oneOf: - $ref: '#/components/schemas/UsEntityV2' - $ref: '#/components/schemas/NonUsEntityV2' discriminator: propertyName: type mapping: us_entity: '#/components/schemas/UsEntityV2' non_us_entity: '#/components/schemas/NonUsEntityV2' AddressDetails: type: object properties: physical_address: $ref: '#/components/schemas/Address' description: >- Physical address for the entity. Physical addresses must not be P.O. boxes, registered agent addresses or in prohibited countries. mailing_address: $ref: '#/components/schemas/Address' description: Mailing address for the entity. other_addresses: type: array description: Other addresses for the entity. items: $ref: '#/components/schemas/Address' IdentificationDetailsIndividualResponseV2: type: object description: >- 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. oneOf: - $ref: '#/components/schemas/UsEntityResponseV2' - $ref: '#/components/schemas/NonUsEntityResponseV2' discriminator: propertyName: type mapping: us_entity: '#/components/schemas/UsEntityResponseV2' non_us_entity: '#/components/schemas/NonUsEntityResponseV2' LegacyAdditionalDocumentsV2: type: array example: - client_document_id: 2026_01_02_statement type: bank_statement description: Bank statement for January description: >- Additional document entries created on v0 Entities, returned exactly as sent. Read only: ignored if included on a POST or PATCH. items: $ref: '#/components/schemas/AdditionalDocument' EligibilityRelationshipV2: type: object required: - status - failed_checks properties: status: $ref: '#/components/schemas/EligibilityStatus' failed_checks: type: array description: >- The checks the entity fails for this relationship type. Empty when `status` is `eligible`. items: $ref: '#/components/schemas/EligibilityFailedCheck' IdentificationDetailsBusinessResponseV2: type: object oneOf: - $ref: '#/components/schemas/UsEntityResponseV2' - $ref: '#/components/schemas/NonUsEntityResponseV2' discriminator: propertyName: type mapping: us_entity: '#/components/schemas/UsEntityResponseV2' non_us_entity: '#/components/schemas/NonUsEntityResponseV2' ContactMethodEmail: title: Email type: object required: - type - email properties: type: $ref: '#/components/schemas/ContactMethodTypeEmail' email: type: string description: >- 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. example: abc@gmail.com ContactMethodPhone: title: Phone Number type: object required: - type - phone_number properties: type: $ref: '#/components/schemas/ContactMethodTypePhone' phone_number: type: string description: Primary phone number of the entity. Must follow E.123 format. UpdateAddress: type: object properties: line_1: type: string description: >- 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: type: string description: >- 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: type: string description: City. postal_code: type: string description: >- 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: type: string description: State. required for US addresses in 2 character code (e.g. NY). country: type: string description: ISO3166-1 Alpha-2 country code. Address: type: object required: - line_1 - city - country properties: line_1: type: string description: >- 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 example: 123 Main St. line_2: type: string description: >- 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. example: Apt 25 city: type: string description: City. example: Denver postal_code: type: string description: >- 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$ example: 80014 state: type: string description: State. required for US addresses in 2 character code (e.g. NY). example: CO country: type: string description: ISO3166-1 Alpha-2 country code. example: US UsEntityV2: title: US Entity type: object required: - type properties: type: $ref: '#/components/schemas/UsEntityTypeEnum' tax_identification: $ref: '#/components/schemas/TaxIdentification' identification_documents: $ref: '#/components/schemas/IdentificationDocumentsV2' NonUsEntityV2: title: Non US Entity type: object required: - type properties: type: $ref: '#/components/schemas/NonUsEntityTypeEnum' identification_documents: $ref: '#/components/schemas/IdentificationDocumentsV2' AdditionalDocumentV2: type: object description: >- A supporting document. Send exactly one of `file_id` or `type`; both returns `422 parameters_invalid` (`parameters_mutually_exclusive`), and neither returns it with `parameter_group_empty`. With a `file_id`, Lead takes the type from the file and the response omits `type`. Retrieve it with `GET /v2/files/{id}`. properties: file_id: $ref: '#/components/schemas/DocumentFileID' type: $ref: '#/components/schemas/AdditionalDocumentTypeV2' UsEntityResponseV2: title: US Entity type: object required: - type properties: type: $ref: '#/components/schemas/UsEntityTypeEnum' tax_identification: $ref: '#/components/schemas/TaxIdentification' identification_documents: $ref: '#/components/schemas/IdentificationDocumentsV2' legacy_identification_documents: $ref: '#/components/schemas/LegacyIdentificationDocumentsV2' NonUsEntityResponseV2: title: Non US Entity type: object required: - type properties: type: $ref: '#/components/schemas/NonUsEntityTypeEnum' identification_documents: $ref: '#/components/schemas/IdentificationDocumentsV2' legacy_identification_documents: $ref: '#/components/schemas/LegacyIdentificationDocumentsV2' AdditionalDocument: type: object required: - type properties: client_document_id: type: string description: Client document ID for the additional document. type: $ref: '#/components/schemas/AdditionalDocumentTypeEnum' description: type: string description: >- Description about the identification document. Required if additional document type is `other`. EligibilityStatus: type: string enum: - eligible - ineligible example: eligible description: >- Whether the entity's current data qualifies it for the relationship type. EligibilityFailedCheck: type: object required: - check - entity_id - reason properties: check: type: string example: check_kyc_status description: >- 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: $ref: '#/components/schemas/EntityID' description: >- The entity whose data failed the check. A business or sole proprietorship fails when a linked individual fails, and the check then points at that individual's `entity_id`. reason: type: string example: >- KYC must be passed. Update kyc_details.result and kyc_details.screened_at on entity_xyz123. description: >- 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. ContactMethodTypeEmail: type: string pattern: ^email$ default: email description: ContactMethodType = email. ContactMethodTypePhone: type: string pattern: ^phone_number$ default: phone_number example: +22 607 123 4567 description: ContactMethodType = phone_number. Conforms to E.123 standard UsEntityTypeEnum: type: string pattern: ^us_entity$ default: us_entity description: >- 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. TaxIdentification: type: object description: >- 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. required: - type - value properties: type: $ref: '#/components/schemas/TaxIdentificationTypeEnum' value: type: string description: >- 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. pattern: ^\d{9}$ IdentificationDocumentsV2: type: array example: - file_id: file_7Tq4mR9vKx2LpW8nZc3B identification_number: X1234567 issuing_country: GB expiration_date: '2030-06-01' - type: passport identification_number: X7654321 issuing_country: GB expiration_date: '2031-01-15' description: >- Government-issued identification. 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. items: $ref: '#/components/schemas/IdentificationDocumentV2' NonUsEntityTypeEnum: type: string pattern: ^non_us_entity$ default: non_us_entity description: >- 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`. DocumentFileID: type: string pattern: ^file_\w+$ description: >- A file ID from `POST /v2/files`. The file must exist, belong to your program, and have a type this entry accepts. Each file can appear at most once on an entity. example: file_7RwQ2mK9pL4xT1vN8jS5 AdditionalDocumentTypeV2: type: string enum: - bank_statement - utility_bills - proof_of_address - investigation_report - financial_statement - public_records - adverse_media - id_selfie example: bank_statement description: The supporting document type. LegacyIdentificationDocumentsV2: type: array example: - client_document_id: passport_jane_doe.pdf type: passport identification_number: X1234567 issuing_country: GB expiration_date: '2026-06-01' description: >- Identification document entries created on v0 Entities, returned exactly as sent. Read only: ignored if included on a POST or PATCH. items: $ref: '#/components/schemas/IdentificationDocument' AdditionalDocumentTypeEnum: type: string enum: - bank_statement - utility_bills - proof_of_address - investigation_report - financial_statement - public_records - adverse_media - id_selfie - other example: bank_statement description: >- 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`. TaxIdentificationTypeEnum: type: string enum: - ssn - itin - ein example: ssn description: > 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. IdentificationDocumentV2: type: object description: >- A government-issued identification document. Send exactly one of `file_id` or `type`; both returns `422 parameters_invalid` (`parameters_mutually_exclusive`), and neither returns it with `parameter_group_empty`. With a `file_id`, Lead takes the type from the file and the response omits `type`. Retrieve it with `GET /v2/files/{id}`. required: - identification_number - issuing_country properties: file_id: $ref: '#/components/schemas/DocumentFileID' type: $ref: '#/components/schemas/IdentificationDocumentTypeV2' identification_number: type: string description: The number on the document. example: X1234567 issuing_country: type: string description: Issuing country, as an ISO 3166-1 alpha-2 code. example: GB minLength: 2 maxLength: 2 pattern: ^[A-Z]{2}$ issuing_state: type: string description: >- Issuing state, as a two-letter code. When `issuing_country` is `US`, it must be a valid US state. expiration_date: type: string format: date description: >- Expiration date, in YYYY-MM-DD format. Cannot be in the past when you create the entity. example: '2030-06-01' IdentificationDocument: type: object required: - type - identification_number - issuing_country properties: client_document_id: type: string description: Client document ID for the identification document. type: $ref: '#/components/schemas/IdentificationDocumentsTypeEnum' description: type: string description: >- Description about the identification document. Required if identification document type is `other`. identification_number: type: string description: Unique identification number on the identification document. expiration_date: type: string format: date description: Expiration date of the identification document. issuing_state: type: string description: >- 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: type: string description: >- Issuing country of the identification document. ISO3166-1 Alpha-2 country code. IdentificationDocumentTypeV2: type: string enum: - drivers_license - state_or_provincial_id - passport - permanent_residency_id - military_id - national_id - matriculate_id - tax_certificate - tax_returns - partnership_agreement - certificate_of_good_standing - formation_document - proof_of_place_on_stock_exchange - name_certificate example: passport description: > The identification document type. - For an `individual`: `drivers_license`, `state_or_provincial_id`, `passport`, `permanent_residency_id`, `military_id`, `national_id`, `matriculate_id`. - For a `business`: `tax_certificate`, `tax_returns`, `partnership_agreement`, `certificate_of_good_standing`, `formation_document`, `proof_of_place_on_stock_exchange`. - For a `sole_prop`: `tax_certificate`, `tax_returns`, `name_certificate`, `drivers_license`, `state_or_provincial_id`, `passport`, `permanent_residency_id`, `military_id`, `national_id`, `matriculate_id`. IdentificationDocumentsTypeEnum: type: string enum: - 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 example: drivers_license description: > 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`. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.