Quickstart

Get from zero to a working request in three steps.

1. Issue an API key

API keys are issued from the brokerage settings UI by a brokerage admin.

1. Sign in at app.evenhandhq.com with an admin account.
2. Open Settings → API keys.
3. Create a key. Choose the scopes the key should carry and an optional per-key rate-limit ceiling.
4. Copy the raw token from the dialog. It is shown once. After you close the dialog only its SHA-256 digest is retained server-side, so a lost token cannot be recovered — only revoked and reissued.

Keys come in two environments:

Prefix	Environment	Use for
evhk_live_	Production	Real brokerage data.
evhk_test_	Test	Integration work and sandboxing.

The remainder of the token is 32 hex characters.

2. Make a request

Send the token as a bearer credential on every request.

curl https://app.evenhandhq.com/api/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY"

Replace YOUR_API_KEY with the value you copied in step 1. Do not commit it to source control. Read it from an environment variable or a secret store.

3. Read the response

A successful response is JSON with a data array and a pagination object:

{
  "data": [
    {
      "id": "8e0f...e4a1",
      "type": "person",
      "displayName": "Casey Rivera",
      "email": "casey@example.com",
      "createdAt": "2026-04-12T15:42:09Z",
      "updatedAt": "2026-04-12T15:42:09Z"
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null
  }
}

To page through more results, pass the nextCursor value back as a cursor query parameter on the next request.

Next

• Read Authentication for the scope catalog and revocation behavior.
• Read Rate limits & errors for the canonical error envelope.
• Browse the full endpoint catalog in the API reference.