SumSub Token Sharing

Share existing SumSub KYC data with Iron to onboard verified applicants in seconds.

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:

1. Prepare your SumSub applicant

   Ensure the applicant’s profile contains all required data — IP address, contact info, and address — before generating a share token.

2. Generate a share token

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

3. Submit the token to Iron

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

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

Preparing Your SumSub Applicant

Before generating a share token, you must ensure the applicant’s SumSub profile contains all the data Iron requires. Missing fields are the most common cause of failed or incomplete token shares.

IP Address

Iron requires the applicant’s IP address. You can provide it in one of three ways:

1. SumSub IP tracking — Enable SumSub’s IP address tracking so the IP is captured automatically during verification.
2. Metadata on the applicant — Store the IP as metadata on the SumSub applicant so it is included in the shared data.
3. Via the Iron API — Pass the ip_address field directly in your identification request to Iron.

If you use SumSub’s IP tracking, you do not need to pass ip_address in the Iron API call — Iron will read it from the shared applicant data.

Required Applicant Data

The following fields must be present on the SumSub applicant’s fixedInfo before sharing. If your KYC flow does not collect them, use SumSub’s Change Provided Info endpoint to PATCH them onto the applicant.

Field	Location	Description
phone	Top-level	Applicant’s phone number (e.g. [phone])
nationality	fixedInfo	ISO 3166-1 alpha-3 country code (e.g. DEU)
street	fixedInfo.addresses[]	Street address
town	fixedInfo.addresses[]	City
postCode	fixedInfo.addresses[]	Postal code
country	fixedInfo.addresses[]	ISO 3166-1 alpha-3 country code

Sample Applicant

Below is a representative SumSub applicant object showing the fields Iron needs. Fields extracted automatically by SumSub (document data, review results, questionnaires) are omitted for brevity.

{
  "clientId": "iron.xyz",
  "info": {
    "firstName": "John",
    "firstNameEn": "John",
    "lastName": "Doe",
    "lastNameEn": "Doe",
    "dob": "1990-01-11",
    "country": "DEU"
  },
  "fixedInfo": {
    "firstName": "John",
    "firstNameEn": "John",
    "lastName": "Doe",
    "lastNameEn": "Doe",
    "dob": "1990-01-11",
    "country": "DEU",
    "nationality": "DEU",
    "addresses": [
      {
        "street": "5 some street.",
        "streetEn": "5 some street.",
        "stateCode": "DE-BE",
        "town": "Berlin",
        "townEn": "Berlin",
        "postCode": "12345",
        "country": "DEU",
        "formattedAddress": "5 some street., Berlin, Germany, 10247"
      }
    ]
  },
  "email": "[e-mail]",
  "phone": "[phone]",
  "lang": "en",
  "type": "individual"
}

The fixedInfo block is the most important section — it contains the data that was provided by the customer and must be collected during your flow or PATCHed via the SumSub API. The info block is typically populated by SumSub’s document extraction and does not need manual intervention.

Integration

1. Generate a SumSub Share Token

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 — see IP address options
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
with_edd	boolean or null	Whether EDD was applied — true, false, or null for pre-feature identifications. See Tracking EDD Status
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",
  "with_edd": true,
  "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",
  "with_edd": true,
  "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.