ComplySwiss API: connect your systems

What you can achieve

Bring customer records from a CRM into ComplySwiss, submit transactions for AML rule checks, read resulting alerts, and receive event notifications in your own system. The API supports your workflow; it does not replace a compliance review.

1. Choose the right organization

Sign in as an administrator allowed to manage settings. Select the organization whose data the integration should use, then open Integrations → API & Webhooks. Every key is bound to that organization; it cannot read or write another organization's data.

2. Create an API key

Enter a descriptive name and select only the scopes needed: customers:read, customers:write, transactions:read, transactions:write, or alerts:read. Select Create API key. The complete key is shown only once: copy it into a secure server-side secret store. If it is exposed, revoke it on the same page and create a new one.

Available v1 endpoints

Base path: /api/v1/. Read operations return JSON. List endpoints support limit (1–100, default 50) and after_id pagination; use next_after_id to request the next page.

3. Test a read request

Use a key with customers:read. Replace YOUR_API_KEY locally. A successful list response contains data and next_after_id. This example only reads records; it does not create anything.

curl -i 'https://complyswiss.ch/api/v1/customers.php?limit=10' \
  -H 'Authorization: Bearer YOUR_API_KEY'

4. Create a practice customer

For a controlled test, use a test organization and a key with customers:write. POST a JSON body for an individual; first_name and last_name are required. The response contains the new id, customer_number, risk_score, risk_level and any country_sanctions_alert. Nationality, residence and beneficial-owner nationality are checked against the SECO country-programme catalogue; a match is a review signal, not a blanket prohibition. A company customer instead needs company_name and at least one beneficial_owners entry with first_name and last_name.

curl -i -X POST 'https://complyswiss.ch/api/v1/customers.php' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"customer_type":"individual","first_name":"Demo","last_name":"Muster","nationality":"CH"}'

5. Submit a practice transaction

With transactions:write, replace customer_id 123 in the example with the id of a customer in the same organization. transaction_type and a positive amount are required. The response contains the transaction reference, risk_score and any alerts; configured AML rules and the transaction country are evaluated. A country-programme alert requires review of the applicable SECO ordinance and does not by itself mean that the transaction is prohibited. Optional blockchain screening runs only when enabled for that organization.

curl -i -X POST 'https://complyswiss.ch/api/v1/transactions.php' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"customer_id":123,"transaction_type":"transfer","amount":100,"fiat_amount":100,"fiat_currency":"CHF"}'

6. Read the alerts

Use alerts:read with GET /api/v1/alerts.php?status=open. An empty data array means no matching alerts for that request; it does not prove that a customer or transaction has no AML risk. Review alerts and decisions in the application.

curl -i 'https://complyswiss.ch/api/v1/alerts.php?status=open&limit=10' \
  -H 'Authorization: Bearer YOUR_API_KEY'

7. Receive events with webhooks (optional)

Under Integrations → API & Webhooks, add a receiver URL and select customer.created, transaction.created, alert.created and/or blockchain.screening.completed. Copy the signing secret when it is shown. ComplySwiss sends a JSON POST with X-ComplySwiss-Event and X-ComplySwiss-Signature. Verify the HMAC SHA-256 signature against the raw request body before processing the event. Return a 2xx status on success; review Recent webhook deliveries and use Retry for failures.

If a request fails

401 means the Bearer key is missing, invalid or inactive; 403 means its scope does not permit the action; 404 means the requested id is not visible in this organization; 422 means input validation failed; 405 means the method is unsupported. Check the JSON error and the key's selected organization and scopes.

Scope and expectations

The current v1 routes above cover customers, transactions and alerts. This tutorial does not describe an API endpoint for identity document scanning or direct sanctions screening. Automation can save manual work, but it does not guarantee regulatory compliance or a financial return.