# 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](./authentication.md))

## Base URL

All API requests use the following base URL:

```
https://a.contactlevel.com
```

## Step 1: Verify Your API Key

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

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

A successful response looks like:

```json
{
  "organization_id": "org_01HX8G3KQZM4NC5S7EVJF4R2WN"
}
```

## Step 2: Search Your Contacts

Search for contacts in your organization using filters:

```bash
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:

```json
{
  "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:

```bash
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:

```json
{
  "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

```bash
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:

```json
{
  "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:

```json
{
  "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](/syncing-audiences) to send an audience to a connected destination and check its progress.

- Connect Claude or Codex with the [MCP setup guide](/mcp).

- Browse the [API Reference](/api) to see all endpoints with request/response examples.
- Review the [Authentication](./authentication.md) guide for security best practices.
- Check your credit balance with the [Get Credit Balance](/api#getCreditBalance) endpoint.