Which requests use credits
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:
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
SendresearchTypes 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.
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 returnsduplicate 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-Creditsheader. - 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 thecode field tells you which applies:
See Error codes for the full status code reference.
Related
- Rate limits — per-endpoint limits and 429 handling
- Error codes — HTTP 400, 401, 403, 422, 429, and more
- Troubleshooting — failed research and auth errors
- Choose an API — when to search, research, or read records you already have