Skip to content

unlock-task.mdx

Latest commit

 

History

History
108 lines (82 loc) · 2.9 KB

unlock-task.mdx

File metadata and controls

108 lines (82 loc) · 2.9 KB
Raw
title Get contact unlock task
description 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": "jane@acme.example"
    },
    {
      "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.