Hiring
Send applicants from your careers page, job board or ATS to your AI recruiter. It calls them, asks your screening questions, checks the answers against your rules, and books interviews with the ones who fit.
How it differs from leads
Hiring works like sending in leads, with a job instead of an offering and a candidate instead of a lead. Three differences matter:
- A new candidate takes no
factsorsource. Send what they told you with a second request (step 3). - The job must be
openfor screening calls (leads need anactiveoffering). - Bookings are interviews, and the final statuses are different (see below).
1. Find your job
curl "https://progz.in/api/v1/jobs?status=open" \
-H "Authorization: Bearer $PROGZ_API_KEY"[
{
"id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
"title": "Customer Support Executive",
"company_name": "Sri Lakshmi Motors",
"location": "Hyderabad",
"employment_type": "full_time",
"openings": 3,
"status": "open",
"employee_id": "65da53ba-cbf3-48f0-ae83-b5c17fb445fc",
…
}
]Or copy the id from the app's address bar on the job's page. A job is draft, open, paused or closed; candidates can be added to any job that isn't closed (else 409 job_closed).
2. Add the candidate
curl -X POST "https://progz.in/api/v1/candidates" \
-H "Authorization: Bearer $PROGZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"job_id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
"contact": {
"full_name": "Sravani Reddy",
"phone": "91234 56789",
"email": "sravani@example.com",
"preferred_language": "te-IN"
},
"notes": "Applied on our careers page."
}'| Field | Required | What it is |
|---|---|---|
job_id | Yes | The job from step 1. |
contact.full_name | Yes | Their name, up to 200 characters. |
contact.phone | Yes | Their mobile. Indian numbers with or without +91; others with + and the country code. |
contact.email | Yes, today | Interview details are sent by email, so a new person needs one (else 422 email_required). |
contact.preferred_language | No | The language to call in, e.g. te-IN, hi-IN, en-IN. |
contact.whatsapp_opt_in | No | Whether they agreed to WhatsApp messages. Default false. |
contact_id | Instead of contact | An existing contact's id. |
notes | No | Anything for your hiring team, up to 5,000 characters. |
The answer (201) is the candidate with status new. As with leads, people are matched by phone number, and the same person twice for the same job gets 409 already_candidate: treat that as success.
3. Send what you already know (optional)
If the application form already asked, save the answers so the AI recruiter doesn't ask again. Only these names are accepted; any other rejects the request with 422:
curl -X PATCH "https://progz.in/api/v1/candidates/c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f" \
-H "Authorization: Bearer $PROGZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"facts": {
"experience_years": 2.5,
"skills": ["customer support", "CRM", "Telugu"],
"current_location": "Kukatpally",
"notice_period_days": 30
}
}'| Fact | Type | Meaning |
|---|---|---|
experience_years | number, 0–60 | Years of relevant experience; halves are fine (2.5). |
skills | list of text, up to 50 | What they can do, in their words. |
current_location | text | Where they live or work now. |
preferred_location | text | Where they want to work. |
current_ctc | whole rupees a year | What they earn now. |
expected_ctc | whole rupees a year | What they want to earn. |
notice_period_days | whole days, 0–365 | How soon they can join (0 = immediately). |
languages | list of text, up to 20 | Languages they speak. |
availability | text | When they can talk or interview, e.g. weekdays after 6 pm. |
interested | true / false | Are they interested in the role? |
Facts you send are added to the ones already saved; ones you leave out stay as they are.
4. Ask for the screening call
curl -X POST "https://progz.in/api/v1/candidates/c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f/request-screening" \
-H "Authorization: Bearer $PROGZ_API_KEY"The answer is the candidate again (200). The call goes out within your calling hours. These answers mean no call was started:
| Status | code | Why | What to do |
|---|---|---|---|
| 409 | call_waiting | The recruiter isn't working yet, the process is off, or the wallet is empty. | Nothing: it is kept and calls by itself once that is fixed. |
| 409 | job_not_open | The job is a draft, paused or closed. | Open the job in the app. |
| 409 | do_not_contact | This person asked not to be contacted. | Don't call them. |
| 409 | already_in_progress | A screening call is already queued or happening. | Nothing. |
| 409 | candidate_closed | They already have an interview, withdrew, or were closed. | Nothing. |
Candidate statuses
| status | Meaning | Set by |
|---|---|---|
new | Added, no call asked for yet. | Progz |
contacting | A screening call is queued, ringing or happening. | Progz |
screening | Being screened. | Progz |
qualified | Meets your rules. If no interview was booked on the call, your team gets a task. | Your rules |
not_qualified | Doesn't meet your rules. | Your rules |
needs_review | Answers were missing or unclear; your team decides. | Your rules |
interview_scheduled | An interview is booked. | Progz (only) |
hired | They got the job. | Your team or your code |
withdrawn | They said no on the call, or dropped out. | Progz, your team or your code |
closed | Finished: your team closed it after a review (for example, never reached). | Progz, your team or your code |
interest records what they said about the role: interested, not_interested or call_back_later.
The final statuses are interview_scheduled, hired, not_qualified, withdrawn and closed. Once a candidate reaches one, you can stop checking them (an interview can still be cancelled; see below).
GET /candidates/{id}/screenings lists every rules check, newest first: the result, the facts it used and which rule passed or failed. Set hired, withdrawn or closed yourself with PATCH /candidates/{id} and {"status": "withdrawn"}; interview_scheduled is only ever set by a booking.
Interviews
Interviews are appointments with kind interview and subject_id set to the candidate. List a candidate's, or leave out subject_id for all upcoming interviews:
curl "https://progz.in/api/v1/appointments?upcoming=true&subject_id=c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f" \
-H "Authorization: Bearer $PROGZ_API_KEY"{
"items": [
{
"id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a80",
"kind": "interview",
"label": "Interview",
"title": "Interview: Sravani Reddy — Customer Support Executive",
"status": "scheduled",
"start_at": "2026-10-27T05:30:00Z",
"end_at": "2026-10-27T06:00:00Z",
"timezone": "Asia/Kolkata",
"subject_type": "candidate",
"subject_id": "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f",
…
}
],
"total": 1,
"limit": 50,
"offset": 0
}If an interview is cancelled (POST /appointments/{id}/cancel, or in the app), the candidate goes back to qualified so they can be booked again. Keeping your ATS in step works the same way as for leads; see Keeping your system up to date.
Many applicants at once (CSV)
Headers are matched loosely: name or full_name, phone or mobile, email, language. Name and phone are required.
name,phone,email,language
Sravani Reddy,91234 56789,sravani@example.com,te-IN
Imran Khan,+91 98480 12345,imran@example.com,hi-INcurl -X POST "https://progz.in/api/v1/jobs/b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e/candidates/import?call=true" \
-H "Authorization: Bearer $PROGZ_API_KEY" \
-H "Content-Type: text/csv" \
--data-binary @applicants.csvThe answer counts created, reused_contacts, skipped_existing and calling, and lists any rows with problems in errors. Up to 5,000 rows and 2 MB, UTF-8. With ?call=true the job must be open and its AI recruiter must have finished setup (else 409 job_not_open or 409 no_working_employee).
Numbers for reports
GET /candidates/results?days=30 gives the period's hiring funnel, counted in the business's time zone: candidates who came in (enquiries), called, reached, met your rules (interested), booked, not_qualified, needs_review, withdrawn and in_progress, plus a breakdown by job in by_job. days is 1 to 365.