Skip to main content

​
Steps to Onboard and Activate a Customer

1

Create a new customer

Customer is created in IdentificationRequired status.
2

Verify the customer's identity using one of these methods

  • Hosted Iron KYC link
  • SumSub token sharing
  • Outsourcing
3

KYC is approved

Customer status transitions to SigningsRequired.
4

Customer signs required documents

Retrieve and present required signings to the customer.
5

Customer is activated

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

​
Customer Status During Lifecycle

Onboarding Lifecycle
  1. IdentificationRequired: Customer has been created and needs to complete the KYC process.
  2. SigningsRequired: Customer has completed KYC and needs to review and sign required documents.
  3. Active: Customer has fulfilled all onboarding requirements and can access Iron services.
Status Reversion
  • To repeat the KYB/C process, initiate a new identification. This transitions the customer’s status to IdentificationRequired and blocks access until completed.
  • A customer’s status may revert from Active to SigningsRequired or IdentificationRequired if new compliance actions are required.
Handling Missing or Additional Information If a customer’s identification becomes incomplete, their status will move to IdentificationRequired and a URL will be made available on the Identification object. You can pass this URL to the customer to access an Iron hosted step up flow. The hosted flow presents a form where the customer provides the exact missing or additional information. Once the data is collected and approved, the customer status returns to Active. This situation occurs in the following cases:
  • A supplied data point is found to be invalid, expired, or inconsistent during processing
  • A customer reaches a limit that triggers additional due diligence requirements
In both cases, the backend updates the Identification with the hosted flow URL and marks the identification as incomplete until the required information is provided.

​
KYC Status

StatusDescription
PendingCustomer has not started the process
ProcessedCustomer has completed the input process
PendingReviewIdentification is ready for compliance review
ApprovedIdentification has been approved
RejectedIdentification has been rejected
Typical Flow: Pending → Processed → PendingReview → Approved / Rejected

​
Onboarding via API

1

Create a Customer

POST /customersThe customer is created immediately in IdentificationRequired status.
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"}' \
     --url 'https://api.sandbox.iron.xyz/api/customers'
2

Create an Identification

POST /customers/{id}/identifications/v2Create and complete a Link, Person, or Token identification.
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 '{}'
Once KYC is approved, the customer status transitions to SigningsRequired.
3

Retrieve Required Signings

GET /customers/{id}/required-signings
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'
Response:
[
  {
    "display_name": "Terms and Conditions",
    "id": "019ababb-ddd6-7f02-8f5d-7469a0e8afb6",
    "type": "Url",
    "url": "https://example.com/terms-and-conditions"
  }
]
Pass the url to your customer for review, similar to how you handle the KYC link.
4

Sign Documents

POST /customers/{id}/signingsMark each document as signed using the id and type from the required signings response.
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>",
       "content_type": "Url",
       "signed": true
     }' \
     --url 'https://api.sandbox.iron.xyz/api/customers/<customer_id>/signings'
Once all required signings are complete, the customer status becomes Active.

​
Onboarding via Partner Dashboard

You can also onboard customers directly in the Partner Dashboard:
1

Log In

Access the Partner Dashboard.
2

Navigate to Customers

Go to the “Customers” section and click the Onboard New button.
3

Create a Label

Assign a temporary label to identify the customer.
4

Generate a Signup Link

After creating the label, generate a signup link to share with the customer. They can complete the onboarding flow using Iron’s user interface.
Ensure you handle idempotency-key correctly to avoid duplicate operations. If additional information is needed, our compliance team will contact you directly.