# Identity Reliance

Share customer identity

Endpoint: POST /eapi/v0/identities/reliance
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

  - `mobileNumber` (string, required)
    Mobile number of the customer.
    Example: 61431000001

  - `email` (string, required)
    Email address of the customer.
    Example: test@bitcoin.com.au

  - `screeningDate` (string, required)
    The UTC screening date of the applicant.
    Example: 2023-06-05

  - `screeningSanctionsResult` (boolean, required)
    The result of the sanction screening.
    Example: true

  - `screeningPepResult` (boolean, required)
    The result of the PEP sanction screening.
    Example: true

  - `customerIdentity` (object, required)

  - `customerIdentity.givenName` (string, required)
    Customer's given / first name.
    Example: Joe

  - `customerIdentity.surname` (string, required)
    Customer's surname / last name.
    Example: Bloggs

  - `customerIdentity.dob` (string, required)
    Customer's date of birth (e.g. "1985-01-31"). Required to format as ISO 8601 Date format : YYYY-MM-DD.
    Example: 1990-01-31

  - `customerIdentity.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"

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

  - `customerIdentity.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

  - `customerIdentity.residentialAddress` (object, required)
    Customer's residential address. Required for identity verification and compliance purposes.
**Important**: This must be the customer's current residential address, not a PO Box or business address.

  - `customerIdentity.residentialAddress.addressLine` (string, required)
    Primary street address including street number and name.
**Examples**:
- "44 Gwynne Street"
- "123 Main Street, Apt 4B"
- "10 Downing Street"

**Requirements**:
- Must include street number and name
- Can include unit/apartment number
- Maximum 200 characters
    Example: 44 Gwynne Street

  - `customerIdentity.residentialAddress.suburb` (string, required)
    Suburb, city, or town name.
**Regional Variations**:
- Australia: Suburb (e.g., "Cremorne")
- USA: City (e.g., "New York")
- UK: Town/City (e.g., "London")
- Europe: City (e.g., "Paris")
    Example: Cremorne

  - `customerIdentity.residentialAddress.state` (string, required)
    State, province, or region code.
**Format**: Typically 2-3 character code
**Examples**:
- Australia: "VIC", "NSW", "QLD"
- USA: "CA", "NY", "TX" (required for US addresses)
- Canada: "ON", "BC", "QC"

**Note**: Required when country is "US"
    Example: VIC

  - `customerIdentity.residentialAddress.postCode` (string, required)
    Postal code, ZIP code, or postCode.
**Format varies by country**:
- Australia: 4 digits (e.g., "3121")
- USA: 5 digits or 5+4 format (e.g., "90210" or "90210-1234")
- UK: Alphanumeric (e.g., "SW1A 1AA")
- Canada: Alphanumeric (e.g., "K1A 0B1")
    Example: 3121

  - `customerIdentity.residentialAddress.country` (string, required)
    Two-letter ISO 3166-1 alpha-2 country code.
**Common Examples**:
- AU - Australia
- US - United States
- GB - United Kingdom
- CA - Canada
- NZ - New Zealand
- SG - Singapore

**Note**: The country must be supported by Banxa for the requested transaction type.
    Example: AU

  - `identityDocuments` (array, required)
    Collection of identity documents colected frofmo the customer. (array of objects)

  - `identityDocuments.type` (string)
    The type of document collected from the applicant.
    Enum: "DRIVING_LICENSE", "PASSPORT", "IDENTIFICATION"

  - `identityDocuments.data` (object)
    The document data collected from the customer.

  - `identityDocuments.data.number` (string)
    Identifier number from the document.
    Example: 123456789

## Request examples:

  - `Share verified identity data` (unknown)
    Share identity data that has been verified by another trusted party

## Response 202:

  - `202` (unknown)
    The identity sharing request has been accepted for processing

## 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)