Skip to main content
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

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

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: See Error codes for the full status code reference.