Get contact unlock task

Poll a Lensmor contact unlock task, inspect task status, retrieve completed email results, and handle failed or pending unlock workflows.

Check the status of a contact email unlock job.

Use this endpoint after POST /external/contacts/unlock returns task_id.

When to use this endpoint

Use GET /external/contacts/unlock-tasks/:taskId to make email unlock workflows resumable. The task ID can be stored in your database, background worker, or frontend state and polled until the job completes or fails.

Do not assume the unlock result is ready immediately after creating the task.

Endpoint

GET /external/contacts/unlock-tasks/:taskId

Authentication

See Authentication

Success status code

200 OK

Path parameters

Name	Required	Type	Notes
taskId	Yes	string	The task_id returned by contact unlock.

Request example

curl "https://platform.lensmor.com/external/contacts/unlock-tasks/321" \
  -H "Authorization: Bearer $LENSMOR_API_KEY"

Response example

{
  "taskId": "321",
  "taskStatus": "processing",
  "items": [
    {
      "personnelId": "789",
      "status": "unlocked",
      "email": "[e-mail]"
    },
    {
      "personnelId": "790",
      "status": "processing"
    }
  ]
}

Response fields

Field	Description
taskId	Contact unlock task identifier.
taskStatus	Overall task state.
items	Per-person unlock results.
items[].personnelId	Personnel identifier submitted in the unlock request.
items[].status	Item-level unlock state.
items[].email	Email address when the item is unlocked successfully.
items[].errorCode	Error code when an individual item fails, if provided.

Status values

Task status:

• pending
• processing
• completed
• failed

Item status:

• pending
• processing
• unlocked
• failed

Result interpretation

Treat each items[] entry independently:

• Count a contact as delivered only when item status is unlocked and email is present.
• Surface failed items separately with errorCode when provided.
• A task can reach a terminal state while individual items have different outcomes.
• Refresh credit balance and contact/personnel records after terminal states when your UI needs billing or access-state reconciliation.

Polling guidance

Use a backoff schedule instead of polling aggressively:

3 seconds -> 5 seconds -> 10 seconds -> 20 seconds

Stop polling when taskStatus is completed or failed. If some items remain failed while the task is completed, handle those item statuses individually.

Error responses

• 401 Unauthorized
• 404 Not Found
• 429 Too Many Requests

Notes

• email is present only when the individual item has been unlocked successfully.
• Failed items can include errorCode.