Third-Party Integration Documentation

Third-Party Integration Documentation

This guide explains how customers use the third-party integration and the API endpoint once the integration is enabled. It is designed as a practical reference for implementation, support, and operational use.

Overview

The third-party integration supports controlled sharing of patient contact details for appointment-booking workflows. After the integration is enabled, customers use securely shared credentials to authenticate and access permitted API resources.

The customer receives a client ID and client secret through secure communication. Using these credentials, the customer generates a JWT token to authenticate downstream requests.

When a patient has provided consent to share contact details, and the target study is configured for appointment booking, the api endpoint can return the patient record for the code. This only happens if all required validation conditions are met.

How the integration works end to end

• The customer receives the client ID and client secret through a secure channel.

• The customer generates a JWT token using those credentials.

• The customer calls the api endpoint using the invite code.

• If consent and all business conditions are satisfied, patient contact details can be returned for appointment-booking use.

JWT Token Generation

The customer must generate a JWT token using the client ID and client secret provided through a secure channel. Two methods are supported.

Method 1 — curl (bash)

Use the following curl command in Git Bash. Replace your_client_id and your_client_secret with the actual credentials shared with you.

curl --location --request POST 'https://xxx.xxx.xxx/oauth2/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Cookie: XSRF-TOKEN=b4dfa071-b4f5-4e7f-a1e6-04d6235a027a' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=your_client_id' \
  --data-urlencode 'client_secret=your_client_secret'

⚠️ Replace your_client_id and your_client_secret with the actual values provided to you. Do not share these credentials.

Method 2 — HTTP POST (Form Data)

Endpoint: https://xxx.xxx.xxx/oauth2/token

Method:POST

Content-Type:application/x-www-form-urlencoded

Request body (form data):

grant_type=client_credentials
client_id=your_client_id
client_secret=your_client_secret

Response:

{
  "access_token": "<access_token>",
  "expires_in": 3600,
  "token_type": "Bearer"
}

The access_token returned should be used as a Bearer token in the Authorization header for all subsequent API calls. Tokens expire after 3600 seconds (1 hour).

Customer and API flow

From the customer point of view, the integration starts after credentials are securely shared. The customer uses the client ID and client secret to generate a JWT token. This token is then used to call the endpoint.

Before token-based access is accepted, the system validates the customer credentials and confirms that the integration is available for the requested workflow.

API endpoint

Endpoint: https://xxx.xxx.xxx/R4/Patient/{code}

Method: GET

Purpose: Retrieve patient information associated with a valid code when all third-party integration rules are satisfied

HTTP responses

Success response code: 200

A successful response returns the patient details permitted for third-party integration use. The response may include the following Patient fields:

• firstName

• lastName

• phone

• generalPractitioner

  • name

  • address

{
  "data": {
    "firstName": "xxx",
    "lastName": "yyy",
    "phone": "123456",
    "email": "test@xx.com",
    "generalPractitioner": {
      "name": "Some Practice Name",
      "address": "123 Practice Street, London"
    }
  }
}

Error response code: 404

Validation and business-rule failures return an error response using the following structure.

Error Condition	HTTP Status	Example Response
Third-party integration is not configured for this study	404	{ "errors": [ { "message": "Third party integration is not configured for this study" } ] }
Code not found	404	{ "errors": [ { "message": "Invite code 12345 not found" } ] }
Patient has not consented to share contact details	404	{ "errors": [ { "message": "Patient has not consented to share contact details" } ] }
Client ID not found for third-party integration	404	{ "errors": [ { "message": "Client id not found for third party integration" } ] }
Third-party integration organisation does not have access to the patient details	404	{ "errors": [ { "message": "Third party integration organisation does not have access to the patient details" } ] }

When will this api endpoint send Patient Details?

This endpoint becomes valid only after patient consent has been captured. If the patient has agreed to share contact details, and the study is configured for appointment booking, the third-party integration API supports the downstream process by making the relevant patient data available.

Functional sequence

• The customer receives the client credentials securely.

• The customer generates a JWT token using the client ID and client secret.

• The platform validates the client mapping and enabled state.

• The customer calls /R4/Patient/{code} .

• The platform validates code, study configuration, study enablement, location status, and organisation configured for the study.

• If the patient has consented and all checks pass, the patient external appointment booking flow can continue.

Summary

This third-party integration is a controlled mechanism for connecting external systems to patient-sharing workflows. Customers use securely shared credentials to generate JWT tokens and call the API endpoint. The final data-sharing path is guarded by identity validation, patient consent checks, study configuration, and operational rules to ensure access happens only in approved scenarios.