ComplyAdvantage Searches API

openapi: 3.0.3
info:
  title: ComplyAdvantage Case Management Searches 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.
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
      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
      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'
components:
  schemas:
    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'
    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
    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
    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'
  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.
  parameters:
    SearchId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The search ID or ref.
  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.'