ComplyAdvantage Users API

openapi: 3.0.3
info:
  title: ComplyAdvantage API
  description: >-
    The ComplyAdvantage REST API screens people and companies against
    sanctions and watchlists, warnings and fitness-probity lists, politically
    exposed persons (PEPs and RCAs), and adverse media, and keeps them under
    ongoing monitoring. It covers searches (create, list, retrieve, update,
    delete, certificates, entities), monitored searches (start/stop
    monitoring, differences, acknowledge), case management (assignment, match
    status, risk level, comments, tags), and account users. Authentication is
    an api key sent as "Authorization: Token YOUR_API_KEY"; keys are generated
    inside the ComplyAdvantage web platform, so an account is required.
    Standard contracts allow 600 API calls per minute (sandbox 300), with 429
    responses requiring exponential backoff (start at 2 seconds, cap at 60).
    Webhook events match_status_updated, search_status_updated, and
    monitored_search_updated push changes to your systems. This document was
    modeled from the public API reference at docs.complyadvantage.com; the
    endpoint paths are documented publicly, while request/response schemas are
    summarized rather than exhaustive.
  version: '1.0'
  contact:
    name: ComplyAdvantage
    url: https://complyadvantage.com
servers:
  - url: https://api.complyadvantage.com
    description: EU (default)
  - url: https://api.us.complyadvantage.com
    description: US
  - url: https://api.ap.complyadvantage.com
    description: APAC
security:
  - apiKeyAuth: []
tags:
  - name: Searches
    description: Create and manage AML screening searches against sanctions, PEP, warning, and adverse media data.
  - name: Monitored Searches
    description: Ongoing monitoring of searches, change differences, and acknowledgement.
  - name: Case Management
    description: Comments, tags, assignment, and match status workflow on searches.
  - name: Users
    description: Users on your ComplyAdvantage account.
paths:
  /searches:
    post:
      operationId: createSearch
      tags:
        - Searches
      summary: Create a new search
      description: >-
        Screens a search term (person, company, organisation, vessel, or
        aircraft name) against ComplyAdvantage's sanctions, warning,
        fitness-probity, PEP, and adverse media data, returning matching
        entities as hits. Supports fuzziness, exact match mode, filters, tags,
        client references, and pagination via offset/limit.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: The created search with matching hits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    get:
      operationId: listSearches
      tags:
        - Searches
      summary: List previous searches
      description: >-
        Lists previous searches with filtering (match status, risk level,
        assignee, searcher, created date range, client reference, tags,
        monitored state), sorting, and pagination.
      parameters:
        - name: search_term
          in: query
          schema:
            type: string
        - name: client_ref
          in: query
          schema:
            type: string
        - name: monitored
          in: query
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
        - name: per_page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A paginated list of searches.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchListEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /searches/{id}:
    get:
      operationId: getSearch
      tags:
        - Searches
      summary: Retrieve a search
      description: Retrieves the overview of a single search by ID or ref.
      parameters:
        - $ref: '#/components/parameters/SearchId'
      responses:
        '200':
          description: The search overview.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchEnvelope'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateSearch
      tags:
        - Searches
        - Case Management
      summary: Update search details
      description: >-
        Updates case-management details of a search - the assigned user, match
        status (no_match, false_positive, potential_match, true_positive,
        true_positive_approve, true_positive_reject), and risk level (low,
        medium, high, unknown).
      parameters:
        - $ref: '#/components/parameters/SearchId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                match_status:
                  type: string
                risk_level:
                  type: string
                assignee_id:
                  type: integer
      responses:
        '200':
          description: The updated search.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchEnvelope'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteSearch
      tags:
        - Searches
      summary: Delete a search
      description: Deletes a search from your account.
      parameters:
        - $ref: '#/components/parameters/SearchId'
      responses:
        '200':
          description: Deletion confirmation.
        '404':
          $ref: '#/components/responses/NotFound'
  /searches/{id}/details:
    get:
      operationId: getSearchDetails
      tags:
        - Searches
      summary: Retrieve full search results
      description: >-
        Retrieves the full detail of a search including all hits, each with the
        matched entity document (name, aka, associates, sources, types,
        fields, media), match types, score, whitelisting, and match status.
      parameters:
        - $ref: '#/components/parameters/SearchId'
      responses:
        '200':
          description: Full search details with hits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchEnvelope'
        '404':
          $ref: '#/components/responses/NotFound'
  /searches/{ref}/entities/{entity_provider}:
    get:
      operationId: getSearchEntities
      tags:
        - Searches
      summary: Retrieve paginated search entities
      description: Retrieves the matching entities of a search in paginated form.
      parameters:
        - name: ref
          in: path
          required: true
          schema:
            type: string
          description: The search ref.
        - name: entity_provider
          in: path
          required: true
          schema:
            type: string
          description: The entity data provider.
      responses:
        '200':
          description: Paginated entities for the search.
        '404':
          $ref: '#/components/responses/NotFound'
  /searches/{id}/certificate:
    get:
      operationId: getSearchCertificate
      tags:
        - Searches
      summary: Download search certificate
      description: >-
        Downloads a PDF certificate of the search for audit and recordkeeping
        purposes.
      parameters:
        - $ref: '#/components/parameters/SearchId'
      responses:
        '200':
          description: The search certificate PDF.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/NotFound'
  /searches/{id}/entities:
    patch:
      operationId: updateSearchEntities
      tags:
        - Searches
        - Case Management
      summary: Update entity details on a search
      description: >-
        Updates details of matched entities within a search - whitelist status
        (suppress recurring false positives), risk level, and per-entity match
        status.
      parameters:
        - $ref: '#/components/parameters/SearchId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                entities:
                  type: array
                  items:
                    type: string
                is_whitelisted:
                  type: boolean
                match_status:
                  type: string
                risk_level:
                  type: string
      responses:
        '200':
          description: The updated entities.
        '404':
          $ref: '#/components/responses/NotFound'
  /searches/references:
    post:
      operationId: createSearchReferences
      tags:
        - Searches
      summary: Create search references
      description: Creates search references for tracking searches by your own identifiers.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The created references.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /searches/{id}/monitors:
    get:
      operationId: getMonitoredSearch
      tags:
        - Monitored Searches
      summary: Get monitored search details
      description: Retrieves the monitoring configuration and state of a search.
      parameters:
        - $ref: '#/components/parameters/SearchId'
      responses:
        '200':
          description: Monitoring details for the search.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorEnvelope'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateMonitoredSearch
      tags:
        - Monitored Searches
      summary: Update monitored search details
      description: Starts or stops ongoing monitoring for a search.
      parameters:
        - $ref: '#/components/parameters/SearchId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                is_monitored:
                  type: boolean
      responses:
        '200':
          description: The updated monitoring state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorEnvelope'
        '404':
          $ref: '#/components/responses/NotFound'
  /searches/{id}/search-profile:
    patch:
      operationId: updateSearchProfile
      tags:
        - Monitored Searches
      summary: Update the associated search profile
      description: Updates which search profile a monitored search uses.
      parameters:
        - $ref: '#/components/parameters/SearchId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                search_profile:
                  type: string
      responses:
        '200':
          description: The updated search.
        '404':
          $ref: '#/components/responses/NotFound'
  /searches/{id}/monitor/differences:
    get:
      operationId: getMonitoredSearchDifferences
      tags:
        - Monitored Searches
      summary: Retrieve monitored search changes
      description: >-
        Retrieves what changed on a monitored search - new, updated, and
        removed matching entities since the last acknowledgement.
      parameters:
        - $ref: '#/components/parameters/SearchId'
      responses:
        '200':
          description: The differences since last acknowledgement.
        '404':
          $ref: '#/components/responses/NotFound'
  /searches/{id}/monitor/acknowledge:
    post:
      operationId: acknowledgeMonitoredSearchChanges
      tags:
        - Monitored Searches
      summary: Acknowledge monitored search changes
      description: Acknowledges the pending changes on a monitored search.
      parameters:
        - $ref: '#/components/parameters/SearchId'
      responses:
        '200':
          description: Acknowledgement confirmation.
        '404':
          $ref: '#/components/responses/NotFound'
  /searches/{id}/comments:
    post:
      operationId: createSearchComment
      tags:
        - Case Management
      summary: Create a comment on a search
      description: Adds an analyst comment to a search for case audit trails.
      parameters:
        - $ref: '#/components/parameters/SearchId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                comment:
                  type: string
      responses:
        '200':
          description: The created comment.
        '404':
          $ref: '#/components/responses/NotFound'
    get:
      operationId: listSearchComments
      tags:
        - Case Management
      summary: Retrieve comments on a search
      description: Lists the comments attached to a search.
      parameters:
        - $ref: '#/components/parameters/SearchId'
      responses:
        '200':
          description: The comments on the search.
        '404':
          $ref: '#/components/responses/NotFound'
  /searches/{id}/tags/{tag_name}:
    delete:
      operationId: detachSearchTag
      tags:
        - Case Management
      summary: Detach a tag from a search
      description: Removes a key-value tag from a search.
      parameters:
        - $ref: '#/components/parameters/SearchId'
        - name: tag_name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Tag removal confirmation.
        '404':
          $ref: '#/components/responses/NotFound'
  /users:
    get:
      operationId: listUsers
      tags:
        - Users
      summary: List account users
      description: Lists the users on your ComplyAdvantage account for search and case assignment.
      responses:
        '200':
          description: The users on the account.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  content:
                    type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key sent as: Authorization: Token YOUR_API_KEY. Keys are generated in the ComplyAdvantage web platform.'
  parameters:
    SearchId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The search ID or ref.
  responses:
    Unauthorized:
      description: Missing or invalid API key.
    NotFound:
      description: The search or resource was not found.
    TooManyRequests:
      description: >-
        Rate limit exceeded (600 calls/minute on standard contracts, 300 on
        sandbox). Retry with exponential backoff starting at 2 seconds, capped
        at 60 seconds.
  schemas:
    SearchRequest:
      type: object
      required:
        - search_term
      properties:
        search_term:
          description: >-
            The name to screen, either a string (max 255 chars) or an object
            with last_name (required), first_name, and middle_names.
          oneOf:
            - type: string
            - type: object
              properties:
                first_name:
                  type: string
                middle_names:
                  type: string
                last_name:
                  type: string
        client_ref:
          type: string
          description: Your internal reference; enables client-scoped whitelisting.
        fuzziness:
          type: number
          minimum: 0.0
          maximum: 1.0
          description: Match strictness from 0.0 (exact) to 1.0 (broad).
        exact_match:
          type: boolean
          description: Disables fuzzy matching when true; overrides fuzziness.
        search_profile:
          type: string
          description: ID of a predefined search profile configuration.
        offset:
          type: integer
          default: 0
        limit:
          type: integer
          default: 100
          maximum: 100
        share_url:
          type: integer
          enum: [0, 1]
          description: Include a publicly shareable URL in the response.
        tags:
          type: object
          description: Key-value pairs using pre-configured tag names.
        filters:
          type: object
          properties:
            types:
              type: array
              items:
                type: string
              description: >-
                Risk categories such as sanction, warning, fitness-probity,
                pep, pep-class-1 through pep-class-4, adverse-media, and
                adverse media subcategories.
            birth_year:
              type: integer
            remove_deceased:
              type: string
              enum: ['0', '1']
            country_codes:
              type: array
              items:
                type: string
              description: ISO 3166-1 alpha-2 codes; applies to PEP entities.
            entity_type:
              type: string
              enum: [person, company, organisation, vessel, aircraft]
    Search:
      type: object
      properties:
        id:
          type: integer
        ref:
          type: string
        search_term:
          type: string
        match_status:
          type: string
        risk_level:
          type: string
        total_hits:
          type: integer
        total_matches:
          type: integer
        created_at:
          type: string
        updated_at:
          type: string
        tags:
          type: array
          items:
            type: object
        share_url:
          type: string
        hits:
          type: array
          items:
            $ref: '#/components/schemas/Hit'
    Hit:
      type: object
      properties:
        doc:
          type: object
          description: >-
            The matched entity - id, name, entity_type, aka, associates,
            sources, types, fields, and media references.
        match_types:
          type: array
          items:
            type: string
        match_types_details:
          type: object
        score:
          type: number
        is_whitelisted:
          type: boolean
        match_status:
          type: string
    SearchEnvelope:
      type: object
      properties:
        status:
          type: string
        content:
          type: object
          properties:
            data:
              $ref: '#/components/schemas/Search'
    SearchListEnvelope:
      type: object
      properties:
        status:
          type: string
        content:
          type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Search'
    MonitorEnvelope:
      type: object
      properties:
        status:
          type: string
        content:
          type: object
          properties:
            is_monitored:
              type: boolean