Claim Connected Account

Free a LinkedIn slug previously connected by another user.

The frontend calls this after receiving a 409 account_owned_by_another_user from /connect or /connect-cookie. That earlier 409 carries a signed claim_token AND deletes the requesting user’s freshly minted Unipile account upstream so no orphan accumulates if the user never follows through. Presenting the token here:

1. Verifies HMAC + expiry + requesting-user binding (fail-closed).
2. Enforces single-use jti via INSERT into consumed_claim_tokens; a replay returns 410 Gone.
3. Runs the DB function claim_connected_account which (inside one transaction) disconnects the previous owner’s row, pauses their campaigns, and queues a user_alert.
4. Best-effort: deletes the previous owner’s Unipile account upstream.

The function does NOT INSERT a new row for the requesting user. Response carries next_action="reconnect"; the frontend redirects the user back to /connect (or /connect-cookie) to register their own Unipile session, which now succeeds because the slug is no longer held by any connected row.

POST /api/v1/connected-accounts/claim

Claim Connected Account

cURL

curl --request POST \
  --url https://api.example.com/api/v1/connected-accounts/claim \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "claim_token": "<string>"
}
'

200

{
  "previous_owner_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "linkedin_slug": "<string>",
  "success": true,
  "next_action": "reconnect"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request body for POST /api/v1/connected-accounts/claim.

claim_token · string · required

Required string length: 10 - 4096

Response

200

application/json

Successful Response

Response from a successful ownership transfer.

The claim flow only DISCONNECTS the previous owner's row to free the canonical slug; the requesting user re-runs /connect to register their own Unipile session, which then succeeds because the slug is no longer held.

previous_owner_user_id · string<uuid> · required

User ID of the previous owner (for client-side audit logging only).

linkedin_slug · string · required

The canonical slug that was freed. The frontend uses this to prompt the user to re-run /connect and complete onboarding.

success · boolean · default: true

next_action · string · default: reconnect

Always 'reconnect'. The frontend should redirect the user back to the connect flow so they can register their own Unipile session.