Getting Started

We're excited to partner with you! If you have any feedback, please let us know at support@counselhealth.com. We continuously improve based on user feedback, please note that these APIs are subject to change.

Technical Examples

• See Counsel Embedded Example Apps Repo for examples of how to embed the Counsel experience in your app.

• For a live demo see https://embedded-demo.counselhealth.com/. Email support@counselhealth.com to get an access code.

API Details

Counsel uses API keys for authentication. All requests must be made from a secure server environment. Please store this securely and treat it like a password. Counsel does not store your API key once it is issued. Reach out to support@counselhealth.com if you need to rotate your API key. We recommend rotating your API key every 3 months.

Idempotency

It’s recommended that all POST and PATCH APIs are passed an header Idempotency_Key. Idmepotency requests will be processed once and the same request can be retried in the event of a failure without side effects. Conflicting requests will result in a 409 error. Keys must be minimum 10 characters.

JWKS Authorization

• We strongly recommend asymmetric JWKS authorization with signing keys issued by you in conjunction with Counsel API keys

• How it works:

  • You create an JWT token signed using a private key

  • You share a JWKS URI with a public set of JSON web tokens with Counsel

  • You send an API request to the Counsel API with both of the headers

    curl -X POST <https://api.counselhealth.com/v1/user>
      -H "Authorization: Bearer <YOUR_SIGNED_JWT_TOKEN>"
      -H "x-counsel-api-key: Bearer <YOUR_API_KEY>"
    

    bash

  • Counsel verifies both the JWT token against your public JSON web tokens and API key

• What this ensures:

  • A leaked API key alone cannot grant a bad actor access to Counsel

  • Both the JWT private key and API key have to be leaked for there to be a security breach

  • You never have to share the JWT private key with Counsel

• See this for more information

Integration steps

1. Create a user account during onboarding

You will manage the onboarding experience, including the value propositions that you choose to surface and the entry point for the Counsel experience. Capture patient consent in onboarding We must get consent from the user for Counsel’s terms of service. This allows users to message our doctors and for us to retrieve patient medical history from Health Information Exchanges (HIEs). Our legal teams should pair together to understand what additional terms of service this may require.

2. Request a one-time signed URL

Authentication Flow

• Request a one-time signed URL: POST /v1/user/{userId}/signedAppUrl

• Use the returned url to load the iFrame or WebView

• The URL will be valid for a single use for 7 days. Once loaded the iFrame or WebView remains valid indefinitely until closed or explicitly signed out.

3. Embed the Counsel chat experience

The chat experience will be embedded as an iFrame or WebView in your web or mobile app. We will automatically load your custom UI in the chat experience.

<iframe src="${signedAppUrl}" width="100%" height="600px">

4. Sign out users on Counsel

When users sign out of your app or website, you should also sign them out of the Counsel session.

5. Notify your users when they receive a new message

Webhooks notify you of new events such as our physicians sending a new message to your users. Use the content of these webhooks to craft your notification. Alternatively, we can also send white-labeled SMS messages on your behalf to notify your users.

Registered numbers for white-labeled SMS (if applicable):

• Test Environment: +16463286871

• Production Environment: +18572264443

Counsel requires a deep-link to your application where the Counsel iFrame or WebView is embedded that we will use in our white-labeled SMS communications.

6. Webhooks

Webhooks notify you of new events such as our physicians sending a new message to your users. Once you register a webhook subscription, you will receive webhook events via POST request to your server. We use the Standard Webhooks specification to sign and verify webhook requests.

Webhook request/response behavior:

• 2xx response codes are considered successful and the event is considered processed.

• Requests have a 5 second timeout before they are considered failed.

• Failed requests are retried up to 6 times with exponential backoff starting at 10 seconds.

• Retries will respect the Retry-After header if present up to a maximum of 900 seconds (15 minutes).

Webhook security

• Webhook subscription endpoints must be HTTPS endpoints.

• We use the Standard Webhooks symmetric signing method to sign and verify webhook requests.

• We will share a secure secret with you. Each incoming request will have a webhook-signature header that you can use to verify the request with the secret.