# Get a list of identities

Retrieve identities for your organization with optional filters.
Use `limit` and `next-token` for pagination. The response includes a `data` array and an optional `nextToken`.

Endpoint: GET /v3/identities
Version: 2026.04
Security: Bearer

## Security:

  - `Bearer` (unknown)
    http bearer JWT

## Query parameters:

  - `payment-role` (string)
    Filter by payment role.

  - `nick-name` (string)
    Filter by nickname.

  - `limit` (integer)
    Maximum number of identities to return. Default value is 10, maximum is 100.

  - `next-token` (string)
    Opaque token to fetch the next page of results.

## Response 200:

  - `200` (unknown)
    A page of identities.

## Response 200 fields (application/json):

  - `data` (array)
    The list of the identities that match the query parameters

  - `data.identityId` (string, required)
    The unique ID of the identity
    Example: 2f4ac57f-c5ba-4051-b51f-b3565778717b

  - `data.identityType` (string, required)
    The type of the identity
    Example: BUSINESS

  - `data.paymentRole` (string, required)
    The payment role of the identity
    Example: BENEFICIARY

  - `data.createdAt` (string, required)
    The time at which the identity was created
    Example: 2023-11-02T18:26:00.000Z

  - `data.updatedAt` (string, required)
    The time at which the identity was last updated
    Example: 2023-11-03T18:26:00.000Z

  - `data.identityState` (string, required)
    The state of the identity
* ACTIVE
* DEACTIVATED
    Example: ACTIVE

  - `data.nickName` (string)
    The nickname for the identity provided at the time of identity creation
    Example: nickName

  - `data.internalId` (string)
    The client-provided unique identifier supplied when the identity was created or last updated.
    Example: customer-12345-uuid

  - `data.tags` (array)
    Tags are used to categorize the identity.

  - `data.version` (integer, required)
    The version number of the identity
    Example: 2

  - `data.schemaVersion` (string, required)
    The version of the schema
    Example: 1.0.0

  - `nextToken` (string)
    The token to retrieve the next page of results

## Response 400:

  - `400` (unknown)
    Invalid request.

## Response 400 fields (application/json):

  - `status` (integer, required)
    The HTTP status code of the error
    Example: 404

  - `errors` (array, required)

  - `errors.code` (string, required)
    Unique identifier of an error
    Example: SYS_100

  - `errors.title` (string, required)
    Error message providing a brief summary of the error
    Example: No identity exists for identityId

  - `errors.type` (string, required)
    Identifies the problem type
    Example: USER_VALIDATION_ERROR

  - `errors.description` (string, required)
    Provides more technical information
    Example: Unable to get identity. Identity ID should be in UUID format

  - `errors.timestamp` (string, required)
    The time when this error occurred, specified in UTC.
    Example: 2023-11-02T18:26:00.000123Z

  - `timestamp` (string)
    The timestamp of the error
    Example: 2023-11-02T18:26:00.000Z

## Response 404:

  - `404` (unknown)
    No identities found.

## Response 404 fields (application/json):

  - `status` (integer, required)
    The HTTP status code of the error
    Example: 404

  - `errors` (array, required)

  - `errors.code` (string, required)
    Unique identifier of an error
    Example: SYS_100

  - `errors.title` (string, required)
    Error message providing a brief summary of the error
    Example: No identity exists for identityId

  - `errors.type` (string, required)
    Identifies the problem type
    Example: USER_VALIDATION_ERROR

  - `errors.description` (string, required)
    Provides more technical information
    Example: Unable to get identity. Identity ID should be in UUID format

  - `errors.timestamp` (string, required)
    The time when this error occurred, specified in UTC.
    Example: 2023-11-02T18:26:00.000123Z

  - `timestamp` (string)
    The timestamp of the error
    Example: 2023-11-02T18:26:00.000Z

## Response 500:

  - `500` (unknown)
    Internal processing error.

## Response 500 fields (application/json):

  - `status` (integer, required)
    The HTTP status code of the error
    Example: 404

  - `errors` (array, required)

  - `errors.code` (string, required)
    Unique identifier of an error
    Example: SYS_100

  - `errors.title` (string, required)
    Error message providing a brief summary of the error
    Example: No identity exists for identityId

  - `errors.type` (string, required)
    Identifies the problem type
    Example: USER_VALIDATION_ERROR

  - `errors.description` (string, required)
    Provides more technical information
    Example: Unable to get identity. Identity ID should be in UUID format

  - `errors.timestamp` (string, required)
    The time when this error occurred, specified in UTC.
    Example: 2023-11-02T18:26:00.000123Z

  - `timestamp` (string)
    The timestamp of the error
    Example: 2023-11-02T18:26:00.000Z

## Response 200 examples:

  - `list-identities-v3` (unknown)

## Response 400 examples:

  - `error-response-400` (unknown)

## Response 404 examples:

  - `error-response-404` (unknown)

## Response 500 examples:

  - `error-response-500` (unknown)