Getting Started

This guide walks you through making your first API call to the ContactLevel API.

Prerequisites

A ContactLevel account with an active organization
An API key (see Authentication)

Base URL

All API requests use the following base URL:

Code
https://a.contactlevel.com

Step 1: Verify Your API Key

Start by checking your organization ID to confirm your key is working:

Code
curl -X GET https://a.contactlevel.com/api/organizations/get-id \
  -H "X-Api-Key: your_api_key_here"

A successful response looks like:

Code
{
  "organization_id": "org_01HX8G3KQZM4NC5S7EVJF4R2WN"
}

Step 2: Search Your Contacts

Search for contacts in your organization using filters:

Code
curl -X POST https://a.contactlevel.com/api/contacts/search \
  -H "X-Api-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "page_size": 5
  }'

Response:

Code
{
  "contacts": [
    {
      "id": "con_01HX8G3KQZM4NC5S7EVJF4R2WN",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@acme.com",
      "job_title": "VP Marketing",
      "company_name": "Acme Corp",
      "linkedin_url": "https://linkedin.com/in/janedoe"
    }
  ],
  "total": 142,
  "page": 1,
  "page_size": 5
}

You can narrow results with filters like first_name, last_name, company_name, job_title, city, state_region, country, and more.

Step 3: Create an Audience

Audiences are named groups of contacts that you can sync to ad platforms:

Code
curl -X POST https://a.contactlevel.com/api/audiences/ \
  -H "X-Api-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Campaign",
    "description": "Target accounts from Q1 pipeline"
  }'

Response:

Code
{
  "audience": {
    "id": "aud_01HX8G3KQZM4NC5S7EVJF4R2WN",
    "name": "Q1 Campaign",
    "description": "Target accounts from Q1 pipeline",
    "status": "active",
    "tracking_value": "q1-campaign",
    "created_at": "2026-03-30T12:00:00Z"
  }
}

Step 4: Add a Contact to an Audience

Code
curl -X POST https://a.contactlevel.com/api/audiences/contacts/add \
  -H "X-Api-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "audience_id": "aud_01HX8G3KQZM4NC5S7EVJF4R2WN",
    "contact_id": "con_01HX8G3KQZM4NC5S7EVJF4R2WN"
  }'

Pagination

All search endpoints support pagination with two parameters:

Parameter	Default	Range	Description
`page`	1	1+	The page number (1-indexed).
`page_size`	25	1–100	Number of results per page.

Example — fetch page 3 with 10 results per page:

Code
{
  "page": 3,
  "page_size": 10
}

The response always includes total, page, and page_size so you can calculate total pages.

Error Handling

The API uses standard HTTP status codes. Error responses include a detail field:

Code
{
  "detail": "Invalid or missing API key"
}

Status	Meaning
400	Bad request — check your parameters.
401	Unauthorized — your API key is missing or invalid.
402	Insufficient credits — top up your balance.
404	Not found — the resource doesn't exist.
422	Validation error — the request body doesn't match the expected schema.

Available Resources

Resource	Endpoints	Description
Audiences	GET, POST, Search	Create and manage audience groups.
Contacts	GET, Search	Look up individual contacts or search by filters.
Companies	GET, Search	Look up companies or search by domain, industry, size.
Website Visits	GET, Search	View visits tracked by the ContactLevel pixel.
Organization	GET	Check your org ID and credit balance.

Next Steps

Follow Syncing your audiences to send an audience to a connected destination and check its progress.
Connect Claude or Codex with the MCP setup guide.
Browse the API Reference to see all endpoints with request/response examples.
Review the Authentication guide for security best practices.
Check your credit balance with the Get Credit Balance endpoint.

Last modified on November 4, 2026