Elliptic Customers API

openapi: 3.2.0
info:
  title: Elliptic Customers API
  version: '1.0'
  description: 'Operations tagged Customers across 2 of this provider''s published API definitions: aml-api-v2.json, ia-api.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://aml-api.elliptic.co/v2
  description: Production
- url: https://ai-api.elliptic.co
  description: Production server
tags:
- name: Customers
  description: 'The customers endpoints are used to manage customers which you have associated analysis with, via the `customer_reference` analysis subject attribute.


    Currently, the customers endpoints only refer to customers with Transaction Analysis.


    Customers with only Wallet Analysis will not yield responses from these endpoints'
paths:
  /customers:
    get:
      tags:
      - Customers
      summary: Paginate all customers
      description: Paginate through all customers, with various sort/filter parameters.
      parameters:
      - name: page
        in: query
        description: requested page number
        schema:
          type: integer
          format: int32
          minimum: 1
          default: 1
      - name: per_page
        in: query
        description: number of items per page
        schema:
          type: integer
          format: int32
          minimum: 1
          maximum: 100
          default: 20
      - name: workflow_status
        description: workflow status filter
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - active
            - archived
      - name: keyword
        in: query
        description: filter both label and reference (case insensitive). Whitespace implies AND.
        schema:
          type: string
          minLength: 1
      - name: label
        in: query
        description: filter by label name
        schema:
          type: string
          minLength: 1
      - name: label_matches
        in: query
        description: filter by exact label name (case sensitive)
        schema:
          type: string
          minLength: 1
      - name: investigator_id
        description: filter by these ids of users assigned to investigate the customer (can be empty string to get unassigned)
        in: query
        schema:
          type: array
          items:
            type: string
            format: NullableUUIDv4
      - name: customer_label_id
        in: query
        description: label filter (if empty string then customers with no labels are returned)
        schema:
          type: array
          items:
            type: string
            format: NullableUUIDv4
      - name: reference_contains
        in: query
        description: a string on which to match customer references
        schema:
          type: string
          minLength: 1
      - name: reference_matches
        in: query
        description: 'Deprecated

          Use reference instead

          '
        schema:
          type: string
          minLength: 1
      - name: reference
        in: query
        description: a customer reference to match (exactly)
        schema:
          type: string
          minLength: 1
      - name: expand
        in: query
        description: to get more detailed labels object
        schema:
          type: array
          items:
            type: string
            enum:
            - labels
          default: []
      - name: sort
        description: sorting criterion
        in: query
        schema:
          type: string
          enum:
          - 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
          default: -last_queried
      - name: minimum_avg_score
        description: filter by avg_score >= the given value
        in: query
        schema:
          type: number
          format: float
      - name: maximum_avg_score
        description: filter by avg_score <= the given value
        in: query
        schema:
          type: number
          format: float
      - name: minimum_max_score
        description: filter by max_score >= the given value
        in: query
        schema:
          type: number
          format: float
      - name: maximum_max_score
        description: filter by max_score <= the given value
        in: query
        schema:
          type: number
          format: float
      - name: minimum_vol
        description: filter by volume >= the given value in USD
        in: query
        schema:
          type: number
          format: float
      - name: maximum_vol
        description: filter by volume <= the given value in USD
        in: query
        schema:
          type: number
          format: float
      - name: first_tx_before
        description: filter the earliest transaction time of this customer (ISO8601 datetime) <= the given date
        in: query
        schema:
          type: string
          format: date-time
        example: '2030-02-26T14:33:34.787Z'
      - name: first_tx_after
        description: filter the earliest transaction time of this customer (ISO8601 datetime) >= the given date
        in: query
        schema:
          type: string
          format: date-time
        example: '2010-02-26T14:33:34.787Z'
      - name: last_tx_before
        description: filter the latest transaction time of this customer (ISO8601 datetime) <= the given date
        in: query
        schema:
          type: string
          format: date-time
        example: '2030-02-26T14:33:34.787Z'
      - name: last_tx_after
        description: filter the latest transaction time of this customer (ISO8601 datetime) >= the given date
        in: query
        schema:
          type: string
          format: date-time
        example: '2010-02-26T14:33:34.787Z'
      - name: last_queried_before
        description: filter last_queried time of customer (ISO8601 datetime) <= the given date
        in: query
        schema:
          type: string
          format: date-time
        example: '2030-02-26T14:33:34.787Z'
      - name: last_queried_after
        description: filter last_queried time of customer (ISO8601 datetime) >= the given date
        in: query
        schema:
          type: string
          format: date-time
        example: '2010-02-26T14:33:34.787Z'
      - name: status
        description: allowed statuses
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - complete
            - processing
            - error
          minItems: 1
      - name: include_no_risk
        description: 'Deprecated

          No longer supported

          '
        in: query
        schema:
          type: boolean
          default: true
      - name: isMc
        description: 'Deprecated

          This will always evaluate to true. Legacy mode no longer supported

          '
        in: query
        example: true
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: Customers successfully retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    format: int32
                    minimum: 0
                    example: 5
                  per_page:
                    type: number
                    format: int32
                    minimum: 0
                    example: 5
                  total_pages:
                    type: number
                    format: int32
                    minimum: 0
                    example: 5
                  total_items:
                    description: total number of items on all pages
                    type: integer
                    format: int32
                    example: 1
                  items:
                    description: array of retrieved customers
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
                additionalProperties: false
        '400':
          description: Bad request, e.g. invalid `workflow_status` in query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      security:
      - bearer: []
      - apiKey: []
        signature: []
        timestamp: []
      operationId: getCustomers
      x-operation-id-source: derived
    servers:
    - url: https://aml-api.elliptic.co/v2
      description: Production
  /customers/{customer_id}:
    get:
      tags:
      - Customers
      summary: Get customer by ID
      description: Get a single customer by ID
      parameters:
      - name: customer_id
        description: uuid identifier of a customer
        in: path
        required: true
        schema:
          type: string
          format: UUIDv4
      - name: expand
        description: to expand customer labels and/or statistics
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - labels
            - statistics
          default: []
      - name: isMc
        description: 'Deprecated

          This will always evaluate to true. Legacy mode no longer supported

          '
        example: true
        in: query
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: Customer successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          description: Customer ID not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          $ref: '#/components/responses/500'
      security:
      - bearer: []
      - apiKey: []
        signature: []
        timestamp: []
      operationId: getCustomersByCustomerId
      x-operation-id-source: derived
    servers:
    - url: https://aml-api.elliptic.co/v2
      description: Production
  /customers/investigator:
    post:
      tags:
      - Customers
      summary: Bulk update investigator ID
      description: The customers & investigator_id must all exist & belong to the team of the authenticated user.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_ids:
                  description: the customer id(s) to update
                  type: array
                  minItems: 1
                  items:
                    type: string
                    format: UUIDv4
                    example: 61dc6f9c-fb4b-4aad-966e-801ea4caa7d6
                investigator_id:
                  description: new investigator id (can be null). Replaces old.
                  format: NullableUUIDv4
                  example: 801a54af-6bbe-48db-ab28-7edc343649d5
                  type:
                  - string
                  - 'null'
              required:
              - customer_ids
              - investigator_id
      responses:
        '204':
          description: Customers successfully updated
        '400':
          description: Bad request, e.g. invalid `customer_id`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      security:
      - bearer: []
      - apiKey: []
        signature: []
        timestamp: []
      operationId: postCustomersInvestigator
      x-operation-id-source: derived
    servers:
    - url: https://aml-api.elliptic.co/v2
      description: Production
  /customers/workflow_status:
    post:
      tags:
      - Customers
      summary: Bulk update workflow status
      description: 'The customers must all exist & belong to the team of the authenticated user.


        Currently the only states are ''Active'' and ''Archived''. Transitions both ways are allowed.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_ids:
                  description: the customer id(s) to update
                  type: array
                  minItems: 1
                  items:
                    type: string
                    format: UUIDv4
                  example:
                  - 61dc6f9c-fb4b-4aad-966e-801ea4caa7d6
                  - 55f2bf9c-ff91-4146-a9d7-1d484d1dbac5
                workflow_status:
                  description: new workflow status ('active', 'archived'). Replaces old.
                  type: string
                  enum:
                  - active
                  - archived
                waitForSearchSync:
                  type: boolean
                  description: if false, skip waiting for the analysis search index to update
              required:
              - customer_ids
      responses:
        '204':
          description: Customer successfully updated
        '400':
          description: Bad request, e.g. invalid `customer_ids`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      security:
      - bearer: []
      - apiKey: []
        signature: []
        timestamp: []
      operationId: postCustomersWorkflowStatus
      x-operation-id-source: derived
    servers:
    - url: https://aml-api.elliptic.co/v2
      description: Production
  /copilot/customers/summary/{customerId}:
    get:
      tags:
      - Customers
      summary: Get customer summary
      description: Returns a summary for a customer by ID. The shape of the response depends on the `request` query parameter.
      operationId: getCustomerSummary
      parameters:
      - name: customerId
        in: path
        required: true
        description: Customer ID (UUID)
        schema:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
      - name: request
        in: query
        required: false
        description: Type of summary to return. Omit for a full structured summary with analysis IDs. `overview`, `wallet`, or `transaction` return an LLM narrative. `wallet_ids` or `transaction_ids` return the highest-risk items with their hash and analysis ID.
        schema:
          type: string
          enum:
          - overview
          - wallet
          - transaction
          - wallet_ids
          - transaction_ids
          example: overview
      responses:
        '200':
          description: 'Customer summary. Shape depends on `request` query param: `SummaryResult` when omitted, LLM narrative string for `overview`/`wallet`/`transaction`, or `MaxRiskTrigger[]` for `wallet_ids`/`transaction_ids`.'
          content:
            text/plain:
              schema:
                type: string
                description: LLM-generated narrative (returned when request is overview, wallet, or transaction)
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/SummaryResult'
                - type: array
                  items:
                    $ref: '#/components/schemas/MaxRiskTrigger'
                  description: Highest-risk items with hash and analysisId (returned when request is wallet_ids or transaction_ids)
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
      - Bearer: []
      - apiKey: []
        signature: []
        timestamp: []
    servers:
    - url: https://ai-api.elliptic.co
      description: Production server
  /copilot/customers/summary/{customerId}/transaction-assets:
    get:
      tags:
      - Customers
      summary: Get customer transaction assets
      description: Returns an AI-generated analysis of transaction assets for a customer
      operationId: getTransactionAssetsByCustomerId
      parameters:
      - name: customerId
        in: path
        required: true
        description: Customer ID (UUID)
        schema:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: AI-generated transaction assets analysis
          content:
            text/plain:
              schema:
                type: string
                description: LLM-generated narrative about the customer's transaction assets
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
      - Bearer: []
      - apiKey: []
        signature: []
        timestamp: []
    servers:
    - url: https://ai-api.elliptic.co
      description: Production server
components:
  schemas:
    BadRequestError:
      type: object
      properties:
        name:
          type: string
          example: BadRequestError
        message:
          type: string
          example: Invalid id parameter
    Error:
      type: object
      properties:
        name:
          type: string
          example: GenericErrorName
        message:
          type: string
          example: Something bad happened.
    NotFoundError:
      type: object
      properties:
        name:
          type: string
          example: NotFoundError
        message:
          type: string
          example: Entity not found.
    ForbiddenError:
      type: object
      properties:
        name:
          type: string
          example: ForbiddenError
        message:
          type: string
          example: You do not have enough privilege to access this path.
    CustomerTxInfo:
      type: object
      title: customerTxInfo
      description: an object representing a single analysed Transaction attached to a Customer
      properties:
        total_volume:
          description: Sum of all transactions' volume
          example: 993842398342
          type:
          - number
          - 'null'
        customer_tx_count:
          description: Number of transactions
          format: int64
          example: 3341
          type:
          - number
          - 'null'
        total_fees:
          description: sum of all customer transactions fees
          format: int64
          example: 993842398342
          type:
          - number
          - 'null'
      required:
      - total_volume
      - customer_tx_count
      additionalProperties: false
    Customer:
      type: object
      title: Customer
      description: an object representing a single Customer
      properties:
        id:
          description: UUIDv4 identifier of the customer
          type: string
          format: UUIDv4
          example: b7535048-76f8-4f60-bdd3-9d659298f9e7
        updated_at:
          description: ISO date time with time zone (UTC) of when the customer was last updated
          type: string
          format: date-time
          example: '2015-05-13T10:36:21.000Z'
        created_at:
          description: Customer's creation's ISO date time with time zone (UTC)
          type: string
          format: date-time
          example: '2015-05-13T10:36:21.000Z'
        team_id:
          description: UUIDv4 identifier of the team the user belongs to
          type: string
          format: UUIDv4
          example: e333694b-c7c7-4a36-bf35-ed2615865242
        investigator_id:
          description: UUIDv4 identifier of the user assigned to investigate customer
          format: NullableUUIDv4
          example: b68704ce-7aaa-45b1-996d-8d760657baf2
        reference:
          description: used by our client to refer to this customer
          type: string
          example: Investigator
        labels:
          description: list of labels applied to the customer. If not expanded then just array of {"id":// uuid, label ids }
          type: array
          items:
            oneOf:
            - type: string
            - type: object
          example:
          - id: 2118a3ca-a1c0-4f81-92b1-a1069d6a8fb9
            team_id: 15f2b16d-f825-4d40-8db3-f4e080f90759
            name: Parent Label
            parent_customer_label_id: null
        status:
          description: customer's status
          type: string
          enum:
          - processing
          - error
          - complete
          example: complete
        is_processing:
          description: true if a query on this customer currently processing
          type: boolean
          example: false
        has_errors:
          description: true if a query on this customer has errored
          type: boolean
          example: true
        last_queried:
          description: ISO date time with time zone (UTC) of when the last query was run
          type: string
          format: date-time
          example: '2015-05-13T10:36:21.000Z'
        workflow_status:
          type: string
          description: the workflow status
          enum:
          - active
          - archived
        statistics:
          type: object
          title: CustomerStats
          description: an object representing aggregated statistics for a single customer
          properties:
            first_tx_time:
              description: ISO date time with time zone (UTC) of the transaction having the smallest transaction time
              format: date-time
              example: '2015-05-13T10:36:21.000Z'
              type:
              - string
              - 'null'
            last_tx_time:
              description: ISO date time with time zone (UTC) of the transaction having the biggest transaction time
              format: date-time
              example: '2015-05-13T10:36:21.000Z'
              type:
              - string
              - 'null'
            avg_score:
              description: average between all this customer's transactions risks
              format: float
              example: 3.3
              type:
              - number
              - 'null'
            max_score:
              description: the highest risk of this customer's transactions risks
              format: float
              example: 9
              type:
              - number
              - 'null'
            min_score:
              description: the minimum risk of this customer's transactions risks
              format: float
              example: 9
              type:
              - number
              - 'null'
            total_volume:
              description: sum of all customer transactions output satoshis
              format: int64
              example: 993842398342
              type:
              - number
              - 'null'
            total_fees:
              description: sum of all customer transactions fees
              format: int64
              example: 993842398342
              type:
              - number
              - 'null'
            customer_tx_count:
              description: total number of customer_txs that this customer has
              format: int32
              example: 900800
              type:
              - number
              - 'null'
            deposits:
              $ref: '#/components/schemas/CustomerTxInfo'
            withdrawals:
              $ref: '#/components/schemas/CustomerTxInfo'
            min_output_satoshis:
              description: the lowest volume of this customer's transactions volumes
              example: 993842398342
              type:
              - number
              - 'null'
            max_output_satoshis:
              description: the highest volume of this customer's transactions volumes
              example: 993842398342
              type:
              - number
              - 'null'
            avg_output_satoshis:
              description: average of this customer's transactions volumes
              example: 993842398342
              type:
              - number
              - 'null'
          required:
          - first_tx_time
          - last_tx_time
          - avg_score
          - max_score
          - total_volume
          - customer_tx_count
          - deposits
          - withdrawals
          - min_output_satoshis
          - max_output_satoshis
          - avg_output_satoshis
          additionalProperties: false
      required:
      - id
      - team_id
      - reference
      - last_queried
      - workflow_status
      additionalProperties: false
    UnauthorizedError:
      type: string
      example: Unauthorized
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message
        statusCode:
          type: integer
          description: HTTP status code
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the error
        context:
          type: object
          additionalProperties: true
          description: Additional error context
      required:
      - message
      - statusCode
      - timestamp
    SummaryResult:
      type: object
      description: Full customer summary including an LLM narrative and the analysis IDs used to generate it
      properties:
        summary:
          type: string
          description: LLM-generated customer summary
        analysisIds:
          type: object
          properties:
            wallets:
              type: array
              items:
                type: string
                format: uuid
              description: Wallet analysis IDs used in the summary
            transactions:
              type: array
              items:
                type: string
                format: uuid
              description: Transaction analysis IDs used in the summary
          required:
          - wallets
          - transactions
      required:
      - summary
      - analysisIds
    MaxRiskTrigger:
      type: object
      description: A wallet or transaction at the maximum risk score, with its hash and analysis ID
      properties:
        hash:
          type: string
          description: Wallet address or transaction hash
        analysisId:
          type: string
          format: uuid
          description: Analysis ID (UUID)
      required:
      - hash
      - analysisId
  responses:
    '500':
      description: Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '401':
      description: Not authenticated
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
    '403':
      description: Not authorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenError'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Resource not found
            statusCode: 404
            timestamp: '2024-01-01T00:00:00.000Z'
    Unauthorized:
      description: Unauthorized - Missing or invalid authentication token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Unauthorized
            statusCode: 401
            timestamp: '2024-01-01T00:00:00.000Z'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Internal server error
            statusCode: 500
            timestamp: '2024-01-01T00:00:00.000Z'
    BadRequest:
      description: Bad request - Invalid input parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Validation failed
            statusCode: 400
            timestamp: '2024-01-01T00:00:00.000Z'
            context:
              errors:
              - Customer ID must be a valid UUID
    Forbidden:
      description: Forbidden - Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Forbidden - Insufficient permissions
            statusCode: 403
            timestamp: '2024-01-01T00:00:00.000Z'
  securitySchemes:
    bearer:
      description: Bearer Authentication
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKey:
      description: API Key
      type: apiKey
      in: header
      name: x-access-key
    signature:
      description: (Request Time, HTTP Method, Lowercase Path, Request Payload) signed with API Secret
      type: apiKey
      in: header
      name: x-access-sign
    timestamp:
      type: apiKey
      in: header
      name: x-access-timestamp
    Bearer:
      description: Bearer Authentication
      type: http
      scheme: bearer
      bearerFormat: JWT
x-refined-from:
- aml-api-v2.json
- ia-api.json
x-tagGroups:
- name: Navigator
  tags:
  - Transaction Analyses
- name: Lens
  tags:
  - Wallet Analyses
- name: Workflow Management
  tags:
  - Customers
  - Transaction Workflow
- name: Account Management
  tags:
  - Users
- name: Asset Information
  tags:
  - Assets table