Quickstart

Try it in Postman

The fastest way to explore the API is our Postman collection. The OAuth token flow is pre-wired, so you just add your credentials and hit Send — no code required.

Import

Click Run in Postman above to copy the collection into your workspace, then import the Sphinx API - Production environment.

Add your credentials

Open the environment (eye icon) and paste the client_id and client_secret from your dashboard (Organisation → API Credentials).

Run the flow

Send Get Access Token (it saves the token automatically), then Upload Document and Create Case — each request inherits the token, so you just hit Send.

Authentication

All API requests are authenticated using bearer tokens which you can generate from the dashboard. Include the token in the Authorization header. Example: Authorization: Bearer <YOUR_TOKEN>

Easiest steps for running a case

Upload Documents (Optional)
✅ Usually required for KYB, KYC EDD and transaction monitoring
❌ Usually not required for AML (PEP, Sanctions, Adverse Media)
Create a Case
Provide customer details and a case_config slug — checks are created automatically.
Webhook
The result of a case is sent back your side.

1. Upload Documents (Optional)

Use the documents endpoint to upload supporting files and receive a document ID:

curl -X POST https://app.sphinxhq.com/api/documents/ \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "file": "data:application/pdf;base64,JVBERi0xLjQKJ...",
    "original_name": "document.pdf"
  }'

import requests

url = "https://app.sphinxhq.com/api/documents/"
payload = {
    "file": "data:application/pdf;base64,JVBERi0xLjQKJ...",
    "original_name": "document.pdf",
}
r = requests.post(url, json=payload, headers={"Authorization": "Bearer <YOUR_TOKEN>"})
print(r.json())  # Returns: {"id": 123, "original_name": "document.pdf", ...}

import axios from 'axios';

axios.post(
  'https://app.sphinxhq.com/api/documents/',
  {
    file: 'data:application/pdf;base64,JVBERi0xLjQKJ...',
    original_name: 'document.pdf',
  },
  { headers: { Authorization: 'Bearer <YOUR_TOKEN>' } },
).then(res => console.log(res.data));  // Returns: {id: 123, original_name: "document.pdf", ...}

2. Create a Case

Use the cases endpoint to create a new case. Reference a case_config slug to define which checks to run automatically.

curl -X POST https://app.sphinxhq.com/api/cases/ \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "customer": {
    "external_id": "cust-jane-doe-1990",
    "full_name": "Jane Doe",
    "customer_type": "INDIVIDUAL",
    "input_details": {
      "dob": "1990-05-15",
      "nationality": "US"
    }
  },
  "case_config": "standard-kyc",
  "document_ids": [123],
  "webhook_url": "https://example.com/webhook/case-complete"
}'

import requests

payload = {
    "customer": {
        "external_id": "cust-jane-doe-1990",
        "full_name": "Jane Doe",
        "customer_type": "INDIVIDUAL",
        "input_details": {"dob": "1990-05-15", "nationality": "US"},
    },
    "case_config": "standard-kyc",
    "document_ids": [123],
    "webhook_url": "https://example.com/webhook/case-complete",
}

r = requests.post(
    "https://app.sphinxhq.com/api/cases/",
    json=payload,
    headers={"Authorization": "Bearer <YOUR_TOKEN>"},
)
print(r.json())

import axios from 'axios';

const payload = {
  customer: {
    external_id: 'cust-jane-doe-1990',
    full_name: 'Jane Doe',
    customer_type: 'INDIVIDUAL',
    input_details: { dob: '1990-05-15', nationality: 'US' },
  },
  case_config: 'standard-kyc',
  document_ids: [123],
  webhook_url: 'https://example.com/webhook/case-complete',
};

axios
  .post('https://app.sphinxhq.com/api/cases/', payload, {
    headers: { Authorization: 'Bearer <YOUR_TOKEN>', 'Content-Type': 'application/json' },
  })
  .then(res => console.log(res.data));

3. Receive Webhook Notification

When a case’s status is updated (e.g., completed), Sphinx will send a POST request to the webhook_url you provided. The request body will contain the full case object, which is the same as the response from the GET /api/cases/{id}/ endpoint. Below is an example of the payload you can expect to receive:

{
  "id": 6,
  "customer": {
    "id": 11,
    "external_id": "cust-james-torres-1997",
    "full_name": "James Torres",
    "customer_type": "INDIVIDUAL"
  },
  "webhook_url": "https://example.com/webhook/case-complete",
  "note": "The alert was validated due to a 2014 indictment... However, the customer was determined to be different...",
  "risk_score": 0.153,
  "outcome": "ACCEPTED",
  "is_complete": true,
  "failed": false,
  "rfi": null,
  "created_at": "2024-08-01T10:00:00Z",
  "updated_at": "2024-08-01T10:05:00Z",
  "delete_after": -1,
  "checks": [
    {
      "id": 93929,
      "input_details": { "...": "..." },
      "check_type": "ADVERSE_MEDIA",
      "risk_score": 0.85,
      "title": "Adverse Media Hit: 'Operation Horseback'",
      "note": "False positive: Age mismatch - subject was 42 in 2014, customer born 1997 (would be 17).",
      "reasoning": ["The alert subject was 42 years old in 2014, while the customer's date of birth is Mar 26, 1997..."],
      "outcome": "ACCEPTED",
      "status": "DECIDED",
      "created_at": "2024-08-01T10:01:00Z",
      "updated_at": "2024-08-01T10:02:00Z",
      "delete_after": -1
    },
    {
      "id": 93930,
      "input_details": {},
      "check_type": "SANCTION",
      ...
    },
    {
      "id": 93931,
      "input_details": {},
      "check_type": "PEP",
      ...
    }
  ]
}

Start

Models

Cases

Checks

Customers

Documents

Events

oauth

Try it in Postman

Authentication

Easiest steps for running a case

1. Upload Documents (Optional)

2. Create a Case

3. Receive Webhook Notification

​Try it in Postman

​Authentication

​Easiest steps for running a case

​1. Upload Documents (Optional)

​2. Create a Case

​3. Receive Webhook Notification

Try it in Postman

Authentication

Easiest steps for running a case

1. Upload Documents (Optional)

2. Create a Case

3. Receive Webhook Notification