Getting Started

This guide will help you get started with the SimplyCPF API.

Prerequisites

No authentication is required. All endpoints are publicly accessible.

Making Your First Request

Using curl

curl https://simplycpf.com/api/cpf/age-groups

Using JavaScript/TypeScript

const response = await fetch(
  "https://simplycpf.com/api/cpf/calculate",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ income: 5000, age: 30 }),
  }
);

const data = await response.json();
console.log(data);

Using Python

import requests

response = requests.post(
    "https://simplycpf.com/api/cpf/calculate",
    json={"income": 5000, "age": 30}
)

data = response.json()
print(data)

Response Format

All successful responses return JSON with the following structure:

{
  "contribution": {
    "employee": 1000,
    "employer": 850,
    "totalContribution": 1850
  },
  "distribution": {
    "OA": 1085.5,
    "SA": 277.5,
    "MA": 487
  },
  "afterCpfContribution": 4000
}

Error Handling

When an error occurs, the API returns an appropriate HTTP status code with an error message:

{
  "error": "Income must be a non-negative number"
}

Common Status Codes

Status	Description
200	Success
400	Bad Request - Invalid parameters
429	Too Many Requests - Rate limit exceeded
404	Not Found - Endpoint does not exist
500	Internal Server Error

Rate Limits

Production CPF API endpoints are limited to 10 requests per 10 seconds per client IP. If you exceed the limit, the API returns HTTP 429:

{
  "error": "Rate limit exceeded"
}

Back off and retry after the current 10-second window before sending more requests.

Next Steps

Explore the API Reference for detailed endpoint documentation
Check out Examples for common use cases
View the Changelog for recent updates

Getting Started

On this page