Skip to main content
A launch session is one report hand-off: your platform creates it, the assigned clinician completes the report in Everbility, and your platform pulls the finished document back. Sessions expire after 48 hours if not completed. All endpoints on this page require a partner access token from the connect flow: 
Authorization: Bearer pat_...

​
Create a session

POST /v1/partner/launch-sessions with a required Idempotency-Key header: 
curl -s https://api.everbility.com/v1/partner/launch-sessions \
  -H "Authorization: Bearer pat_..." \
  -H "Idempotency-Key: 018f6a1c-5b7e-7c4d-9f3a-2f6f1f6f9d42" \
  -H "Content-Type: application/json" \
  -d '{
    "external_client_id": "your-client-42",
    "clinician_email": "jordan@examplepractice.com",
    "client_first_name": "Alex",
    "client_last_name": "Nguyen"
  }'
Response
{
  "session_id": "psess_Zl9nB1qFhOQe2kQ4rW8xJ3Ty",
  "status": "created",
  "launch_url": "https://www.everbility.com/partner-sessions/psess_Zl9nB1qFhOQe2kQ4rW8xJ3Ty",
  "expires_at": "2026-07-08T04:15:00Z"
}
FieldRequiredDescription
external_client_idYesYour platform’s ID for the client (max 255 chars). Used to remember the client mapping across sessions.
clinician_emailYesMust match the verified email of exactly one member of the connected practice. Matching is case-insensitive.
client_first_nameNoShown to the clinician when they map the client for the first time.
client_last_nameNoShown to the clinician when they map the client for the first time.
Idempotency. Retrying with the same Idempotency-Key and identical body returns the original session instead of creating a duplicate. Reusing a key with a different body fails with 409 Idempotency-Key conflict. Use a fresh UUID per logical session.

​
Hand off to the clinician

Open launch_url for the clinician — as a link, button, or embedded browser view from your platform. From there, Everbility takes over:
1

Sign in

The clinician signs in with their own Everbility account. Only the clinician matched by clinician_email can open the session.
2

Map the client (first time only)

If this external_client_id has not been seen before on this connection, the clinician links it to an Everbility client or creates a new one. The mapping is remembered, so later sessions for the same client skip this step.
3

Write and complete

The clinician writes the report in the Everbility writer and marks the session complete, which attaches the finished document to the session.

​
Poll session status

curl -s https://api.everbility.com/v1/partner/launch-sessions/psess_Zl9nB1qFhOQe2kQ4rW8xJ3Ty \
  -H "Authorization: Bearer pat_..."
Response
{
  "session_id": "psess_Zl9nB1qFhOQe2kQ4rW8xJ3Ty",
  "status": "completed",
  "created_at": "2026-07-06T04:15:00Z",
  "opened_at": "2026-07-06T04:22:41Z",
  "completed_at": "2026-07-06T05:03:12Z",
  "expires_at": "2026-07-08T04:15:00Z",
  "document_url": "/v1/partner/launch-sessions/psess_Zl9nB1qFhOQe2kQ4rW8xJ3Ty/document"
}
StatusMeaning
createdSession exists; the clinician has not opened it yet.
openedThe clinician has opened the session in Everbility.
completedA document is attached — document_url is now populated.
expiredThe 48-hour window lapsed, or the connection was revoked, before completion. Terminal.
There are no webhooks yet; poll on a modest interval (for example every 30–60 seconds while you expect the clinician to be working) or when a user views the record in your platform.

​
Retrieve the completed document

Once status is completed, fetch the rendered report: 
curl -s "https://api.everbility.com/v1/partner/launch-sessions/psess_Zl9nB1qFhOQe2kQ4rW8xJ3Ty/document?format=html" \
  -H "Authorization: Bearer pat_..."
Response
{
  "session_id": "psess_Zl9nB1qFhOQe2kQ4rW8xJ3Ty",
  "title": "Functional capacity report",
  "everbility_client_id": 864,
  "format": "html",
  "content": "<h1>Functional capacity report</h1>..."
}
Use format=markdown (default) or format=html. The document stays available on the completed session, so you can re-fetch it after the 48-hour session window.

​
Errors

StatusDetailCause
400Idempotency-Key is requiredMissing or blank Idempotency-Key header on create.
400clinician_email_not_resolvedThe email does not match exactly one verified member of the connected practice.
401Invalid bearer tokenAccess token missing, expired (1 h), or revoked — refresh and retry.
401Invalid partner connectionThe connection was revoked or needs re-authorization.
403client_access_deniedThe mapped Everbility client is not accessible to the assigned clinician.
404Session not foundUnknown session_id, or it belongs to a different connection.
409Idempotency-Key conflictKey reused with a different request body.
409Session not completedDocument requested before the session reached completed.
410Session expiredDocument requested on an expired session.
Errors use the standard shape: 
{ "detail": "Session not completed" }