API Documentation

Everything you need to integrate the SA Fake Data API

Getting Started

Get up and running in four simple steps.

1

Create Account

Sign up for a free account to get access to the API.

Create account →
2

Verify Email

Confirm your email so your account becomes eligible to use the API.

Sign in after verifying →
3

Get API Key

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

Go to API keys →
4

Make Requests

Include your key in the request header. Free accounts get 500 requests/month.

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. Each example shows a response with seed=42.

GET/api/v1/person

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

Request

curl https://safakedata.dev/api/v1/person?seed=42 \
  -H "x-api-key: safk_..."

Response

200
{
  "data": [
    {
      "firstName": "Sipho",
      "lastName": "Dlamini",
      "fullName": "Sipho Dlamini",
      "email": "sipho.dlamini@gmail.com",
      "phone": "071 482 9371",
      "gender": "male",
      "dateOfBirth": "1992-03-14",
      "idNumber": "9203145081082",
      "address": {
        "streetNumber": 42,
        "streetName": "Mandela Drive",
        "suburb": "Braamfontein",
        "city": "Johannesburg",
        "province": "Gauteng",
        "postalCode": "2001"
      }
    }
  ],
  "meta": {
    "count": 1,
    "endpoint": "/api/v1/person",
    "seed": 42
  }
}
GET/api/v1/id

Generate valid SA ID numbers with correct Luhn check digits.

Request

curl https://safakedata.dev/api/v1/id?seed=42 \
  -H "x-api-key: safk_..."

Response

200
{
  "data": [
    {
      "idNumber": "9203145081082",
      "dateOfBirth": "1992-03-14",
      "gender": "male",
      "citizenship": "citizen"
    }
  ],
  "meta": {
    "count": 1,
    "endpoint": "/api/v1/id",
    "seed": 42
  }
}
GET/api/v1/address

Generate SA addresses across all 9 provinces.

Request

curl https://safakedata.dev/api/v1/address?seed=42 \
  -H "x-api-key: safk_..."

Response

200
{
  "data": [
    {
      "streetNumber": 15,
      "streetName": "Protea Road",
      "suburb": "Claremont",
      "city": "Cape Town",
      "province": "Western Cape",
      "postalCode": "7708"
    }
  ],
  "meta": {
    "count": 1,
    "endpoint": "/api/v1/address",
    "seed": 42
  }
}
GET/api/v1/company

Generate SA company data with registration and VAT numbers.

Request

curl https://safakedata.dev/api/v1/company?seed=42 \
  -H "x-api-key: safk_..."

Response

200
{
  "data": [
    {
      "name": "Ndalo Technologies (Pty) Ltd",
      "registrationNumber": "2019/284751/07",
      "vatNumber": "4012847519",
      "industry": "Information Technology",
      "type": "Private Company"
    }
  ],
  "meta": {
    "count": 1,
    "endpoint": "/api/v1/company",
    "seed": 42
  }
}
GET/api/v1/bank

Generate SA bank account details for major banks.

Request

curl https://safakedata.dev/api/v1/bank?seed=42 \
  -H "x-api-key: safk_..."

Response

200
{
  "data": [
    {
      "bankName": "First National Bank",
      "accountNumber": "62847195023",
      "branchCode": "250655",
      "accountType": "Cheque Account"
    }
  ],
  "meta": {
    "count": 1,
    "endpoint": "/api/v1/bank",
    "seed": 42
  }
}

Query Parameters

These parameters are accepted by all endpoints.

ParameterTypeDefaultStatusDescription
countinteger1optionalNumber of records to generate (1–100)
seedintegerrandomoptionalPass 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.

AllowanceMonthly LimitOverage
Free forever500 requests429 until calendar-month 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 Types

TypeCodeDescription
authentication_error401Missing or invalid API key
invalid_request_error400Malformed request or unknown query parameters
rate_limit_error429Monthly request quota exceeded
401Authentication ErrorMissing or invalid API key
Response
{
  "error": {
    "type": "authentication_error",
    "code": "INVALID_API_KEY",
    "message": "API key is invalid"
  },
  "meta": {
    "request_id": "req_abc123-def4-5678-9abc-def012345678"
  }
}
400Invalid RequestBad parameters or unknown query keys
Response
{
  "error": {
    "type": "invalid_request_error",
    "code": "INVALID_PARAMETER",
    "message": "count must be between 1 and 100",
    "param": "count"
  }
}
429Rate Limit ExceededMonthly quota used up
Response
{
  "error": {
    "type": "rate_limit_error",
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Monthly request limit reached"
  },
  "meta": {
    "request_id": "req_abc123-def4-5678-9abc-def012345678"
  }
}

Tip:Check the Retry-After and X-RateLimit-Reset headers to know when you can resume making requests.