Quickstart guide

You’ll need an API key. Create one under Settings → API keys in the dashboard, then keep this page open. For this page, tick contacts:read, contacts:write and events:read. (You need a verified email and the workspace admin role to create a key. The dashboard shows a verification banner if your email isn’t verified yet. See Authentication for details.)

1. Verify your key

curl https://api.pathbound.ai/v1/auth/status \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch('https://api.pathbound.ai/v1/auth/status', {
  headers: { Authorization: `Bearer ${process.env.PATHBOUND_API_KEY}` },
});
console.log(await res.json());

import os, requests

res = requests.get(
    'https://api.pathbound.ai/v1/auth/status',
    headers={'Authorization': f"Bearer {os.environ['PATHBOUND_API_KEY']}"},
)
print(res.json())

You should see your user_id, email, and tenant_id, and the key’s scopes.

2. Create a contact

curl -X POST https://api.pathbound.ai/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "properties": {
      "firstname": "Ada",
      "lastname": "Lovelace",
      "company": "Analytical Engines",
      "lifecyclestage": "lead"
    }
  }'

const res = await fetch('https://api.pathbound.ai/v1/contacts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PATHBOUND_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: '[email protected]',
    properties: {
      firstname: 'Ada',
      lastname: 'Lovelace',
      company: 'Analytical Engines',
      lifecyclestage: 'lead',
    },
  }),
});
const { contact } = await res.json();
console.log(contact.contact_id);

res = requests.post(
    'https://api.pathbound.ai/v1/contacts',
    headers={
        'Authorization': f"Bearer {os.environ['PATHBOUND_API_KEY']}",
        'Content-Type': 'application/json',
    },
    json={
        'email': '[email protected]',
        'properties': {
            'firstname': 'Ada',
            'lastname': 'Lovelace',
            'company': 'Analytical Engines',
            'lifecyclestage': 'lead',
        },
    },
)
print(res.json()['contact']['contact_id'])

Save the returned contact.contact_id. You need it to read the contact, attach notes and tags, or send it an email. (contact._id is also returned as a transitional alias for backward compatibility, but prefer contact_id in new code.)

Running this twice returns 409 Conflict the second time, with the existing contact’s id as contact_id.

Required scope: contacts:write.

3. List recent events

If you’ve installed the events snippet on your site, you’ll already have events flowing. Otherwise this returns an empty array.

curl "https://api.pathbound.ai/v1/events?limit=5&sort_dir=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

const url = new URL('https://api.pathbound.ai/v1/events');
url.searchParams.set('limit', '5');
url.searchParams.set('sort_dir', 'desc');

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.PATHBOUND_API_KEY}` },
});
const { events } = await res.json();
console.log(events);

res = requests.get(
    'https://api.pathbound.ai/v1/events',
    headers={'Authorization': f"Bearer {os.environ['PATHBOUND_API_KEY']}"},
    params={'limit': 5, 'sort_dir': 'desc'},
)
for e in res.json()['events']:
    print(e['event'], e.get('url'))

Required scope: events:read.

4. Count instead of paging

Most questions about your data are “how many”. Ask the server to count, and nothing is paged or metered:

curl "https://api.pathbound.ai/v1/contacts?lifecycle_stage=lead&count_only=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

The answer is one number:

{ "status": "success", "count": 1 }

Required scope: contacts:read.

What’s next

Read the REST API overview: everything the API covers, and the conventions every endpoint shares (filters, errors, idempotency, rate limits, what counts against your plan).
Group and count on the server with POST /v1/aggregate, and read many records at once with POST /v1/batch/details.
Have changes pushed to you as they happen with Streaming.
Drop in the events snippet to start capturing visitor behavior.
Connect Pathbound to Claude.ai via the MCP server.