---
title: "Paginate all customers"
method: GET
path: "/customers"
tags: ["Customers"]
---

# Paginate all customers

`GET /customers`

## Request

- Base URL: `https://aml-api.elliptic.co/v2`
- URL: `https://aml-api.elliptic.co/v2/customers`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-access-key` and API key in header `x-access-sign` and API key in header `x-access-timestamp`

Paginate through all customers, with various sort/filter parameters.

## Query parameters

- `page` integer
- `per_page` integer
- `workflow_status` string[]
- `keyword` string
- `label` string
- `label_matches` string
- `investigator_id` string[]
- `customer_label_id` string[]
- `reference_contains` string
- `reference_matches` string
- `reference` string
- `expand` string[]
- `sort` 'last_queried' | '-last_queried' | 'reference' | '-reference' | 'first_tx_time' | '-first_tx_time' | 'last_tx_time' | '-last_tx_time' | 'max_score' | '-max_score' | 'avg_score' | '-avg_score' | 'total_volume' | '-total_volume' | 'total_volume_usd' | '-total_volume_usd' | 'workflow_status' | '-workflow_status'
- `minimum_avg_score` number, float
- `maximum_avg_score` number, float
- `minimum_max_score` number, float
- `maximum_max_score` number, float
- `minimum_vol` number, float
- `maximum_vol` number, float
- `first_tx_before` string, date-time
- `first_tx_after` string, date-time
- `last_tx_before` string, date-time
- `last_tx_after` string, date-time
- `last_queried_before` string, date-time
- `last_queried_after` string, date-time
- `status` string[]
- `include_no_risk` boolean
- `isMc` boolean

## Response `200`

Customers successfully retrieved

- object
  - `page` number
  - `per_page` number
  - `total_pages` number
  - `total_items` integer: total number of items on all pages
  - `items` Customer[]: array of retrieved customers
    - `id` string, UUIDv4, required: UUIDv4 identifier of the customer
    - `updated_at` string, date-time: ISO date time with time zone (UTC) of when the customer was last updated
    - `created_at` string, date-time: Customer's creation's ISO date time with time zone (UTC)
    - `team_id` string, UUIDv4, required: UUIDv4 identifier of the team the user belongs to
    - `investigator_id` string, NullableUUIDv4: UUIDv4 identifier of the user assigned to investigate customer
    - `reference` string, required: used by our client to refer to this customer
    - `labels` union[]: list of labels applied to the customer. If not expanded then just array of {"id":// uuid, label ids }
      - union
        - string
        - object
    - `status` 'processing' | 'error' | 'complete': customer's status
    - `is_processing` boolean: true if a query on this customer currently processing
    - `has_errors` boolean: true if a query on this customer has errored
    - `last_queried` string, date-time, required: ISO date time with time zone (UTC) of when the last query was run
    - `workflow_status` 'active' | 'archived', required: the workflow status
    - `statistics` object: an object representing aggregated statistics for a single customer
      - `first_tx_time` string, date-time, nullable, required: ISO date time with time zone (UTC) of the transaction having the smallest transaction time
      - `last_tx_time` string, date-time, nullable, required: ISO date time with time zone (UTC) of the transaction having the biggest transaction time
      - `avg_score` number, float, nullable, required: average between all this customer's transactions risks
      - `max_score` number, float, nullable, required: the highest risk of this customer's transactions risks
      - `min_score` number, float, nullable: the minimum risk of this customer's transactions risks
      - `total_volume` number, nullable, required: sum of all customer transactions output satoshis
      - `total_fees` number, nullable: sum of all customer transactions fees
      - `customer_tx_count` number, nullable, required: total number of customer_txs that this customer has
      - `deposits` CustomerTxInfo, required: an object representing a single analysed Transaction attached to a Customer
        - `total_volume` number, nullable, required: Sum of all transactions' volume
        - `customer_tx_count` number, nullable, required: Number of transactions
        - `total_fees` number, nullable: sum of all customer transactions fees
      - `withdrawals` CustomerTxInfo, required: an object representing a single analysed Transaction attached to a Customer
        - `total_volume` number, nullable, required: Sum of all transactions' volume
        - `customer_tx_count` number, nullable, required: Number of transactions
        - `total_fees` number, nullable: sum of all customer transactions fees
      - `min_output_satoshis` number, nullable, required: the lowest volume of this customer's transactions volumes
      - `max_output_satoshis` number, nullable, required: the highest volume of this customer's transactions volumes
      - `avg_output_satoshis` number, nullable, required: average of this customer's transactions volumes

## Other responses

- `400`: Bad request, e.g. invalid `workflow_status` in query.
- `401`: Not authenticated
- `403`: Not authorized
- `500`: Server Error

---

[API](https://skmtc.dev/elliptic/apis/aml-api-v2.md) - [All operations](https://skmtc.dev/elliptic/apis/aml-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/elliptic/apis/aml-api-v2/revisions/e0bcbfe65e14?raw)