Sentinel Comply API

Authentication

Every Partner API request carries your API key in the X-API-Key header. A missing or unknown key is answered with 401, a deactivated one with 403.

Each key has its own request limit per minute, set on the key in the console (60 unless changed). Every Partner API response reports where you stand in X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the count restarts); over the limit the answer is 429 with a Retry-After header.

The hosted KYC flow does not use your key. Opening the kyc_url once sets a session cookie in the customer's browser, and the hosted page's calls are authorised by that cookie, so the key never reaches the applicant's browser.

curl -X POST "https://comply.mapaycard.com/partner/api/v1/sessions" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
       "user_id": "u_4411",
       "reference": "PC-118822",
       "applicant": {
         "first_name": "Mamadou Saliou",
         "last_name": "Diallo",
         "date_of_birth": "1990-04-12",
         "gender": "M"
       },
       "locale": "fr",
       "success_redirect": "https://app.example.com/kyc/done",
       "failure_redirect": "https://app.example.com/kyc/failed",
       "cancel_redirect": "https://app.example.com/kyc/cancelled",
       "pending_redirect": "https://app.example.com/kyc/pending",
       "metadata": {}
     }'

Hosted flow integration

The customer verifies their identity on a page this server hosts: you create a session from your server, open its kyc_url on the customer's phone, and get them back in your app when they finish. The decision reaches your server by webhook.

Sequence

1. Your app→Your server

   The customer taps "Verify my identity".

2. Your server→Sentinel

   POST /partner/api/v1/sessions with user_id, applicant and the four *_redirect URLs. The answer carries kyc_url: single-use, valid 30 minutes.

3. Your server→Your app

   Hand kyc_url to the app. Do not open or fetch it on the way.

4. Your app→Browser

   Open it once: a Custom Tab on Android, SFSafariViewController or ASWebAuthenticationSession on iOS (a WebView only with the checklist below).

5. Browser↔Sentinel

   Consent, ID document, face. The first open spends the link's token and sets a session cookie in that browser.

6. Sentinel→Browser

   At the end, or when the customer leaves, the browser is sent to one of your redirect URLs with ?session_id=…&status=….

7. Browser→Your app

   Your redirect URL is an Android App Link or an iOS universal link (or the ASWebAuthenticationSession callback), so the app comes back to the front and shows the outcome.

8. Sentinel→Your server

   Webhook session.approved, session.rejected or session.completed (in review). This, or GET /partner/api/v1/sessions/{session_id}, is the decision.

One customer at a time per device. Opening a link ends any other customer's verification on that browser: their page asks them to sign in again. On a phone shared by two customers (an in-app browser keeps one cookie store), the first one gets a new link from your app (create the session again with their user_id) to resume or to see their outcome.

Return URLs

The browser is sent to your URL with session_id, status and, when you gave one, reference added to its query string. No reason, code or score is ever added. Without a URL for an outcome, the page tells the customer they can close it.

status is for what the app shows only: anyone can type that URL. Grant nothing on it; read the decision from the webhook or GET /partner/api/v1/sessions/{session_id}.

Opening the link on Android

Use a Custom Tab (androidx.browser): the camera, the photo picker and the cookie work with no extra code, and the customer sees the real address. Make your redirect URLs verified App Links (an https intent filter with android:autoVerify="true" and an assetlinks.json on your domain), so the redirect returns to the app.

CustomTabsIntent.Builder()
    .setShowTitle(true)
    .build()
    .launchUrl(context, Uri.parse(kycUrl))

Opening the link on iOS

Use ASWebAuthenticationSession with your redirect's callback (a custom scheme, or an https callback on iOS 17.4 and later): the session closes by itself when the browser reaches your redirect URL. SFSafariViewController also works, with the redirect URLs as universal links. Both have the camera. A WKWebView needs NSCameraUsageDescription, allowsInlineMediaPlayback = true, mediaTypesRequiringUserActionForPlayback = [], and on iOS 15 and later a WKUIDelegate that grants requestMediaCapturePermissionFor for this server's origin.

If you must use an Android WebView

A WebView has none of this by default. Without every item below the camera stays black, the upload button does nothing, or the redirect opens inside the WebView.

• Declare android.permission.CAMERA in the manifest and ask for it at run time before opening the page.
• setJavaScriptEnabled(true) and setDomStorageEnabled(true).
• setMediaPlaybackRequiresUserGesture(false), or the camera preview does not start.
• A WebChromeClient whose onPermissionRequest grants RESOURCE_VIDEO_CAPTURE to this server's origin only.
• onShowFileChooser, for "choose a photo or PDF".
• shouldOverrideUrlLoading, to catch your redirect URLs and close the WebView.
• Cookies on (CookieManager.setAcceptCookie(true)): the session continues on a cookie after the first open.

val kycOrigin = "https://comply.mapaycard.com"

webView.settings.apply {
    setJavaScriptEnabled(true)
    setDomStorageEnabled(true)
    setMediaPlaybackRequiresUserGesture(false)
}
CookieManager.getInstance().setAcceptCookie(true)

webView.webChromeClient = object : WebChromeClient() {
    // The app must already hold android.permission.CAMERA.
    override fun onPermissionRequest(request: PermissionRequest) {
        val video = PermissionRequest.RESOURCE_VIDEO_CAPTURE
        if (request.origin.toString().startsWith(kycOrigin) && video in request.resources) {
            request.grant(arrayOf(video))
        } else {
            request.deny()
        }
    }

    override fun onShowFileChooser(
        view: WebView, callback: ValueCallback<Array<Uri>>, params: FileChooserParams,
    ): Boolean {
        filePathCallback = callback              // answered from the launcher's result
        fileChooser.launch(params.createIntent())
        return true
    }
}

webView.webViewClient = object : WebViewClient() {
    override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
        val url = request.url
        if (url.toString().startsWith("https://app.example.com/kyc/")) {   // your *_redirect URLs
            onKycReturn(url.getQueryParameter("session_id"), url.getQueryParameter("status"))
            return true
        }
        return false
    }
}

webView.loadUrl(kycUrl)

Errors

Errors use the HTTP status codes below and a JSON body with a detail key, in one of three shapes. Branch on detail.error when it is there, never on message: messages are English text for your logs and may change.

// 1. A coded error: detail is an object with error and message (and sometimes more keys)
{
  "detail": {
    "error": "SESSION_IN_REVIEW",
    "message": "This customer has a verification in review. Wait for the decision.",
    "session_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

// 2. A plain error: detail is a string (401, 403, 404, 429, some 400)
{
  "detail": "Session not found"
}

// 3. Validation (422): detail lists every failing field. On POST /sessions,
//    error and message are added next to it for applicant and user_id.
{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "applicant", "gender"],
      "msg": "Value error, must be M or F",
      "input": "X"
    }
  ],
  "error": "APPLICANT_INVALID",
  "message": "applicant.gender: must be M or F"
}

Error codes

A 429 or 503 answered while the server restarts has the body {"code": "…", "message": "…", "detail": "…"}, with a plain detail string: retry after a short wait.

Webhooks

Set a webhook URL and signing secret on your API key in the console. Events for every session created with that key are then POSTed to it as JSON. In production a key without a signing secret gets no deliveries: an unsigned event is never sent.

{
  "event_id": "3f6c2b1e-8a4d-4f7e-9c21-5d8e7a1b0c42",
  "event_type": "session.approved",
  "created_at": "2026-09-22T10:30:00",
  "sequence": 7,
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "reference": "PC-118822",
    "user_id": "u_4411",
    "status": "approved",
    "generation": 0,
    "source": "session",
    "purpose": "onboarding",
    "previous_session_id": null,
    "risk_score": 12,
    "risk_level": "low",
    "approved_at": "2026-09-22T10:30:00",
    "decided_by": "system",
    "reason_codes": [],
    "identity_match": "match"
  }
}

• All timestamps are UTC (ISO 8601, no offset): 2026-09-22T10:30:00 is 10:30 UTC.
• sequence counts the events of one session, starting at 1. Deliveries can arrive late or out of order: store the highest sequence applied per session and apply an event only if its sequence is greater.
• Every data carries session_id, reference, user_id, status, generation, source, purpose, previous_session_id. status is the onboarding status when the event was sent; generation counts the session's resets; source is session, or a dossier's source (see Dossiers without verification); purpose is onboarding, or renewal with previous_session_id naming the approval it renews (see Renewals).
• risk_score is an integer from 0 to 100. Screening events report status but never change it.

Events

Headers

Verifying a delivery

The signature is an HMAC-SHA256 of <timestamp>.<raw body>, keyed with your signing secret. Compute it over the raw request body, compare in constant time, and reject timestamps outside a short window (five minutes is typical) to stop replays.

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str, tolerance: int = 300) -> bool:
    timestamp = headers["X-Webhook-Timestamp"]
    if abs(time.time() - int(timestamp)) > tolerance:
        return False
    expected = hmac.new(
        secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    received = headers.get("X-Webhook-Signature", "").removeprefix("sha256=")
    return hmac.compare_digest(expected, received)

Delivery and retries

Deliveries are sent in the background, so the request that triggered an event never waits on your endpoint. Answer with any 2xx status; anything else, or no answer within 15 seconds, counts as a failure.

Each delivery is attempted up to 5 times: once straight away, then again after 1 min, 5 min, 15 min and 1 h. The same event can arrive more than once, so use X-Webhook-ID to ignore repeats. Deliveries can be listed and retried by hand with the webhook endpoints below.

Face duplicates

After a session is submitted, its selfie is compared with the faces of every other customer. A match with another user_id is never approved or declined automatically: the case goes to manual review with a high priority, you receive session.duplicate_detected, and a reviewer compares both people and resolves the match (session.duplicate_resolved). A match with the same user_id is a new attempt by the same customer and is not reported.

GET /partner/api/v1/sessions/{session_id} carries the result in duplicates. It is null until the session is submitted.

{
  "checked": true,
  "review_priority": "high",
  "open_count": 1,
  "items": [
    {
      "duplicate_check_id": 41,
      "match_type": "FACE_MATCHES_OTHER_IDENTITY",
      "same_partner": true,
      "matched_user_id": "u_9",
      "matched_session_id": "5b1e2c4a-7d0f-4e8b-9a61-0c3d2f1e4b57",
      "matched_session_ids": ["5b1e2c4a-7d0f-4e8b-9a61-0c3d2f1e4b57"],
      "similarity": 0.812,
      "detected_at": "2026-10-09T10:02:11",
      "resolution": null,
      "resolved_at": null
    }
  ],
  "flag": null
}

PDF documents

In the hosted flow, the ID document (front and back) and the proof of residence can be a photo or a PDF. A PDF must have at most 5 pages, weigh at most 10 MB and have no password. The server renders one page and checks it like a photo: an ID card scanned on a full page is cropped to the card, and the back of the card can be page 2 of the same PDF. The selfie and the liveness check are photos only. Nothing changes in the Partner API: results and webhooks are the same whatever the file type.

Renewals

When the ID document of a customer you already verified expires, create a session for the same user_id with "purpose": "renewal" and send the customer through the hosted flow as usual (new document, selfie, liveness). The customer must have an approved session or an imported dossier under your key, otherwise the create answers 409 NO_APPROVED_SESSION; previous_session_id names that approval in the create response, in every webhook and in GET /sessions/{id}.

The renewal is checked against the approval, and goes to manual review (never a rejection) with one of these reason codes:

The duplicate checks treat the customer's own sessions as expected, so a renewal is never a duplicate of its approval. Once the renewal is approved, screening by user_id uses it: there is nothing to import again.

Dossiers without verification

A customer can be screened without going through the hosted flow. The identity is kept as a dossier: a session with no document image, no selfie and no liveness check, whose source says where the identity came from. Every session payload and every webhook carries source: session for the hosted verification, declared for an identity your app sent unverified, legacy_import for a KYC you approved before Sentinel. For a dossier, dossier is set and every onboarding.checks value is not_performed.

Declared dossier

POST /partner/api/v1/dossiers/declared keeps the identity a customer declared, for a customer with no submitted verification. Its status is unverified and it is never approved. Screen it with POST /sessions/{session_id}/screening, or by user_id with allow_unapproved. Sending the same user_id again updates it: when the name, date of birth, nationality or document changed, identity_changed is true, earlier results are stale, and the next screening request screens again. A customer with a submitted verification gets 409 SESSION_EXISTS. A verification the customer submits later supersedes the dossier: dossier.superseded_by_session_id names it, and the dossier stays readable. No webhook is sent for the dossier itself.

Imported dossier

POST /partner/api/v1/dossiers/import keeps a KYC you approved before Sentinel as an approved dossier (source legacy_import, onboarding.decided_by partner_import), with who approved it and when in approval. approval.approved_at is UTC (an ISO datetime without offset is read as UTC) or null when unknown, which dossier.approved_at_unknown then says. No image is sent and no check is run: it was approved by your officer, not verified here, and no session.approved webhook is sent. Document images cannot be sent with an import in this version. Screen it like any approved session.

The document number is checked against every other customer's dossier and verification. A match with one of your own customers is returned in duplicates, sent as session.duplicate_detected and shown in the session's duplicates.items with match_type DOCUMENT_NUMBER_MATCH. It is reported once and never changes the approval; it does not count in open_count. A number held by another partner's customer is shown to Sentinel's reviewers only. Importing the same user_id again updates the dossier. A customer's declared dossier becomes the imported one with the same session_id (superseded_declared), and keeps its screening when the identity is the same. A customer with a submitted verification gets 409 SESSION_EXISTS. Neither kind of dossier can be reset, and a Sentinel officer cannot approve or reject one.

document.type takes the values listed in Document types.

Screening a name

POST /partner/api/v1/screenings/names screens a name now, without a session: the beneficiary of a transfer, a person or an organization. The answer comes in the response. Nothing follows it: no webhook, no adjudication, no session.

// Request
{"name": "Mamadou Diallo", "country": "SN", "entity_type": "person", "reference": "TRF-2026-104233"}

// 200
{
  "query_id": "6f1c2a…",
  "screening_status": "completed",
  "screening_outcome": "potential_match",
  "results": [
    {"category": "sanctions", "state": "potential_match", "matches": [
      {"entity_id": "NK-…", "name": "…", "score": 91.0, "datasets": ["us_ofac_sdn"], "topics": ["sanction"], "url": "…"}
    ]},
    {"category": "pep", "state": "no_match", "matches": []},
    {"category": "adverse_media", "state": "no_match", "matches": []}
  ],
  "billed": true
}

• One OpenSanctions query, billed like a session's: GET /me counts it in billed_queries. A call answered 503 (SCREENING_UNAVAILABLE, SCREENING_DISABLED, SCREENING_NOT_CONFIGURED) is not billed.
• A person is also compared with the national list, free; a hit there has an entity_id starting with gn-local: and a local_entry with the act's reference and the notes (null on other matches). An organization is not screened for PEP, nor against the national list.
• country is ISO 3166-1 alpha-2 (alpha-3 accepted), optional; reference is yours, up to 100 characters; entity_type defaults to person. Scores are 0 to 100, as on a session's results.
• Sentinel keeps the query_id, your reference, the entity type, the country and the outcome, for billing and audit. It never stores the name.

National list

Besides the OpenSanctions sources (the UN Security Council consolidated list, OFAC, EU, UK, PEPs, adverse media), every screening compares the people screened with Sentinel's local list: people designated by a Guinean act (an arrêté), entered by Sentinel's administrators. It starts empty: no Guinean national list was found published.

• A hit on it is a sanctions hit like any other: entity_id starts with gn-local:, datasets is ["gn_local_list"], topics is ["sanction"], and local_entry gives the act's reference and the notes. Adjudicate it as any hit.
• It costs nothing: only the OpenSanctions query is billed.
• Editing the list screens no one. A person added to it takes effect at each customer's next screening: the first screening of the account, the monthly re-screening (POST /screenings/batch with rescreen: true) or a screening request with rescreen: true. Until then, a customer already screened is not compared with the new entry. A person taken off the list leaves their hits until a reviewer clears them.

Document types

The same values everywhere: document.type of a declared or imported dossier, document_type of GET /sessions/{session_id}/identity and of document_identity in GET /sessions/{session_id}. Compare them exactly (lower case); a value not listed here is never sent.