Introduction

The Medtimes API allows you to embed regulated clinical capabilities directly into your application. We provide the infrastructure for telehealth consultations, medical aid billing, and electronic prescriptions.

Our API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

Base URL

Authentication

The Medtimes API uses API keys to authenticate requests. You can view and manage your API keys in the Partner Console.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Bearer Auth. Provide your API key as the bearer token value.

curl https://api.medtimes.health/v1/consults \
  -H "Authorization: Bearer sk_live_abc123..."

Generates a secure, HIPAA/POPIA compliant video room and assigns the next available Locum GP from the Medtimes network to the session.

import { Medtimes } from '@medtimes/sdk';

const medtimes = new Medtimes('sk_live_...');

const consult = await medtimes.consults.create({
  patient_id: 'usr_8921a',
  symptoms: ['persistent cough', 'fever'],
  billing_mode: 'medical_aid',
  scheme_details: {
    name: 'Discovery Health',
    number: '123456789'
  }
});

{
  "id": "cns_4492193",
  "object": "consult",
  "status": "waiting_for_doctor",
  "join_url": "https://meet.medtimes.health/cns_4492193",
  "expires_at": 1740075551
}

Allows your platform to submit an EDI claim directly to a South African medical aid switcher.

const claim = await medtimes.claims.submit({
  patient_id: 'usr_8921a',
  amount: 45000,
  currency: 'zar',
  icd10_codes: ['J20.9'], // Acute Bronchitis
  tariff_codes: ['0132'] // Telehealth Consult
});

Errors

Medtimes uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted). Codes in the 5xx range indicate an error with our servers.

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "The 'patient_id' field is required."
  }
}

For Corporate Wellness Days and high-volume screenings. Upload a batch of employees to instantly validate medical aid standing and provision temporary EMR profiles for the event.

{
  "id": "evt_909112",
  "status": "processed",
  "summary": {
    "total_received": 500,
    "validated": 485,
    "scheme_suspended": 15
  },
  "validation_report_url": "https://..."
}

Fetch the details of an electronic prescription issued by a Medtimes Locum during a telehealth consultation. You can use this to show users their script status or pharmacy token.

{
  "id": "scr_881920",
  "consult_id": "cns_4492193",
  "doctor": "Dr Medstar (MP 000000)",
  "medication": [
    {
      "name": "Amoxicillin 500mg",
      "dosage": "1 cap TDS for 5 days"
    }
  ],
  "status": "dispatched",
  "pharmacy": "Clicks Sandton",
  "collection_token": "MED-A92B"
}

Webhook Events

Medtimes uses webhooks to notify your application when an asynchronous event happens in your account. Webhooks are particularly useful for asynchronous events like medical aid claim settlements or when a doctor completes a consultation.

Verifying Signatures

To verify that a webhook was actually sent by Medtimes and not a malicious third party, every payload includes a Medtimes-Signature header. This is an HMAC SHA256 signature generated using your Endpoint Secret.

const crypto = require('crypto');

app.post('/webhooks/medtimes', express.raw({type: 'application/json'}), (request, response) => {
  const signature = request.headers['medtimes-signature'];
  const endpointSecret = process.env.MEDTIMES_WEBHOOK_SECRET;

  const hash = crypto
    .createHmac('sha256', endpointSecret)
    .update(request.body)
    .digest('hex');

  if (hash === signature) {
    console.log('Webhook verified successfully!');
    // Process the event...
    response.status(200).send();
  } else {
    response.status(400).send('Invalid signature');
  }
});

Support & Contact

Need help integrating the Medtimes API? We offer several channels for developer and enterprise support to ensure your deployment goes smoothly.