AHFOZ Tariff API v1

Programmatic access to the official AHFOZ (Association of Healthcare Funders of Zimbabwe) medical procedure tariff schedule. Integrate tariff data directly into your claims system, practice management software, or health information exchange.

Overview

The AHFOZ Tariff API is a RESTful JSON API hosted on the PSMAS platform. It provides read-only access to the published tariff schedule, including procedure codes, diagnosis code mappings, and amounts in both USD and ZWG.

Access: API access requires a token issued by PSMAS. Contact it@psmas.co.zw to request credentials.

Base URL

https://psmas.herokuapp.com/api/v1

All endpoints are relative to this base URL. HTTPS is required on all requests.

Authentication

Need credentials? Submit an API Access Request to obtain your integration token. Approved requests receive a secure one-time retrieval link by email.

Every request must include your API token as a Bearer token in the Authorization HTTP header:

Authorization: Bearer <your_api_token>

Requests without a valid token receive a 401 Unauthorized response.

Keep tokens secret. Never expose your token in client-side code, public repositories, or URLs. Rotate it immediately if compromised — contact PSMAS support.

Example request

curl -H "Authorization: Bearer sk_live_abc123..." \
     "https://psmas.herokuapp.com/api/v1/tariffs?status=active"

Error Handling

All errors return a JSON body with error and message fields.

HTTP Status	Meaning
200 OK	Success
401 Unauthorized	Missing or invalid Bearer token
403 Forbidden	Token lacks required scope
404 Not Found	Resource does not exist
422 Unprocessable	Invalid query parameters
500 Server Error	Contact PSMAS support

Error response shape

{
  "error":   "Unauthorized",
  "message": "Invalid or missing API token."
}

Pagination

List endpoints are paginated. Use page and per_page query parameters. Maximum per_page is 200.

GET /api/v1/tariffs?page=2&per_page=100

All list responses include a meta object:

{
  "meta": {
    "current_page": 2,
    "per_page":     100,
    "total_pages":  5,
    "total_count":  487
  }
}

List Tariffs

GET /api/v1/tariffs

Returns the paginated AHFOZ tariff schedule. Filter by status, procedure code, diagnosis code, or effective date.

Query Parameters

Parameter	Type		Description
status	string	optional	`active` or `inactive`. Omit for all.
procedure_code	string	optional	Filter by exact AHFOZ procedure code (e.g. `0030`).
diagnosis_code	string	optional	Filter tariffs that include this ICD-10 diagnosis code.
effective_on	date (ISO 8601)	optional	Return only tariffs effective on this date (e.g. `2026-04-28`).
scheme_id	integer	optional	Scheme ID. Defaults to the primary PSMAS scheme if omitted.
page	integer	optional	Page number. Default: 1.
per_page	integer	optional	Results per page. Default: 50. Max: 200.

Example Request

curl -H "Authorization: Bearer sk_live_abc123..." \
     "https://psmas.herokuapp.com/api/v1/tariffs?status=active&effective_on=2026-04-28"

200 Response

{
  "data": [
    {
      "id": 12,
      "code": "AHFOZ-0030-001",
      "procedure_code": "0030",
      "description": "General Practitioner Consultation",
      "diagnosis_codes": ["Z00.0", "Z00.1"],
      "amounts": {
        "usd": "45.00",
        "zwg": "3150.00"
      },
      "effective_from": "2026-01-01",
      "effective_to": null,
      "active": true,
      "created_at": "2026-01-15T08:00:00Z",
      "updated_at": "2026-04-01T10:23:45Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total_pages": 10,
    "total_count": 487
  },
  "schema": "AHFOZ",
  "scheme": "PSMAS Premier",
  "generated_at": "2026-04-28T12:00:00Z"
}

Get Tariff

GET /api/v1/tariffs/:id

Returns a single tariff by its integer ID.

Path Parameters

Parameter	Type		Description
id	integer	required	The tariff's unique integer ID.

Example Request

curl -H "Authorization: Bearer sk_live_abc123..." \
     "https://psmas.herokuapp.com/api/v1/tariffs/12"

200 Response

{
  "data": {
    "id": 12,
    "code": "AHFOZ-0030-001",
    "procedure_code": "0030",
    "description": "General Practitioner Consultation",
    "diagnosis_codes": ["Z00.0", "Z00.1"],
    "amounts": { "usd": "45.00", "zwg": "3150.00" },
    "effective_from": "2026-01-01",
    "effective_to": null,
    "active": true,
    "created_at": "2026-01-15T08:00:00Z",
    "updated_at": "2026-04-01T10:23:45Z"
  }
}

Tariff Object Reference

Field	Type	Description
id	integer	Unique identifier.
code	string	AHFOZ tariff code (unique per scheme).
procedure_code	string	AHFOZ procedure code (e.g. `0030`).
description	string	Human-readable description of the procedure.
diagnosis_codes	string[]	ICD-10 diagnosis codes that apply to this tariff.
amounts.usd	decimal string	Tariff amount in USD (e.g. `"45.00"`).
amounts.zwg	decimal string	Tariff amount in ZWG.
effective_from	date (ISO 8601)	Date from which this tariff applies.
effective_to	date or null	Date until which this tariff applies. `null` means no expiry.
active	boolean	Whether the tariff is currently active.
created_at	datetime (ISO 8601)	Record creation timestamp.
updated_at	datetime (ISO 8601)	Last modified timestamp.

Scopes

Each API token is issued with one or more scopes that control what the token can access.

Scope	Access Granted
tariffs:read	Read access to all tariff endpoints (index + show).

Rate Limits

The API enforces a limit of 1,000 requests per hour per API token. Exceeding this limit returns 429 Too Many Requests. Contact PSMAS if your integration requires a higher limit.

SDKs & Client Libraries

No official SDK is available yet. The API is standard REST+JSON, compatible with any HTTP client:

cURL

curl -H "Authorization: Bearer <token>" \
     "https://psmas.herokuapp.com/api/v1/tariffs?status=active"

Python (requests)

import requests

headers = {"Authorization": "Bearer <token>"}
r = requests.get("https://psmas.herokuapp.com/api/v1/tariffs", headers=headers, params={"status": "active"})
tariffs = r.json()["data"]

JavaScript (fetch)

const res = await fetch("https://psmas.herokuapp.com/api/v1/tariffs?status=active", {
  headers: { "Authorization": "Bearer <token>" }
});
const { data } = await res.json();

PHP (Guzzle)

$client = new \GuzzleHttp\Client();
$response = $client->get("https://psmas.herokuapp.com/api/v1/tariffs", [
    "headers" => ["Authorization" => "Bearer <token>"],
    "query"   => ["status" => "active"]
]);
$tariffs = json_decode($response->getBody(), true)["data"];

AHFOZ Tariff API — Powered by PSMAS PremierCare Platform · For API access enquiries: it@psmas.co.zw