Identification Errors

Machine-readable error codes returned by POST /customers//identifications/v2 when a Business, Person, or Token submission fails validation.

POST /api/customers/{id}/identifications/v2 validates data-carrying submissions (Business, Person, and Token) synchronously. Under X-API-Version: 2026-08-01 or later, a failed submission returns 400 with an array of structured error objects instead of the plain string returned by earlier versions:

[
  {
    "code": "tin_required",
    "message": "Beneficiary at index 1 is missing a tax identification number",
    "docs_url": "https://docs.iron.xyz/errors#tin_required",
    "beneficiary_index": 1
  }
]

The response is always an array. Most checks stop at the first problem and return a single entry, the same as the plain-string behavior on earlier versions, but the four document-requirement checks (company_details_required, legal_presence_required, ownership_structure_required, control_structure_required) report every missing group at once: non-US Business submissions check all four independently, so more than one can genuinely be missing at the same time. Don’t assume exactly one entry; always iterate the array.

[
  { "code": "company_details_required", "message": "Company Details (state registry excerpt, certificate of incorporation, or certificate of good standing)", "docs_url": "https://docs.iron.xyz/errors#company_details_required", "beneficiary_index": null },
  { "code": "legal_presence_required", "message": "Legal Presence (memorandum/articles of incorporation)", "docs_url": "https://docs.iron.xyz/errors#legal_presence_required", "beneficiary_index": null }
]

code · string · required

Machine-readable identifier. One of the fixed set of values documented below. Safe to match on in code; it does not change across submissions the way message does.

message · string · required

Human-readable description of this specific occurrence of the error, for example naming the exact field or beneficiary involved. Useful for logs and support tickets, but don’t pattern-match on it: it can be reworded without notice. Match on code instead.

docs_url · string · required

Link back to this page, anchored to the specific code (https://docs.iron.xyz/errors#<code>).

beneficiary_index · integer

Zero-based index into company_data.beneficiaries identifying which beneficiary the error originated from. Present only on Business submissions, and only when the error is scoped to a specific beneficiary rather than the submission as a whole.

Callers on an earlier or unversioned X-API-Version keep receiving today’s plain error string on 400, unchanged. The structured array is opt-in via the version header. See API Versions.

Link identifications never return this shape. A Link submission only opens a hosted flow, so it has nothing to validate synchronously at creation.

invalid_request

A catch-all for straightforward, client-preventable problems: a required field was left empty, a value doesn’t match the expected format (email, phone, country code, date), a file exceeds its size limit, or too many documents or beneficiaries were submitted. Check message for the specific field and reason. Add client-side validation for the same rule so your integration catches it before it reaches the API.

selfie_required

The submission is missing a selfie where one is required. Every Director beneficiary on a Business submission needs one, and every Person submission needs one, in any country. Capture and submit a selfie along with selfie_collected_at.

selfie_expired

A selfie was provided, but it’s too old to accept: for Person submissions, older than 6 months. Capture a fresh selfie and resubmit.

tin_required

A tax identification number is missing where one is required. On a Business submission, this applies to any beneficiary with the Director or UltimateBeneficialOwner role, in any country. On a Person submission, it applies when the identity document’s issuing country (identity.identity_country_code) is US, regardless of the person’s residential address. Provide tax_identification_number, and tax_residence_country if the identity document’s country isn’t already US.

identity_document_rejected

The identity document type provided isn’t accepted for this submission. ResidencePermit is never accepted. Beneficiaries of US companies (except sole proprietorships) must use Passport or a US-issued DriverLicense, no other type. DigitalDriversLicense is only accepted when the identity document’s issuing country (identity.identity_country_code) is BRA, on both Person submissions and Business beneficiaries. Resubmit with an accepted document type.

identity_document_images_identical

The front and back images submitted for an identity document are byte-identical, which almost always means the same image was uploaded twice by mistake. Capture and submit distinct front and back images.

structure_invalid

The beneficiary or ownership structure on a Business submission violates a structural rule, for example: a sole proprietorship submitted with more than one beneficiary, or one that doesn’t own 100%; no root-level beneficiary holding the Director role, or no root-level beneficiary owning 25% or more (or 10% or more, if nobody owns 25% or more) — both required for any company other than a sole proprietorship, in every country, and neither satisfied by a Representative-only beneficiary regardless of their disclosed share_percentage (Iron never independently verifies a Representative-only beneficiary’s identity); or combined shares of qualifying owners (any UltimateBeneficialOwner, or any other non-Representative-only beneficiary) exceeding 100%. Check message for the specific rule and adjust the company_data.beneficiaries array.

attestation_invalid

The beneficial-ownership attestation is missing or invalid on a US Business submission. US companies, other than sole proprietorships, need exactly one root-level beneficiary with the Director role marked attesting_party: true and a past attested_at timestamp, certifying the submitted ownership information. Check message for the specific problem: a missing attesting party, more than one, or one without the Director role or not at the root.

cdd_certification_invalid

Iron generates a beneficial-ownership certification document for US Business submissions automatically, and the submitted data can’t produce it. Common causes: a beneficiary is missing a required identity or tax number, or the submitted text can’t be rendered into the document. Check message for the specific gap and provide the missing data. Note that a submission with no beneficiary owning 25% or more is not itself an error — the certification’s ownership section falls back to listing 10%+ owners instead; having nobody at either threshold is rejected separately, as structure_invalid. See Company Documents.

business_description_insufficient

business_model_description in the business questionnaire is shorter than 80 characters (after trimming leading and trailing whitespace). This applies to every industry, not only specific ones. Expand the description and resubmit.

industry_required

The business questionnaire’s industry field is missing. It’s required from X-API-Version: 2026-08-01 onward. industry_type alone is no longer sufficient. Provide business_details.industry. See Business Questionnaire.

miscellaneous_industry_deprecated

business_details.industry was submitted as Miscellaneous. That value is no longer accepted, on any submission, however detailed business_model_description is. Pick the closest specific value from industry values and resubmit.

The check reads the industry field only. The deprecated industry_type field’s own catch-all values, Other and NonProfitAndCharitable, still pass validation, but both resolve to Miscellaneous internally and are sent for review that way. That slows the review and can produce a request for more information later. Send a specific industry instead of relying on either.

prohibited_industry

The company’s resolved industry is on Iron’s prohibited-industries list: resolved from industry, or from industry_type on submissions still using the deprecated field. The company isn’t eligible for onboarding under this classification. See Prohibited Industries for the full list. No industry_type value currently resolves to a prohibited industry, so in practice this code only fires on industry.

foundation_intended_use_not_supported

A company with company_type PrivateFoundation was submitted with a purpose_and_intended_use Iron doesn’t support for that entity type. Foundations face additional restrictions on eligible account purposes. See Foundations to discuss whether onboarding is possible for your use case.

funds_flow_disclosure_required

The questionnaire indicates the company sends funds on behalf of customers (sends_funds_on_customer_behalf: true), which requires supporting disclosure that wasn’t fully provided. Include a description, a flow-of-funds diagram, and a source-of-funds document together.

license_details_required

The questionnaire indicates the company holds licenses or registrations (has_licenses_or_registrations: true), which requires details that weren’t provided. Provide license_details.

company_details_required

The company’s “Company Details” document group is missing: a state registry excerpt, a certificate of incorporation, or a certificate of good standing. Required on every Business submission, US and non-US alike: the root company or a nested beneficiary company. Check message (and beneficiary_index, if present) for which company is affected. Rejected outright with no resume URL, for every country. See Company Documents.

legal_presence_required

The company’s “Legal Presence” document (memorandum or articles of incorporation) is missing. Non-US Business submissions only. US submissions never require this group. See Company Documents.

ownership_structure_required

The company’s “Ownership Structure” document group is missing: a shareholder registry, information statement, trust agreement, or certificate of incumbency. On a US Business submission this is satisfied automatically by the beneficial-ownership certification Iron generates on your behalf (see cdd_certification_invalid), so in practice you’ll only see this code on non-US submissions or nested beneficiary companies. See Company Documents.

control_structure_required

The company’s “Control Structure” document group is missing: a directors registry, information statement, trust agreement, or certificate of incumbency. Non-US Business submissions only. US submissions never require this group. See Company Documents.

ubo_country_prohibited

A beneficiary with the UltimateBeneficialOwner role has a residential address (address.country) in a country Iron’s compliance policy prohibits for business KYB. Check beneficiary_index for which beneficiary is affected: the root company’s beneficiaries array or a nested beneficiary company’s. This isn’t the same as a country simply being unrated: a beneficiary in a country Iron hasn’t assessed yet is not rejected on that basis alone. There’s no self-service fix. The business can’t onboard with this beneficiary as a UBO from this address.

ubo_share_below_threshold

A beneficiary whose only role is UltimateBeneficialOwner doesn’t meet the disclosure threshold for their company (or nested company) — 25% if any beneficiary at that level owns 25% or more, otherwise 10% if any beneficiary there owns 10% or more, otherwise nobody at that level qualifies — and has no other role to be reported under instead. Check beneficiary_index for which beneficiary is affected. If this person also holds another role on the company (for example Director), submit them with that role instead of, or in addition to, UltimateBeneficialOwner. A beneficiary below the threshold with an additional role is accepted, just without the UltimateBeneficialOwner tag.

proof_of_address_required_for_edd

A Person submission included edd_questionnaire without a proof-of-address document. Enhanced Due Diligence requires one. Include a ProofOfAddress document alongside the EDD questionnaire.

outsourcing_agreement_not_signed

Your outsourcing agreement with Iron isn’t signed yet, so data-carrying identifications can’t be processed via the API for this customer type. This is an account configuration issue, not a data problem: contact your Iron partnership representative to get it signed.

uk_customers_not_enabled

Your account isn’t enabled to onboard UK-resident (Person) or UK-registered (Business) customers. Contact your Iron partnership representative if you expect to onboard UK customers.

duplicate_upload_blocked

The verification provider temporarily blocked a duplicate upload of file content that’s byte-identical to a very recent upload. This is transient: retry the same submission and it succeeds shortly after.

provider_rejected_document

The verification provider rejected a submitted document, for example because it was corrupted, too blurry to read, or the wrong type for the requested document category. Check message for the provider’s specific rejection reason and resubmit with a corrected file.

reuse_rejected

A Token submission tried to reuse an existing verified identity via a share token, and the referenced identity isn’t eligible for reuse: it isn’t approved, its email doesn’t match, or it fails an age restriction. Check message for the specific reason. The customer will most likely need to complete a fresh identification instead of reusing this one.