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.

Before diving into the technical details, it's worth being clear about who this API is for and what problems it typically solves. Developers reach for the Tenders-SA API when they need procurement data inside a product or process that isn't the Tenders-SA website itself: an internal bid-tracking tool for a mid-sized construction firm, a research dashboard analysing award patterns across provinces, a plugin that surfaces relevant tenders inside an existing business tool, or an automated script that checks for new opportunities in a specific category every morning. In each case, the alternative to using the API is manually re-checking the website or, worse, re-scraping government portals directly — something the API's own enrichment pipeline has already done the hard work of normalising and structuring.

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:

Treat your API key with the same care you would a password. Because keys are tied to your subscription's rate limits and permissions, a leaked key in a public repository or client-side script could let someone else consume your daily or monthly quota. Store keys as environment variables in your deployment environment rather than hard-coding them into source files, and rotate a key immediately through the Developer Portal if you suspect it has been exposed.

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:

A Typical Integration Walkthrough

A common first project for developers new to the API is a simple internal alert: notify a sales or bid team whenever a new tender opens in a specific province and category combination that matches their business. Building this well means combining several of the pieces covered above rather than any single endpoint in isolation. You would start with /v1/tenders, filtered by province, category, and status=OPEN, using the sort parameter to order by publication or closing date. Because this kind of check typically runs on a schedule rather than in response to a user action, keeping the fields parameter narrow — just the identifiers, title, and closing date you need to decide whether to alert someone — reduces both the payload size and the load on your own rate limit. From there, a scheduled job comparing the current result set against the previous run's cached tender IDs is enough to detect what's genuinely new, without needing to re-process the full list every time.

For a more involved integration — say, enriching your own CRM with company intelligence — you would combine the /v1/companies/{name} endpoint with the /v1/awards endpoint filtered by supplier, giving you both the company's registration-level detail and its historical award record in a single workflow. Whatever you build, it pays to design your integration around the assumption that the underlying data will occasionally be incomplete or delayed for a specific record — procurement data sourced from dozens of government portals is not always perfectly consistent — so defensive handling of missing fields is worth the small amount of extra code it takes upfront.

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

.