Elliptic Transaction Workflow API

openapi: 3.2.0
info:
  version: 2.0.0
  title: AML API V2 Transaction Workflow API
  description: '# Introduction

    **Welcome to the Elliptic API Documentation**


    In its simplest form, the Elliptic API allows you to submit batches of transactions programmatically, without human intervention.'
servers:
- url: https://aml-api.elliptic.co/v2
  description: Production
security:
- bearer: []
- apiKey: []
  signature: []
  timestamp: []
tags:
- name: Transaction Workflow
paths:
  /analyses/{mc_analysis_id}:
    patch:
      tags:
      - Transaction Workflow
      summary: Update the notes of an analysis by ID
      description: Given an ID, update the notes of the analysis
      parameters:
      - name: mc_analysis_id
        in: path
        required: true
        description: id of the analysis to update
        schema:
          type: string
          format: UUIDv4
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                note:
                  description: new note
                  example: this is now a very important tx
                  type:
                  - string
                  - 'null'
              required:
              - note
      responses:
        '200':
          description: The updated fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  note:
                    type: string
                    description: The saved note.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      operationId: patchAnalysesByMcAnalysisId
      x-operation-id-source: derived
  /analyses/workflow_status:
    post:
      tags:
      - Transaction Workflow
      summary: Bulk update workflow status
      description: Set the workflow status of the analyses having the ids passed as body to the desired value.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                analyses_ids:
                  description: id of the analyses to change status. Duplicate ids will be considered as one.
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: string
                    format: UUIDv4
                    example: b8ae5c56-c2a6-4868-a03e-b59cb28ecede
                workflow_status:
                  $ref: '#/components/schemas/WalletAnalysisResponse/properties/workflow_status'
                waitForSearchSync:
                  type: boolean
                  description: if false, skip waiting for the analysis search index to update
              required:
              - analyses_ids
              - workflow_status
      responses:
        '200':
          description: status has been set
        '400':
          description: Bad request, invalid `analysis_ids` in body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      operationId: postAnalysesWorkflowStatus
      x-operation-id-source: derived
  /analyses/assigned_team_user:
    post:
      tags:
      - Transaction Workflow
      summary: Update assigned team user for transaction analysis
      description: Set the assigned team user for a transaction analysis
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                analysis_id:
                  description: Id of the analysis
                  type: string
                  format: UUIDv4
                  example: b8ae5c56-c2a6-4868-a03e-b59cb28ecede
                assigned_team_user_id:
                  description: Id of the team user to assign the analysis to, or null to set the analysis as unassigned
                  type:
                  - string
                  - 'null'
                  format: uuid
                  example: b8ae5c56-c2a6-4868-a03e-b59cb28ecede
              required:
              - analysis_id
              - assigned_team_user_id
      responses:
        '204':
          description: Assigned team user has been set successfully
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      operationId: postAnalysesAssignedTeamUser
      x-operation-id-source: derived
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.
    WalletAnalysisResponse:
      title: WalletAnalysisResponse
      type: object
      description: 'Response for Wallet Analysis. Represents the full result of a holistic wallet analysis, including metadata, risk scores, and contributing entities.

        '
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the wallet analysis
          example: b7535048-76f8-4f60-bdd3-9d659298f9e7
        type:
          $ref: '#/components/schemas/WalletAnalysisType'
        subject:
          allOf:
          - $ref: '#/components/schemas/WalletAnalysisSubject'
          - type: object
        customer:
          type: object
          description: The customer that submitted the request
          properties:
            id:
              type:
              - string
              - 'null'
              format: uuid
              description: The UUIDv4 of the customer this analysis is associated with
              example: b7535048-76f8-4f60-bdd3-9d659298f9e7
            reference:
              type: string
              description: The string reference that has been given to this customer. Can be empty
              example: foobar
        blockchain_info:
          description: The relevant blockchain data related to the subject's hash
          type: object
          properties:
            cluster:
              type: object
              properties:
                inflow_value:
                  type: object
                  description: Value of cluster's inflowing funds
                  properties:
                    usd:
                      type:
                      - number
                      - 'null'
                      description: 'Transaction amount expressed in US dollars of the blockchain it has occurred in the most precise unit possible, e.g. satoshis for bitcoin

                        '
                      example: 38383838
                outflow_value:
                  type: object
                  description: Value of cluster's outflowing funds
                  properties:
                    usd:
                      type:
                      - number
                      - 'null'
        created_at:
          description: ISO datetime (UTC) when the analysis was first analysed
          type: string
          format: date-time
          example: '2015-05-13T10:36:21.000Z'
        updated_at:
          description: ISO datetime (UTC) when the wallet analysis was last updated
          type: string
          format: date-time
          example: '2015-05-13T10:36:21.000Z'
        analysed_at:
          description: ISO datetime (UTC) when this analysis was completed
          type: string
          format: date-time
          example: '2015-05-13T10:36:21.000Z'
        analysed_by:
          description: The actor who executed the analysis
          type:
          - object
          - 'null'
          properties:
            id:
              type: string
              format: UUIDv4
              description: Team User's UUIDv4 (unique for team & user)
              example: 17535048-76f8-4f60-bdd3-9d659298f9e5
            email:
              type: string
              description: the email address of the User
              example: foo_bar@elliptic.co
            first_name:
              type: string
              description: the first name of the User
              example: Foo
            last_name:
              type: string
              description: the last name of the User
              example: Bar
            type:
              type: string
              description: Type of actor (e.g. user, system, api_key). Only present for analysed_by.
              example: api_key
        asset_tier:
          type: string
          enum:
          - full
          - sanctions
          description: The asset tier
          example: full
        cluster_entities:
          type: array
          description: An Elliptic-created, wallet asserted label to be attached to a cluster
          items:
            $ref: '#/components/schemas/WalletAssertedLabel'
        team_id:
          description: UUIDv4 identifier of the team the user belongs to
          type: string
          format: uuid
          example: e333694b-c7c7-4a36-bf35-ed2615865242
        risk_score:
          type:
          - number
          - 'null'
          format: float
          description: 'The risk score calculated as an aggregation from all the rules. If null is returned, no risk rules have been triggered. If 0 is returned, risk rules were triggered and the calculated score was 0.

            '
          example: 9.038007
        risk_score_detail:
          type: object
          description: Details on the risk scores of the source and destination of funds
          properties:
            source:
              type:
              - number
              - 'null'
              format: float
              example: 6
            destination:
              type:
              - number
              - 'null'
              format: float
              example: 6
        error:
          type:
          - object
          - 'null'
          description: Property containing information about a failed screening, null unless process_status = 'error'
          properties:
            message:
              type: string
              description: Error message
              example: something went wrong
        evaluation_detail:
          type: object
          description: Details of risk rule evaluations for both source and destination of funds
          properties:
            source:
              type: array
              items:
                $ref: '#/components/schemas/EvaluationDetail'
            destination:
              type: array
              items:
                $ref: '#/components/schemas/EvaluationDetail'
        contributions:
          type: object
          description: Array of contributions for the analysis subject retrieved
          properties:
            source:
              type: array
              items:
                $ref: '#/components/schemas/Contribution'
            destination:
              type: array
              items:
                $ref: '#/components/schemas/Contribution'
        detected_behaviors:
          type: array
          description: 'Array of detected behaviors for the analysis subject retrieved from the graph server

            '
          items:
            title: DetectedBehavior
            type: object
            properties:
              behavior_type:
                type: string
                description: Type of the Behavioral pattern detected of potential suspicious activity
                example: Peeling Chain
              length:
                type: number
                description: Length associated with the Behavior detected
                example: 7
              usd_value:
                type: number
                format: float
                description: aggregated value (sum) associated with the behavior detected
                example: 10500
            required:
            - behavior_type
            - length
            - usd_value
        changes:
          type: object
          description: Changes compared to previous screening of analysis
          properties:
            risk_score_change:
              type: number
              format: float
              description: 'Change in risk score compared to previous screening of analysis. - A positive number means the risk score has increased. - A negative number means it has decreased. - Zero means it remained unchanged.

                '
              example: 0.1
        workflow_status:
          title: WorkflowStatus
          description: The status of the analysis. "archived" is deprecated and you should use "closed" instead.
          type: string
          enum:
          - active
          - archived
          - escalated
          - closed
          example: active
        workflow_status_id:
          title: WorkflowStatusId
          description: 'A number representation of the status of an analysis. "archived" is deprecated and you should use "closed" instead. - 1 = active - 2 = archived (deprecated) - 3 = escalated - 4 = closed

            '
          type: integer
          enum:
          - 1
          - 2
          - 3
          - 4
          example: 1
        assigned_team_user:
          $ref: '#/components/schemas/WalletAnalysisResponse/properties/analysed_by'
          description: The team user assigned to this analysis
        process_status:
          type: string
          enum:
          - running
          - complete
          - error
          example: running
          description: The process status ('running','complete','error')
        process_status_id:
          type: integer
          enum:
          - 1
          - 2
          - 3
          example: 2
          description: 'The screening process status. - 1 = running - 2 = completed - 3 = error

            '
        triggered_rules:
          type: array
          description: Deprecated. This property is retained for backward compatibility and is always an empty array in this response. To see the set of rules that were triggered, use `evaluation_detail` instead.
          deprecated: true
          items: {}
          example: []
        screening_id:
          type: string
          format: uuid
          description: The identifier of the specific screening in the analysis
          example: d1afc6f3-6431-4566-8260-8e6db0b4ecf2
        screening_source:
          type: string
          enum:
          - sync
          - async
          - system_rescreen
          - automatic_rescreen
          - continuous_monitoring
          example: sync
          description: 'Indicates whether the screening was done via the Synchronous endpoint, Asynchronous endpoint, system rescreen, automatic rescreen, or continuous monitoring.

            '
      required:
      - id
      - type
      - subject
      - customer
      - blockchain_info
      - created_at
      - updated_at
      - analysed_at
      - cluster_entities
      - process_status
      - team_id
      - workflow_status
      additionalProperties: false
    UnauthorizedError:
      type: string
      example: Unauthorized
  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'
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequestError'
    '404':
      description: Resource item not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
    '403':
      description: Not authorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenError'
  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
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