Metadata-Version: 2.5
Name: manatal
Version: 0.1.0
Summary: Unofficial Python client for the Manatal Open API v3
Project-URL: Homepage, https://github.com/TasfiqulGhani/manatal-python
Project-URL: Documentation, https://developers.manatal.com/reference/getting-started
Project-URL: Issues, https://github.com/TasfiqulGhani/manatal-python/issues
Author: Tasfiqul Ghani
License-Expression: MIT
License-File: LICENSE
Keywords: api,ats,manatal,recruiting,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# manatal

Unofficial Python client for the [Manatal Open API v3](https://developers.manatal.com/reference/getting-started).

> **Disclaimer:** This is a personal, community package — not an official Manatal product.

## Install

```bash
pip install manatal
```

## Quick start

```python
from manatal import Manatal

client = Manatal(api_key="YOUR_OPEN_API_TOKEN")
# or: export MANATAL_API_KEY=...

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

for job in client.jobs.list():
    print(job["id"], job.get("position_name"))
```

Get an API token from the Manatal app (API users) or via [support](mailto:support@manatal.com).

## Features

- `Authorization: Token …` auth against `https://api.manatal.com/open/v3`
- Proactive client rate limit (default **90 req/min**, under the API’s 100/min)
- Automatic **429** retries using `Retry-After`
- Pagination helpers (`list()` walks all pages; default `page_size=100`)
- Typed exceptions for 400 / 401 / 403 / 404 / 429
- Resources: candidates, jobs, organizations, matches, contacts, users, lookups, plus nested notes/attachments/activities/etc.

## Resources

```python
client.candidates.list(email="jane@example.com")
client.candidates.retrieve(123)
client.candidates.update(123, phone_number="+10000000000")
client.candidates.notes(123).create(info="Called candidate")
client.jobs.create(organization=1, position_name="Engineer")
client.matches.create(candidate=123, job=456)
client.organizations.list()
client.contacts.list()
client.users.list()
client.currencies.list()
client.match_stages.list()
client.skills.list()
```

Single page:

```python
page = client.candidates.list_page(page=1, page_size=50)
print(page.count, len(page.results))
```

## Errors

```python
from manatal import Manatal, RateLimitError, NotFoundError

try:
    client.candidates.retrieve(999999)
except NotFoundError as exc:
    print(exc.status_code, exc.body)
```

## Backend-friendly defaults

Manatal Open API throttles at **100 requests/minute** per token. This client:

1. Soft-limits locally to ~90/min
2. On 429, sleeps for `Retry-After` and retries
3. Uses `page_size=100` by default to reduce round-trips
4. Sends `User-Agent: manatal-python/x.y.z`

## License

MIT
# manatal-python
