API Documentation

Everything you need to integrate the SA Fake Data API

Getting Started

Get up and running in three simple steps.

Create Account

Create account →

Get API Key

Generate an API key from your dashboard. Keep it secret.

Go to dashboard →

Make Requests

Include your key in the request header and start generating data.

curl /api/v1/person \
  -H "x-api-key: safk_..."

Authentication

All API requests require authentication. Pass your API key using either of the two supported methods below.

x-api-key header

cURL

curl https://safakedata.dev/api/v1/person \
  -H "x-api-key: safk_your_key_here"

Authorization Bearer

cURL

curl https://safakedata.dev/api/v1/person \
  -H "Authorization: Bearer safk_your_key_here"

Endpoints

All endpoints return JSON and accept optional query parameters.

GET/api/v1/person

Try it

Generate person data including name, SA ID number, phone, email, and address.

GET/api/v1/id

Try it

Generate valid SA ID numbers with correct Luhn check digits.

GET/api/v1/address

Try it

Generate SA addresses across all 9 provinces.

GET/api/v1/company

Try it

Generate SA company data with registration and VAT numbers.

GET/api/v1/bank

Try it

Generate SA bank account details.

Query Parameters

These parameters are accepted by all endpoints.

Parameter	Type	Default	Status	Description
count	integer	1	optional	Number of records to generate (1–100)
seed	integer	random	optional	Pass any integer to get identical results every time. Same seed = same data.

How Seeds Work

The seed parameter makes your API responses deterministic. When you pass the same seed value, the API returns identical data every time — same names, same ID numbers, same addresses. This is useful for:

Testing — Write assertions against known data
Demos — Show the same realistic data every time
Debugging — Reproduce exact scenarios

Example: same seed = same output

# Run this twice — you'll get identical results
curl /api/v1/person?seed=42 -H "x-api-key: safk_..."
# → { "firstName": "Sipho", "lastName": "Dlamini", ... }

# Same seed, same data — every time
curl /api/v1/person?seed=42 -H "x-api-key: safk_..."
# → { "firstName": "Sipho", "lastName": "Dlamini", ... }

# Different seed = different data
curl /api/v1/person?seed=99 -H "x-api-key: safk_..."
# → { "firstName": "Lerato", "lastName": "Mokoena", ... }

Omit the seed parameter to get random data on every request.

Strict mode:Unknown or unsupported query parameters will return a 400 error. Only pass the parameters listed above.

Rate Limits

Rate limits are enforced on a monthly basis. Headers are included in every response.

Plan	Monthly Limit	Overage
Free	1,000 requests	429 until reset
Premium	10,000 requests	429 until reset

Response Headers

X-RateLimit-LimitYour monthly request allowance

X-RateLimit-RemainingRequests remaining in the current period

X-RateLimit-ResetUTC timestamp when the rate limit resets

Error Responses

Errors follow a consistent format across all endpoints. Every error response includes a structured body and a unique request ID for debugging.

Error format

{
  "error": {
    "type": "authentication_error",
    "code": 401,
    "message": "Invalid or missing API key."
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

Error Types

Type	Code	Description
authentication_error	401	Missing or invalid API key
invalid_request_error	400	Malformed request or unknown query parameters
rate_limit_error	429	Monthly request quota exceeded