HRIS Private API

This site contains the technical resources required to build internal integrations or automation using CATAPA's private endpoints.

This is not intended for public use

This section is designed for developers who need to interact with CATAPA features that is not exposed via the Public API. If you are an external developer looking to build a standard integration using the Public API, please refer to the Public API Section. Ignorance of this notice might lead to break in your integration as our private API contract might change without public notice.

Installation

pip

pip install catapa-private

poetry

uv

Quick Start

A complete Hello World example to get you started immediately.

from catapa_private import CatapaPrivate

def main() -> None:
    client = CatapaPrivate(
        tenant="zfrl",
        username="demo",
        password="dmo-password"
    )

    response = client.get("/core/countries", params={"page": 0, "size": 10})
    response.raise_for_status()
    data = response.json()
    print(f"Found {len(data.get('content', []))} countries")

if __name__ == "__main__":
    main()

💡 Tip: By default, the SDK connects to https://api.catapa.com. To use a different base URL (e.g., for staging or testing), pass the base_url parameter:

client = CatapaPrivate(
    ...,
    base_url="https://api-development.catapa.com"
)

Getting Your Credentials

To use the SDK with your own account, you'll need the following authentication credentials:

Tenant ID

Your tenant ID is your organization's unique identifier in CATAPA. To obtain it, please contact [e-mail].

Username and Password

Your username and password are your CATAPA account credentials used for session-based authentication.

Important: Keep your credentials secure and never commit them to version control. Consider using environment variables or a secrets management system.

Private API Documentation

Explore our interactive Swagger documentation to understand the available endpoints, request schemas, and response models for each module.

Core API

https://api.catapa.com/core/swagger/swagger-ui/index.html

Time Management

https://api.catapa.com/timemanagement/swagger/swagger-ui/index.html

Recruitment

https://api.catapa.com/recruitment/swagger/swagger-ui/index.html

Tutorials

More intermediate examples to help you learn the SDK.

Tutorial 1: Complete CRUD Operations

A complete example showing how to perform Create, Read, Update, and Delete operations.

import random
import string

from catapa_private import CatapaPrivate

def main() -> None:
    """Main function demonstrating CRUD operations."""
    client = CatapaPrivate(
        tenant="zfrl",
        username="demo",
        password="dmo-password"
    )

    # Step 1: GET - Retrieve list of countries
    response = client.get("/core/countries", params={"page": 0, "size": 10})
    response.raise_for_status()
    data = response.json()
    countries = data.get("content", [])
    print(f"Found {len(countries)} countries")

    # Step 2: POST - Create a new country
    random_suffix = "".join(random.choices(string.ascii_lowercase + string.digits, k=6))
    new_country = {
        "code": f"IDN{random_suffix[:3].upper()}",
        "callingCode": "+62",
        "name": f"Indonesia_{random_suffix}",
        "taxTreaty": True,
    }
    response = client.post("/core/countries", json=new_country)
    response.raise_for_status()
    created_country = response.json()
    country_id = created_country.get("id")
    print(f"Created country: {created_country.get('name')} (ID: {country_id})")

    # Step 3: GET - Retrieve the created country by ID
    response = client.get(f"/core/countries/{country_id}")
    response.raise_for_status()
    retrieved_country = response.json()
    print(f"Retrieved country: {retrieved_country.get('name')}")

    # Step 4: PUT - Update the country
    retrieved_country["name"] = f"Indonesia_{random_suffix}_updated"
    response = client.put(f"/core/countries/{country_id}", json=retrieved_country)
    response.raise_for_status()
    updated_country = response.json()
    print(f"Updated country: {updated_country.get('name')}")

    # Step 5: DELETE - Delete the country
    payload = [{"id": country_id}]
    response = client.delete("/core/countries", json=payload)
    response.raise_for_status()
    print(f"Deleted country (ID: {country_id})")

if __name__ == "__main__":
    main()

Tutorial 2: Error Handling and Response Management

A complete example showing how to handle errors and manage responses properly.

from catapa_private import CatapaPrivate
from requests.exceptions import HTTPError, RequestException

def main() -> None:
    """Main function demonstrating error handling."""
    client = CatapaPrivate(
        tenant="zfrl",
        username="demo",
        password="dmo-password"
    )

    try:
        response = client.get("/core/countries", params={"page": 0, "size": 10})
        response.raise_for_status()
        data = response.json()
        print(f"Success: Retrieved {len(data.get('content', []))} countries")
    except HTTPError as e:
        print(f"HTTP Error {e.response.status_code}: {e.response.text}")
    except RequestException as e:
        print(f"Request failed: {e}")

if __name__ == "__main__":
    main()

Cookbook

Intermediate to Advanced examples for real-world scenarios. In this scenario we try to making concurrent API calls efficiently using the SDK.

from catapa_private import CatapaPrivate
from concurrent.futures import ThreadPoolExecutor, as_completed

def main() -> None:
    """Main function for concurrent API calls example."""
    client = CatapaPrivate(
        tenant="zfrl",
        username="demo",
        password="dmo-password"
    )

    # Define API call functions
    def get_countries():
        response = client.get("/core/countries", params={"page": 0, "size": 10})
        response.raise_for_status()
        return response.json()

    def get_banks():
        response = client.get("/core/banks", params={"page": 0, "size": 10})
        response.raise_for_status()
        return response.json()

    def get_companies():
        response = client.get("/core/companies", params={"page": 0, "size": 10})
        response.raise_for_status()
        return response.json()

    # Execute API calls concurrently
    with ThreadPoolExecutor(max_workers=3) as executor:
        futures = {
            executor.submit(get_countries): "countries",
            executor.submit(get_banks): "banks",
            executor.submit(get_companies): "companies"
        }

        results = {}
        for future in as_completed(futures):
            task_name = futures[future]
            try:
                results[task_name] = future.result()
                print(f"✅ {task_name} retrieved successfully")
            except Exception as e:
                print(f"❌ {task_name} failed: {e}")

    # Use the results
    if "countries" in results:
        data = results["countries"]
        print(f"Countries: {len(data.get('content', []))}")
    if "banks" in results:
        data = results["banks"]
        print(f"Banks: {len(data.get('content', []))}")
    if "companies" in results:
        data = results["companies"]
        print(f"Companies: {len(data.get('content', []))}")

if __name__ == "__main__":
    main()

Requirements

• Python 3.11+