SumSub Token Sharing

Introduction

If your organization already verifies customers through SumSub, you can share that verification data with Iron using a share token — no need for your customers to go through KYC again. This requires a tri-party agreement between Iron, your organization, and SumSub. Once signed, the integration is straightforward:

Generate a share token

Call SumSub’s API to create a one-time share token for your applicant.

Submit the token to Iron

Send the token to Iron’s identification endpoint with the required parameters.

Handle the response

If the data is sufficient, onboarding completes in seconds. If not, redirect the customer to complete the missing steps.

What Data Does Iron Expect?

At minimum, Iron expects the applicant data described in the standard onboarding requirements. The share token must carry enough verified data to satisfy these requirements. To ensure smooth onboarding and avoid any additional steps for your customer:

Include the KYC questionnaire in your request. This covers employment status, income, source of wealth, and transaction expectations — data that SumSub may not have collected.
Include the EDD questionnaire as well if you already know the customer will transact large amounts or resides in a higher-risk jurisdiction. This prevents a step-up flow later.

If any required data is missing, Iron returns a Pending status with a url. This URL opens a hosted SumSub flow that only asks for the missing information — not a full KYC redo. You should redirect your customer to this URL to complete onboarding. See handling missing information for details.

Integration

Use SumSub’s share token API to issue a one-time token. This call is made server-side using your SumSub credentials.

curl --request POST \
  --url https://api.sumsub.com/resources/accessTokens/shareToken \
  --header 'Content-Type: application/json' \
  --header 'X-App-Token: <your-sumsub-app-token>' \
  --data '{
    "applicantId": "YOUR_APPLICANT_ID",
    "forClientId": "iron.xyz",
    "ttlInSecs": 600
  }'

Share tokens are single-use — SumSub invalidates a token after it has been consumed. Generate a new token for each submission attempt.

2. Submit the Token to Iron

POST /api/customers/<customer_id>/identifications/v2

Headers

Header	Required	Description
`X-API-Key`	Yes	Your Iron API key
`Idempotency-Key`	Yes	A unique UUID. Prevents duplicate identifications if retried.
`X-Sub-Partner-ID`	No	Sub-partner UUID, if scoped to a sub-partner

Body Parameters

Parameter	Type	Required	Description
`type`	`"Token"`	Yes	Must be `"Token"`
`token`	string	Yes	The SumSub share token
`intended_use`	string	Yes	One of: `Investing`, `PaymentToFriendsFamilyorOthers`, `PurchaseDigitalAssets`, `OnlinePurchasesOfGoodsOrServices`, `Trading`
`ip_address`	string	No	Applicant IP. Optional if already captured via SumSub IP check
`kyc_questionnaire`	object	Recommended	See KYC questionnaire fields
`edd_questionnaire`	object	Recommended for high-risk	See EDD questionnaire fields

Basic Request

At minimum, provide the token and intended use:

curl --request POST \
     --url https://api.sandbox.iron.xyz/api/customers/<customer_id>/identifications/v2 \
     --header 'X-API-Key: <your-api-key>' \
     --header 'Idempotency-Key: <unique-request-id>' \
     --header 'content-type: application/json; charset=utf-8' \
     --data '{
       "type": "Token",
       "token": "sumsub_token",
       "intended_use": "Investing",
       "ip_address": "203.0.113.42"
     }'

With KYC Questionnaire

Include the questionnaire to avoid the customer being redirected to a step-up flow:

curl --request POST \
     --url https://api.sandbox.iron.xyz/api/customers/<customer_id>/identifications/v2 \
     --header 'X-API-Key: <your-api-key>' \
     --header 'Idempotency-Key: <unique-request-id>' \
     --header 'content-type: application/json; charset=utf-8' \
     --data '{
       "type": "Token",
       "token": "sumsub_token",
       "intended_use": "Investing",
       "ip_address": "203.0.113.42",
       "kyc_questionnaire": {
         "employment_status": "Employed",
         "yearly_gross_income": "From50001To60000",
         "source_of_wealth": "Salary",
         "expected_monthly_transaction_count": "Between5And10",
         "expected_monthly_transaction_volume": "MoreThan500LessThan2000"
       }
     }'

With KYC + EDD Questionnaire

If the customer resides in a higher-risk jurisdiction or will transact large amounts, include both to complete onboarding in one step:

curl --request POST \
     --url https://api.sandbox.iron.xyz/api/customers/<customer_id>/identifications/v2 \
     --header 'X-API-Key: <your-api-key>' \
     --header 'Idempotency-Key: <unique-request-id>' \
     --header 'content-type: application/json; charset=utf-8' \
     --data '{
       "type": "Token",
       "token": "sumsub_token",
       "intended_use": "Investing",
       "ip_address": "203.0.113.42",
       "kyc_questionnaire": {
         "employment_status": "Employed",
         "yearly_gross_income": "From50001To60000",
         "source_of_wealth": "Salary",
         "expected_monthly_transaction_count": "Between5And10",
         "expected_monthly_transaction_volume": "MoreThan500LessThan2000"
       },
       "edd_questionnaire": {
         "occupation": "FinancialServices",
         "approximate_net_worth": "Between100001And300000",
         "source_of_funds_proof": "<base64-encoded-document>"
       }
     }'

KYC Questionnaire Fields

Field	Values
`employment_status`	`Employed`, `SelfEmployed`, `Unemployed`, `Retired`, `Student`
`yearly_gross_income`	`LessThan20000`, `From20001To30000`, `From30001To40000`, `From40001To50000`, `From50001To60000`, `From60001To70000`, `From70001To80000`, `From80001To90000`, `From90001To100000`, `From100001To110000`, `From110001To120000`, `From120001To130000`, `From130001To140000`, `From140001To150000`, `MoreThan150000`
`source_of_wealth`	`Salary`, `Savings`, `Investments`, `CryptoTrading`, `Other`
`expected_monthly_transaction_count`	`LessThan5`, `Between5And10`, `MoreThan10`
`expected_monthly_transaction_volume`	`LessThan500`, `MoreThan500LessThan2000`, `MoreThan2000`

EDD Questionnaire Fields

Field	Values
`occupation`	`Agriculture`, `ArtsAndEntertainment`, `Construction`, `Education`, `FinancialServices`, `InformationAndTechnology`, `Retail`, `RealEstate`, `Other`
`approximate_net_worth`	`UpTo25000`, `Between25001And50000`, `Between50001And100000`, `Between100001And300000`, `Between300001And500000`, `Between500001And1000000`, `Over1000001`
`source_of_funds_proof`	Base64-encoded document (jpg, png, pdf, doc, docx, xls, xlsx, odt, ods, txt). Max 10 MB.

3. Handle the Response

The endpoint returns an Identification object:

Field	Type	Description
`id`	string (UUID)	Unique identification ID
`customer_id`	string (UUID)	The customer this identification belongs to
`status`	string	Current status — see Identification Lifecycle
`url`	string or null	If `Pending`, redirect the customer to this URL to complete missing steps
`created_at`	string (ISO 8601)	Creation timestamp
`updated_at`	string (ISO 8601)	Last update timestamp

Sufficient data — onboarding proceeds immediately:

{
  "id": "9a667227-6992-4c6b-951e-63765d5d8f33",
  "customer_id": "c5f2e8a1-3b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "status": "Processed",
  "url": null,
  "created_at": "2025-01-06T16:54:40.162807+00:00",
  "updated_at": "2025-01-06T16:54:40.162807+00:00"
}

Insufficient data — redirect the customer to complete the missing information:

{
  "id": "9a667227-6992-4c6b-951e-63765d5d8f33",
  "customer_id": "c5f2e8a1-3b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "status": "Pending",
  "url": "https://in.sumsub.com/idensic/l/#/...",
  "created_at": "2025-01-06T16:54:40.162807+00:00",
  "updated_at": "2025-01-06T16:54:40.162807+00:00"
}

Error Responses

Status	Cause
`400`	Missing `Idempotency-Key`, invalid body, or `source_of_funds_proof` exceeds 10 MB
`401`	Invalid API key or missing `CreateIdentification` permission
`404`	Customer not found
`409`	An identification is already in progress for this customer

4. Identification Lifecycle

Status	Description
`Pending`	Waiting for the end-user to complete missing steps via the returned URL
`Processed`	Data submitted and verification is underway
`PendingReview`	Under manual review by the compliance team
`Approved`	Identification approved — customer is verified
`Declined`	Identification declined
`Expired`	Identification expired due to inactivity

In the best case, an applicant with sufficient data moves from Processed to Approved within seconds.

Subscribe to the identification_status webhook to track status changes in real time rather than polling.

Introduction

Orchestration

Issuance

Use Cases

Coverage

Contact Us

SumSub Token Sharing

Introduction

What Data Does Iron Expect?

Integration

2. Submit the Token to Iron

Basic Request

With KYC Questionnaire

With KYC + EDD Questionnaire

KYC Questionnaire Fields

EDD Questionnaire Fields

3. Handle the Response

4. Identification Lifecycle

Introduction

Orchestration

Issuance

Use Cases

Coverage

Contact Us

​Introduction

​What Data Does Iron Expect?

​Integration

​1. Generate a SumSub Share Token

​2. Submit the Token to Iron

​Basic Request

​With KYC Questionnaire

​With KYC + EDD Questionnaire

​KYC Questionnaire Fields

​EDD Questionnaire Fields

​3. Handle the Response

​4. Identification Lifecycle

Introduction

What Data Does Iron Expect?

Integration

1. Generate a SumSub Share Token

2. Submit the Token to Iron

Basic Request

With KYC Questionnaire

With KYC + EDD Questionnaire

KYC Questionnaire Fields

EDD Questionnaire Fields

3. Handle the Response

4. Identification Lifecycle