Unlock contact emails

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:

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.

1. Collect personnel IDs

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

{
  "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

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.

{
  "status": "accepted",
  "task_id": "321",
  "job_id": "321"
}

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

3. Poll the task

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 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.

Search contacts

Find people by name, company, event, or LinkedIn context.