> ## Documentation Index
> Fetch the complete documentation index at: https://testdocs.clodura.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Clodura REST API — Overview, Auth, and Quick Start

> Explore the Clodura REST API: search contacts, reveal emails and phones, enrich companies, and verify emails — all over a single HTTPS interface.

The Clodura REST API gives you programmatic access to one of the most comprehensive B2B data platforms available. With a single authenticated HTTP call you can search a database of 600 million+ contacts, reveal verified email addresses and phone numbers, pull deep firmographic data on any organisation, monitor job postings and funding news, and verify email deliverability — all in real time from your own application, CRM, or workflow automation.

## Base URL

Every API request targets the following base URL:

```text theme={null}
https://api.clodura.ai
```

All endpoints are versioned under `/api/v1/`. For example, the People Search endpoint lives at:

```text theme={null}
https://api.clodura.ai/api/v1/search/people
```

## REST Conventions

The Clodura API is built around REST principles so it behaves predictably alongside any HTTP client or library.

* **Resource-oriented URLs** — endpoints map to logical resources such as `/people`, `/organizations`, and `/credits`.
* **JSON everywhere** — all request bodies and all responses use `application/json`. Set `Content-Type: application/json` on every request that carries a body.
* **Standard HTTP verbs** — `GET` to read, `POST` to search or submit data.
* **Standard HTTP status codes** — `2xx` for success, `4xx` for client errors, `5xx` for server-side problems.

## Authentication

You authenticate every request by passing your API key in the `X-API-KEY` request header. There are no cookies or OAuth flows to manage. See the [Authentication guide](/api/authentication) for full details on obtaining your key, securing it, and handling auth errors.

```bash theme={null}
curl -X POST https://api.clodura.ai/api/v1/search/people \
  -H 'X-API-KEY: your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Jane Doe", "organisationName": "Acme Corp"}'
```

## Quick Start

The example below searches for a person by name and company, printing the JSON response directly to your terminal. Replace `your_api_key_here` with your real key before running it.

```bash theme={null}
curl -X POST https://api.clodura.ai/api/v1/search/people \
  -H 'X-API-KEY: your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "firstName": "John",
    "lastName": "Smith",
    "organizationName": "Salesforce",
    "personTitle": ["VP Sales"],
    "page": 1,
    "perPage": 25
  }'
```

A successful call returns `200 OK` with a JSON body containing matched contact records. Each non-empty record returned deducts one credit from your account balance.

## Available API Groups

<CardGroup cols={2}>
  <Card title="People API" icon="users" href="/api/people/search-people">
    Search contacts, reveal email addresses and phone numbers, enrich person profiles, verify emails, and track results via webhook.
  </Card>

  <Card title="Company API" icon="building" href="/api/company/search-organizations">
    Discover organisations, enrich firmographic data, pull technographics and funding history, monitor job postings, and track corporate news.
  </Card>
</CardGroup>

## Credits

Most API calls that return data consume credits from your account balance. The exact cost depends on the data type and the endpoint:

| Action                                 | Credit Cost   |
| -------------------------------------- | ------------- |
| Search People (per non-empty record)   | 1 credit      |
| Reveal email address                   | 1–6 credits   |
| Reveal phone number                    | 10–20 credits |
| Company enrichment — base              | 1 credit      |
| Company enrichment — + technographics  | +1 credit     |
| Company enrichment — + acquisitions    | +1 credit     |
| Company enrichment — + funding details | +1 credit     |
| Job Posts per request                  | 2 credits     |
| News per request                       | 2 credits     |
| Email verification (standard)          | 0.04 credits  |
| Email verification (deep)              | 0.1 credits   |

Credits are deducted **only when data is successfully returned**. If a provider returns nothing for a given contact or company, no credits are consumed. See the [Credits guide](/docs/credits) for full pricing, rollover rules, and how to monitor your balance via the `/api/v1/credits` endpoint.

<Note>
  If you are on a **Prospect** or **Prospect Pro** plan, credit consumption is tracked differently — your plan includes a fixed number of requests (1,000 or 2,000 respectively) rather than a common credit pool. Check the [Credits guide](/docs/credits) for plan-specific details.
</Note>

## Rate Limits

Rate limits are enforced per API key and vary by subscription plan. Exceeding a limit returns `429 Too Many Requests` (or `409 Conflict` for daily limits). Implement exponential backoff when you encounter these responses.

| Plan                   | Per Second | Per Minute | Per Day |
| ---------------------- | ---------- | ---------- | ------- |
| MAX                    | 10         | 100        | 2,000   |
| PayG                   | 10         | 100        | 2,000   |
| Professional           | 10         | 100        | 2,000   |
| Enterprise             | 10         | 100        | 2,000   |
| Prospect Pro           | 10         | 100        | 2,000   |
| Prospect               | 10         | 100        | 2,000   |
| Starter                | 1          | 10         | 600     |
| Lifetime               | 1          | 10         | 300     |
| Basic                  | 1          | 10         | 600     |
| Default / Free Forever | 1          | 10         | 300     |

<Tip>
  Higher-tier plans not only unlock more daily requests, they also reduce your cost per credit — helping you lower your cost per lead as your usage scales.
</Tip>

## HTTP Error Codes

The table below covers the standard codes you will encounter across all Clodura API endpoints.

| Status Code                | Meaning                                                                      |
| -------------------------- | ---------------------------------------------------------------------------- |
| `200 OK`                   | Request succeeded. Response body contains the requested data.                |
| `202 Accepted`             | Request accepted for asynchronous processing (e.g. deep email verification). |
| `400 Bad Request`          | Malformed request syntax or missing required parameters.                     |
| `401 Unauthorized`         | API key is missing or invalid.                                               |
| `402 Payment Required`     | Your credit balance is exhausted.                                            |
| `403 Forbidden`            | Your API key is valid but your plan does not permit this action.             |
| `404 Not Found`            | The requested resource does not exist.                                       |
| `409 Conflict`             | Daily rate limit exceeded.                                                   |
| `422 Unprocessable Entity` | Parameter validation failed — check the `errors` array in the response.      |
| `429 Too Many Requests`    | Per-second or per-minute rate limit exceeded. Retry after a short backoff.   |
| `5xx Server Error`         | An unexpected error on Clodura's servers. Retry with exponential backoff.    |

## API Usage Policy and Fair Use

By calling the Clodura API you agree to the following restrictions. Violations may result in immediate API key revocation.

<Warning>
  **Real-time use only.** Data returned by the API is licensed for immediate outreach and integration purposes. You may **not** store API responses in a permanent database or use them to build a standalone contact or company repository.
</Warning>

* **24-hour cache allowed.** You may cache API responses for up to 24 hours to reduce latency and avoid redundant calls — but not longer.
* **No reselling.** You cannot resell enriched data, build a competing lead-generation tool, or distribute API results to third parties.
* **Scraping is monitored.** Clodura actively monitors for high-frequency harvesting patterns. Accounts exhibiting automated bulk-extraction behaviour will have their API key revoked without prior notice.
* **HTTPS only.** All API requests must use HTTPS. Requests over plain HTTP will fail.