Turn any search into ongoing monitoring so customers are automatically re-screened as sanctions lists, PEP registries, and adverse media change. Start and stop monitoring on a search, swap the associated search profile, retrieve what changed (new, updated, and removed matching entities), and acknowledge changes. The monitored_search_updated webhook pushes change notifications to your systems.
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