Programmatic Access to South African Procurement Data

Tenders-SA.org aggregates tenders from national, provincial, and municipal government departments, SOEs (Eskom, Transnet, SANRAL), and public entities across South Africa. The data is sourced directly from official OCDS (Open Contracting Data Standard) feeds and then enriched through AI pipelines for summarisation, requirement extraction, value estimation, and classification.

The Tenders-SA Developer API exposes this enriched procurement data through a set of RESTful endpoints. It runs on a dedicated infrastructure layer with its own database — synced from the main platform — so the API remains fast and available independently of the web application. This guide covers the API architecture, authentication, available endpoints, and usage patterns.

API Base URL and Authentication

All API requests are made to the following base URL:

Copy
1https://api.tenders-sa.org/v1
TEXT

Authentication is handled via Bearer tokens passed in the Authorization header. API keys use the format tsa_prod_ followed by a unique generated string:

Copy
1Authorization: Bearer tsa_prod_your_api_key
TEXT

API keys are generated through the Developer Portal

. Access requires a Professional or Enterprise subscription with the following rate limits:

Response Format

Every API response follows a consistent envelope structure. A successful response contains a success boolean, a data payload, and a meta object with pagination and rate limit information:

Copy
1{
2  "success": true,
3  "data": { ... },
4  "meta": {
5    "requestId": "req_uuid",
6    "timestamp": "2026-01-01T00:00:00Z",
7    "apiVersion": "v1",
8    "page": 1,
9    "pageSize": 20,
10    "totalCount": 142,
11    "totalPages": 8,
12    "hasNext": true,
13    "hasPrev": false,
14    "rateLimit": {
15      "limit": 500,
16// ... (truncated)
Show More (6 more lines)
JSON

Error responses follow a similar pattern with an error string, a machine-readable code, a human-readable message, and a docs URL pointing to the relevant error documentation:

Copy
1{
2  "success": false,
3  "error": "Not found",
4  "code": "NOT_FOUND",
5  "message": "The requested resource was not found",
6  "requestId": "req_xxx",
7  "docs": "https://tenders-sa.org/developers/docs/errors#NOT_FOUND",
8  "timestamp": "2026-01-01T00:00:00Z"
9}
JSON

Available Endpoints

The API is organised into five resource groups. Here is every available endpoint with its purpose:

Tenders

Awards

Companies

Organisations (Procurement Bodies)

Meta

Pagination

All list endpoints are paginated with a page-based cursor system. You control pagination with page and pageSize query parameters. The response meta includes everything you need to navigate: page, pageSize, totalCount, totalPages, hasNext, and hasPrev.

Copy
1GET /v1/tenders?status=OPEN&page=2&pageSize=50
TEXT

Page size defaults to 20 items and can be set up to 100. All three official SDKs implement pagination iterators that handle page traversal automatically.

Rate Limiting

Rate limit status is returned in both HTTP response headers and the response body's meta.rateLimit object:

• Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Policy
• Body: meta.rateLimit.limit, meta.rateLimit.remaining, meta.rateLimit.reset, meta.rateLimit.policy

When a rate limit is exceeded, the API returns a 429 status with either RATE_LIMIT_DAILY_EXCEEDED or RATE_LIMIT_MONTHLY_EXCEEDED error code.

Error Codes

Sparse Fields

Reduce response payload size by specifying only the fields you need with the fields query parameter:

Copy
1GET /v1/tenders?fields=tenderId,title,status,closingDate,estimatedValue
TEXT

This is particularly useful for list endpoints where you may only need a subset of fields for display purposes — for example, populating a table or a dropdown selector without loading the full tender object.

Filtering Parameters

List endpoints support a common set of filter parameters. The exact set varies by resource, but the most widely supported are:

Getting Started

The quickest way to start exploring the API is through the official SDKs, which handle authentication, pagination, error handling, and retry logic:

• JavaScript / TypeScript SDK — github.com/Tenders-SA/js
  (@tenders-sa-org/sdk-js on npm)
• Python SDK — github.com/Tenders-SA/python
  (tendersa-sdk on PyPI)
• CLI — github.com/Tenders-SA/cli
  (@tenders-sa-org/cli on npm)

For direct API access, the full API reference is available at tenders-sa.org/developers/docs

. API keys can be generated at tenders-sa.org/developers/api-keys

.