Required permissions: body.fields includes email: people:enrich_email; body.fields includes phone: people:enrich_phone. All scopes for the selected fields are required. Omitting body.fields uses ["email"] and requires people:enrich_email. Malformed values: no additional scopes; unknown fields add no scopes. Request validation still applies.

Give a person — their name, and their LinkedIn profile or where they work — and get their email back in the same response, and their phone as a lookup to poll. The person does not have to exist in your workspace, and this call does not create them: it is POST /v1/people/{id}/enrich with the person row taken out of the middle, for the case where you are still deciding whether someone is worth keeping.

Email is synchronous. Typically a few seconds, and the server gives up at 120 seconds by default with 503 contact_lookup_failed, so set your client timeout above that. Import the people you want afterwards with POST /v1/people (send the email you got back as the person's email).

Phone is asynchronous. Ask for it with fields: ["phone"] and the response is 202 with phone.status: "pending" and a phone.lookupId; collect it from GET /v1/contacts/lookups/{lookupId}. Phone lookups typically take one to two minutes, but can take up to four minutes. Email asked for in the same call is still answered inline, in the same response.

What it costs. One lookup per field when a search starts (a phone counts when it starts, so polling is free), counted against your plan's allowance for that field — email and phone have separate limits. A lookup here and a lookup on a person draw on the same allowance for the same field. Over the limit is 402 lookup_limit_reached before any search starts. The response carries quota: the allowance left per field after this call, the same numbers GET /v1/whoami reports.

Asking twice is free. The workspace's answer for one identity is remembered — a month for a found address, a week for not_found — and a repeat request reads it: source: "saved", no new lookup, and nothing counted against your allowance. So a retry after not_found costs nothing.

A found address is not a verified owner. status: "found" means a search returned the address and nothing suggests it belongs to someone else. status: "unconfirmed" means a search returned it but email.identityConfidence is conflict: the address is still in value, and a human should look before anyone sends to it. email.identityConfidence (match, conflict or unknown) says why. It compares the address against the fullName you sent, always, and against the company.website you sent, when you sent one. Include the known employer website even with a LinkedIn profile; without it, a matching name can produce match at the wrong employer. match does not prove mailbox ownership or current employment, and this field does not block sending.

not_found is an answer. The lookup finished without a value and returns 200. A 503 means the question was never answered — nothing charged, nothing stored.

Partial success is the contract. When you ask for both fields and one fails because of a plan limit or a lookup error, the call still answers. That field reads status: "failed" with error.code, error.retry and error.message, exactly what an error response would have carried. The other field keeps its answer and its lookupId. Nothing is charged for a field that failed. The call itself fails only when every field you asked for did.

What to send. Include the LinkedIn profile when known to improve the chance of finding contact details. Otherwise, send the company website. A name alone returns 400.