# Open In Buttons

Open In Buttons let a clinic add a link to your application on every patient record in PracSuite. When a user clicks the button, PracSuite opens your URL in a new browser tab and includes the patient's ID, so your application can go straight to that patient.

![Open In Buttons in the patient toolbar](/assets/patient-toolbar.04fa775cdbe3ec118eca35c28775ad270fe54287528f902fabc71a6bdc9957a4.ab781818.png)

This guide covers:

1. [How it works](#how-it-works)
2. [Handling the request in your application](#handling-the-request-in-your-application)
3. [Getting your origin approved](#getting-your-origin-approved)
4. [Setting up a button in PracSuite](#setting-up-a-button-in-pracsuite)


## How it works

PracSuite adds the patient's ID to your URL as a `client_id` query parameter and sends the user there with a browser `GET` request.

For example, if the button URL is:

```
https://example.com/patient
```

Clicking the button for patient `12345` opens:

```
https://example.com/patient?client_id=12345
```

This is the same `client_id` used in the PracSuite API, so you can use it to fetch the patient's details:

```
curl -X GET "https://api.pracsuite.com/v1/patient/12345" \
  -H "x-api-key: VENDOR_API_KEY_HERE" \
  -H "a-api-key: SUBSCRIBER_API_KEY_HERE"
```

Note
The request comes from the user's browser, not from PracSuite's servers. It contains only the `client_id`. It carries no API keys, user details or signature.

## Handling the request in your application

Your endpoint must accept a `GET` request with a `client_id` query parameter. When it receives one, it should:

1. Read `client_id` from the URL.
2. If the user isn't signed in to your application, show your login page, then send them back to the original URL (including `client_id`).
3. Show the matching patient. If there isn't one, let the user find, link or create the patient.
4. Optionally, use the PracSuite API to fetch or sync the patient's details.


Important
Anyone can type any `client_id` into the URL. Never trust the parameter alone. Only show patient data to signed-in users who have access to that clinic.

Patient IDs are only unique within a clinic. If your application serves more than one clinic, match on both the user's clinic and the `client_id`.

## Getting your origin approved

Clinics can add a button with any URL, but the button won't open it unless PracSuite has approved the URL's origin.

PracSuite approves origins, not individual URLs. An origin is the scheme, host and port of a URL, without the path or query string. For example, the origin of `https://example.com/patient` is `https://example.com`. Once an origin is approved, buttons can open any path on it, such as `https://example.com/patient` or `https://example.com/v2/patients/open`.

When your endpoint is ready, email [api@pracsuite.com](mailto:api@pracsuite.com) with:

- Your vendor name.
- The origin to approve, for example `https://example.com`.
- A short description of what your application does with the patient.


We'll let you know when your origin has been approved. You can change paths on an approved origin at any time. If you move to a different origin, such as a new domain or subdomain, send it to us to approve before you give it to clinics.

## Setting up a button in PracSuite

Clinics add the button themselves under **Open In Buttons** at [app.pracsuite.com/settings/integrations/api](https://app.pracsuite.com/settings/integrations/api). A clinic can add more than one button.

![Open In Buttons settings](/assets/settings-list.c138931b993f167a140bb4a2bc930539a97458a8bf993f4f0f6c5767cc672d1a.ab781818.png)

| Field | Description |
|  --- | --- |
| Active | Shows or hides the button on patient records. |
| Button Label | Text shown on the button. |
| URL | Your URL. PracSuite adds `client_id` to it. The button only opens the URL if its origin is approved. |
| Background | Button background colour. |
| Text | Button text colour. |


The dialog shows an example link and a preview of the button before the clinic saves it.

![Configuring an Open In Button](/assets/configure-button.1c09660d9ae9ca724fc9fd1e06f544980051b724cc3b1fff46bc184dc9d2bff0.ab781818.png)

### Giving clinics your URL

Give clinics your URL on the approved origin. If you'd like clinics to use a particular label or colours, tell them at the same time. Use the same URL for every clinic and work out which clinic it is from the signed-in user. Don't create a separate URL for each clinic.