Skip to main content
POST
/
api
/
unipile
/
connect
Start a Unipile LinkedIn connection flow
curl --request POST \
  --url https://app.puffle.ai/api/unipile/connect \
  --header 'Authorization: Bearer <token>'
{ "url": "https://account.unipile.com/hosted/abc123xyz" }

​
Overview

Returns a one-time hosted Unipile URL that the user must open in a browser to complete LinkedIn OAuth. Unipile handles the actual LinkedIn login, MFA, and cookie capture — none of which can be completed headlessly. Once the user finishes the hosted flow, Unipile fires an AccountStatus webhook to /api/webhooks/unipile which:
  • Creates the row in accounts with type='linkedin'
  • Links it to the user via the pending_unipile_connections handshake (keyed by user_id)
  • Flips status to connected
The generated URL expires 1 hour after issuance.

​
AI agent notes

Cannot be completed autonomously. The url field in the response MUST be opened in a human-operated browser. LinkedIn blocks headless logins. The typical pattern for an AI agent:
  1. Call this endpoint.
  2. Surface the url to the human and ask them to complete the flow.
  3. Poll GET /api/unipile/accounts every 10–20 s — when a new row appears with status: "connected", the link is live.
  4. The account’s provider_account_id on that row is what you pass to searchUnipile, refreshUnipileAccount, or reconnectUnipileAccount later.
Stale pending rows. The route deletes any prior pending_unipile_connections entry for this user before inserting a fresh one, so calling connect twice in a row is safe — the most recent call wins.Expiration. If the user doesn’t complete the flow within 1 hour, call this endpoint again for a fresh URL.Premium detection is automatic. When the webhook creates the row, is_premium / has_sales_navigator / weekly limits are derived from Unipile’s account payload. If the user upgrades LinkedIn later, call refreshUnipileAccount to pick up the new limits without re-auth.

Authorizations

​
Authorization
string
header
required

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

Response

Hosted auth URL created. Redirect the user here to complete LinkedIn OAuth.

​
url
string<uri>
required

Hosted Unipile auth URL. Redirect the user's browser here to complete LinkedIn OAuth. Expires 1 hour after creation.