# Identity Retrieval

Enables retrieval of detailed information about a specific identity using the unique identityReference.

Endpoint: GET /eapi/v0/identities/{identity_reference}
Version: 0 BETA
Security: HMACAuth

## Security:

  - `HMACAuth` (unknown)
    apiKey in header Authorization

## Path parameters:

  - `identity_reference` (string, required)
    The identity reference to retrieve data for.

## Query parameters:

  - `email` (string)
    Optional email address to assist with identity matching.

## Response 200:

  - `200` (unknown)
    Successful identity response

## Response 200 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

  - `account` (object, required)

  - `account.blocked` (boolean, required)
    The account status
    Example: false

  - `account.exists` (boolean, required)
    Indicated wether the account exists
    Example: true

  - `account.createdAt` (string | null, required)
    The UTC date time of the identity. Null if identity does not exist.
    Example: 2023-06-05T19:53:08.320Z

  - `kyc` (object, required)
    Reflects the verification status of identity documents submitted through Banxa's identity provider. This status is updated based on document and liveness verification only — it does not account for Lite tier data, supplementary fields (e.g. purpose of transaction, occupation), or overall transaction eligibility. Use the eligibility endpoint to determine whether a customer can transact.

  - `kyc.status` (string, required)
    The verification outcome of the customer's submitted identity documents (selfie + document), as processed by Banxa's identity provider. APPROVED indicates that document and liveness verification passed. It does not indicate that all required data for a given transaction has been collected or that the customer is eligible to transact.
    Enum: "PENDING", "UNDER_REVIEW", "ACTION_REQUIRED", "VERIFIED", "REJECTED"

## 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 429:

  - `429` (unknown)
    Rate limit exceeded.
**Rate Limits**:
- General API: 100 requests per minute
- Price endpoint: 60 requests per minute

**Action**: Wait for the duration specified in `Retry-After` header before retrying.

## Response 429 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Too Many Requests. Please try again later.

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

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

## Response 429 headers (application/json):

  - `Retry-After` (integer)
    Number of seconds to wait before retrying.

**Important**: Always respect this header to avoid further rate limiting.
    Example: 60

## 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 200 examples:

  - `Existing verified identity` (unknown)
    Identity exists with verified KYC data on file. Note: VERIFIED status means the identity data we have is validated, but does not guarantee transaction eligibility. Check the eligibility endpoint before allowing transactions.

  - `Blocked identity` (unknown)
    Identity exists but has been blocked

  - `New identity (not yet created)` (unknown)
    Identity does not exist in the system