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
    The Case creation endpoint combines Customer and Check (typically a single alert) details
  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, including serialized customer, serialized checks, and document IDs: 
curl -X POST https://app.sphinxhq.com/api/cases/ \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "customer": {
    "external_id": "cust-james-torres-1997",
    "full_name": "James Torres",
    "customer_type": "INDIVIDUAL",
    "input_details": {
      "dob": "1997-03-26",
      "nationality": "US"
    }
  },
  "notes": "Initial screening for a high-risk customer. See adverse media check for details.",
  "checks": [
    {
      "check_type": "ADVERSE_MEDIA",
      "input_details": {
        "media_hits": [
          {
            "url": "http://interactives.wivb.com/photomojo/gallery/13470/1/",
            "source": "interactives.wivb.com",
            "details": "Source relates to ''Operation Horseback'' and James Torres'' drug trafficking involvement.",
            "snippet": "The U.S. New York State Attorney General announced on July 30, 2014..."
          }
        ]
      }
    },
    { "check_type": "SANCTION" },
    { "check_type": "PEP" }
  ],
  "documents": [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",
  "notes": "The alert was validated due to a 2014 indictment... However, the customer was determined to be different...",
  "risk_score": 0.153,
  "outcome": "ACCEPTED",
  "rfi": "Hi John\n\nWe need additional documentation to complete your verification:\n\n1. Proof of address (utility bill or bank statement from the last 3 months)...",
  "created_at": "2024-08-01T10:00:00Z",
  "updated_at": "2024-08-01T10:05:00Z",
  "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",
      "created_at": "2024-08-01T10:01:00Z",
      "updated_at": "2024-08-01T10:02:00Z"
    },
    {
      "id": 93930,
      "input_details": {},
      "check_type": "SANCTION",
      ...
    },
      {
      "id": 93931,
      "input_details": {},
      "check_type": "PEP",
      ...
    }
  ]
}