# Identity token sharing (sumsub)

Share customer identity

Endpoint: POST /eapi/v0/identities/share/token
Version: 0 BETA
Security: HMACAuth

## Security:

  - `HMACAuth` (unknown)
    apiKey in header Authorization

## Request fields (application/json):

  - `identityReference` (string, required)
    A unique customer identifier provided by the partner. This field is required and must be unique for each customer.
**Important**: You must consistently reuse the same identityReference for repeat interactions with the same customer, allowing Banxa to reliably recognize and associate their identity across multiple transactions.
**Format Requirements**:
- Only ASCII letters (a-z, A-Z), digits (0-9), and hyphens (-) are allowed
- Must be between 1 and 255 characters
- Case-sensitive

**Best Practices**:
- Use a consistent format across your system
- Consider using a prefix to identify your organization (e.g., 'partner-customer-123')
- Do not include personally identifiable information (PII) in the reference
- Store the mapping between your internal customer ID and this reference securely
    Example: c-13344

  - `email` (string, required)
    The customer email
    Example: user@banxa.com

  - `mobileNumber` (string)
    Mobile phone number in international format (E.164).
**Format**: Include country code with + prefix
**Examples**:
- "+61431000001" (Australia)
- "+14155552671" (USA)
- "+442071234567" (UK)

**Requirements**:
- Must be a valid, active mobile number
- Used for SMS verification if needed
- Maximum 20 characters
    Example: 61410001000

  - `taxIdType` (string)
    The category of tax or government identifier supplied in `taxId`. The correct value depends on the customer's country and the identifier type accepted for that country.
| Value | Description |
|  --- | --- |
| `identity_card` | A government-issued identity card number used for identity or tax reporting in the customer's country. |
| `tax_id` | A tax identification number issued by a tax authority, such as a TFN, TIN, ITIN, or equivalent. |
| `national_number` | A national, citizen, resident, or social insurance number used to identify an individual in their country. |
| `ssn` | A Social Security Number, generally used for US individuals. |
    Enum: "identity_card", "tax_id", "national_number", "ssn"

  - `taxId` (string)
    Tax identification number.
See [TIN validation](https://docs.banxa.com/products/native-api/docs/compliance/tin-validation).
    Example: 123-11-123

  - `taxState` (string)
    Tax state or region if applicable.(associated with the taxId) Required format as two characters. Note; We do not accept any states where Banxa is not licensed.
    Example: IL

  - `provider` (object, required)

  - `provider.vendor` (string, required)
    The KYC provider e.g. sumsub
    Enum: "sumsub"

  - `provider.token` (string, required)
    Arbitrary string
    Example: eyJhbGciOiJub25lIn0.eyJqdGkiOiJfYWN0LTZmODI2ZTU0LTE2MzctNDViMS05NzMyLWY1MjZiN2YxNWE3YyIsInVybCI6Imh0dHBzOi8vYXBpLnN1bXN1Yi5jb20ifQ.

## Request examples:

  - `Share Sumsub KYC token` (unknown)
    Share existing KYC verification from Sumsub

## Response 202:

  - `202` (unknown)
    The identity sharing request has been accepted for processing, but the processing has not been finished yet.

## Response 202 fields (application/json):

  - `identityReference` (string, required)
    A unique customer identifier provided by the partner. This field is required and must be unique for each customer.
**Important**: You must consistently reuse the same identityReference for repeat interactions with the same customer, allowing Banxa to reliably recognize and associate their identity across multiple transactions.
**Format Requirements**:
- Only ASCII letters (a-z, A-Z), digits (0-9), and hyphens (-) are allowed
- Must be between 1 and 255 characters
- Case-sensitive

**Best Practices**:
- Use a consistent format across your system
- Consider using a prefix to identify your organization (e.g., 'partner-customer-123')
- Do not include personally identifiable information (PII) in the reference
- Store the mapping between your internal customer ID and this reference securely
    Example: c-13344

## Response 400:

  - `400` (unknown)
    Bad request due to invalid input.
**Common Causes**:
- Malformed JSON in request body
- Invalid data types
- Missing required fields
- Invalid request structure

## Response 400 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Bad Request

  - `code` (integer)
    HTTP status code
    Example: 400

  - `traceId` (string)
    Unique identifier for this error instance. Use this when contacting support.
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 401:

  - `401` (unknown)
    Authentication failed or missing credentials.
**Common Causes**:
- Missing Authorization header
- Invalid API key
- Expired or invalid HMAC signature
- Incorrect timestamp (must be within 5 minutes of server time)

## Response 401 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Unauthenticated.

  - `code` (integer)
    HTTP status code
    Example: 401

  - `traceId` (string)
    Unique identifier for this error instance
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 404:

  - `404` (unknown)
    The requested resource was not found.
**Common Causes**:
- Invalid ramp ID
- Invalid identity reference
- Resource has been deleted
- Incorrect endpoint URL

## Response 404 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Not Found

  - `code` (integer)
    Error code (may be HTTP status or custom code)
    Example: 500100

  - `traceId` (string)
    Unique identifier for this error instance
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 422:

  - `422` (unknown)
    Validation error - request is well-formed but contains invalid data.
**Common Causes**:
- Field validation failures
- Business rule violations
- Invalid field combinations
- Out of range values

## Response 422 fields (application/json):

  - `message` (string)
    Summary of validation errors
    Example: The given data was invalid.

  - `errors` (object)
    Map of field names to error messages.
**Format**: Each key is a field name, value is an array of error messages for that field.
    Example: {"email":["The email field is required."],"fiatAmount":["The fiat amount must be at least 10."]}

  - `code` (integer)
    HTTP status code
    Example: 422

  - `traceId` (string)
    Unique identifier for this error instance
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 500:

  - `500` (unknown)
    Unexpected server error.
**Action**:
- Retry with exponential backoff (up to 3 attempts)
- If error persists, contact support with the traceId

**Note**: This is a temporary issue on our side, not a problem with your request.

## Response 500 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Server Error

  - `code` (integer)
    HTTP status code
    Example: 500

  - `traceId` (string)
    Unique identifier for this error instance. **Important**: Include this when contacting support.
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 202 examples:

  - `Request accepted for processing` (unknown)