Global Clinic ConnectGuides
Integration step 01

Getting started

Create a narrowly scoped API key, make a safe first request, and understand the response and rate-limit basics.

OutcomeAn authenticated test request from your server environment
Required scopesChoose scopes for the capabilities you implement
Step by step

Typical integration workflow

01

Choose your capability

Decide whether the integration will send messages, read conversations, publish social content, or ingest documents.

02

Create an API key

In Global Clinic Connect, open Settings, choose Developer, create a key with only the scopes needed, and store the one-time secret in your server-side secret manager.

03

Choose the environment

Use the API base URL for the same environment where the key was created. Keys do not move between development, staging, and production.

04

Send the bearer token

Add Authorization: Bearer YOUR_API_KEY to every request. Do not send an X-Tenant-Id header; the key already belongs to one workspace.

05

Handle the first response

Treat 2xx as acceptance of the state described by the response. Handle 4xx outcomes explicitly and retry only when the guidance says it is safe.

API reference

Endpoint for this capability

These are the supported public contracts for this integration step.

GET/api/public/v1/conversations?channel=whatsapp&limit=25
Scope · conversations:read

List conversations

Read a recent page of conversations, optionally limited to one channel.

Example request
GET /api/public/v1/conversations?channel=whatsapp&limit=25
Authorization: Bearer YOUR_API_KEY
Accept: application/json
Example response
{
  "conversations": [
    {
      "conversation_id": "conv_example",
      "channel": "whatsapp",
      "status": "open",
      "last_message_at": "2026-07-12T08:30:00.000Z",
      "last_message_preview": "Your appointment is confirmed"
    }
  ],
  "next_cursor": null
}

Error handling

400invalid channel filter

Use web_chat, sms, whatsapp, or email as the channel.

403INSUFFICIENT_SCOPE

Create a key with conversations:read.

429RATE_LIMITED

Pause until the current minute ends.

Best practices

  • Use next_cursor exactly as returned.
  • Keep page sizes modest for responsive synchronization.
  • Store only the conversation information your integration needs.
  • Protect message previews as sensitive data.
Try this endpoint in the console
Production checklist

Best practices

  • ✓Create separate keys for each integration and environment.
  • ✓Give each key the smallest set of scopes.
  • ✓Set an expiry and rotate before it is reached.
  • ✓Never place a key in browser code, mobile apps, source control, or logs.
Interactive console

Try a supported API

Requests go directly from this browser tab to the API environment you choose. Keys and responses are held in memory only and are cleared when the page closes.

Do not use real patient data in tests
GET/api/public/v1/conversations?channel=whatsapp&limit=25
Response
Ready when you are

Enter a test key, review the sample request, and send it. The response will appear here.

Equivalent cURL example
curl -X GET 'https://api.connect.globalclinic.app/api/public/v1/conversations?channel=whatsapp&limit=25' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json'
Required scopeconversations:read

Read a recent page of conversations, optionally limited to one channel.

Next steps