Getting Started

The Bynn API is a REST API for identity verification and fraud detection. It takes JSON, returns JSON, and uses standard HTTP status codes. This page takes you from an API key to a working request.

What the API covers

The complete OpenAPI 3.0 definition is at https://api.bynn.com/openapi.json.

Base URL

All requests go over HTTPS to:

https://api.bynn.com/v1

Get your API keys

Sign in at dashboard.bynn.com and open Integration, then the API Keys tab. There are two pairs of keys:

• Production keys work on live data and are billed.
• Sandbox keys are for building and testing. They are not billed, and endpoints such as AML search return sample data.

Each pair has a private key and a public key:

Authenticate

Send your key in the Authorization header as a bearer token:

Authorization: Bearer private_YOUR_KEY

HTTP Basic authentication also works: use the key as the username and leave the password empty (curl -u "private_YOUR_KEY:"). Each endpoint in this reference states whether it takes the private or the public key.

Make your first call

This request checks that your private key works and returns the matching public key. It has no side effects and costs nothing.

curl https://api.bynn.com/v1/api_keys/public \
  -H "Authorization: Bearer private_sandbox_YOUR_KEY"

{
  "public_key": "public_sandbox_...",
  "is_test": true
}

is_test is true for a sandbox key and false for a production key.

Next, run a real check. With a sandbox key this AML search is free and returns a sample match, so you can build against the response shape:

curl https://api.bynn.com/v1/aml/search \
  -H "Authorization: Bearer private_sandbox_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Example", "type": "person"}'

{
  "query": "Jane Example",
  "type": "person",
  "total": 1,
  "results": [
    {
      "id": "sample-aml-0001",
      "name": "Jane Example",
      "schema": "Person",
      "match": true,
      "score": 0.95,
      "topics": ["sanction"],
      "birth_date": ["1970-01-01"],
      "birth_place": null,
      "death_date": null,
      "country": ["ru"]
    }
  ]
}

With a production key the same request screens the live data and is billed.

Responses and errors

A successful request returns the resource as a JSON object: 200 for reads, 201 for anything that creates something.

A failed request returns a 4xx or 5xx status and an error object with a machine-readable type and a readable message:

{
  "error": {
    "type": "authentication_error",
    "message": "You did not provide a valid PRIVATE API key or the API key has expired."
  }
}

Webhooks

Verification results arrive as HTTPS POST requests to an endpoint you configure in Webhook settings. Every delivery is signed with RS256, so check the signature before you trust it, and answer with a 2xx within 10 seconds. Sandbox deliveries carry the X-Test-Mode header.

• Bynn webhooks: setup and delivery
• Webhook security: signature verification and the public key
• Webhook events reference: every event and its payload

SDKs, CLI and MCP

• Web SDK (bynn.js): run the verification flow in the browser.
• Mobile SDK: iOS, Android, React Native and Flutter.
• Bynn CLI: call the API from your terminal, for example to submit local files. Install with brew install bynn-intelligence/bynn/bynn.
• Bynn MCP: connect Claude, ChatGPT, Cursor, VS Code and other MCP clients to Bynn at https://mcp.bynn.com.

Set up with a coding agent

If you build with a coding agent such as Claude Code, Cursor or GitHub Copilot in VS Code, paste this line into it:

Set up Bynn, ZOREAL, DecisionNode, Agemin and Detector24 for me: fetch https://bynn.com/agent-setup.md and follow it.

The agent installs the Bynn skills and the Bynn MCP server and tells you which steps are yours, such as signing in. It never needs you to paste a key into the chat.