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

# Unlock contact emails

> Unlock contact email addresses through Lensmor async tasks, poll unlock status, handle credit outcomes, and sync verified results into your CRM.

Use this guide when your integration has identified relevant personnel records and needs email addresses for outreach, CRM enrichment, or sales workflows.

Email unlocks run asynchronously. The create request validates the batch and starts a task. Your integration then polls the task endpoint until the result is ready.

## When to use this workflow

Use contact email unlock after you already know which people are worth enriching. Typical inputs come from:

* [List event personnel](/api-reference/personnel/list)
* [Get personnel profile](/api-reference/personnel/profile)
* [Search contacts](/api-reference/contacts/search)

<Warning>
  Do not call email unlock as a blind bulk export. Batch only the people your user has selected or your scoring workflow has marked as relevant.
</Warning>

## 1. Collect personnel IDs

Most personnel responses include `id`, name, title, company context, and `contactUnlockStatus`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "789",
  "fullName": "Jane Doe",
  "title": "VP of Partnerships",
  "companyName": "Example Retail Co",
  "email": null,
  "contactUnlockStatus": "locked"
}
```

Only send records that are still locked. Already unlocked contacts are not charged again, but filtering them out keeps your task easier to audit.

## 2. Start the unlock task

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://platform.lensmor.com/external/contacts/unlock" \
  -H "Authorization: Bearer $LENSMOR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-call-source: api" \
  -d '{
    "event_id": "139574",
    "personnel_ids": ["789", "790"]
  }'
```

The API accepts up to `100` personnel IDs per request.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "accepted",
  "task_id": "321",
  "job_id": "321"
}
```

Store `task_id`. It is the stable identifier you need for polling.

## 3. Poll the task

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://platform.lensmor.com/external/contacts/unlock-tasks/321" \
  -H "Authorization: Bearer $LENSMOR_API_KEY"
```

Poll with backoff rather than a tight loop. A practical pattern is to wait a few seconds between attempts, then increase the interval for longer jobs.

## 4. Handle task states

Your integration should account for these outcomes:

* `accepted` or in-progress state: continue polling.
* completed state: inspect item-level results. Count a contact as delivered only when its item status is unlocked and an email is present.
* failed state: show the task error and decide whether the user should retry.
* `404 Not Found`: the task ID is invalid or not visible to the API key owner.

See [Get contact unlock task](/api-reference/contacts/unlock-task) for the exact response shape.

Completed tasks can contain mixed item outcomes. Show failed, ineligible, or unresolved contacts separately instead of folding them into the unlocked count.

## Credit behavior

Contact email unlock currently costs `15` credits per chargeable contact.

* Already unlocked contacts are not charged again.
* Batches larger than `100` personnel IDs are rejected.
* Insufficient balance returns `402 Payment Required`.
* The response and your commercial agreement are the source of truth for billing.

## Recommended integration behavior

* Show the estimated number of locked contacts before creating the task.
* Check `GET /external/credits/balance` before large batches.
* Store the task ID and make polling resumable.
* Back off on `429 Too Many Requests`.
* Re-fetch `GET /external/credits/balance` after terminal task states when you need final credit reconciliation.
* Re-fetch personnel or contact records after completion if your UI needs the latest unlock status or email visibility.

## Related endpoints

<CardGroup cols={2}>
  <Card title="Search contacts" icon="search" href="/api-reference/contacts/search">
    Find people by name, company, event, or LinkedIn context.
  </Card>

  <Card title="Unlock contact emails" icon="mail-check" href="/api-reference/contacts/unlock">
    Start an asynchronous email unlock task.
  </Card>

  <Card title="Get unlock task" icon="list-checks" href="/api-reference/contacts/unlock-task">
    Poll task status and retrieve task results.
  </Card>

  <Card title="Credits and access" icon="coins" href="/concepts/credits-and-access">
    Understand credit costs, balances, and access semantics.
  </Card>
</CardGroup>