manatal

The easiest way to use the Manatal Open API from Python.

Manatal is an AI-powered ATS built for modern recruiting teams. Use this SDK to connect Manatal with your own tools — sync candidates and jobs, automate workflows, and integrate one of the best ATS platforms into your stack — with auth, pagination, and rate limiting handled for you.

Note: Community-maintained package. Not affiliated with or officially supported by Manatal.

Why use this package?

Whether you are extending an AI-powered ATS workflow or connecting Manatal to HRIS/payroll systems, calling the Open API raw means handling tokens, page loops, and 429 throttling yourself. manatal wraps that into a small, predictable client:

• One line to authenticate
• Simple resource methods (candidates, jobs, matches, …)
• Automatic pagination
• Built-in protection against rate limits
• Clear Python exceptions for common API errors

Installation

pip install manatal

Requires Python 3.9+.

How to get an Open API token

Open API access depends on your Manatal plan. Follow the official guide: Manatal Open API.

1. Enable Open API

1. Sign in to Manatal.
2. Go to Administration → Features → Open API, or open
   Open API settings.
3. If it is not enabled yet, click Contact our support to request access.

Open API is available by default on the Enterprise Plus plan. See the support article for details.

2. Generate a token

1. Open the same Open API settings page.
2. Click Generate new token.
3. Copy the token and store it securely (you will use it as api_key).

You can also copy or delete existing tokens from that page.

3. Use the token in Python

from manatal import Manatal

client = Manatal(api_key="YOUR_OPEN_API_TOKEN")

Or set an environment variable:

export MANATAL_API_KEY="YOUR_OPEN_API_TOKEN"

from manatal import Manatal

client = Manatal()  # reads MANATAL_API_KEY

Quick start

from manatal import Manatal

client = Manatal(api_key="YOUR_OPEN_API_TOKEN")

# Create a candidate
candidate = client.candidates.create(
    full_name="Jane Doe",
    email="jane@example.com",
)
print(candidate.id)

# List jobs (automatically walks every page)
for job in client.jobs.list():
    print(job.id, job.position_name)

# Fetch one record
job = client.jobs.retrieve(123)
print(job.id)

API responses support both styles:

job = client.jobs.create(organization=2208123, position_name="pyp")
print(job.id)          # recommended
print(job["id"])       # still works
print(job.position_name)

What you can access

Nested data works the same way:

client.candidates.notes(123).create(info="Called candidate")
client.candidates.experiences(123).list()
client.jobs.attachments(456).list()

Pagination

By default, .list() returns all results across pages (page_size=100).

Need a single page?

page = client.candidates.list_page(page=1, page_size=50)
print(page.count)       # total matching records
print(len(page.results))  # records on this page

Rate limiting & retries

Manatal allows about 100 requests per minute per API token.

This client is designed to be gentle on the API:

• Soft client-side limit (~90 requests/minute by default)
• Automatic retry on 429 using the Retry-After header
• Sensible timeouts and connection reuse
• Identifies itself with User-Agent: manatal-python/...

You can tune the soft limit if needed:

client = Manatal(api_key="...", rate_limit=60)  # slower scripts

Error handling

from manatal import (
    Manatal,
    AuthenticationError,
    NotFoundError,
    RateLimitError,
    ValidationError,
)

client = Manatal(api_key="...")

try:
    client.candidates.retrieve(999999)
except NotFoundError as exc:
    print("Missing record:", exc.status_code, exc.body)
except ValidationError as exc:
    print("Invalid payload:", exc.body)
except RateLimitError as exc:
    print("Still throttled after retries:", exc.retry_after)
except AuthenticationError:
    print("Check your API token")

Useful links

Contributing

Issues and pull requests are welcome:
https://github.com/TasfiqulGhani/manatal-python

License

MIT