Restricted APIs
Some APIs return sensitive personal data. Using them needs an approved account that accepted the permissible-purpose terms. How access works, what is not allowed, and how restricted calls are stored.
Last updated
A few APIs return personal data that can hurt people when it is misused: contact details of individuals, people search results, some public records. These APIs are marked restricted. You can read their documentation and schemas like any other, but calling them requires an account that has accepted the permissible-purpose terms and been approved by our team.
How to tell
- Restricted APIs carry a restricted badge in the API reference and on their API pages.
GET /v1/apisandGET /v1/apis/{sku}return"restricted": true.- Calling one without access answers
403 restricted_api, before anything runs. It costs nothing, and every other API keeps working.
{
"code": "restricted_api",
"error": "<sku> returns sensitive personal data: accept the permissible-purpose terms and get your account approved in the dashboard first.",
"requestId": "req_01JBXX6Z8B0D2F4H6K8M0P2R4T"
}Getting access
- Accept the terms. A signed-in person in the workspace accepts the permissible-purpose terms in the dashboard and describes the intended use. (The dashboard calls
POST /v1/workspace/restricted-termswith an optionalpurpose; this endpoint accepts browser sessions only, never API keys.) - Approval. Our team reviews the account and the stated purpose. We may ask questions about your use case before approving.
- Done. Once approved, every key of the workspace can call restricted APIs, subject to its access level and spend limit.
GET /v1/workspace(afullorviewkey, or the dashboard) shows"restrictedAccess": true.
Access belongs to the account. Agent trial keys from POST /agent/signup belong to an account with no person behind it, so they can never call restricted APIs; after a human claims such a key, it follows the access of the human's account.
Permissible purpose
You may use restricted data only for a lawful purpose you are able to explain and document, such as preventing fraud, verifying an identity with the person's knowledge, or business-to-business research where the law allows it, and only in line with the Acceptable Use Policy and the Terms of Service. Among other things, they do not allow:
- decisions about a person's eligibility for credit, insurance, employment, housing or tenancy, education, licences or government benefits,
- any purpose that legally requires a permissible purpose under the Gramm-Leach-Bliley Act or the Driver's Privacy Protection Act, and locating or skip-tracing private individuals,
- stalking, harassment, doxxing, or monitoring a person without a lawful basis,
- discrimination, or inferring sensitive characteristics such as health, religion, sexual orientation or political views,
- contacting people in breach of telemarketing, anti-spam or privacy laws.
You are responsible for having a lawful basis for the personal data you request and for what you do with it, including notices you owe to the people concerned. We suspend access when we see signs of prohibited use.
How restricted calls are handled
- Inputs are not stored. For restricted APIs we keep only a one-way fingerprint of the input (used for idempotency), never the input itself. For other APIs the input is kept with your request history for support.
- Results expire. Like every call, the result is stored so you can re-read it for as long as your plan keeps results (24 hours on Pay as you go, 7 to 90 days on a plan: Durable requests), then deleted. The request's metadata (SKU, status, cost, timing) stays in your history.
- Deletion requests. If you need a request history deleted, or a person asks you to delete data you obtained through us, write to [email protected].
The Security and data handling page describes the rest of our controls.