Identities API

Identities represent the senders behind outreach actions — the email accounts and LinkedIn profiles that send messages on behalf of a tenant. Every action requires an identity_id.

Read endpoints require identities:read; write and LinkedIn endpoints require identities:write.

Create an Identity

POST /v1/identities

Required scope: identities:write

Request Body

Field	Type	Required	Description
firstName	string	yes	First name.
lastName	string	yes	Last name.
role	string	yes	Role or job title.

Response — 201 Created

{
  "status": "success",
  "identity": { /* identity object */ }
}

---

List Identities

GET /v1/identities

Required scope: identities:read

Returns all identities for the authenticated user’s tenant. Credentials are never returned.

---

Get an Identity

GET /v1/identities/:identity_id

Required scope: identities:read

---

Update an Identity

PUT /v1/identities/:identity_id

Required scope: identities:write

Request Body

Field	Type	Required	Description
firstName	string	no	First name.
lastName	string	no	Last name.
jobTitle	string	no	Job title.

---

Delete an Identity

DELETE /v1/identities/:identity_id

Required scope: identities:write

---

LinkedIn Integration

Connecting LinkedIn is a multi-step asynchronous flow. You start a login, poll for status, and (if challenged) submit a 2FA code. Most calls complete within 30 seconds; verification can take longer.

1. Start the login

POST /v1/identities/:identity_id/linkedin/login

Required scope: identities:write

Field	Type	Required	Description
username	string	no	LinkedIn username / email.
password	string	no	LinkedIn password.
country	string	no	Country code for the login request (default: US).
max_verification_wait_time	number	no	Max seconds to wait for verification (default: 600).

If the identity already has a stored LinkedIn profile_id, you can omit username and password to re-authenticate using the existing session.

Response — 200 OK

{
  "status": "success",
  "message": "LinkedIn login initiated",
  "identity_id": "id_abc",
  "login_result": {
    "profile_id": "li_abc",
    "session_id": "sess_xyz",
    "status": "queued"
  }
}

2. Poll for status

GET /v1/identities/:identity_id/linkedin/status/:session_id

Required scope: identities:write

Poll every 2–3 seconds. Possible status values:

Status	Meaning
queued	Job accepted, not yet picked up.
running	Login in progress.
awaiting_2fa	LinkedIn challenged with a verification code.
awaiting_email	LinkedIn requires confirmation via email link.
completed	Logged in successfully.
failed	Login failed (see error field).

3. Submit a 2FA code (if challenged)

POST /v1/identities/:identity_id/linkedin/code/:session_id

Required scope: identities:write

Field	Type	Required	Description
code	string	yes	Two-factor auth code.

After submitting, return to step 2 (polling) until status: "completed".

Check current connection

GET /v1/identities/:identity_id/linkedin/check

Required scope: identities:write

Returns whether the identity currently has a valid LinkedIn session, without starting a new login.

{
  "status": "success",
  "connected": true,
  "profile_id": "li_abc",
  "checked_at": "2026-04-29T12:00:00.000Z"
}

Error handling

Status	Meaning
400	Invalid request (e.g. missing 2FA code, invalid country).
401	LinkedIn rejected the credentials.
408	Verification timed out (max_verification_wait_time exceeded).
423	LinkedIn account is locked. User must unlock via linkedin.com.