CPFHub Getting Started: Account, Keys & First API Call (2026)

Getting started overview

Integrating with CPFHub involves a structured process designed to facilitate secure and compliant access to CPF-related services in Singapore. The initial steps include account registration, API key generation, and testing within a sandbox environment. This approach allows developers to validate their integration logic without affecting live data, aligning with best practices for API integration as outlined by organizations like the W3C's recommendations for web services.

CPFHub provides APIs for core functions such as CPF Contribution and CPF Statement Retrieval, which are essential for payroll and HR systems operating in Singapore. The platform is designed to comply with Singapore's Personal Data Protection Act (PDPA) and holds ISO 27001 certification, indicating a commitment to information security (CPFHub documentation on compliance). The developer experience is supported by comprehensive documentation, SDKs for Node.js, Python, and Java, and a responsive sandbox environment for iterative development.

The following table summarizes the key steps to get started with CPFHub:

Create an account and get keys

To begin using CPFHub, the first action is to create a developer account. This account provides access to the developer dashboard, where you can manage applications, generate API credentials, and monitor usage. The signup process is typically straightforward, requiring basic contact information and agreement to the terms of service (CPFHub account registration guide).

Once your account is active, navigate to the API Keys section within your developer dashboard. Here, you will generate your unique API credentials, which usually consist of a Client ID and a Client Secret. These keys are crucial for authenticating your requests to the CPFHub API. Treat your Client Secret as sensitive information, similar to a password, and store it securely. Best practices for API key management recommend avoiding hardcoding keys directly into your application code and instead using environment variables or a secure configuration management system. For instance, Google Cloud's API key security best practices offer general guidance on protecting API access.

CPFHub's sandbox environment is immediately accessible upon account creation, allowing you to test integrations without incurring costs or affecting live data. This environment is distinct from the production environment, and separate API keys may be required for each. Ensure you are using the correct set of keys for the environment you intend to interact with.

Your first request

After obtaining your API keys, the next step is to make your first authenticated request to the CPFHub API. This typically involves an OAuth 2.0 client credentials flow to obtain an access token, which is then used in subsequent API calls (OAuth 2.0 client credentials grant type overview). CPFHub provides SDKs for Node.js, Python, and Java, which abstract away much of the authentication complexity, making it easier to integrate.

Example: Obtaining an Access Token (Node.js)

Using the Node.js SDK, you would typically configure it with your Client ID and Client Secret, then call an authentication method:

const CPFHub = require('cpfhub-sdk');

const client = new CPFHub({
  clientId: process.env.CPF_HUB_CLIENT_ID,
  clientSecret: process.env.CPF_HUB_CLIENT_SECRET,
  environment: 'sandbox' // or 'production'
});

async function getAccessToken() {
  try {
    const tokenResponse = await client.auth.getAccessToken();
    console.log('Access Token:', tokenResponse.access_token);
    return tokenResponse.access_token;
  } catch (error) {
    console.error('Error getting access token:', error.message);
  }
}

getAccessToken();

Example: Making a CPF Contribution API Call (Python)

Once you have an access token, you can use it to interact with CPFHub's core APIs, such as the CPF Contribution API (CPF Contribution API reference). This example demonstrates a basic call using the Python SDK:

from cpfhub_sdk import CPFHubClient
import os

client = CPFHubClient(
    client_id=os.environ.get('CPF_HUB_CLIENT_ID'),
    client_secret=os.environ.get('CPF_HUB_CLIENT_SECRET'),
    environment='sandbox'
)

def submit_cpf_contribution():
    try:
        access_token = client.auth.get_access_token()
        print(f"Access Token: {access_token}")

        contribution_data = {
            "employer_uen": "S12345678A",
            "employee_nric": "S9999999Z",
            "contribution_month": "2026-04",
            "ordinary_wage": 2000.00,
            "additional_wage": 500.00
        }
        
        response = client.cpf_contribution.submit(contribution_data)
        print("Contribution Submission Response:", response)
        return response
    except Exception as e:
        print(f"Error submitting CPF contribution: {e}")

submit_cpf_contribution()

Remember to replace placeholder values like S12345678A and S9999999Z with valid sandbox test data for successful execution. The CPFHub documentation provides specific test data guidelines for the sandbox environment (CPFHub sandbox test data guidelines).

Common next steps

After successfully making your first API call in the sandbox, several common next steps will help you further your integration and prepare for production use:

• Explore Additional APIs: Familiarize yourself with other CPFHub APIs, such as the CPF Statement Retrieval API, to understand the full range of functionalities available for your application (CPFHub API reference documentation).
• Error Handling and Webhooks: Implement robust error handling mechanisms within your application. CPFHub's error messages are designed to be descriptive, aiding in debugging. Consider setting up webhooks for asynchronous notifications on important events, if supported, to build more resilient integrations.
• Security Best Practices: Review and implement security best practices for API integration, including secure storage of API keys, proper token management, and input validation to prevent common vulnerabilities. The IETF's RFC 6749 details OAuth 2.0 security considerations, which are relevant for token-based authentication.
• Performance Testing: Conduct performance testing in the sandbox environment to understand API response times and potential bottlenecks under expected load. This helps in optimizing your application's interaction with CPFHub.
• Upgrade to a Paid Plan: Once your integration is stable and tested in the sandbox, choose a suitable paid plan from CPFHub's offerings to transition to the production environment (CPFHub pricing page). CPFHub offers various tiers, starting with the Basic Plan at SGD 99/month, scaling with transaction volume.
• Production Environment Configuration: Configure your application to use the production API endpoints and production API keys. Ensure all sensitive data handling complies with PDPA and other relevant regulations.
• Monitoring and Logging: Set up comprehensive monitoring and logging for your API calls to CPFHub. This allows you to track usage, identify issues proactively, and ensure the smooth operation of your integrated services.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some typical problems and troubleshooting steps:

• Invalid API Keys: Double-check that you are using the correct Client ID and Client Secret for the target environment (sandbox vs. production). API keys are case-sensitive.
• Authentication Errors (401 Unauthorized): This often indicates an issue with the access token. Ensure your access token is valid, not expired, and included correctly in the Authorization: Bearer <token> header. Re-authenticate to obtain a new token if necessary.
• Bad Request (400): This error usually means there's an issue with your request payload. Verify that your JSON or request body matches the API's expected schema, including required fields and correct data types. Consult the CPFHub API reference for specific endpoint requirements.
• Forbidden (403): A 403 error might indicate that your API keys do not have the necessary permissions to access the requested resource or perform the action. Check your account settings or contact CPFHub support if you suspect a permissions issue.
• Rate Limiting (429 Too Many Requests): In the sandbox, you might encounter rate limits. If this happens, reduce the frequency of your requests or implement a backoff strategy. Information on rate limits is typically found in the API documentation.
• Network Issues: Confirm that your development environment has stable internet connectivity and that no firewall rules are blocking outgoing requests to CPFHub API endpoints.
• SDK Configuration Problems: If you are using an SDK, ensure it is correctly initialized with your credentials and configured for the correct environment (sandbox or production). Refer to the specific CPFHub SDK documentation for setup instructions.
• Consult Documentation and Support: The CPFHub documentation is the primary resource for detailed error codes and troubleshooting guides. If you cannot resolve an issue, contact CPFHub's developer support for assistance.