Partner API developer guide

Before you start

• The Partner API is an add-on for organizations, in two tiers, with one key per organization. Connect ($249 a month) links members by your own ID after they sign the disclosure and share their link code, and unlinks them; sends appointments into their app calendar, sealed with the member's own key on arrival, with changes, cancellations and a 6 pm day-before reminder that shows no title or place; shows accepted or declined if the member chose to share it; passes on shared answers and signed disclosures; gives rounded monthly counts (1 to 10 shows as “fewer than 11”); sends signed webhooks with the Part 2 notice; and passes identity-free “Can we talk?” alerts. Connect+ ($750 a month) adds automatic seats (join codes labelled with your ID, never a name, on the plan your system picks), automatic discharge that starts the member's aftercare, funder outcome reports at 30, 60 and 90 days after discharge (totals only: members active, days in program, check-ins, meetings attended, appointments accepted; at least 11 people, or it shows “too few members”), scheduled care messages and broadcasts under the portal's rules (up to 5 broadcasts a day, and up to 10 care team messages per member in any 7 days, across the program), documents such as discharge plans sent to one member and sealed with their own key (after a new disclosure from that member), and Resources sync, stored and sent securely. All features are live. The Connect+ endpoints are shared with your engineers during onboarding; write to support@freeandsober.com to request access. See pricing on the Organizations page.
• A member is linked only after they sign the privacy disclosure in the app and give you the link code the app shows them. A link code links one member to one external_id at a time.
• Your system knows each member by your own identifier (external_id). A member's first name and last initial appear in the staff portal only, after they sign the privacy disclosure; the API works with your ID. A member's words and recordings stay in their own account.

Signing your calls

Send Authorization: Bearer <key> on every call. Each key can make 300 calls a minute.

Calls go to https://api.freeandsober.com.

The calls

• GET /v1/partner/org The organization and this key.
• GET /v1/partner/counts?month=YYYY-MM The same counts as your admin page: members, joined and left are exact, and an activity count from 1 to 10 is held back.
• POST /v1/partner/members with {link_code, external_id}. Links a member who signed the disclosure and gave you the code the app showed them.
• GET /v1/partner/members/:external_id What the member chose to share, and each appointment, as delivered.
• DELETE /v1/partner/members/:external_id Unlinks the member. Any appointment they haven't answered yet is deleted.
• POST /v1/partner/members/:external_id/appointments with {title, day, start_time?, end_time?, kind?, location?, notes?, time_zone?, external_ref?}. Sends an appointment or program date. Its title, kind, location and notes are sealed to the member's key the moment it arrives. The day, the times, the time zone and your external_ref stay readable, so put nothing about the member in external_ref. The member accepts or declines it in the app.
• GET /v1/partner/members/:external_id/appointments Each appointment you sent, as delivered, and whether the member accepted or declined it, if the member chose to share that. Never its words.
• GET /v1/partner/authorizations/:id The signed disclosure that every answer and event names: its version, when it was signed, what the member chose, and its words with your organization's name.

Webhooks

We send a POST to the address you set on your admin page. The body is {id, event, created_at, data, part2_notice, authorization}, and the headers are X-FS-Event, X-FS-Part2-Notice and X-FS-Signature.

• The signature. X-FS-Signature is t=<seconds>,v1=<hex>: an HMAC-SHA256 of <t>.<body> made with your webhook secret, which your admin page shows once.
• The events. member.linked, member.unlinked, member.left and member.seat_ended.
• Retries. A delivery that isn't answered with a 2xx status is tried again, with longer waits between tries, for about a week and eight tries at most.
• The address. A webhook address must use https.

The Part 2 notice and the member's authorization

Every answer about one member (the link, the member, the unlink, an appointment you sent and the list of appointments) carries the 42 CFR Part 2 notice in its body (part2_notice) and in the header X-FS-Part2-Notice. Every event carries it too.

Each also carries authorization: {id, version, scope_url}. It is the record of the disclosure the member signed, and the address of its scope (GET /v1/partner/authorizations/:id). You can read it with your key, for your own members only, and each read is logged.

What is not shared

• Whether a member accepted or declined an appointment, unless the member chose to share that.
• A member's words, recordings, mentor conversations, notes, calendar or corner. These stay in the member's own account, signed or not.
• Anything about a member who has not signed the disclosure, beyond the counts your admin page shows.

How long we keep events

An event is kept only to deliver it, and only while you have a webhook address set. Nothing is queued without one, and removing your webhook address deletes what was waiting for it.

Every event is deleted seven days after it was made, delivered or not. When a member withdraws, leaves or their seat ends, anything queued for them and not yet delivered is deleted, and the one event that says sharing ended (member.unlinked, member.left or member.seat_ended) is sent.

Questions

Write to support@freeandsober.com, and a person replies within 24 hours.

Free and Sober Inc., 89 Moody Road, Enfield, CT 06082