Onboarding Lifecycle

Iron gives you full visibility into your customer onboarding: clear status at every stage, written feedback from our compliance team when something needs fixing, and real-time insight into your customer’s payment abilities.

Steps to Onboard and Activate a Customer

Create a new customer

POST /api/customersCreate a customer record. The customer is created in IdentificationRequired status.

API Example

curl --request POST \
     --header 'content-type: application/json; charset=utf-8' \
     --header 'idempotency-key: <unique-request-id>' \
     --header 'x-api-key: <your-api-key>' \
     --data '{"name": "new_amazing_customer", "email": "customer@example.com", "customer_type": "Person"}' \
     --url 'https://api.sandbox.iron.xyz/api/customers'

Verify the customer's identity

POST /api/customers/{id}/identifications/v2Create an identification using one of these methods:

Hosted Iron KYC link
SumSub token sharing
Outsourcing

This endpoint is not an upsert. Every call creates a new identification record, and the newest record drives the customer’s status. If you create a new identification while another is in flight, the customer resets to IdentificationRequired and the older identification stops counting, even if it is approved later.Create one identification, then wait for it to reach a terminal status (Approved, Declined, or Expired) before creating another. To track progress, subscribe to the identification_status webhook or poll GET /api/customers/{id}/identifications. Never re-call this endpoint to refresh status.

API Example

curl --request POST \
     --header 'accept: application/json; charset=utf-8' \
     --header 'idempotency-key: <unique-request-id>' \
     --header 'x-api-key: <your-api-key>' \
     --url 'https://api.sandbox.iron.xyz/api/customers/<customer_id>/identifications/v2' \
     --data '{"type": "Link"}'

KYC is approved

Once approved, the customer status transitions to SigningsRequired.

Customer signs required documents

GET /api/customers/{id}/required-signingsRetrieve the required documents and present them to your customer. Mark each as signed via POST /api/customers/{id}/signings.

API Example

curl --request GET \
     --header 'accept: application/json; charset=utf-8' \
     --header 'x-api-key: <your-api-key>' \
     --url 'https://api.sandbox.iron.xyz/api/customers/<customer_id>/required-signings'

curl --request POST \
     --header 'accept: application/json; charset=utf-8' \
     --header 'idempotency-key: <unique-request-id>' \
     --header 'x-api-key: <your-api-key>' \
     --data '{
       "content_id": "<id_from_required_signings>",
       "signed": true
     }' \
     --url 'https://api.sandbox.iron.xyz/api/customers/<customer_id>/signings'

Example response from required-signings:

[
  {
    "display_name": "Terms and Conditions",
    "id": "019ababb-ddd6-7f02-8f5d-7469a0e8afb6",
    "url": "https://example.com/terms-and-conditions"
  }
]

Pass the url to your customer for review. The signing request takes content_id (the id from required-signings) and signed: true.

Customer is activated

Once all required signings are complete, the customer status becomes Active.

Check payout rail availability

abilities.fiat_payout is nested by currency, then by rail. Check the specific rail you plan to use, for example abilities.fiat_payout.usd.ach === "Active", before initiating payouts.

{
  "fiat_payout": {
    "usd": { "ach": "Active", "wire": "Active", "rtp": "Pending", "fednow": "Unavailable", "swift": "Active" },
    "eur": { "sepa": "Active", "swift": "Active" },
    "gbp": { "fps": "Active", "chaps": "Active", "swift": "Active" }
  }
}

Each rail also has a _thirdparty variant (e.g. ach_thirdparty) for payouts to a third party. The abilities object also returns fiat_deposit with the same shape and a currencies array listing the flows (mint, redeem, onramp, offramp, swap) available per currency.

Before an active customer can transact, register their wallet addresses for Travel Rule compliance. Self-hosted wallets register with a signed proof-of-ownership message, or, for US and Rest of World customers, by self-attestation. See the Crypto Addresses guide.

A customer’s status may revert from Active to SigningsRequired or IdentificationRequired if new compliance actions are required (e.g. updated terms and conditions, fraud review, enhanced due diligence).

Handling Missing Information

If an identification is incomplete, the customer’s status is IdentificationRequired and a url is returned on the Identification object. Redirect your customer to this URL. It opens a hosted step-up flow that collects only the missing data. This occurs when:

A data point is found to be invalid, expired, or inconsistent
A limit triggers additional due diligence requirements
A Business submission is created without all required documents or beneficiary proofs of address (see Incomplete Submissions)

Mapping Onboarding Statuses in Your App

Use the customer’s status and identification_status together to drive a three-stage progress stepper. Both fields are returned on the customer object.

`status`	`identification_status`	Stage	What to show
`IdentificationRequired`	None	Submission	Prompt customer to start KYC
`IdentificationRequired`	`Pending`	Submission	Prompt customer to complete KYC
`IdentificationRequired`	`Expired`	Submission	Previous attempt expired. Prompt to restart
`IdentificationRequired`	`Declined`	Submission	Show `review_comment`, prompt to retry
`IdentificationRequired`	`Processed`	Compliance Review	Show waiting state. No customer action needed
`IdentificationRequired`	`PendingReview`	Compliance Review	Show waiting state. Under active review
`SigningsRequired`	`Approved`	Activation	KYC approved. Present required documents to sign
`Active`	`Approved`	Complete	Fully onboarded. Customer can transact

Typical compliance review turnaround is 24-48 hours. Customers can re-enter SigningsRequired at any time (e.g. updated terms). Use the abilities endpoint to confirm the specific banking rail you need is Active (e.g. abilities.fiat_payout.usd.ach). That’s when the customer is truly ready to transact.

Tracking EDD Status

Each identification includes a with_edd field that indicates whether Enhanced Due Diligence was applied. This field is an optional boolean:

true: EDD was triggered (either by the partner or automatically by Iron’s AML checks)
false: EDD was explicitly not required
null: Identification was created before this feature was available

with_edd can be set in two ways:

Partner-initiated. Pass with_edd: true (Link flow) or include edd_questionnaire (Token/Person flow) when creating the identification. See Proactively Increasing Customer Limits.
Automatically by Iron. If AML checks determine EDD is required (e.g. customer resides in a high-risk jurisdiction), Iron sets with_edd to true server-side.

Use status and with_edd together to understand where a customer is in the verification process:

`status`	`with_edd`	Meaning
`Pending`	`null` / `false`	Standard KYC in progress
`Pending`	`true`	EDD flow in progress
`PendingReview`	`null` / `false`	Standard KYC under manual review
`PendingReview`	`true`	EDD complete at verification provider, awaiting compliance review
`Approved`	`null` / `false`	Standard KYC approved, no EDD
`Approved`	`true`	Approved through EDD
`Declined`	`null` / `false`	Standard KYC rejected
`Declined`	`true`	Rejected after EDD review

Edge Cases

`status`	Meaning
`Suspended`	Blocked. Can happen at any stage. Contact support.
`UserRequired`	Partner-area user must be created first. Only applies if `requires_user` is enabled.

Displaying Onboarding Comments to Your Customer

If a customer’s KYC submission is incomplete or needs correction, our onboarding team may provide written feedback explaining what needs to be improved. This feedback is available on the identification object via review_comment and step_status.*.comment fields. Display these comments to your customer so they know exactly what to fix before resubmitting. Show these comments when identification_status is Pending or Declined.

Do not display step_status results directly to the customer. The per-step breakdown (e.g. “identity: Declined, selfie: Approved”) creates confusion and support tickets. Instead, extract the comment fields and combine them into a single message.

Implementation example

Example identification response with feedback:

{
  "id": "abc-123",
  "status": "Declined",
  "with_edd": false,
  "review_comment": "Please provide a clearer photo of your ID.",
  "step_status": {
    "identity": { "result": "Declined", "comment": "Document is blurry", "retry": true },
    "selfie": { "result": "Approved", "comment": null, "retry": false },
    "questionnaire": { "result": "Approved", "comment": null, "retry": false }
  }
}

Extract and display all comments in a single message box:

function getVerificationMessages(identification: Identification): string[] {
  const messages: string[] = [];
  if (identification.step_status) {
    for (const step of Object.values(identification.step_status)) {
      if (step?.comment) { messages.push(step.comment); }
    }
  }
  if (identification.review_comment) {
    messages.push(identification.review_comment);
  }
  return messages;
}

API Endpoints

Endpoint	Purpose
`GET /api/customers/{id}`	Customer object with `status` and `identification_status`
`GET /api/customers/{id}/identifications`	Identifications with `status`, `step_status`, and `review_comment`
`GET /api/customers/{id}/abilities`	Customer capabilities: `fiat_deposit` and `fiat_payout` (nested by currency then rail) plus a `currencies` array

Status Reference

Customer Status

Returned on the customer object.

Status	Description
`IdentificationRequired`	Must complete KYC/KYB
`SigningsRequired`	Must sign required documents
`Active`	Fully onboarded. Can transact
`Suspended`	Blocked for compliance or fraud reasons
`UserRequired`	Partner-area user must be created first

Identification Status

Returned on each identification object.

Status	Description
`Pending`	Customer has not started, or a business submission is waiting on missing items (resume `url` set on the identification)
`Processed`	Documents submitted, awaiting review
`PendingReview`	Under compliance review
`Approved`	Approved
`Declined`	Rejected
`Expired`	Expired due to inactivity

Typical Flow: Pending → Processed → PendingReview → Approved / Declined The identification object also includes with_edd (boolean, nullable) to indicate whether EDD was applied. See Tracking EDD Status for the full interpretation table.

Ability Status

Returned on each rail leaf under abilities.fiat_payout and abilities.fiat_deposit (e.g. abilities.fiat_payout.usd.ach).

Status	Description
`Active`	Available for use
`Pending`	Activation in progress
`Unavailable`	Not offered for this customer
`Blocked`	Blocked for this customer
`Maintenance`	Temporarily unavailable

​Steps to Onboard and Activate a Customer

​Handling Missing Information

​Mapping Onboarding Statuses in Your App

​Tracking EDD Status

​Edge Cases

​Displaying Onboarding Comments to Your Customer

​API Endpoints

​Status Reference

​Customer Status

​Identification Status

​Ability Status

Steps to Onboard and Activate a Customer

Handling Missing Information

Mapping Onboarding Statuses in Your App

Tracking EDD Status

Edge Cases

Displaying Onboarding Comments to Your Customer

API Endpoints

Status Reference

Customer Status

Identification Status

Ability Status