---

name: manatal-api description: Interact with Manatal recruitment API for candidates, jobs, matches, contacts, and organizations. Use when working with recruiting data, applicant tracking, or HR automation.

Manatal API Reference

Authentication

Set your API key as an environment variable:

export MANATAL_API_KEY="your-api-key-here"

All requests require authentication via header:

• Preferred: Authorization: Token $MANATAL_API_KEY
• Alternative: x-api-key: $MANATAL_API_KEY

Base URL: https://api.manatal.com/open/v3/

Quick Reference

| Resource | List | Create | Get | Update | Delete | |----------|------|--------|-----|--------|--------| | Candidates | GET /candidates/ | POST /candidates/ | GET /candidates/{id}/ | PATCH /candidates/{id}/ | DELETE /candidates/{id}/ | | Jobs | GET /jobs/ | POST /jobs/ | GET /jobs/{id}/ | PATCH /jobs/{id}/ | DELETE /jobs/{id}/ | | Matches | GET /matches/ | POST /matches/ | GET /matches/{id}/ | PATCH /matches/{id}/ | DELETE /matches/{id}/ | | Contacts | GET /contacts/ | POST /contacts/ | GET /contacts/{id}/ | PATCH /contacts/{id}/ | DELETE /contacts/{id}/ | | Organizations | GET /organizations/ | POST /organizations/ | GET /organizations/{id}/ | PATCH /organizations/{id}/ | DELETE /organizations/{id}/ |

Common Query Parameters

• Pagination: ?limit=20&offset=0
• Ordering: ?ordering=created_at or ?ordering=-created_at (descending)
• Search: ?search=keyword
• Filtering: Resource-specific, e.g., ?status=active

---

Candidates

List Candidates

curl -X GET "https://api.manatal.com/open/v3/candidates/?limit=20&offset=0" \
  -H "Authorization: Token $MANATAL_API_KEY"

Create Candidate

curl -X POST "https://api.manatal.com/open/v3/candidates/" \
  -H "Authorization: Token $MANATAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "+1234567890",
    "position_applied": "Software Engineer"
  }'

Get Candidate

curl -X GET "https://api.manatal.com/open/v3/candidates/{id}/" \
  -H "Authorization: Token $MANATAL_API_KEY"

Update Candidate

curl -X PATCH "https://api.manatal.com/open/v3/candidates/{id}/" \
  -H "Authorization: Token $MANATAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Jane"}'

Delete Candidate

curl -X DELETE "https://api.manatal.com/open/v3/candidates/{id}/" \
  -H "Authorization: Token $MANATAL_API_KEY"

Candidate Sub-resources

| Sub-resource | Endpoint | |--------------|----------| | Activities | GET/POST /candidates/{id}/activities/ | | Educations | GET/POST /candidates/{id}/educations/ | | Experiences | GET/POST /candidates/{id}/experiences/ | | Attachments | GET/POST /candidates/{id}/attachments/ | | Notes | GET/POST /candidates/{id}/notes/ | | Matches | GET /candidates/{id}/matches/ |

Add Candidate Education

curl -X POST "https://api.manatal.com/open/v3/candidates/{id}/educations/" \
  -H "Authorization: Token $MANATAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "school": "MIT",
    "degree": "Bachelor",
    "field_of_study": "Computer Science",
    "start_date": "2015-09-01",
    "end_date": "2019-06-01"
  }'

Add Candidate Experience

curl -X POST "https://api.manatal.com/open/v3/candidates/{id}/experiences/" \
  -H "Authorization: Token $MANATAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Tech Corp",
    "position_title": "Software Developer",
    "start_date": "2019-07-01",
    "is_current": true
  }'

Upload Candidate Attachment (Resume)

curl -X POST "https://api.manatal.com/open/v3/candidates/{id}/attachments/" \
  -H "Authorization: Token $MANATAL_API_KEY" \
  -F "file=@/path/to/resume.pdf" \
  -F "attachment_type=resume"

---

Jobs

List Jobs

curl -X GET "https://api.manatal.com/open/v3/jobs/?limit=20&offset=0" \
  -H "Authorization: Token $MANATAL_API_KEY"

Create Job

curl -X POST "https://api.manatal.com/open/v3/jobs/" \
  -H "Authorization: Token $MANATAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "position_name": "Senior Software Engineer",
    "department": "Engineering",
    "status": "open",
    "job_type": "full_time",
    "description": "We are looking for...",
    "requirements": "5+ years experience..."
  }'

Get Job

curl -X GET "https://api.manatal.com/open/v3/jobs/{id}/" \
  -H "Authorization: Token $MANATAL_API_KEY"

Update Job

curl -X PATCH "https://api.manatal.com/open/v3/jobs/{id}/" \
  -H "Authorization: Token $MANATAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "closed"}'

Delete Job

curl -X DELETE "https://api.manatal.com/open/v3/jobs/{id}/" \
  -H "Authorization: Token $MANATAL_API_KEY"

Job Sub-resources

| Sub-resource | Endpoint | |--------------|----------| | Activities | GET/POST /jobs/{id}/activities/ | | Attachments | GET/POST /jobs/{id}/attachments/ | | Matches | GET /jobs/{id}/matches/ | | Notes | GET/POST /jobs/{id}/notes/ |

---

Matches

Matches connect candidates to jobs through the recruitment pipeline.

List Matches

curl -X GET "https://api.manatal.com/open/v3/matches/?limit=20" \
  -H "Authorization: Token $MANATAL_API_KEY"

Filter by job or candidate:

curl -X GET "https://api.manatal.com/open/v3/matches/?job={job_id}" \
  -H "Authorization: Token $MANATAL_API_KEY"

curl -X GET "https://api.manatal.com/open/v3/matches/?candidate={candidate_id}" \
  -H "Authorization: Token $MANATAL_API_KEY"

Create Match

curl -X POST "https://api.manatal.com/open/v3/matches/" \
  -H "Authorization: Token $MANATAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "candidate": {candidate_id},
    "job": {job_id},
    "stage": {stage_id}
  }'

Update Match Stage

curl -X PATCH "https://api.manatal.com/open/v3/matches/{id}/" \
  -H "Authorization: Token $MANATAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stage": {new_stage_id}}'

Match Sub-resources

| Sub-resource | Endpoint | |--------------|----------| | Activities | GET/POST /matches/{id}/activities/ | | Attachments | GET/POST /matches/{id}/attachments/ | | Notes | GET/POST /matches/{id}/notes/ |

---

Contacts

Contacts are people at client organizations (hiring managers, etc.).

List Contacts

curl -X GET "https://api.manatal.com/open/v3/contacts/?limit=20" \
  -H "Authorization: Token $MANATAL_API_KEY"

Create Contact

curl -X POST "https://api.manatal.com/open/v3/contacts/" \
  -H "Authorization: Token $MANATAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Sarah",
    "last_name": "Smith",
    "email": "sarah.smith@company.com",
    "organization": {organization_id},
    "position_title": "HR Manager"
  }'

Get/Update/Delete Contact

# Get
curl -X GET "https://api.manatal.com/open/v3/contacts/{id}/" \
  -H "Authorization: Token $MANATAL_API_KEY"

# Update
curl -X PATCH "https://api.manatal.com/open/v3/contacts/{id}/" \
  -H "Authorization: Token $MANATAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"position_title": "Senior HR Manager"}'

# Delete
curl -X DELETE "https://api.manatal.com/open/v3/contacts/{id}/" \
  -H "Authorization: Token $MANATAL_API_KEY"

---

Organizations

Client companies/organizations.

List Organizations

curl -X GET "https://api.manatal.com/open/v3/organizations/?limit=20" \
  -H "Authorization: Token $MANATAL_API_KEY"

Create Organization

curl -X POST "https://api.manatal.com/open/v3/organizations/" \
  -H "Authorization: Token $MANATAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "industry": "Technology",
    "website": "https://acme.com",
    "description": "Leading tech company"
  }'

Get/Update/Delete Organization

# Get
curl -X GET "https://api.manatal.com/open/v3/organizations/{id}/" \
  -H "Authorization: Token $MANATAL_API_KEY"

# Update
curl -X PATCH "https://api.manatal.com/open/v3/organizations/{id}/" \
  -H "Authorization: Token $MANATAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"industry": "Software"}'

# Delete
curl -X DELETE "https://api.manatal.com/open/v3/organizations/{id}/" \
  -H "Authorization: Token $MANATAL_API_KEY"

---

Reference Data

Read-only endpoints for system reference data.

Match Stages (Pipeline Stages)

curl -X GET "https://api.manatal.com/open/v3/match-stages/" \
  -H "Authorization: Token $MANATAL_API_KEY"

Job Pipelines

curl -X GET "https://api.manatal.com/open/v3/job-pipelines/" \
  -H "Authorization: Token $MANATAL_API_KEY"

Users

curl -X GET "https://api.manatal.com/open/v3/users/" \
  -H "Authorization: Token $MANATAL_API_KEY"

Other Reference Endpoints

• GET /currencies/ - Available currencies
• GET /languages/ - Language codes
• GET /nationalities/ - Nationality codes
• GET /industries/ - Industry categories
• GET /countries/ - Country codes

---

Career Page (Public)

Public endpoints for career page integrations.

List Public Jobs

curl -X GET "https://api.manatal.com/open/v3/career-page/{career_page_id}/jobs/"

Get Application Form Schema

curl -X GET "https://api.manatal.com/open/v3/career-page/{career_page_id}/jobs/{job_id}/application-form/"

Submit Application

curl -X POST "https://api.manatal.com/open/v3/career-page/{career_page_id}/jobs/{job_id}/apply/" \
  -H "Content-Type: multipart/form-data" \
  -F "first_name=John" \
  -F "last_name=Doe" \
  -F "email=john@example.com" \
  -F "resume=@/path/to/resume.pdf"

Submit Referral

curl -X POST "https://api.manatal.com/open/v3/career-page/{career_page_id}/jobs/{job_id}/refer/" \
  -H "Content-Type: application/json" \
  -d '{
    "referrer_name": "Jane Smith",
    "referrer_email": "jane@example.com",
    "candidate_first_name": "John",
    "candidate_last_name": "Doe",
    "candidate_email": "john@example.com"
  }'

---

Webhooks

Subscribe to events for real-time notifications.

List Webhooks

curl -X GET "https://api.manatal.com/open/v3/webhooks/" \
  -H "Authorization: Token $MANATAL_API_KEY"

Create Webhook

curl -X POST "https://api.manatal.com/open/v3/webhooks/" \
  -H "Authorization: Token $MANATAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["candidate.created", "candidate.updated", "match.stage_changed"],
    "is_active": true
  }'

Available Events

• candidate.created, candidate.updated, candidate.deleted
• job.created, job.updated, job.deleted
• match.created, match.updated, match.deleted, match.stage_changed
• contact.created, contact.updated, contact.deleted
• organization.created, organization.updated, organization.deleted

Update/Delete Webhook

# Update
curl -X PATCH "https://api.manatal.com/open/v3/webhooks/{id}/" \
  -H "Authorization: Token $MANATAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

# Delete
curl -X DELETE "https://api.manatal.com/open/v3/webhooks/{id}/" \
  -H "Authorization: Token $MANATAL_API_KEY"

---

Error Handling

Common HTTP Status Codes

• 200 - Success
• 201 - Created
• 204 - No Content (successful delete)
• 400 - Bad Request (invalid data)
• 401 - Unauthorized (invalid/missing API key)
• 403 - Forbidden (insufficient permissions)
• 404 - Not Found
• 429 - Rate Limited
• 500 - Server Error

Error Response Format

{
  "detail": "Error message here",
  "errors": {
    "field_name": ["Specific field error"]
  }
}

Rate Limiting

If you receive a 429 response, wait and retry with exponential backoff:

# Check rate limit headers in response
# X-RateLimit-Limit: requests allowed per window
# X-RateLimit-Remaining: requests remaining
# X-RateLimit-Reset: Unix timestamp when limit resets

---

Tips

1. Bash variable timing: When using $MANATAL_API_KEY, export it in a separate command first, or use the key directly. Running export VAR=x && curl $VAR won't work because bash expands variables before executing export.
2. Always paginate large lists to avoid timeouts
3. Use filters to narrow results before fetching
4. Store IDs returned from create operations for future reference
5. Check stage IDs via /match-stages/ before moving candidates through pipeline
6. Validate webhooks by checking the signature header on incoming requests