Skip to main content

​
Introduction

If your organization uses SumSub for KYC, you can enable token-based KYC data sharing with Iron through a tri-party agreement between Iron, your organization, and SumSub. This allows Iron to access applicant data already verified by you. Once the agreement is in place, you can:
  • Generate a SumSub share token for each applicant
  • Send the token to Iron via API along with a few additional parameters
If the shared data meets Iron’s standards, onboarding can be completed in seconds.

​
Integration

​
Generating Share Tokens with SumSub

​
1. Generate a SumSub Share Token

Use SumSub’s share token API to issue a one-time share token: 
curl --request POST \
  --url https://api.sumsub.com/resources/accessTokens/shareToken \
  --header 'Content-Type: application/json' \
  --data '{
    "applicantId": "YOUR_APPLICANT_ID",
    "forClientId": "iron.xyz",
    "ttlInSecs": 600
  }'
Response: 
{
  "token": "eyJhbGciOiJub25lIn0…",
  "forClientId": "iron.xyz"
}
The token is a short-lived string you pass to Iron using the Identification endpoint.

​
2. Request Parameters

Risk Tiers Iron operates a tiered KYC process. Applicants are categorized as Low, Medium, or High Risk based on:
  1. Nationality (Proof of Identity)
  2. Address (Proof of Address)
If an applicant is imported at the incorrect risk level, the identification will have a Pending state and we return a URL for the customer to supply the missing data.
For country risk levels, please reach out to us.
High Risk Requires a questionnaire with compliance questions and source of funds proof (base64 encoded). 
curl --request POST \
     --url https://api.sandbox.iron.xyz/api/customers/<customer_id>/identifications \
     --header 'X-API-Key: <your-api-key>' \
     --header 'IDEMPOTENCY-KEY: <unique-request-id>' \
     --header 'accept: application/json; charset=utf-8' \
     --header 'content-type: application/json; charset=utf-8' \
     --data '{
       "ip_address": "127.0.0.1",
       "token": "sumsub_token",
       "high_risk_questionnaire": {
         "employment_status": "Employed",
         "expected_monthly_volume": "LessThan1000",
         "monthly_income": "Between1000And2000",
         "source_of_funds": "SalaryAndWages",
         "source_of_funds_proof": "some-doc-as-base64"
       }
     }'
Medium Risk 
curl --request POST \
     --url https://api.sandbox.iron.xyz/api/customers/<customer_id>/identifications \
     --header 'X-API-Key: <your-api-key>' \
     --header 'IDEMPOTENCY-KEY: <unique-request-id>' \
     --header 'accept: application/json; charset=utf-8' \
     --header 'content-type: application/json; charset=utf-8' \
     --data '{
       "ip_address": "127.0.0.1",
       "token": "sumsub_token",
       "medium_risk_questionnaire": {
         "employment_status": "Employed",
         "expected_monthly_volume": "LessThan1000",
         "monthly_income": "Between1000And2000",
         "source_of_funds": "SalaryAndWages"
       }
     }'
Low Risk 
curl --request POST \
     --url https://api.sandbox.iron.xyz/api/customers/<customer_id>/identifications \
     --header 'X-API-Key: <your-api-key>' \
     --header 'IDEMPOTENCY-KEY: <unique-request-id>' \
     --header 'accept: application/json; charset=utf-8' \
     --header 'content-type: application/json; charset=utf-8' \
     --data '{
       "ip_address": "127.0.0.1",
       "token": "sumsub_token"
     }'

​
3. Response

Success (sufficient data) The identification status is Processing, indicating the applicant contains sufficient data. 
{
  "created_at": "2025-01-06T16:54:40.162807+00:00",
  "id": "9a667227-6992-4c6b-951e-63765d5d8f33",
  "status": "Processing",
  "updated_at": "2025-01-06T16:54:40.162807+00:00",
  "url": ""
}
Success (insufficient data) If the imported KYC data is insufficient, the status is Pending and a url is returned for the customer to provide missing information. 
{
  "created_at": "2025-01-06T16:54:40.162807+00:00",
  "id": "9a667227-6992-4c6b-951e-63765d5d8f33",
  "status": "Pending",
  "updated_at": "2025-01-06T16:54:40.162807+00:00",
  "url": "some_url_to_pass_to_end_customer"
}

​
4. Lifecycle and Webhooks

This process triggers a SumSub applicant import and requests to our banking providers. The Identification status may change quickly after import—ideally to Approved.
We strongly recommend subscribing to webhooks to track status changes.

​
5. Reliance vs. Token Sharing

There is overlap. In legal terms, “reliance” means Iron can fully rely on your KYC processes. We offer this, but by default we still run imported applicants through our own AML/Compliance checks. Once we confirm the quality of applicant data meets our standards, we can consider bypassing internal checks and fully embracing the reliance model.