ComplyAdvantage Custom Lists API

openapi: 3.2.0
info:
  title: Mesh Custom Lists API
  version: v2.0
servers:
- description: ComplyAdvantage Mesh API
  url: https://api.mesh.complyadvantage.com
security:
- BearerAuth: []
tags:
- name: Custom Lists
paths:
  /v2/custom-lists:
    get:
      description: 'Retrieve all custom lists regardless of their status


        You need "Access to custom lists for customer screening" enabled to use this endpoint.'
      operationId: customListAPIAllCustomLists
      parameters:
      - description: One-based page index (1..N)
        example: 1
        in: query
        name: page_number
        required: false
        schema:
          default: 1
          minimum: 1
          type: integer
      - description: The size of the page to be returned
        example: 20
        in: query
        name: page_size
        required: false
        schema:
          default: 50
          minimum: 1
          type: integer
      - description: 'Sorting criteria in the format of: `[-]property` (`-` descending modifier).


          * Default sort order is ascending (without `-`).


          * Multiple sort criteria are supported.'
        example:
        - -timestamp
        in: query
        name: sort
        required: false
        schema:
          default: []
          items:
            type: string
          type: array
      - description: Filter by custom list type.
        example:
        - CUSTOM_ENTITY
        - RISK_WORD
        in: query
        name: type
        required: false
        schema:
          items:
            enum:
            - CUSTOM_ENTITY
            - RISK_WORD
            type: string
          type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customlist_CustomListPageDTO'
          description: OK
      summary: Retrieve all custom lists
      tags:
      - Custom Lists
    post:
      description: 'Create a new empty custom list ready to be populated


        You need "Access to custom lists for customer screening" enabled and the "Create, update, and delete custom lists and their entities, and download entities" permission to use this endpoint.'
      operationId: customListAPINewCustomList
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customlist_CustomListAddDTO'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customlist_CustomListDTO'
          description: Created
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/customlist_ProblemDetailErrorResponse'
          description: The request body required fields are invalid or missing
      summary: Create a new custom list
      tags:
      - Custom Lists
  /v2/custom-lists/{custom_list_id}/entity:
    post:
      description: 'Register the operation to add a new entity to an existing and active custom list.

        The entity will be effectively added asynchronously and will be searchable later.


        You need "Access to custom lists for customer screening" enabled and the "Create, update, and delete custom lists and their entities, and download entities" permission to use this endpoint.'
      operationId: customListAPINewEntityAddedToList
      parameters:
      - description: The identifier of the custom list to which the entity will be added.
        example: 00000000-0000-0000-0000-000000000000
        in: path
        name: custom_list_id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customlist_EntityAddDTO'
        required: true
      responses:
        '202':
          description: The requested entity has been registered and will be searchable as soon as possible
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/customlist_ProblemDetailErrorResponse'
          description: The custom list id is expected to be a UUID
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/customlist_ProblemDetailErrorResponse'
          description: The custom list has exceeded the number of entities that can be added (1,000,000)
        '409':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/customlist_ProblemDetailErrorResponse'
          description: "An entity with the same id already exists therefore the request has been denied.\n                    If you need to update a entity, please refer to [PATCH] /{custom_list_id}/entity/{entity_id}\n                     "
      summary: Add a specific entity to a list
      tags:
      - Custom Lists
    put:
      description: 'Register the operation to add or update a new entity to an existing and active custom list.

        The entity will be effectively added or updated asynchronously and will be searchable later.


        You need "Access to custom lists for customer screening" enabled and the "Create, update, and delete custom lists and their entities, and download entities" permission to use this endpoint.'
      operationId: customListAPINewEntityAddedOrUpdatedToList
      parameters:
      - description: The identifier of the custom list containing the entity to be added/updated.
        example: 00000000-0000-0000-0000-000000000000
        in: path
        name: custom_list_id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customlist_EntityAddDTO'
        required: true
      responses:
        '202':
          description: The requested entity has been registered and will be searchable as soon as possible
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/customlist_ProblemDetailErrorResponse'
          description: The custom list id is expected to be a UUID
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/customlist_ProblemDetailErrorResponse'
          description: The custom list has exceeded the number of entities that can be added (1,000,000)
      summary: Add or update a specific entity to a list
      tags:
      - Custom Lists
  /v2/custom-lists/{custom_list_id}/entity/{id}:
    delete:
      description: 'Register the operation to archive an existing entity to an existing custom list.

        The entity will be archived asynchronously and will be removed from search later.


        You need "Access to custom lists for customer screening" enabled and the "Create, update, and delete custom lists and their entities, and download entities" permission to use this endpoint.'
      operationId: customListAPIEntityArchivedFromList
      parameters:
      - description: The identifier of the custom list containing the entity to be deleted.
        example: 00000000-0000-0000-0000-000000000000
        in: path
        name: custom_list_id
        required: true
        schema:
          format: uuid
          type: string
      - description: The identifier of the entity to delete
        example: my-entity-id
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '202':
          description: The requested entity will be archived and removed from search as soon as possible
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/customlist_ProblemDetailErrorResponse'
          description: The custom list id is expected to be a UUID
      summary: Archive an entity from a list
      tags:
      - Custom Lists
    get:
      description: 'Retrieve the latest version of an entity by id within a list


        You need "Access to custom lists for customer screening" enabled and the "Create, update, and delete custom lists and their entities, and download entities" permission to use this endpoint.'
      operationId: customListAPIFetchLatestEntityById
      parameters:
      - description: The identifier of the custom list containing the entity to be retrieved.
        example: 00000000-0000-0000-0000-000000000000
        in: path
        name: custom_list_id
        required: true
        schema:
          format: uuid
          type: string
      - description: The identifier of the entity to retrieve
        example: my-entity-id
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customlist_EntityDTO'
          description: The requested entity has been found and returned
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/customlist_ProblemDetailErrorResponse'
          description: The custom list id is expected to be a UUID
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/customlist_ProblemDetailErrorResponse'
          description: The requested entity could not be found.
      summary: Fetch a specific entity from a list
      tags:
      - Custom Lists
  /v2/custom-lists/{custom_list_id}/risk-word:
    post:
      description: 'Adds a single risk word to a custom list of type `RISK_WORD`.


        You need "Access to custom lists for customer screening" enabled and the "Create, update, and delete custom lists and their entities, and download entities" permission to use this endpoint.'
      operationId: customListAPIAddRiskWordToList
      parameters:
      - description: The identifier of the custom list to which the risk word will be added.
        example: 00000000-0000-0000-0000-000000000000
        in: path
        name: custom_list_id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customlist_RiskWordAddDTO'
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customlist_RiskWordDTO'
          description: The risk word has been registered and will be searchable as soon as possible
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/customlist_ProblemDetailErrorResponse'
          description: The custom list id is expected to be a UUID, or the custom list is not of type RISK_WORD
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/customlist_ProblemDetailErrorResponse'
          description: The custom list has exceeded the number of entities that can be added (1,000,000)
        '409':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/customlist_ProblemDetailErrorResponse'
          description: A risk word with the same identifier already exists therefore the request has been denied.
      summary: Add a risk word
      tags:
      - Custom Lists
    put:
      description: 'Adds a risk word to a custom list of type `RISK_WORD`, or updates it if a risk word with the same identifier already exists.


        You need "Access to custom lists for customer screening" enabled and the "Create, update, and delete custom lists and their entities, and download entities" permission to use this endpoint.'
      operationId: customListAPIAddOrUpdateRiskWordInList
      parameters:
      - description: The identifier of the custom list containing the risk word to be added/updated.
        example: 00000000-0000-0000-0000-000000000000
        in: path
        name: custom_list_id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customlist_RiskWordAddDTO'
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customlist_RiskWordDTO'
          description: The risk word has been registered and will be searchable as soon as possible
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/customlist_ProblemDetailErrorResponse'
          description: The custom list id is expected to be a UUID, or the custom list is not of type RISK_WORD
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/customlist_ProblemDetailErrorResponse'
          description: The custom list has exceeded the number of entities that can be added (1,000,000)
      summary: Add or update a risk word
      tags:
      - Custom Lists
  /v2/custom-lists/{custom_list_id}/risk-word/{id}:
    delete:
      description: 'Removes a single risk word from a custom list of type `RISK_WORD`, identified by its identifier. The risk word will be archived asynchronously and removed from search later.


        You need "Access to custom lists for customer screening" enabled and the "Create, update, and delete custom lists and their entities, and download entities" permission to use this endpoint.'
      operationId: customListAPIArchiveRiskWordFromList
      parameters:
      - description: The identifier of the custom list containing the risk word to be deleted.
        example: 00000000-0000-0000-0000-000000000000
        in: path
        name: custom_list_id
        required: true
        schema:
          format: uuid
          type: string
      - description: The identifier of the risk word to delete
        example: risk_word_1
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '202':
          description: The requested risk word will be archived and removed from search as soon as possible
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/customlist_ProblemDetailErrorResponse'
          description: The custom list id is expected to be a UUID, or the custom list is not of type RISK_WORD
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/customlist_ProblemDetailErrorResponse'
          description: The requested risk word could not be found.
      summary: Delete a risk word
      tags:
      - Custom Lists
    get:
      description: 'Retrieves a single risk word from a custom list of type `RISK_WORD` by its identifier.


        You need "Access to custom lists for customer screening" enabled and the "Create, update, and delete custom lists and their entities, and download entities" permission to use this endpoint.'
      operationId: customListAPIFetchRiskWordById
      parameters:
      - description: The identifier of the custom list containing the risk word to retrieve.
        example: 00000000-0000-0000-0000-000000000000
        in: path
        name: custom_list_id
        required: true
        schema:
          format: uuid
          type: string
      - description: The identifier of the risk word to retrieve
        example: risk_word_1
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customlist_RiskWordDTO'
          description: The requested risk word has been found and returned
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/customlist_ProblemDetailErrorResponse'
          description: The custom list id is expected to be a UUID, or the custom list is not of type RISK_WORD
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/customlist_ProblemDetailErrorResponse'
          description: The requested risk word could not be found.
      summary: Retrieve a risk word
      tags:
      - Custom Lists
  /v2/custom-lists/{id}:
    delete:
      description: 'Deletes a custom list if it''s not being used by a Screening Configuration


        You need "Access to custom lists for customer screening" enabled and the "Create, update, and delete custom lists and their entities, and download entities" permission to use this endpoint.'
      operationId: customListAPIDeleteCustomListById
      parameters:
      - description: The identifier of the custom list you wish to delete.
        example: 00000000-0000-0000-0000-000000000000
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '202':
          description: The custom list is deleted
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/customlist_ProblemDetailErrorResponse'
          description: The custom list id is expected to be a UUID
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/customlist_ProblemDetailErrorResponse'
          description: The custom list could not be found
        '409':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/customlist_ProblemDetailErrorResponse'
          description: The custom list being used by the Screening Configuration
      summary: Delete a custom list by its identifier
      tags:
      - Custom Lists
    get:
      description: 'Retrieve the custom list details by identifier


        You need "Access to custom lists for customer screening" enabled and the "Create, update, and delete custom lists and their entities, and download entities" permission to use this endpoint.'
      operationId: customListAPIFetchCustomListById
      parameters:
      - description: The identifier of the custom list you wish to retrieve.
        example: 00000000-0000-0000-0000-000000000000
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: The HTTP Accept header.
        example: text/csv
        in: header
        name: accept
        required: false
        schema:
          type: string
      - description: Filter by entity status.
        examples:
          Multiple statuses:
            description: Multiple statuses
            value:
            - ACTIVE
            - ARCHIVED
        in: query
        name: status
        required: false
        schema:
          default:
          - ACTIVE
          items:
            enum:
            - ACTIVE
            - ARCHIVED
            type: string
          type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customlist_CustomListDTO'
            text/csv:
              examples:
                CSV representation of a custom list:
                  description: CSV representation of a custom list
                  value: '"name","Demo"

                    "custom_list_id","01979de6-bbd0-7a82-a70d-4129d910a8d5"

                    "created_date","2025-06-23T17:47:13.744007Z"

                    "last_updated_date","2025-06-23T17:47:13.744007Z"

                    "distinct_entities","0"'
              schema:
                type: string
          description: OK
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/customlist_ProblemDetailErrorResponse'
          description: The custom list id is expected to be a UUID
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/customlist_ProblemDetailErrorResponse'
          description: The custom list could not be found
      summary: Retrieve a custom list from its identifier
      tags:
      - Custom Lists
components:
  schemas:
    customlist_PersonDTO:
      properties:
        addresses:
          items:
            $ref: '#/components/schemas/customlist_AddressDTO'
          type: array
          uniqueItems: true
        date_of_birth:
          format: date
          type:
          - string
          - 'null'
        identifiers:
          items:
            $ref: '#/components/schemas/customlist_IdentifierDTO'
          type: array
          uniqueItems: true
        names:
          $ref: '#/components/schemas/customlist_PersonNamesDTO'
        nationalities:
          description: 2 letter country code as defined by iso-3166-alpha-2
          format: iso-3166-alpha-2
          items:
            description: 2 letter country code as defined by iso-3166-alpha-2
            format: iso-3166-alpha-2
            type: string
          type: array
          uniqueItems: true
      required:
      - addresses
      - identifiers
      - names
      - nationalities
      type: object
    customlist_CustomListAddDTO:
      properties:
        description:
          type: string
        name:
          type: string
        type:
          enum:
          - CUSTOM_ENTITY
          - RISK_WORD
          type: string
      required:
      - description
      - name
      - type
      type: object
    customlist_CustomListPageDTO:
      properties:
        first:
          type: string
        lists:
          items:
            $ref: '#/components/schemas/customlist_CustomListDTO'
          type: array
        next:
          type:
          - string
          - 'null'
        prev:
          type:
          - string
          - 'null'
        self:
          type: string
      required:
      - first
      - lists
      - self
      type: object
    customlist_RiskWordAddDTO:
      properties:
        identifier:
          type: string
        word:
          maxLength: 256
          minLength: 0
          type: string
      required:
      - identifier
      - word
      type: object
    customlist_CompanyDTO:
      properties:
        addresses:
          items:
            $ref: '#/components/schemas/customlist_AddressDTO'
          type: array
          uniqueItems: true
        legal_forms:
          items:
            type: string
          type: array
          uniqueItems: true
        names:
          $ref: '#/components/schemas/customlist_CompanyNamesDTO'
        registration_numbers:
          items:
            type: string
          type: array
          uniqueItems: true
      required:
      - addresses
      - legal_forms
      - names
      - registration_numbers
      type: object
    customlist_EntityDTO:
      properties:
        additional_information:
          type:
          - string
          - 'null'
        archived_at:
          format: date-time
          type:
          - string
          - 'null'
        company:
          $ref: '#/components/schemas/customlist_CompanyDTO'
        custom_list_id:
          format: uuid
          type: string
        id:
          type: string
        last_updated:
          $ref: '#/components/schemas/customlist_AuditDTO'
        narrative:
          type:
          - string
          - 'null'
        person:
          $ref: '#/components/schemas/customlist_PersonDTO'
        url:
          type:
          - string
          - 'null'
        version:
          format: int32
          type: integer
      required:
      - custom_list_id
      - id
      - last_updated
      - version
      type: object
    customlist_PersonNamesDTO:
      properties:
        aliases:
          items:
            $ref: '#/components/schemas/customlist_PersonNameDTO'
          type:
          - array
          - 'null'
          uniqueItems: true
        primary_name:
          $ref: '#/components/schemas/customlist_PersonNameDTO'
      required:
      - primary_name
      type: object
    customlist_CompanyNamesDTO:
      properties:
        aliases:
          items:
            type: string
          type:
          - array
          - 'null'
          uniqueItems: true
        legal:
          type: string
        trading:
          items:
            type: string
          type:
          - array
          - 'null'
          uniqueItems: true
      required:
      - legal
      type: object
    customlist_EntityAddDTO:
      properties:
        additional_information:
          type:
          - string
          - 'null'
        company:
          $ref: '#/components/schemas/customlist_CompanyAddDTO'
        id:
          type: string
        narrative:
          type:
          - string
          - 'null'
        person:
          $ref: '#/components/schemas/customlist_PersonAddDTO'
        url:
          type:
          - string
          - 'null'
      required:
      - id
      type: object
    customlist_AuditDTO:
      properties:
        issued_at:
          format: date-time
          type: string
        issued_by:
          format: uuid
          type: string
        reason:
          type: string
      required:
      - issued_at
      - issued_by
      - reason
      type: object
    customlist_AddressDTO:
      properties:
        address_line1:
          type:
          - string
          - 'null'
        address_line2:
          type:
          - string
          - 'null'
        address_type:
          enum:
          - RESIDENTIAL
          - MAILING
          - OPERATING
          - REGISTRATION
          - BILLING
          type:
          - string
          - 'null'
        country_code:
          description: 2 letter country code as defined by iso-3166-alpha-2
          example: FR
          format: iso-3166-alpha-2
          maxLength: 2
          minLength: 2
          type:
          - string
          - 'null'
        country_subdivision:
          type:
          - string
          - 'null'
        full_address:
          type:
          - string
          - 'null'
        postal_code:
          type:
          - string
          - 'null'
        town_name:
          type:
          - string
          - 'null'
      type: object
    customlist_CustomListDTO:
      properties:
        archived_at:
          format: date-time
          type:
          - string
          - 'null'
        created:
          $ref: '#/components/schemas/customlist_AuditDTO'
        custom_list_id:
          format: uuid
          type: string
        description:
          type: string
        entities:
          $ref: '#/components/schemas/customlist_EntitiesCountDTO'
        last_updated:
          $ref: '#/components/schemas/customlist_AuditDTO'
        name:
          type: string
        type:
          enum:
          - CUSTOM_ENTITY
          - RISK_WORD
          type: string
      required:
      - created
      - custom_list_id
      - description
      - entities
      - last_updated
      - name
      - type
      type: object
    customlist_ProblemDetailErrorResponse:
      additionalProperties: true
      properties:
        detail:
          type:
          - string
          - 'null'
        identifier:
          format: uuid
          type: string
        instance:
          format: uri
          type:
          - string
          - 'null'
        status:
          format: int32
          type:
          - integer
          - 'null'
        timestamp:
          format: date-time
          type: string
        title:
          type:
          - string
          - 'null'
        type:
          format: uri
          type:
          - string
          - 'null'
      required:
      - identifier
      - timestamp
      type: object
    customlist_RiskWordDTO:
      properties:
        created_at:
          format: date-time
          type: string
        created_by:
          format: uuid
          type: string
        identifier:
          type: string
        updated_at:
          format: date-time
          type: string
        updated_by:
          format: uuid
          type:
          - string
          - 'null'
        word:
          type: string
      required:
      - created_at
      - created_by
      - identifier
      - updated_at
      - word
      type: object
    customlist_PersonNameDTO:
      description: "\nA name will be considered valid if:\n- full_name is set and the other fields are not\n- first_name, middle_names and last_name are set and full_name is not set\n- first_name and last_name are the only fields with a value\nAny other combination will be considered invalid\n    "
      properties:
        first_name:
          type:
          - string
          - 'null'
        full_name:
          type:
          - string
          - 'null'
        last_name:
          type:
          - string
          - 'null'
        middle_names:
          type:
          - string
          - 'null'
      type: object
    customlist_EntitiesCountDTO:
      properties:
        active_count:
          format: int32
          type: integer
      required:
      - active_count
      type: object
    customlist_PersonAddDTO:
      properties:
        addresses:
          items:
            $ref: '#/components/schemas/customlist_AddressDTO'
          type:
          - array
          - 'null'
          uniqueItems: true
        date_of_birth:
          description: Date in the format YYYY-MM-DD. Expected to be in the past and later than 1800-01-01
          example: '2000-01-01T00:00:00.000Z'
          format: date
          type:
          - string
          - 'null'
        identifiers:
          items:
            $ref: '#/components/schemas/customlist_IdentifierDTO'
          type:
          - array
          - 'null'
          uniqueItems: true
        names:
          $ref: '#/components/schemas/customlist_PersonNamesDTO'
        nationalities:
          description: 2 letter country code as defined by iso-3166-alpha-2
          format: iso-3166-alpha-2
          items:
            description: 2 letter country code as defined by iso-3166-alpha-2
            format: iso-3166-alpha-2
            type: string
          type:
          - array
          - 'null'
          uniqueItems: true
      required:
      - names
      type: object
    customlist_CompanyAddDTO:
      properties:
        addresses:
          items:
            $ref: '#/components/schemas/customlist_AddressDTO'
          type:
          - array
          - 'null'
          uniqueItems: true
        legal_forms:
          items:
            type: string
          type:
          - array
          - 'null'
          uniqueItems: true
        names:
          $ref: '#/components/schemas/customlist_CompanyNamesDTO'
        registration_numbers:
          items:
            type: string
          type:
          - array
          - 'null'
          uniqueItems: true
      required:
      - names
      type: object
    customlist_IdentifierDTO:
      properties:
        type:
          enum:
          - PASSPORT
          - NATIONAL_ID
          type: string
        value:
          type: string
      required:
      - type
      - value
      type: object
  securitySchemes:
    BearerAuth:
      description: HTTP Bearer Token Authentication
      scheme: bearer
      type: http