AML API reference

Create and review AML screening cases with an existing flow.

The AML API creates persistent screening cases with a status and audit trail.

AML routes use the unversioned API origin. Sandbox requests start with https://api.voveid.net/aml; Production requests start with https://api.voveid.com/aml. Send your private API key in the x-api-key header from your backend.

A screening result is evidence, not a final compliance decision. Review possible matches according to your organization's policy.

Configure AML flows

AML flows define which watchlists to search, whether the subject is an individual or entity, and the matching sensitivity. Create and manage flows in the VOVE ID dashboard under AML Screening → Screening Flows.

Use clear names such as “Standard individual screening” or “High-risk entity screening.” Before using a flow in Production, test it with approved sample data and confirm that its sources and matching settings meet your compliance requirements.

Create an AML case

POST /aml/case

Creates a persistent AML case and runs the screening with an existing active flow. Use this workflow when you need to review matches, track the case status, or receive status webhooks.

Request body

Field	Type	Required	Description
flowId	string	Yes	ID of the active AML flow used for screening.
screeningData	object	Yes	Person or entity data to screen.
screeningData.name	string	Yes	Full name of the person or entity.
screeningData.dob	string	No	Date of birth in DD.MM.YYYY format.
screeningData.gender	enum	No	male or female.
refId	string	Yes	Your internal reference ID for tracking this case.

type AmlGender = 'male' | 'female';
type AmlCaseStatus = 'NO_MATCH' | 'IN_REVIEW' | 'CLEARED' | 'REJECTED';

interface CreateAmlCaseRequest {
  flowId: string;
  screeningData: {
    name: string;
    dob?: string;
    gender?: AmlGender;
  };
  refId: string;
}

interface AmlCase {
  id: string;
  flowId: string;
  screeningData: CreateAmlCaseRequest['screeningData'];
  status: AmlCaseStatus;
  refId: string;
  createdAt: string;
  updatedAt: string;
}

Example request

curl https://api.voveid.net/aml/case \
  --request POST \
  --header "Content-Type: application/json" \
  --header "x-api-key: $VOVE_API_KEY" \
  --data '{
    "flowId": "507f1f77bcf86cd799439011",
    "screeningData": {
      "name": "John Doe",
      "dob": "15.03.1985",
      "gender": "male"
    },
    "refId": "customer-12345"
  }'

Example response

{
  "id": "507f1f77bcf86cd799439014",
  "flowId": "507f1f77bcf86cd799439011",
  "screeningData": {
    "name": "John Doe",
    "dob": "15.03.1985",
    "gender": "male"
  },
  "status": "IN_REVIEW",
  "refId": "customer-12345",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

The initial status is:

• NO_MATCH when the configured screening returns no matches.

• IN_REVIEW when a possible match requires manual review.

The response does not include sensitive hit details. Review possible matches in the dashboard.

List AML cases

GET /aml/case

Returns a paginated list of your organization's AML cases. Filter by status or creation date to support review queues and reconciliation jobs.

Query parameters

Parameter	Type	Required	Default	Description
page	number	No	1	One-indexed page number.
limit	number	No	10	Number of cases per page.
status	enum	No	—	NO_MATCH, IN_REVIEW, CLEARED, or REJECTED.
startDate	ISO 8601 string	No	—	Include cases created at or after this time.
endDate	ISO 8601 string	No	—	Include cases created at or before this time.

Example request

curl "https://api.voveid.net/aml/case?page=1&limit=20&status=IN_REVIEW" \
  --header "x-api-key: $VOVE_API_KEY"

Example response

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439014",
      "flowId": "507f1f77bcf86cd799439011",
      "screeningData": {
        "name": "John Doe",
        "dob": "15.03.1985",
        "gender": "male"
      },
      "status": "IN_REVIEW",
      "refId": "customer-12345",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}

interface AmlCaseListResponse {
  data: AmlCase[];
  total: number;
  page: number;
  limit: number;
}

To filter by date range:

curl "https://api.voveid.net/aml/case?startDate=2024-01-01T00:00:00.000Z&endDate=2024-01-31T23:59:59.999Z" \
  --header "x-api-key: $VOVE_API_KEY"

Get an AML case by reference ID

GET /aml/case/{refId}

Retrieves one case using the refId you supplied when creating it.

Path parameter	Type	Required	Description
refId	string	Yes	Your internal case reference.

curl https://api.voveid.net/aml/case/customer-12345 \
  --header "x-api-key: $VOVE_API_KEY"

The response uses the AmlCase shape shown above. A 404 Not Found response means the reference does not exist or does not belong to your organization.

Webhook events

VOVE ID sends AML webhooks when a case is created or its status changes. Webhooks are sent only when the case has a refId.

Event	Status
user.aml.no_match	NO_MATCH
user.aml.in_review	IN_REVIEW
user.aml.cleared	CLEARED
user.aml.rejected	REJECTED

{
  "refId": "customer-12345",
  "status": "IN_REVIEW"
}

Case creation with POST /aml/case can trigger a webhook when the case has a refId.

Verify the Svix signature, deduplicate events using svix-id, and retrieve the current case before applying a consequential decision. See Webhooks.

Errors

HTTP status	Meaning	Recommended action
400	Invalid request data or an inactive flow.	Correct the request before trying again.
401	Missing or invalid API key.	Check the environment and private key.
404	Flow or case not found.	Check the identifier and environment.
429	Rate limit exceeded.	Retry with bounded backoff.
500	Unexpected server error.	Retry safely with backoff and reconcile before repeating a write.

{
  "statusCode": 400,
  "message": "Date of birth must be in DD.MM.YYYY format",
  "error": "Bad Request"
}

Integration guidance

• Keep the private API key on your backend.

• Use a stable, non-sensitive refId for each subject.

• Use AML cases when you need review history or webhooks.

• Review names, aliases, dates, citizenship, positions, and source details. Do not decide from a score alone.

• Treat unknown statuses as pending review.

• Do not log full screening payloads or watchlist records.

Continue with the AML operations guide for the analyst and reviewer workflow.