Skip to main content

​
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

  1. Upload Documents (Optional)
    ✅ Usually required for KYB, KYC EDD and transaction monitoring
    ❌ Usually not required for AML (PEP, Sanctions, Adverse Media)
  2. Create a Case
    Provide customer details and a case_config slug — checks are created automatically.
  3. 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"
  }'

​
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"
}'

​
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",
      ...
    }
  ]
}