Skip to main content
POST
Create a connect session

Authorizations

Authorization
string
header
required

A platform access token. Get one on the Create an access token endpoint by exchanging your client_id + client_secret, then send it as Authorization: Bearer <token>. Tokens live one hour.

Body

application/json
return_url
string
required

Where we send the company when the flow completes. Must exactly match (origin + path) a redirect URI registered on your OAuth client. https required; http://localhost is allowed in test mode.

state
string

Opaque value echoed back on the redirect — bind it to the company's session on your side to prevent CSRF.

Maximum string length: 512

Response

The session, including the hosted url to send the company to.

id
string

Session id (pcs_…). Use it to poll status and exchange the code.

object
string
Example:

"platform_connect_session"

status
enum<string>

pending → the company hasn't finished the hosted flow. bound → the company picked an organization but hasn't confirmed yet. completed → the code was issued and is ready to exchange. claimed → you already exchanged it. expired → the link lapsed.

Available options:
pending,
bound,
completed,
claimed,
expired
return_url
string
state
string | null

Your opaque passthrough value, echoed on the final redirect.

sandbox
boolean
deprecated

Deprecated spelling of test_mode.

test_mode
boolean

Inherited from the credential that created the session.

connected_organization_id
string | null

The connected organization, present once the company completes the flow.

created_at
string<date-time>
completed_at
string<date-time> | null
expires_at
string<date-time>

The hosted link expires 60 minutes after creation.

url
string

The hosted flow URL. Redirect the company here.