Skip to content

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 facts or source. Send what they told you with a second request (step 3).
  • The job must be open for screening calls (leads need an active offering).
  • Bookings are interviews, and the final statuses are different (see below).
Your rules decide, never the AI
Whether someone qualifies is decided only by the rules you set on the job (experience, notice period, location and so on), applied the same way to everyone. The AI recruiter collects the answers; it doesn't score people, and it never asks about or guesses religion, caste, gender or similar.

1. Find your job

Request
curl "https://progz.in/api/v1/jobs?status=open" \
  -H "Authorization: Bearer $PROGZ_API_KEY"
Response 200 (shortened)
[
  {
    "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

Request
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."
  }'
FieldRequiredWhat it is
job_idYesThe job from step 1.
contact.full_nameYesTheir name, up to 200 characters.
contact.phoneYesTheir mobile. Indian numbers with or without +91; others with + and the country code.
contact.emailYes, todayInterview details are sent by email, so a new person needs one (else 422 email_required).
contact.preferred_languageNoThe language to call in, e.g. te-IN, hi-IN, en-IN.
contact.whatsapp_opt_inNoWhether they agreed to WhatsApp messages. Default false.
contact_idInstead of contactAn existing contact's id.
notesNoAnything 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:

Request
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
    }
  }'
FactTypeMeaning
experience_yearsnumber, 0–60Years of relevant experience; halves are fine (2.5).
skillslist of text, up to 50What they can do, in their words.
current_locationtextWhere they live or work now.
preferred_locationtextWhere they want to work.
current_ctcwhole rupees a yearWhat they earn now.
expected_ctcwhole rupees a yearWhat they want to earn.
notice_period_dayswhole days, 0–365How soon they can join (0 = immediately).
languageslist of text, up to 20Languages they speak.
availabilitytextWhen they can talk or interview, e.g. weekdays after 6 pm.
interestedtrue / falseAre 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

Request
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:

StatuscodeWhyWhat to do
409call_waitingThe 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.
409job_not_openThe job is a draft, paused or closed.Open the job in the app.
409do_not_contactThis person asked not to be contacted.Don't call them.
409already_in_progressA screening call is already queued or happening.Nothing.
409candidate_closedThey already have an interview, withdrew, or were closed.Nothing.

Candidate statuses

statusMeaningSet by
newAdded, no call asked for yet.Progz
contactingA screening call is queued, ringing or happening.Progz
screeningBeing screened.Progz
qualifiedMeets your rules. If no interview was booked on the call, your team gets a task.Your rules
not_qualifiedDoesn't meet your rules.Your rules
needs_reviewAnswers were missing or unclear; your team decides.Your rules
interview_scheduledAn interview is booked.Progz (only)
hiredThey got the job.Your team or your code
withdrawnThey said no on the call, or dropped out.Progz, your team or your code
closedFinished: 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:

Request
curl "https://progz.in/api/v1/appointments?upcoming=true&subject_id=c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f" \
  -H "Authorization: Bearer $PROGZ_API_KEY"
Response 200 (shortened)
{
  "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.

applicants.csv
name,phone,email,language
Sravani Reddy,91234 56789,sravani@example.com,te-IN
Imran Khan,+91 98480 12345,imran@example.com,hi-IN
Request
curl -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.csv

The 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.