Everything you need to integrate the SA Fake Data API
Get up and running in four simple steps.
Confirm your email so your account becomes eligible to use the API.
Sign in after verifying →Include your key in the request header. Free accounts get 500 requests/month.
curl /api/v1/person \ -H "x-api-key: safk_..."
All API requests require authentication. Pass your API key using either of the two supported methods below.
curl https://safakedata.dev/api/v1/person \ -H "x-api-key: safk_your_key_here"
curl https://safakedata.dev/api/v1/person \ -H "Authorization: Bearer safk_your_key_here"
All endpoints return JSON and accept optional query parameters. Each example shows a response with seed=42.
/api/v1/personGenerate 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
}
}/api/v1/idGenerate 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
}
}/api/v1/addressGenerate 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
}
}/api/v1/companyGenerate 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
}
}/api/v1/bankGenerate 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
}
}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. |
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:
# 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 are enforced on a monthly basis. Headers are included in every response.
| Allowance | Monthly Limit | Overage |
|---|---|---|
| Free forever | 500 requests | 429 until calendar-month reset |
X-RateLimit-LimitYour monthly request allowanceX-RateLimit-RemainingRequests remaining in the current periodX-RateLimit-ResetUTC timestamp when the rate limit resetsErrors follow a consistent format across all endpoints. Every error response includes a structured body and a unique request ID for debugging.
| 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 |
{
"error": {
"type": "authentication_error",
"code": "INVALID_API_KEY",
"message": "API key is invalid"
},
"meta": {
"request_id": "req_abc123-def4-5678-9abc-def012345678"
}
}{
"error": {
"type": "invalid_request_error",
"code": "INVALID_PARAMETER",
"message": "count must be between 1 and 100",
"param": "count"
}
}{
"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.