API Docs

Authentication

• Send the API key in header X-Api-Key.
• The company is resolved automatically from the key (no company-id header required).
• Keys are shown once when created. Rotate by creating a new key and revoking the old one.

Endpoints

Create customer (JSON)

Required: type. Recommended: externalId.

curl -X POST "$API_BASE/api/public/customers" \
  -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "crm-123",
    "type": "Individual",
    "fullName": "Jane Doe",
    "email": "jane@example.com",
    "country": "US",
    "dateOfBirth": "1990-01-01",
    "isPep": false,
    "customFieldValues": [
      { "fieldDefinitionId": "GUID", "value": "Example" }
    ]
  }'

{ "customerId": "GUID", "documentIds": [] }

Create customer (multipart + documents)

• Include customer (JSON string) in the form body.
• If you upload files, also include documentsMeta as a JSON array with the same length and order as the files.

curl -X POST "$API_BASE/api/public/customers" \
  -H "X-Api-Key: YOUR_KEY" \
  -F "customer={\"externalId\":\"crm-123\",\"type\":\"Individual\",\"fullName\":\"Jane Doe\"}" \
  -F "documentsMeta=[{\"documentTypeId\":\"GUID\",\"documentCategoryId\":null}]" \
  -F "file=@passport.jpg"

{ "customerId": "GUID", "documentIds": ["GUID"] }

Create customer from images (AI)

Upload 1–2 images. The API runs AI extraction and creates the customer + stores a document.

curl -X POST "$API_BASE/api/public/customers/ai-create" \
  -H "X-Api-Key: YOUR_KEY" \
  -F "files=@front.jpg" \
  -F "files=@back.jpg"

Request requirements

• Required: type
• If type = Business: businessName is required.
• If type = Individual: fullName is required.
• Recommended: externalId (lets you safely retry without duplicates).

Operational headers

• X-Api-Key — required on all public API calls.
• Idempotency-Key — optional on POST/PATCH; safe retries within TTL (default 24h). Reuse with a different body → 409.
• X-Correlation-Id — optional tracing; echoed when provided.

Mandatory field policies (profile & transaction)

Admins configure mandatory standard/custom fields per customer type, country, subgroup, and optional transaction participant role (sender vs beneficiary). These policies drive gap queries and payment readiness — separate from compliance holds (TM/screening).

• POST /api/public/customers enforces only requirement sets with no participant role selected.
• PATCH /api/public/customers accepts partial updates; use data-gaps endpoints to see what is still required.
• GET /api/public/customers/{id}/data-gaps uses role-agnostic sets only (refresh=true re-evaluates first).
• Sets scoped to SENDER, BENEFICIARY, etc. apply on GET .../transactions/{id}/customer-data-gaps and nested payment-readiness.customerDataGaps. Ingest role RECEIVER is normalized to BENEFICIARY.
• KYC document gaps use dashboard Document requirements (customer type + country filters). missingDocuments lists documentTypeId; upload via POST .../customers/{id}/documents. kycDataComplete = fields + documents (not TM).
• Transaction-level mandatory fields use GET .../transaction-data-gaps; PATCH /api/public/transactions can fill narrative/SOF fields.

Get customer (lookup)

Load a full profile by Complii customer ID, external ID, or phone. The profile includes ucidId when the customer is in a cluster. by-external-id returns 409 when more than one customer shares the same externalId.

curl "$API_BASE/api/public/customers/by-external-id?externalId=crm-123" \
  -H "X-Api-Key: YOUR_KEY"

Update customer (PATCH)

Send only fields to change (same shape as create, all optional). Supports customerSubtypeId and customFieldValues. Omitted properties are left unchanged.

curl -X PATCH "$API_BASE/api/public/customers/{customerId}" \
  -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: patch-crm-123-v2" \
  -d '{
    "email": "jane@example.com",
    "addressLine1": "1 Main St",
    "customFieldValues": [{ "fieldDefinitionId": "GUID", "value": "Updated" }]
  }'

{ "customerId": "GUID", "updated": true }

Customer KYC data gaps (single customer)

Returns missingMandatory (profile fields) and missingDocuments (document requirement policies). refresh=true re-evaluates field and document requirements. profileDataComplete / documentsDataComplete are separate; kycDataComplete is true when both are satisfied.

curl "$API_BASE/api/public/customers/{customerId}/data-gaps?refresh=true" \
  -H "X-Api-Key: YOUR_KEY"

{
  "customerId": "GUID",
  "externalId": "crm-123",
  "profileDataComplete": false,
  "mandatoryPendingCount": 2,
  "missingMandatory": [
    { "fieldLabel": "Date of birth", "fieldKind": "Standard", "standardFieldKey": "dateOfBirth", "customFieldDefinitionId": null }
  ],
  "documentsDataComplete": false,
  "documentMandatoryPendingCount": 1,
  "missingDocuments": [
    { "documentTypeId": "GUID", "documentTypeName": "Passport", "templateId": "GUID", "requirementNodeId": "GUID", "label": null }
  ],
  "kycDataComplete": false
}

Field role-specific sets apply on transaction customer-data-gaps. Document policies are per customer (same missingDocuments for each participant role sharing that customer).

Upload customer document (KYC)

Attach 1–2 files (documentTypeId required). AI runs only when the matching document requirement policy has Use AI analysis enabled and the AI add-on is active; otherwise plain store (aiValidated false).

curl -X POST "$API_BASE/api/public/customers/{customerId}/documents" \
  -H "X-Api-Key: YOUR_KEY" \
  -F "documentTypeId=GUID" \
  -F "documentCategoryId=GUID" \
  -F "documentNumber=B00001234" \
  -F "file=@passport-front.jpg" \
  -F "file=@passport-back.jpg"

{ "customerId": "GUID", "documentId": "GUID", "aiValidated": false }
// With AI Compliance Automation add-on: aiValidated true + confidence; 400 if validation fails (document not stored)

Transaction customer data gaps (per role)

One participants[] entry per transaction party with participantRole and role-filtered missingMandatory. Configure role scope on dashboard Customers → Field requirements.

curl "$API_BASE/api/public/transactions/{transactionId}/customer-data-gaps?refresh=true" \
  -H "X-Api-Key: YOUR_KEY"

{
  "transactionId": "GUID",
  "profileDataComplete": false,
  "participants": [
    {
      "customerId": "GUID",
      "externalId": "CM-CUST-SENDER",
      "participantRole": "SENDER",
      "roles": ["SENDER"],
      "profileDataComplete": false,
      "mandatoryPendingCount": 1,
      "missingMandatory": [
        { "fieldLabel": "Occupation", "fieldKind": "Standard", "standardFieldKey": "occupation" }
      ],
      "documentsDataComplete": true,
      "missingDocuments": [],
      "kycDataComplete": false
    },
    {
      "customerId": "GUID",
      "externalId": "CM-CUST-BEN",
      "participantRole": "BENEFICIARY",
      "roles": ["BENEFICIARY"],
      "profileDataComplete": true,
      "mandatoryPendingCount": 0,
      "missingMandatory": [],
      "documentsDataComplete": false,
      "missingDocuments": [{ "documentTypeName": "Proof of address" }],
      "kycDataComplete": false
    }
  ]
}

Compliance preview (before a transaction)

Ask what to collect before MoneyRail creates the transfer. These calls do not create customers or transactions and do not change ingest or the existing gap endpoints. RECEIVER is returned as BENEFICIARY. Document rules follow the person's country and type. After the transfer exists, keep using GET .../customer-data-gaps.

curl -X POST "$API_BASE/api/public/compliance/requirements" \
  -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parties": [
      { "role": "SENDER", "country": "US", "customerType": "Individual" },
      { "role": "RECEIVER", "country": "CO", "customerType": "Individual" }
    ],
    "draft": { "amount": 1500, "currency": "USD", "originCountry": "US", "destinationCountry": "CO", "payoutMethod": "CASH" }
  }'

curl -X POST "$API_BASE/api/public/compliance/gaps" \
  -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parties": [
      { "role": "SENDER", "externalId": "mr-sender-1" },
      { "role": "BENEFICIARY", "externalId": "mr-receiver-9" }
    ],
    "draft": { "originCountry": "US", "destinationCountry": "CO", "purposeOfTransfer": "Family support", "sourceOfFunds": "Salary" }
  }'

Synchronous transaction ingest

POST .../ingest-sync runs UCID transaction monitoring (and configured TM webhooks) before the HTTP response when SynchronousTransactionIngest:Enabled on the API host. Returns 403 when disabled.

curl -X POST "$API_BASE/api/public/transactions/ingest-sync" \
  -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... same body as POST /api/public/transactions ... }'

Update transaction (PATCH)

Partial update for purpose, source of funds, relationship, notes, fundingSourceType, and payoutMethod — commonly used to clear transaction-level mandatory field gaps.

curl -X PATCH "$API_BASE/api/public/transactions/{transactionId}" \
  -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "purposeOfTransfer": "Family support",
    "sourceOfFunds": "Salary",
    "relationshipSenderBeneficiary": "Sibling"
  }'

Payment readiness & data gaps

KYC (profile fields + documents), transaction field gaps, and compliance holds are separate checks. readyToPay requires kycDataComplete for every participant, transaction fields, and cleared holds.

• GET .../customer-data-gaps — mandatory profile fields per participant; use participantRole (sender vs beneficiary) to drive UI.
• GET .../transaction-data-gaps — mandatory transaction-level fields (tenant policy).
• GET .../compliance-holds — open TM and screening alerts blocking payout (separate from profile gaps).
• GET .../payment-readiness — aggregate: readyToPay when profile + transaction data complete and compliance holds cleared.

{
  "transactionId": "GUID",
  "profileDataComplete": false,
  "documentsDataComplete": false,
  "kycDataComplete": false,
  "transactionDataComplete": true,
  "complianceHoldsCleared": true,
  "readyToPay": false,
  "customerDataGaps": {
    "profileDataComplete": false,
    "documentsDataComplete": false,
    "kycDataComplete": false,
    "participants": [
      {
        "customerId": "GUID",
        "participantRole": "SENDER",
        "roles": ["SENDER"],
        "missingMandatory": [{ "fieldLabel": "Occupation", "standardFieldKey": "occupation" }]
      },
      {
        "customerId": "GUID",
        "participantRole": "BENEFICIARY",
        "roles": ["BENEFICIARY"],
        "missingMandatory": []
      }
    ]
  },
  "transactionDataGaps": { "transactionDataComplete": true, "missingMandatory": [] },
  "complianceHolds": { "complianceHoldsCleared": true, "blockingMonitoringAlerts": [], "blockingScreeningAlerts": [] }
}

Outbound webhooks (TM clearance URL)

Configure the transaction clearance webhook in the dashboard (JWT). The same HTTPS URL can receive customer profile gap events when notifyCustomerDataGaps is enabled.

• transaction.alertsCleared — TM clearance when transaction and all customers are clear.
• customer.profileDataGapsChanged / customer.profileDataComplete — when notifyCustomerDataGaps is enabled on the same TM clearance webhook URL (dashboard / JWT settings).

{
  "event": "customer.profileDataGapsChanged",
  "customerId": "GUID",
  "externalId": "crm-123",
  "profileDataComplete": false,
  "mandatoryPendingCount": 1,
  "missingMandatory": [ { "fieldLabel": "...", "fieldKind": "Standard", "standardFieldKey": "email" } ]
}

Inbound crypto event ingest uses POST /api/public/crypto/webhooks/events (separate from TM clearance). See repository docs/public-api.md for Blockchain Intelligence.

Create customer (JSON) — full field reference

customFieldValues[] item — field reference

documentsMeta[] item — field reference (multipart documents)

AI create response — extracted fields

The AI endpoint returns analysis.fields where each value is a string (or null).

Public Transactions API

Ingest transactions with participant snapshots. Complii resolves/matches customers, stores the transaction + snapshot, and calculates a transaction risk summary. Screening is executed using the selected Screening Preset (or the default preset marked as "Incoming Tx Default").

curl -X POST "$API_BASE/api/public/transactions" \
  -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalTransactionId": "CM-00012345",
    "createdAtUtc": "2025-12-16T18:20:00Z",
    "transactionType": "REMITTANCE",
    "status": "COMPLETED",
    "amount": 250.00,
    "currency": "USD",
    "screeningPresetId": "GUID (optional)",
    "originCountry": "US",
    "destinationCountry": "CO",
    "participants": [
      { "role": "SENDER", "customerType": "INDIVIDUAL", "externalCustomerId": "CM-CUST-7788", "fullName": "Carlos Mendoza", "country": "US" },
      { "role": "BENEFICIARY", "customerType": "INDIVIDUAL", "fullName": "Maria Perez", "country": "CO" }
    ]
  }'

{ "transactionId": "GUID", "externalTransactionId": "CM-00012345", "participantCustomerIds": ["GUID","GUID"], "riskScore": 30, "riskLevel": "Medium", "screeningRunId": "GUID", "screeningPresetIdUsed": "GUID", "screeningTotalMatches": 0, "screeningSuspectAlerts": 0, "participants": [{ "role": "SENDER", "customerId": "GUID", "universalCustomerIdentityId": "GUID", "customerStatus": "Exists", "matchMethod": "ExternalId" }] }

Transaction (top-level) — full field reference

attachments[] item — field reference

participants[] item — field reference

participant documents (identificationDocuments[] / businessDocuments[] / files[]) — field reference