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

# Credits

> Which Seamless API requests use credits, contact research costs, refunds, and how to check your credit balance.

Credits apply at the **organization** level. All API keys and users under your Seamless org share the same balance.

Search and research spend the same credit balance. Reading records already in your org, polling for results, and OAuth do not.

## Which requests use credits

| Request type | Uses credits? |
| - | - |
| **Search** — `POST /search/contacts`, `POST /search/companies` | **Yes** — 1 credit for every 50 results returned, rounded up. Returning 1–50 results costs 1 credit, and each further 50 results, or part of them, costs 1 more. A response with no rows costs nothing. If the balance cannot cover the requested `limit`, the page is shortened to what the balance can pay for. The request returns 422 when fewer than 1 credit remains. |
| **Company research** — `POST /companies/research` | **Yes** — 1 credit per record submitted for enrichment |
| **Contact research** — `POST /contacts/research` | **Yes** — each contact is charged for the contact data it researches. See [Contact research costs](#contact-research-costs). |
| **Org data** — `GET /companies`, `GET /contacts` | **No** — reads records already in your org |
| **Poll** — `GET /companies/research/poll`, `GET /contacts/research/poll` | **No** |
| **OAuth** — `POST /oauth/accessToken`, `GET /oauth/me` | **No** |

Search does not start a research job. Researching a `searchResultId` is a separate charge on top of the search that found it.

## Contact research costs

Each researched contact is charged for the contact data it researches:

| Contact data | Default credits per contact |
| - | - |
| Email only | 1 |
| Phone only | 5 |
| Full Contact (email and phone) | 6 |

Your organization may set its own prices. Without `researchTypes`, a research covers what your Contact Data settings enable. Accounts that aren't on component-based pricing pay a flat price per contact (1 credit unless your organization has custom pricing), and those credits are refunded all or nothing.

### Choosing the contact data per request

Send `researchTypes` on `POST /contacts/research` to research only `["email"]`, only `["phone"]`, or both. It's rejected with a 403 when:

* `fullContactRequired`: your organization's Contact Data is locked to Full Contact and you sent one component.
* `component-disabled-for-org`: your organization disabled a component you sent.
* `variable-credits-disabled`: your account isn't on component-based pricing and you sent one component.

A 400 or 403 is returned before any credit check, and nothing is charged.

### Refunds and repeat research

With component-based pricing, email and phone are refunded separately when that data isn't found: email when no valid business email is found, phone when no contact phone (mobile, main line, or other contact number) is found. A contact is charged once for phone however many numbers are found, and company phones are free. Organizations on a mobile-only agreement are only charged for mobile phones, and get the phone refunded when no mobile phone is found. A component you didn't request is never charged or refunded.

Accounts that find full contacts only (email-only and phone-only finds aren't available) get the whole contact refunded when no valid email is found; phones aren't refunded on their own.

Researching a contact you researched in the last few minutes returns `duplicate` and charges nothing when that contact already has the contact data you asked for. If it doesn't, for example `researchTypes: ["phone"]` after an email-only research, the phone is researched onto the same contact and only the phone is charged; the contact's `researchedTypes` becomes `["email", "phone"]`. `skipDeduplicationCheck: true` skips this check and researches the contact again as a new contact, charged for every component requested.

### Insufficient contact research credits

`POST /contacts/research` returns a 422 `insufficientCredits` when your balance can't cover every contact in the request. `data.additionalCreditsNeeded` is the shortfall, and can be fractional under custom pricing.

On a `202` from `POST /contacts/research`, `X-PublicAPI-Credits` is your balance minus the cost of every accepted contact. It's a projection: research runs after the response, so duplicates aren't charged and refunds land as each research completes.

The cost behind the 422 and this header is an upper bound. A contact that's already in your My Contacts, or a follow-up that identifies the same person differently (for example by name or email after a `searchResultId`), is only recognized once research runs, so it can end up costing less or nothing.

## Check your credit balance

* Every authenticated response includes the remaining balance in the **`X-PublicAPI-Credits`** header.
* v2 (beta) has a dedicated endpoint, `GET /client/v2/credits`. v1 has none.
* You can also check **Settings → Billing** in the Seamless app.

## License vs credits (HTTP 422)

Both problems return **HTTP 422**, but the `code` field tells you which applies:

| `code` | Meaning | What to do |
| - | - | - |
| **`insufficientCredits`** | Not enough credits for this search or research request | Check billing, lower the search `limit`, or reduce the research batch |
| **`missingApiAccess`** | No active Public API license | Contact your administrator or support |

See [Error codes](https://docs.seamless.ai/api-catalog/error-codes.md) for the full status code reference.

| Symptom | Likely cause |
| - | - |
| Poll status `error` | Insufficient credits or license restriction |
| HTTP 422 on search or research | Insufficient credits or missing license — see [Error codes](https://docs.seamless.ai/api-catalog/error-codes.md) |
| Low `X-PublicAPI-Credits` | Org is near its credit limit |

## Related

* [Rate limits](https://docs.seamless.ai/core-concepts/rate-limits.md) — per-endpoint limits and 429 handling
* [Error codes](https://docs.seamless.ai/api-catalog/error-codes.md) — HTTP 400, 401, 403, 422, 429, and more
* [Troubleshooting](https://docs.seamless.ai/troubleshooting/authentication-and-request-failures.md) — failed research and auth errors
* [Choose an API](https://docs.seamless.ai/api-catalog/choose-an-api.md) — when to search, research, or read records you already have


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.