Skip to main content
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:
The response is always an array. Today it contains exactly one entry — validation stops at the first problem it finds, the same as the plain-string behavior on earlier versions — but the array shape leaves room for returning multiple problems in one response in the future without another change to the response format. Don’t assume exactly one entry; iterate the array.
​
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.
​
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.
​
string
required
Link back to this page, anchored to the specific code (https://docs.iron.xyz/errors#<code>).
​
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. 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%; a nested business beneficiary with no Director; or combined ownership percentages 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: no beneficiary owns 25% or more, 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.

​
business_description_insufficient

The company is classified under a “Miscellaneous” industry_type, which requires a more detailed business_model_description than other industries: at least two sentences. Expand the description and resubmit.

​
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.

​
document_requirement_not_met

A required company document group is missing on a US Business submission. Unlike non-US businesses, which can be accepted with documents still missing and given a resume URL to complete later, a US submission is rejected outright when a required group is absent. Check message for which document category is missing, then resubmit with the complete document set. See Company Documents.

​
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.

​
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.