API reference
Hiring
Jobs made from open positions: the post drafted from the position with its pay range and a wording check, opening, pausing and closing; hiring plans (steps) and settings. Hiring is off until a company switches it on.
95 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
List jobs#
POST/v1/hiring/jobs.listRead
Lists jobs made from open positions: title, status (draft, open, paused, closed), team, location, workplace, contract, pay range, language, the post, steps, hiring manager, readiness to open. status: live (default: draft, open and paused), one status, or all; position_id: the job of one position. Open first, then paused, draft and closed; newest change first within each. Owners, admins and HR see every job; a hiring manager only the jobs they manage; anyone else is refused. Over an API key or MCP the pay range of a job never opened is hidden (salary_hidden). At most limit (default 100, at most 500); total counts them all.
- Who can call it
- Manage key any Manage role
Me key anyone - Keys and apps
- The pay range of a job never opened is hidden (salary_hidden).
- MCP tool
hiring_jobs_liston HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
status"live" | "draft" | "open" | "paused" | "closed" | "all"Default
"live".position_idstring1–100 characters.
limitintegerFrom 1 to 500. Default
100.
Returns
jobsobject[]required41 fields
idstringrequiredposition_idstringrequiredslugstringrequiredstatus"draft" | "open" | "paused" | "closed"requiredtitlestringrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
locationobject | nullrequired4 fields
idstringrequirednamestringrequiredcitystring | nullrequiredcountrystringrequired
workplace"on_site" | "hybrid" | "remote"requiredcountrystring | nullrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredweekly_hoursnumber | nullrequiredemployment_type"full_time" | "part_time" | "contract" | "temporary" | "internship"requiredsalaryobject | nullrequiredThe range the post shows (from the position's budget or band, or set on the job).
5 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredsource"position" | "band" | "job"required
salary_hiddenbooleanrequiredTrue over an API key or MCP before the job was first opened: the range is the budget until it is published.
language"en" | "pt" | "es" | "fr" | "de"requiredpostobjectrequired4 fields
what_you_dostringrequiredwhat_you_needstringrequiredwhat_you_getstringrequiredhow_it_goesstringrequired
processobjectrequiredWhat the post's "How it goes" shows above post.how_it_goes (the company's note), in the job's language: the answer promise and each step with its length, from answer_days and the steps. Change the steps to change it.
2 fields
promisestringrequiredstepsstring[]required
stepsobject[]required13 fields
idstringrequirednamestringrequiredkindstring (enum)requiredOne of:
call,interview,panel,task,trial,presentation,references,final.minutesnumber | nullrequiredbuffer_minutesintegerrequiredMinutes kept clear after the interview.
place"video" | "video_auto" | "phone" | "on_site" | "none"requiredaddressstring | nullrequiredIn person: the address.
video_linkstring | nullrequiredVideo (pasted): the meeting link.
interviewers_neededintegerrequiredpoolobjectrequired2 fields
group_idsstring[]requiredperson_idsstring[]required
scorecard_idstring | nullrequiredfeedback_due_hoursintegerrequiredscorecardobject | nullrequiredWhat interviewers rate at this step (null: no scorecard, only a recommendation and words).
2 fields
skillsobject[]required4 fields
idstringrequirednamestringrequiredpromptstring | nullrequiredlevelsstring[]required4–4 items.
overall_questionstring | nullrequired
template_idstring | nullrequiredinterviews"in_bizisy" | "outside"requiredHow interviews run for this job (its own choice, else the company default).
interviews_override"in_bizisy" | "outside"requiredanswer_daysintegerrequiredWorking days to answer each candidate (its own, else the company default).
answer_days_overrideinteger | nullrequiredfree_sitesbooleanrequiredaudience"public" | "internal_first" | "internal_only"requiredWho the job is for (Settings → Hiring → Internal jobs): public (the careers page, the feed and Me), internal_first (Me only for internal_days, then also public), internal_only (Me only: never the careers page, feed or job sites).
internal_daysinteger | nullrequiredinternal_first: days in Me before it goes public (null: the company default).
public_fromstring | nullrequiredinternal_first: when it went (or goes) public; null while internal.
listed_publiclybooleanrequiredShown on the careers page and the feed now.
referral_bonusobjectrequiredThis job's own referral bonus; null follows the company's (Settings → Hiring).
4 fields (one of several shapes)
Option 1
kind"none"required
Option 2
kind"amount"requiredamountnumberrequiredcurrencystringrequired
hiring_managerobject | nullrequired2 fields
idstringrequirednamestringrequired
questionsobject[]required6 fields
idstringrequiredtextstringrequiredkind"text" | "yes_no" | "choice"requiredoptionsstring[]requiredbooleanrequiredexternal_onlybooleanrequiredShown to outside candidates only, never to people who work here.
valid_throughstring | nullrequiredcareers_pathstringrequiredIts address on the company's careers page, once open.
readyobjectrequiredWhether it can be opened, and what is missing: title, description (what you'll do), pay_range, gaps (a [[…]] left from the draft).
2 fields
okbooleanrequiredmissing"title" | "description" | "pay_range" | "gaps"[]required
opened_atstring | nullrequiredclosed_atstring | nullrequiredclose_reason"filled" | "cancelled" | "other"requiredclose_replyobject | nullrequiredClosed with "reply to everyone still open": when the kind "not this time" goes out to them.
1 field
send_atstringrequired
created_atstringrequiredupdated_atstringrequiredpipelineobjectrequired7 fields
newintegerrequiredCandidates in New, not answered yet.
in_stepsintegerrequiredCandidates in one of the job's steps.
offerintegerrequiredhiredintegerrequirednot_this_timeintegerrequiredTold (or about to be told) "not this time".
overdueintegerrequiredStill open and past the answer promise.
appliedintegerrequiredEveryone who applied or was added, withdrawn ones included.
totalintegerrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/jobs.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status":"all","position_id":"pos1","limit":50}'const res = await fetch('https://api.bizisy.com/v1/hiring/jobs.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"status": "all",
"position_id": "pos1",
"limit": 50
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/jobs.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"status": "all",
"position_id": "pos1",
"limit": 50,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"jobs": [
{
"id": "j1",
"position_id": "pos1",
"slug": "line-cook",
"status": "open",
"title": "Line cook",
"unit": {
"id": "u1",
"name": "Kitchen"
},
"location": {
"id": "l1",
"name": "Braga kitchen",
"city": "Braga",
"country": "PT"
},
"workplace": "on_site",
"country": "PT",
"contract_type": "permanent",
"weekly_hours": 40,
"employment_type": "full_time",
"salary": {
"min": 18000,
"max": 22000,
"currency": "EUR",
"period": "year",
"source": "position"
},
"salary_hidden": false,
"language": "en",
"post": {
"what_you_do": "Prepare the mise en place and cook the lunch service with a team of four.",
"what_you_need": "Two years in a professional kitchen and a food hygiene certificate.",
"what_you_get": "- Pay: €18,000–€22,000 a year\n- A permanent contract\n- Full time, 40 hours a week\n- On site in Braga\n\nMeals on shift.",
"how_it_goes": "Then an offer."
},
"process": {
"promise": "We answer within 5 working days.",
"steps": [
"Talking · 30 mins",
"Trial shift · 4 hrs"
]
},
"steps": [
{
"id": "talking",
"name": "Talking",
"kind": "call",
"minutes": 30,
"buffer_minutes": 15,
"place": "phone",
"address": null,
"video_link": null,
"interviewers_needed": 0,
"pool": {
"group_ids": [],
"person_ids": []
},
"scorecard_id": null,
"feedback_due_hours": 24,
"scorecard": null
},
{
"id": "trial",
"name": "Trial shift",
"kind": "trial",
"minutes": 240,
"buffer_minutes": 30,
"place": "on_site",
"address": "Rua do Souto 12, Braga",
"video_link": null,
"interviewers_needed": 1,
"pool": {
"group_ids": [
"g1"
],
"person_ids": [
"p2"
]
},
"scorecard_id": null,
"feedback_due_hours": 24,
"scorecard": {
"skills": [
{
"id": "practical",
"name": "Practical work",
"prompt": "Watch how they work: quality, pace, safety, asking for help.",
"levels": [
"Could not do the tasks safely or correctly.",
"Did the tasks with frequent help or mistakes.",
"Did the tasks well at a good pace; asked when unsure.",
"Quick, careful and independent; improved as it went on."
]
},
{
"id": "teamwork",
"name": "Working with others",
"prompt": "Ask about a time they disagreed with a colleague and what happened.",
"levels": [
"Blamed others or avoided the question.",
"Works with others, but the examples were thin.",
"Good examples of working with others and settling disagreements.",
"Lifts the team: shares credit, gives and takes feedback well."
]
}
],
"overall_question": "What would this person bring to the team, and what support would they need?"
}
}
],
"template_id": "simple",
"interviews": "outside",
"interviews_override": null,
"answer_days": 5,
"answer_days_override": null,
"free_sites": true,
"referral_bonus": null,
"audience": "public",
"internal_days": null,
"public_from": null,
"listed_publicly": true,
"hiring_manager": {
"id": "p2",
"name": "Rita Lopes"
},
"questions": [
{
"id": "right_to_work",
"text": "Do you have the right to work in the EU?",
"kind": "yes_no",
"required": true,
"external_only": true
}
],
"valid_through": null,
"careers_path": "/careers/line-cook",
"ready": {
"ok": true,
"missing": []
},
"opened_at": "2026-10-18T09:00:00.000Z",
"closed_at": null,
"close_reason": null,
"close_reply": null,
"created_at": "2026-10-17T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z",
"pipeline": {
"new": 3,
"in_steps": 1,
"offer": 0,
"hired": 0,
"not_this_time": 1,
"overdue": 1,
"applied": 5
}
},
{
"id": "j2",
"position_id": "pos1",
"slug": "pastry-chef",
"status": "draft",
"title": "Pastry chef",
"unit": {
"id": "u1",
"name": "Kitchen"
},
"location": {
"id": "l1",
"name": "Braga kitchen",
"city": "Braga",
"country": "PT"
},
"workplace": "on_site",
"country": "PT",
"contract_type": "permanent",
"weekly_hours": 40,
"employment_type": "full_time",
"salary": null,
"salary_hidden": true,
"language": "en",
"post": {
"what_you_do": "Prepare the mise en place and cook the lunch service with a team of four.",
"what_you_need": "[[List what the job really needs: skills, experience, languages, licences. Leave out what is only nice to have.]]",
"what_you_get": "- Pay: €18,000–€22,000 a year\n- A permanent contract\n- Full time, 40 hours a week\n- On site in Braga\n\nMeals on shift.",
"how_it_goes": "Then an offer."
},
"process": {
"promise": "We answer within 5 working days.",
"steps": [
"Talking · 30 mins",
"Trial shift · 4 hrs"
]
},
"steps": [
{
"id": "talking",
"name": "Talking",
"kind": "call",
"minutes": 30,
"buffer_minutes": 15,
"place": "phone",
"address": null,
"video_link": null,
"interviewers_needed": 0,
"pool": {
"group_ids": [],
"person_ids": []
},
"scorecard_id": null,
"feedback_due_hours": 24,
"scorecard": null
}
],
"template_id": "simple",
"interviews": "outside",
"interviews_override": null,
"answer_days": 5,
"answer_days_override": null,
"free_sites": true,
"referral_bonus": null,
"audience": "public",
"internal_days": null,
"public_from": null,
"listed_publicly": true,
"hiring_manager": null,
"questions": [
{
"id": "right_to_work",
"text": "Do you have the right to work in the EU?",
"kind": "yes_no",
"required": true,
"external_only": true
}
],
"valid_through": null,
"careers_path": "/careers/line-cook",
"ready": {
"ok": false,
"missing": [
"gaps"
]
},
"opened_at": null,
"closed_at": null,
"close_reason": null,
"close_reply": null,
"created_at": "2026-10-17T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z",
"pipeline": {
"new": 0,
"in_steps": 0,
"offer": 0,
"hired": 0,
"not_this_time": 0,
"overdue": 0,
"applied": 0
}
}
],
"total": 2
}
}Get a job#
POST/v1/hiring/jobs.getRead
One job with its post, steps, questions, readiness to open (ready.missing: title, description, pay_range, gaps) and the wording check (warnings: words in the title or post that put people off or exclude them by age, gender, family, origin, health or looks, with suggestions; never blocks). Owners, admins and HR any job; a hiring manager their own; otherwise not_found. Over an API key or MCP the pay range of a job never opened is hidden.
- Who can call it
- Manage key any Manage role
Me key anyone - Keys and apps
- The pay range of a job never opened is hidden (salary_hidden).
- MCP tool
hiring_jobs_geton HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
job_idstringrequired1–100 characters.
Returns
41 fields
idstringrequiredposition_idstringrequiredslugstringrequiredstatus"draft" | "open" | "paused" | "closed"requiredtitlestringrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
locationobject | nullrequired4 fields
idstringrequirednamestringrequiredcitystring | nullrequiredcountrystringrequired
workplace"on_site" | "hybrid" | "remote"requiredcountrystring | nullrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredweekly_hoursnumber | nullrequiredemployment_type"full_time" | "part_time" | "contract" | "temporary" | "internship"requiredsalaryobject | nullrequiredThe range the post shows (from the position's budget or band, or set on the job).
5 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredsource"position" | "band" | "job"required
salary_hiddenbooleanrequiredTrue over an API key or MCP before the job was first opened: the range is the budget until it is published.
language"en" | "pt" | "es" | "fr" | "de"requiredpostobjectrequired4 fields
what_you_dostringrequiredwhat_you_needstringrequiredwhat_you_getstringrequiredhow_it_goesstringrequired
processobjectrequiredWhat the post's "How it goes" shows above post.how_it_goes (the company's note), in the job's language: the answer promise and each step with its length, from answer_days and the steps. Change the steps to change it.
2 fields
promisestringrequiredstepsstring[]required
stepsobject[]required13 fields
idstringrequirednamestringrequiredkindstring (enum)requiredOne of:
call,interview,panel,task,trial,presentation,references,final.minutesnumber | nullrequiredbuffer_minutesintegerrequiredMinutes kept clear after the interview.
place"video" | "video_auto" | "phone" | "on_site" | "none"requiredaddressstring | nullrequiredIn person: the address.
video_linkstring | nullrequiredVideo (pasted): the meeting link.
interviewers_neededintegerrequiredpoolobjectrequired2 fields
group_idsstring[]requiredperson_idsstring[]required
scorecard_idstring | nullrequiredfeedback_due_hoursintegerrequiredscorecardobject | nullrequiredWhat interviewers rate at this step (null: no scorecard, only a recommendation and words).
2 fields
skillsobject[]required4 fields
idstringrequirednamestringrequiredpromptstring | nullrequiredlevelsstring[]required4–4 items.
overall_questionstring | nullrequired
template_idstring | nullrequiredinterviews"in_bizisy" | "outside"requiredHow interviews run for this job (its own choice, else the company default).
interviews_override"in_bizisy" | "outside"requiredanswer_daysintegerrequiredWorking days to answer each candidate (its own, else the company default).
answer_days_overrideinteger | nullrequiredfree_sitesbooleanrequiredaudience"public" | "internal_first" | "internal_only"requiredWho the job is for (Settings → Hiring → Internal jobs): public (the careers page, the feed and Me), internal_first (Me only for internal_days, then also public), internal_only (Me only: never the careers page, feed or job sites).
internal_daysinteger | nullrequiredinternal_first: days in Me before it goes public (null: the company default).
public_fromstring | nullrequiredinternal_first: when it went (or goes) public; null while internal.
listed_publiclybooleanrequiredShown on the careers page and the feed now.
referral_bonusobjectrequiredThis job's own referral bonus; null follows the company's (Settings → Hiring).
4 fields (one of several shapes)
Option 1
kind"none"required
Option 2
kind"amount"requiredamountnumberrequiredcurrencystringrequired
hiring_managerobject | nullrequired2 fields
idstringrequirednamestringrequired
questionsobject[]required6 fields
idstringrequiredtextstringrequiredkind"text" | "yes_no" | "choice"requiredoptionsstring[]requiredbooleanrequiredexternal_onlybooleanrequiredShown to outside candidates only, never to people who work here.
valid_throughstring | nullrequiredcareers_pathstringrequiredIts address on the company's careers page, once open.
readyobjectrequiredWhether it can be opened, and what is missing: title, description (what you'll do), pay_range, gaps (a [[…]] left from the draft).
2 fields
okbooleanrequiredmissing"title" | "description" | "pay_range" | "gaps"[]required
opened_atstring | nullrequiredclosed_atstring | nullrequiredclose_reason"filled" | "cancelled" | "other"requiredclose_replyobject | nullrequiredClosed with "reply to everyone still open": when the kind "not this time" goes out to them.
1 field
send_atstringrequired
created_atstringrequiredupdated_atstringrequiredwarningsobject[]requiredThe wording check (never blocks): words that put people off or exclude them, with suggestions.
4 fields
field"title" | "what_you_do" | "what_you_need" | "what_you_get" | "how_it_goes"requiredtermstringrequiredcategory"age" | "gender" | "family" | "origin" | "health" | "looks"requiredsuggestionsstring[]required
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/jobs.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"job_id":"j1"}'const res = await fetch('https://api.bizisy.com/v1/hiring/jobs.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"job_id": "j1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/jobs.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"job_id": "j1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "j1",
"position_id": "pos1",
"slug": "line-cook",
"status": "open",
"title": "Line cook",
"unit": {
"id": "u1",
"name": "Kitchen"
},
"location": {
"id": "l1",
"name": "Braga kitchen",
"city": "Braga",
"country": "PT"
},
"workplace": "on_site",
"country": "PT",
"contract_type": "permanent",
"weekly_hours": 40,
"employment_type": "full_time",
"salary": {
"min": 18000,
"max": 22000,
"currency": "EUR",
"period": "year",
"source": "position"
},
"salary_hidden": false,
"language": "en",
"post": {
"what_you_do": "Prepare the mise en place and cook the lunch service with a team of four.",
"what_you_need": "Two years in a professional kitchen and a food hygiene certificate.",
"what_you_get": "- Pay: €18,000–€22,000 a year\n- A permanent contract\n- Full time, 40 hours a week\n- On site in Braga\n\nMeals on shift.",
"how_it_goes": "Then an offer."
},
"process": {
"promise": "We answer within 5 working days.",
"steps": [
"Talking · 30 mins",
"Trial shift · 4 hrs"
]
},
"steps": [
{
"id": "talking",
"name": "Talking",
"kind": "call",
"minutes": 30,
"buffer_minutes": 15,
"place": "phone",
"address": null,
"video_link": null,
"interviewers_needed": 0,
"pool": {
"group_ids": [],
"person_ids": []
},
"scorecard_id": null,
"feedback_due_hours": 24,
"scorecard": null
},
{
"id": "trial",
"name": "Trial shift",
"kind": "trial",
"minutes": 240,
"buffer_minutes": 30,
"place": "on_site",
"address": "Rua do Souto 12, Braga",
"video_link": null,
"interviewers_needed": 1,
"pool": {
"group_ids": [
"g1"
],
"person_ids": [
"p2"
]
},
"scorecard_id": null,
"feedback_due_hours": 24,
"scorecard": {
"skills": [
{
"id": "practical",
"name": "Practical work",
"prompt": "Watch how they work: quality, pace, safety, asking for help.",
"levels": [
"Could not do the tasks safely or correctly.",
"Did the tasks with frequent help or mistakes.",
"Did the tasks well at a good pace; asked when unsure.",
"Quick, careful and independent; improved as it went on."
]
},
{
"id": "teamwork",
"name": "Working with others",
"prompt": "Ask about a time they disagreed with a colleague and what happened.",
"levels": [
"Blamed others or avoided the question.",
"Works with others, but the examples were thin.",
"Good examples of working with others and settling disagreements.",
"Lifts the team: shares credit, gives and takes feedback well."
]
}
],
"overall_question": "What would this person bring to the team, and what support would they need?"
}
}
],
"template_id": "simple",
"interviews": "outside",
"interviews_override": null,
"answer_days": 5,
"answer_days_override": null,
"free_sites": true,
"referral_bonus": null,
"audience": "public",
"internal_days": null,
"public_from": null,
"listed_publicly": true,
"hiring_manager": {
"id": "p2",
"name": "Rita Lopes"
},
"questions": [
{
"id": "right_to_work",
"text": "Do you have the right to work in the EU?",
"kind": "yes_no",
"required": true,
"external_only": true
}
],
"valid_through": null,
"careers_path": "/careers/line-cook",
"ready": {
"ok": true,
"missing": []
},
"opened_at": "2026-10-18T09:00:00.000Z",
"closed_at": null,
"close_reason": null,
"close_reply": null,
"created_at": "2026-10-17T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z",
"warnings": []
}
}Create a job from a position#
POST/v1/hiring/jobs.createWrite
Starts hiring for an open position (org_positions_list; status open or on hold): a draft job with the position's title, team, location, contract, weekly hours and pay range (its budget, else the band of its title), the hiring manager (default: the person the position reports to), the steps and questions of a plan (template_id from hiring_templates_list; default simple: one step "Talking"), and a post drafted from the position in its language (language: en, pt, es, fr or de; default the company's; draft false for an empty post). slug: its careers page address (default from the title; unique in the company). A position has at most one draft, open or paused job; at most 200 per company. Nothing is published: check the post (hiring_jobs_get: ready, warnings), then hiring_jobs_open. Owners, admins and HR. Over an API key or MCP the pay range is copied but hidden in the result until the job is opened. Use dry_run first.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- The pay range is copied from the position, and hidden in the result until the job is opened.
- MCP tool
hiring_jobs_createon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
position_idstringrequired1–100 characters.
template_idstring1–100 characters.
language"en" | "pt" | "es" | "fr" | "de"slugstring2–80 characters. Pattern
^[a-z0-9]+(?:-[a-z0-9]+)*$.hiring_manager_idstring | null1–100 characters.
draftbooleanDefault
true.audience"public" | "internal_first" | "internal_only"Who it is for (default: Settings → Hiring → Internal jobs default, public until HR changes it). internal_first and internal_only need internal jobs on.
internal_daysinteger | nullFrom 1 to 60.
Returns
41 fields
idstringrequiredposition_idstringrequiredslugstringrequiredstatus"draft" | "open" | "paused" | "closed"requiredtitlestringrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
locationobject | nullrequired4 fields
idstringrequirednamestringrequiredcitystring | nullrequiredcountrystringrequired
workplace"on_site" | "hybrid" | "remote"requiredcountrystring | nullrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredweekly_hoursnumber | nullrequiredemployment_type"full_time" | "part_time" | "contract" | "temporary" | "internship"requiredsalaryobject | nullrequiredThe range the post shows (from the position's budget or band, or set on the job).
5 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredsource"position" | "band" | "job"required
salary_hiddenbooleanrequiredTrue over an API key or MCP before the job was first opened: the range is the budget until it is published.
language"en" | "pt" | "es" | "fr" | "de"requiredpostobjectrequired4 fields
what_you_dostringrequiredwhat_you_needstringrequiredwhat_you_getstringrequiredhow_it_goesstringrequired
processobjectrequiredWhat the post's "How it goes" shows above post.how_it_goes (the company's note), in the job's language: the answer promise and each step with its length, from answer_days and the steps. Change the steps to change it.
2 fields
promisestringrequiredstepsstring[]required
stepsobject[]required13 fields
idstringrequirednamestringrequiredkindstring (enum)requiredOne of:
call,interview,panel,task,trial,presentation,references,final.minutesnumber | nullrequiredbuffer_minutesintegerrequiredMinutes kept clear after the interview.
place"video" | "video_auto" | "phone" | "on_site" | "none"requiredaddressstring | nullrequiredIn person: the address.
video_linkstring | nullrequiredVideo (pasted): the meeting link.
interviewers_neededintegerrequiredpoolobjectrequired2 fields
group_idsstring[]requiredperson_idsstring[]required
scorecard_idstring | nullrequiredfeedback_due_hoursintegerrequiredscorecardobject | nullrequiredWhat interviewers rate at this step (null: no scorecard, only a recommendation and words).
2 fields
skillsobject[]required4 fields
idstringrequirednamestringrequiredpromptstring | nullrequiredlevelsstring[]required4–4 items.
overall_questionstring | nullrequired
template_idstring | nullrequiredinterviews"in_bizisy" | "outside"requiredHow interviews run for this job (its own choice, else the company default).
interviews_override"in_bizisy" | "outside"requiredanswer_daysintegerrequiredWorking days to answer each candidate (its own, else the company default).
answer_days_overrideinteger | nullrequiredfree_sitesbooleanrequiredaudience"public" | "internal_first" | "internal_only"requiredWho the job is for (Settings → Hiring → Internal jobs): public (the careers page, the feed and Me), internal_first (Me only for internal_days, then also public), internal_only (Me only: never the careers page, feed or job sites).
internal_daysinteger | nullrequiredinternal_first: days in Me before it goes public (null: the company default).
public_fromstring | nullrequiredinternal_first: when it went (or goes) public; null while internal.
listed_publiclybooleanrequiredShown on the careers page and the feed now.
referral_bonusobjectrequiredThis job's own referral bonus; null follows the company's (Settings → Hiring).
4 fields (one of several shapes)
Option 1
kind"none"required
Option 2
kind"amount"requiredamountnumberrequiredcurrencystringrequired
hiring_managerobject | nullrequired2 fields
idstringrequirednamestringrequired
questionsobject[]required6 fields
idstringrequiredtextstringrequiredkind"text" | "yes_no" | "choice"requiredoptionsstring[]requiredbooleanrequiredexternal_onlybooleanrequiredShown to outside candidates only, never to people who work here.
valid_throughstring | nullrequiredcareers_pathstringrequiredIts address on the company's careers page, once open.
readyobjectrequiredWhether it can be opened, and what is missing: title, description (what you'll do), pay_range, gaps (a [[…]] left from the draft).
2 fields
okbooleanrequiredmissing"title" | "description" | "pay_range" | "gaps"[]required
opened_atstring | nullrequiredclosed_atstring | nullrequiredclose_reason"filled" | "cancelled" | "other"requiredclose_replyobject | nullrequiredClosed with "reply to everyone still open": when the kind "not this time" goes out to them.
1 field
send_atstringrequired
created_atstringrequiredupdated_atstringrequiredwarningsobject[]requiredThe wording check (never blocks): words that put people off or exclude them, with suggestions.
4 fields
field"title" | "what_you_do" | "what_you_need" | "what_you_get" | "how_it_goes"requiredtermstringrequiredcategory"age" | "gender" | "family" | "origin" | "health" | "looks"requiredsuggestionsstring[]required
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/jobs.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"position_id": "pos1",
"template_id": "warehouse",
"language": "pt",
"slug": "line-cook",
"hiring_manager_id": "p2",
"draft": true
}'const res = await fetch('https://api.bizisy.com/v1/hiring/jobs.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"position_id": "pos1",
"template_id": "warehouse",
"language": "pt",
"slug": "line-cook",
"hiring_manager_id": "p2",
"draft": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/jobs.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"position_id": "pos1",
"template_id": "warehouse",
"language": "pt",
"slug": "line-cook",
"hiring_manager_id": "p2",
"draft": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "j2",
"position_id": "pos1",
"slug": "line-cook",
"status": "draft",
"title": "Pastry chef",
"unit": {
"id": "u1",
"name": "Kitchen"
},
"location": {
"id": "l1",
"name": "Braga kitchen",
"city": "Braga",
"country": "PT"
},
"workplace": "on_site",
"country": "PT",
"contract_type": "permanent",
"weekly_hours": 40,
"employment_type": "full_time",
"salary": null,
"salary_hidden": true,
"language": "pt",
"post": {
"what_you_do": "Prepare the mise en place and cook the lunch service with a team of four.",
"what_you_need": "[[List what the job really needs: skills, experience, languages, licences. Leave out what is only nice to have.]]",
"what_you_get": "- Pay: €18,000–€22,000 a year\n- A permanent contract\n- Full time, 40 hours a week\n- On site in Braga\n\nMeals on shift.",
"how_it_goes": "Then an offer."
},
"process": {
"promise": "We answer within 5 working days.",
"steps": [
"Talking · 30 mins",
"Trial shift · 4 hrs"
]
},
"steps": [
{
"id": "talking",
"name": "Talking",
"kind": "call",
"minutes": 30,
"buffer_minutes": 15,
"place": "phone",
"address": null,
"video_link": null,
"interviewers_needed": 0,
"pool": {
"group_ids": [],
"person_ids": []
},
"scorecard_id": null,
"feedback_due_hours": 24,
"scorecard": null
}
],
"template_id": "simple",
"interviews": "outside",
"interviews_override": null,
"answer_days": 5,
"answer_days_override": null,
"free_sites": true,
"referral_bonus": null,
"audience": "public",
"internal_days": null,
"public_from": null,
"listed_publicly": true,
"hiring_manager": null,
"questions": [
{
"id": "right_to_work",
"text": "Do you have the right to work in the EU?",
"kind": "yes_no",
"required": true,
"external_only": true
}
],
"valid_through": null,
"careers_path": "/careers/line-cook",
"ready": {
"ok": false,
"missing": [
"gaps"
]
},
"opened_at": null,
"closed_at": null,
"close_reason": null,
"close_reply": null,
"created_at": "2026-10-17T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z",
"warnings": [
{
"field": "what_you_do",
"term": "young team",
"category": "age",
"suggestions": [
"motivated",
"curious"
]
}
]
}
}Change a job#
POST/v1/hiring/jobs.updateWrite
Changes a draft, open or paused job; send only what changes (null clears where allowed). The post: title, language (en, pt, es, fr, de), post sections (what_you_do, what_you_need, what_you_get, how_it_goes: the company's note after the answer promise and steps the post shows from the job; ≤ 5,000 characters each; written in Markdown-lite: paragraphs separated by a blank line, "- " bullets, "1. " numbered lists, "### " subheadings, **bold** and *italic*, nothing else: links, images and HTML show as plain text), questions (at most 2; never about pay history, age, family, health or religion; each confirmed job_related). The place: unit_id, location_id, workplace (on_site, hybrid, remote), country, contract_type, weekly_hours, valid_through. salary {min, max, currency, period}: the range the post shows. steps: the plan between New and Offer (1 to 10; keep a step's id to keep its candidates; removing a step with candidates in it is refused). interviews (in_bizisy: colleagues interview in Bizisy, booked from their usual weeks; outside: HR records interviews held elsewhere; null: the company default; refused while interviews are booked or offered), steps also take minutes (15 to 480), buffer_minutes (0 to 60, default 15), place with address (in person) or video_link, interviewers_needed and pool {group_ids, person_ids}, answer_days (1 to 30; null: the company default), free_sites (listed in the job feed that job sites read), referral_bonus ({kind: none} or {kind: amount, amount, currency}; null: the company's), hiring_manager_id, slug. An open or paused job must keep its title, description and pay range, without [[…]] gaps. Owners, admins and HR change anything; a hiring manager only the post, language, steps and questions of their own jobs. salary and referral_bonus are refused over MCP or an API key (set them signed in to Bizisy).
- Who can call it
- Manage key any Manage role
Me key anyone - Keys and apps
- Pay ranges (salary) and referral bonuses are set in the app only.
- MCP tool
hiring_jobs_updateon HR Assistant, My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
job_idstringrequired1–100 characters.
titlestring1–120 characters.
slugstring2–80 characters. Pattern
^[a-z0-9]+(?:-[a-z0-9]+)*$.unit_idstring | null1–100 characters.
location_idstring | null1–100 characters.
workplace"on_site" | "hybrid" | "remote"countryany | nullcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"weekly_hoursnumber | nullFrom 0 to 80.
salaryobject | null4 fields
minnumberrequiredFrom 0 to 100000000.
maxnumberrequiredFrom 0 to 100000000.
currencyanyrequiredperiod"year" | "month" | "hour"required
language"en" | "pt" | "es" | "fr" | "de"postobject4 fields
what_you_dostringUp to 5000 characters.
what_you_needstringUp to 5000 characters.
what_you_getstringUp to 5000 characters.
how_it_goesstringUp to 5000 characters.
stepsobject[]The steps between New and Offer, in order (1 to 10).
1–10 items.
12 fields
idstringKeep the id of an existing step to keep its candidates in it; leave it out for a new step.
1–40 characters.
namestringrequiredWhat the company and the candidate call it, e.g. "Phone call", "Trial shift".
1–60 characters.
kindstring (enum)requiredcall, interview, panel, task, trial, presentation, references or final.
One of:
call,interview,panel,task,trial,presentation,references,final.minutesinteger | nullHow long the interview lasts, 15 to 480 minutes (e.g. intro call 30, technical interview 120, trial day 480). Default by kind for steps with interviewers.
From 15 to 480.
buffer_minutesintegerMinutes kept clear after it, 0 to 60 (default 15).
From 0 to 60.
place"video" | "video_auto" | "phone" | "on_site" | "none"video (with the link HR pastes), video_auto (a Google Meet or Microsoft Teams link made by the company's connected calendar for each interview: hiring_interviews_calendar says which; booking is refused while no calendar is connected), phone, on_site (in person) or none (a task done at home). Default: by kind.
addressstring | nullIn person (on_site): the address the candidate and interviewers go to.
1–300 characters.
video_linkURL | nullVideo: the meeting link HR pastes (Meet, Teams, Zoom…); sent with the invitation.
Up to 500 characters.
interviewers_neededintegerColleagues who interview together at this step (0: nobody is asked). Default 0 for call, task and references, else 1.
From 0 to 5.
poolobjectWho may interview at this step: interview groups and people. Leave out to keep it as it is.
2 fields
group_idsstring[]Interview groups (hiring_pools_list).
Up to 20 items.
person_idsstring[]People (person ids).
Up to 50 items.
feedback_due_hoursintegerHours after the interview to send feedback (default 24).
From 1 to 336.
scorecardobject | nullWhat interviewers rate at this step: up to 8 skills, each with four anchored descriptions (1 to 4), and an optional overall question. null removes it; leave out to keep it.
2 fields
skillsobject[]requiredUp to 8 skills, each rated 1 to 4.
Up to 8 items.
4 fields
idstringKeep a skill's id to keep the ratings already given on it; leave it out for a new skill.
1–40 characters.
namestringrequiredWhat is rated, e.g. "Problem solving".
1–60 characters.
promptstring | nullWhat to ask or look for (shown to the interviewer).
1–300 characters.
levelsany[]requiredWhat each rating looks like, from 1 (clear concerns) to 4 (excellent): four short anchored descriptions.
4–4 items.
overall_questionstring | nullAn optional question every interviewer answers in their own words.
1–300 characters.
interviews"in_bizisy" | "outside"answer_daysinteger | nullFrom 1 to 30.
free_sitesbooleanreferral_bonusobject4 fields (one of several shapes)
Option 1
kind"none"required
Option 2
kind"amount"requiredamountnumberrequiredFrom 0 to 1000000.
currencyanyrequired
hiring_manager_idstring | null1–100 characters.
questionsobject[]At most 2 extra questions on the form (yes/no, a choice or short text).
Up to 2 items.
7 fields
idstring1–40 characters.
textstringrequired3–200 characters.
kind"text" | "yes_no" | "choice"requiredoptionsstring[]For kind choice: 2 to 6 answers.
1–60 characters. 2–6 items.
requiredbooleanDefault
false.external_onlybooleanOnly for candidates from outside the company: people who work here don't see it when they apply from My workspace (internal jobs). Default: true for right-to-work, work-permit, visa and residence questions, else false.
job_relatedtruerequiredConfirms the question is about the job itself (H14). Questions about pay history, age, family, health, religion or pregnancy are refused.
valid_throughstring | nullPattern
^\d{4}-\d{2}-\d{2}$.audience"public" | "internal_first" | "internal_only"internal_daysinteger | nullFrom 1 to 60.
Returns
41 fields
idstringrequiredposition_idstringrequiredslugstringrequiredstatus"draft" | "open" | "paused" | "closed"requiredtitlestringrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
locationobject | nullrequired4 fields
idstringrequirednamestringrequiredcitystring | nullrequiredcountrystringrequired
workplace"on_site" | "hybrid" | "remote"requiredcountrystring | nullrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredweekly_hoursnumber | nullrequiredemployment_type"full_time" | "part_time" | "contract" | "temporary" | "internship"requiredsalaryobject | nullrequiredThe range the post shows (from the position's budget or band, or set on the job).
5 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredsource"position" | "band" | "job"required
salary_hiddenbooleanrequiredTrue over an API key or MCP before the job was first opened: the range is the budget until it is published.
language"en" | "pt" | "es" | "fr" | "de"requiredpostobjectrequired4 fields
what_you_dostringrequiredwhat_you_needstringrequiredwhat_you_getstringrequiredhow_it_goesstringrequired
processobjectrequiredWhat the post's "How it goes" shows above post.how_it_goes (the company's note), in the job's language: the answer promise and each step with its length, from answer_days and the steps. Change the steps to change it.
2 fields
promisestringrequiredstepsstring[]required
stepsobject[]required13 fields
idstringrequirednamestringrequiredkindstring (enum)requiredOne of:
call,interview,panel,task,trial,presentation,references,final.minutesnumber | nullrequiredbuffer_minutesintegerrequiredMinutes kept clear after the interview.
place"video" | "video_auto" | "phone" | "on_site" | "none"requiredaddressstring | nullrequiredIn person: the address.
video_linkstring | nullrequiredVideo (pasted): the meeting link.
interviewers_neededintegerrequiredpoolobjectrequired2 fields
group_idsstring[]requiredperson_idsstring[]required
scorecard_idstring | nullrequiredfeedback_due_hoursintegerrequiredscorecardobject | nullrequiredWhat interviewers rate at this step (null: no scorecard, only a recommendation and words).
2 fields
skillsobject[]required4 fields
idstringrequirednamestringrequiredpromptstring | nullrequiredlevelsstring[]required4–4 items.
overall_questionstring | nullrequired
template_idstring | nullrequiredinterviews"in_bizisy" | "outside"requiredHow interviews run for this job (its own choice, else the company default).
interviews_override"in_bizisy" | "outside"requiredanswer_daysintegerrequiredWorking days to answer each candidate (its own, else the company default).
answer_days_overrideinteger | nullrequiredfree_sitesbooleanrequiredaudience"public" | "internal_first" | "internal_only"requiredWho the job is for (Settings → Hiring → Internal jobs): public (the careers page, the feed and Me), internal_first (Me only for internal_days, then also public), internal_only (Me only: never the careers page, feed or job sites).
internal_daysinteger | nullrequiredinternal_first: days in Me before it goes public (null: the company default).
public_fromstring | nullrequiredinternal_first: when it went (or goes) public; null while internal.
listed_publiclybooleanrequiredShown on the careers page and the feed now.
referral_bonusobjectrequiredThis job's own referral bonus; null follows the company's (Settings → Hiring).
4 fields (one of several shapes)
Option 1
kind"none"required
Option 2
kind"amount"requiredamountnumberrequiredcurrencystringrequired
hiring_managerobject | nullrequired2 fields
idstringrequirednamestringrequired
questionsobject[]required6 fields
idstringrequiredtextstringrequiredkind"text" | "yes_no" | "choice"requiredoptionsstring[]requiredbooleanrequiredexternal_onlybooleanrequiredShown to outside candidates only, never to people who work here.
valid_throughstring | nullrequiredcareers_pathstringrequiredIts address on the company's careers page, once open.
readyobjectrequiredWhether it can be opened, and what is missing: title, description (what you'll do), pay_range, gaps (a [[…]] left from the draft).
2 fields
okbooleanrequiredmissing"title" | "description" | "pay_range" | "gaps"[]required
opened_atstring | nullrequiredclosed_atstring | nullrequiredclose_reason"filled" | "cancelled" | "other"requiredclose_replyobject | nullrequiredClosed with "reply to everyone still open": when the kind "not this time" goes out to them.
1 field
send_atstringrequired
created_atstringrequiredupdated_atstringrequiredwarningsobject[]requiredThe wording check (never blocks): words that put people off or exclude them, with suggestions.
4 fields
field"title" | "what_you_do" | "what_you_need" | "what_you_get" | "how_it_goes"requiredtermstringrequiredcategory"age" | "gender" | "family" | "origin" | "health" | "looks"requiredsuggestionsstring[]required
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/jobs.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"job_id": "j1",
"title": "Line cook",
"slug": "line-cook",
"workplace": "hybrid",
"country": "PT",
"weekly_hours": 38,
"language": "en",
"steps": [
{
"id": "talking",
"name": "Talking",
"kind": "call"
},
{
"name": "Trial shift",
"kind": "trial",
"minutes": 240,
"pool": {
"person_ids": [
"p2"
]
}
}
],
"questions": [
{
"text": "Do you hold a food hygiene certificate?",
"kind": "yes_no",
"required": true,
"job_related": true
}
],
"interviews": "in_bizisy",
"answer_days": 3,
"free_sites": true,
"hiring_manager_id": "p2",
"valid_through": "2026-12-31"
}'const res = await fetch('https://api.bizisy.com/v1/hiring/jobs.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"job_id": "j1",
"title": "Line cook",
"slug": "line-cook",
"workplace": "hybrid",
"country": "PT",
"weekly_hours": 38,
"language": "en",
"steps": [
{
"id": "talking",
"name": "Talking",
"kind": "call"
},
{
"name": "Trial shift",
"kind": "trial",
"minutes": 240,
"pool": {
"person_ids": [
"p2"
]
}
}
],
"questions": [
{
"text": "Do you hold a food hygiene certificate?",
"kind": "yes_no",
"required": true,
"job_related": true
}
],
"interviews": "in_bizisy",
"answer_days": 3,
"free_sites": true,
"hiring_manager_id": "p2",
"valid_through": "2026-12-31"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/jobs.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"job_id": "j1",
"title": "Line cook",
"slug": "line-cook",
"workplace": "hybrid",
"country": "PT",
"weekly_hours": 38,
"language": "en",
"steps": [
{
"id": "talking",
"name": "Talking",
"kind": "call",
},
{
"name": "Trial shift",
"kind": "trial",
"minutes": 240,
"pool": {
"person_ids": [
"p2",
],
},
},
],
"questions": [
{
"text": "Do you hold a food hygiene certificate?",
"kind": "yes_no",
"required": True,
"job_related": True,
},
],
"interviews": "in_bizisy",
"answer_days": 3,
"free_sites": True,
"hiring_manager_id": "p2",
"valid_through": "2026-12-31",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "j1",
"position_id": "pos1",
"slug": "line-cook",
"status": "open",
"title": "Line cook",
"unit": {
"id": "u1",
"name": "Kitchen"
},
"location": {
"id": "l1",
"name": "Braga kitchen",
"city": "Braga",
"country": "PT"
},
"workplace": "hybrid",
"country": "PT",
"contract_type": "permanent",
"weekly_hours": 38,
"employment_type": "full_time",
"salary": {
"min": 18000,
"max": 22000,
"currency": "EUR",
"period": "year",
"source": "position"
},
"salary_hidden": false,
"language": "en",
"post": {
"what_you_do": "Prepare the mise en place and cook the lunch service with a team of four.",
"what_you_need": "Two years in a professional kitchen and a food hygiene certificate.",
"what_you_get": "- Pay: €18,000–€22,000 a year\n- A permanent contract\n- Full time, 40 hours a week\n- On site in Braga\n\nMeals on shift.",
"how_it_goes": "Then an offer."
},
"process": {
"promise": "We answer within 5 working days.",
"steps": [
"Talking · 30 mins",
"Trial shift · 4 hrs"
]
},
"steps": [
{
"id": "talking",
"name": "Talking",
"kind": "call",
"minutes": 30,
"buffer_minutes": 15,
"place": "phone",
"address": null,
"video_link": null,
"interviewers_needed": 0,
"pool": {
"group_ids": [],
"person_ids": []
},
"scorecard_id": null,
"feedback_due_hours": 24,
"scorecard": null
},
{
"id": "trial",
"name": "Trial shift",
"kind": "trial",
"minutes": 240,
"buffer_minutes": 30,
"place": "on_site",
"address": "Rua do Souto 12, Braga",
"video_link": null,
"interviewers_needed": 1,
"pool": {
"group_ids": [
"g1"
],
"person_ids": [
"p2"
]
},
"scorecard_id": null,
"feedback_due_hours": 24,
"scorecard": {
"skills": [
{
"id": "practical",
"name": "Practical work",
"prompt": "Watch how they work: quality, pace, safety, asking for help.",
"levels": [
"Could not do the tasks safely or correctly.",
"Did the tasks with frequent help or mistakes.",
"Did the tasks well at a good pace; asked when unsure.",
"Quick, careful and independent; improved as it went on."
]
},
{
"id": "teamwork",
"name": "Working with others",
"prompt": "Ask about a time they disagreed with a colleague and what happened.",
"levels": [
"Blamed others or avoided the question.",
"Works with others, but the examples were thin.",
"Good examples of working with others and settling disagreements.",
"Lifts the team: shares credit, gives and takes feedback well."
]
}
],
"overall_question": "What would this person bring to the team, and what support would they need?"
}
}
],
"template_id": "simple",
"interviews": "in_bizisy",
"interviews_override": null,
"answer_days": 3,
"answer_days_override": null,
"free_sites": true,
"referral_bonus": null,
"audience": "public",
"internal_days": null,
"public_from": null,
"listed_publicly": true,
"hiring_manager": {
"id": "p2",
"name": "Rita Lopes"
},
"questions": [
{
"id": "right_to_work",
"text": "Do you have the right to work in the EU?",
"kind": "yes_no",
"required": true,
"external_only": true
}
],
"valid_through": "2026-12-31",
"careers_path": "/careers/line-cook",
"ready": {
"ok": true,
"missing": []
},
"opened_at": "2026-10-18T09:00:00.000Z",
"closed_at": null,
"close_reason": null,
"close_reply": null,
"created_at": "2026-10-17T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z",
"warnings": []
}
}Open a job (publish it)#
POST/v1/hiring/jobs.openWrite
Publishes a draft, paused or closed job on the company's careers page (and, with free_sites, the job feed that job sites read): its position must be open, and the job needs a title, a description (what_you_do), a pay range and no [[…]] gaps left from the draft (ready.missing in hiring_jobs_get says what is missing). Reopening a closed job needs the position to have no other draft, open or paused job. Sends the hiring.job_opened webhook. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
hiring_jobs_openon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
job_idstringrequired1–100 characters.
Returns
41 fields
idstringrequiredposition_idstringrequiredslugstringrequiredstatus"draft" | "open" | "paused" | "closed"requiredtitlestringrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
locationobject | nullrequired4 fields
idstringrequirednamestringrequiredcitystring | nullrequiredcountrystringrequired
workplace"on_site" | "hybrid" | "remote"requiredcountrystring | nullrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredweekly_hoursnumber | nullrequiredemployment_type"full_time" | "part_time" | "contract" | "temporary" | "internship"requiredsalaryobject | nullrequiredThe range the post shows (from the position's budget or band, or set on the job).
5 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredsource"position" | "band" | "job"required
salary_hiddenbooleanrequiredTrue over an API key or MCP before the job was first opened: the range is the budget until it is published.
language"en" | "pt" | "es" | "fr" | "de"requiredpostobjectrequired4 fields
what_you_dostringrequiredwhat_you_needstringrequiredwhat_you_getstringrequiredhow_it_goesstringrequired
processobjectrequiredWhat the post's "How it goes" shows above post.how_it_goes (the company's note), in the job's language: the answer promise and each step with its length, from answer_days and the steps. Change the steps to change it.
2 fields
promisestringrequiredstepsstring[]required
stepsobject[]required13 fields
idstringrequirednamestringrequiredkindstring (enum)requiredOne of:
call,interview,panel,task,trial,presentation,references,final.minutesnumber | nullrequiredbuffer_minutesintegerrequiredMinutes kept clear after the interview.
place"video" | "video_auto" | "phone" | "on_site" | "none"requiredaddressstring | nullrequiredIn person: the address.
video_linkstring | nullrequiredVideo (pasted): the meeting link.
interviewers_neededintegerrequiredpoolobjectrequired2 fields
group_idsstring[]requiredperson_idsstring[]required
scorecard_idstring | nullrequiredfeedback_due_hoursintegerrequiredscorecardobject | nullrequiredWhat interviewers rate at this step (null: no scorecard, only a recommendation and words).
2 fields
skillsobject[]required4 fields
idstringrequirednamestringrequiredpromptstring | nullrequiredlevelsstring[]required4–4 items.
overall_questionstring | nullrequired
template_idstring | nullrequiredinterviews"in_bizisy" | "outside"requiredHow interviews run for this job (its own choice, else the company default).
interviews_override"in_bizisy" | "outside"requiredanswer_daysintegerrequiredWorking days to answer each candidate (its own, else the company default).
answer_days_overrideinteger | nullrequiredfree_sitesbooleanrequiredaudience"public" | "internal_first" | "internal_only"requiredWho the job is for (Settings → Hiring → Internal jobs): public (the careers page, the feed and Me), internal_first (Me only for internal_days, then also public), internal_only (Me only: never the careers page, feed or job sites).
internal_daysinteger | nullrequiredinternal_first: days in Me before it goes public (null: the company default).
public_fromstring | nullrequiredinternal_first: when it went (or goes) public; null while internal.
listed_publiclybooleanrequiredShown on the careers page and the feed now.
referral_bonusobjectrequiredThis job's own referral bonus; null follows the company's (Settings → Hiring).
4 fields (one of several shapes)
Option 1
kind"none"required
Option 2
kind"amount"requiredamountnumberrequiredcurrencystringrequired
hiring_managerobject | nullrequired2 fields
idstringrequirednamestringrequired
questionsobject[]required6 fields
idstringrequiredtextstringrequiredkind"text" | "yes_no" | "choice"requiredoptionsstring[]requiredbooleanrequiredexternal_onlybooleanrequiredShown to outside candidates only, never to people who work here.
valid_throughstring | nullrequiredcareers_pathstringrequiredIts address on the company's careers page, once open.
readyobjectrequiredWhether it can be opened, and what is missing: title, description (what you'll do), pay_range, gaps (a [[…]] left from the draft).
2 fields
okbooleanrequiredmissing"title" | "description" | "pay_range" | "gaps"[]required
opened_atstring | nullrequiredclosed_atstring | nullrequiredclose_reason"filled" | "cancelled" | "other"requiredclose_replyobject | nullrequiredClosed with "reply to everyone still open": when the kind "not this time" goes out to them.
1 field
send_atstringrequired
created_atstringrequiredupdated_atstringrequiredwarningsobject[]requiredThe wording check (never blocks): words that put people off or exclude them, with suggestions.
4 fields
field"title" | "what_you_do" | "what_you_need" | "what_you_get" | "how_it_goes"requiredtermstringrequiredcategory"age" | "gender" | "family" | "origin" | "health" | "looks"requiredsuggestionsstring[]required
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/jobs.open \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"job_id":"j1"}'const res = await fetch('https://api.bizisy.com/v1/hiring/jobs.open', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"job_id": "j1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/jobs.open",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"job_id": "j1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "j1",
"position_id": "pos1",
"slug": "line-cook",
"status": "open",
"title": "Line cook",
"unit": {
"id": "u1",
"name": "Kitchen"
},
"location": {
"id": "l1",
"name": "Braga kitchen",
"city": "Braga",
"country": "PT"
},
"workplace": "on_site",
"country": "PT",
"contract_type": "permanent",
"weekly_hours": 40,
"employment_type": "full_time",
"salary": {
"min": 18000,
"max": 22000,
"currency": "EUR",
"period": "year",
"source": "position"
},
"salary_hidden": false,
"language": "en",
"post": {
"what_you_do": "Prepare the mise en place and cook the lunch service with a team of four.",
"what_you_need": "Two years in a professional kitchen and a food hygiene certificate.",
"what_you_get": "- Pay: €18,000–€22,000 a year\n- A permanent contract\n- Full time, 40 hours a week\n- On site in Braga\n\nMeals on shift.",
"how_it_goes": "Then an offer."
},
"process": {
"promise": "We answer within 5 working days.",
"steps": [
"Talking · 30 mins",
"Trial shift · 4 hrs"
]
},
"steps": [
{
"id": "talking",
"name": "Talking",
"kind": "call",
"minutes": 30,
"buffer_minutes": 15,
"place": "phone",
"address": null,
"video_link": null,
"interviewers_needed": 0,
"pool": {
"group_ids": [],
"person_ids": []
},
"scorecard_id": null,
"feedback_due_hours": 24,
"scorecard": null
},
{
"id": "trial",
"name": "Trial shift",
"kind": "trial",
"minutes": 240,
"buffer_minutes": 30,
"place": "on_site",
"address": "Rua do Souto 12, Braga",
"video_link": null,
"interviewers_needed": 1,
"pool": {
"group_ids": [
"g1"
],
"person_ids": [
"p2"
]
},
"scorecard_id": null,
"feedback_due_hours": 24,
"scorecard": {
"skills": [
{
"id": "practical",
"name": "Practical work",
"prompt": "Watch how they work: quality, pace, safety, asking for help.",
"levels": [
"Could not do the tasks safely or correctly.",
"Did the tasks with frequent help or mistakes.",
"Did the tasks well at a good pace; asked when unsure.",
"Quick, careful and independent; improved as it went on."
]
},
{
"id": "teamwork",
"name": "Working with others",
"prompt": "Ask about a time they disagreed with a colleague and what happened.",
"levels": [
"Blamed others or avoided the question.",
"Works with others, but the examples were thin.",
"Good examples of working with others and settling disagreements.",
"Lifts the team: shares credit, gives and takes feedback well."
]
}
],
"overall_question": "What would this person bring to the team, and what support would they need?"
}
}
],
"template_id": "simple",
"interviews": "outside",
"interviews_override": null,
"answer_days": 5,
"answer_days_override": null,
"free_sites": true,
"referral_bonus": null,
"audience": "public",
"internal_days": null,
"public_from": null,
"listed_publicly": true,
"hiring_manager": {
"id": "p2",
"name": "Rita Lopes"
},
"questions": [
{
"id": "right_to_work",
"text": "Do you have the right to work in the EU?",
"kind": "yes_no",
"required": true,
"external_only": true
}
],
"valid_through": null,
"careers_path": "/careers/line-cook",
"ready": {
"ok": true,
"missing": []
},
"opened_at": "2026-10-18T09:00:00.000Z",
"closed_at": null,
"close_reason": null,
"close_reply": null,
"created_at": "2026-10-17T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z",
"warnings": []
}
}Pause a job#
POST/v1/hiring/jobs.pauseWrite
Takes an open job off the careers page and the job feed for now: candidates already in it stay where they are; open it again with hiring_jobs_open. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
hiring_jobs_pauseon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
job_idstringrequired1–100 characters.
Returns
41 fields
idstringrequiredposition_idstringrequiredslugstringrequiredstatus"draft" | "open" | "paused" | "closed"requiredtitlestringrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
locationobject | nullrequired4 fields
idstringrequirednamestringrequiredcitystring | nullrequiredcountrystringrequired
workplace"on_site" | "hybrid" | "remote"requiredcountrystring | nullrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredweekly_hoursnumber | nullrequiredemployment_type"full_time" | "part_time" | "contract" | "temporary" | "internship"requiredsalaryobject | nullrequiredThe range the post shows (from the position's budget or band, or set on the job).
5 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredsource"position" | "band" | "job"required
salary_hiddenbooleanrequiredTrue over an API key or MCP before the job was first opened: the range is the budget until it is published.
language"en" | "pt" | "es" | "fr" | "de"requiredpostobjectrequired4 fields
what_you_dostringrequiredwhat_you_needstringrequiredwhat_you_getstringrequiredhow_it_goesstringrequired
processobjectrequiredWhat the post's "How it goes" shows above post.how_it_goes (the company's note), in the job's language: the answer promise and each step with its length, from answer_days and the steps. Change the steps to change it.
2 fields
promisestringrequiredstepsstring[]required
stepsobject[]required13 fields
idstringrequirednamestringrequiredkindstring (enum)requiredOne of:
call,interview,panel,task,trial,presentation,references,final.minutesnumber | nullrequiredbuffer_minutesintegerrequiredMinutes kept clear after the interview.
place"video" | "video_auto" | "phone" | "on_site" | "none"requiredaddressstring | nullrequiredIn person: the address.
video_linkstring | nullrequiredVideo (pasted): the meeting link.
interviewers_neededintegerrequiredpoolobjectrequired2 fields
group_idsstring[]requiredperson_idsstring[]required
scorecard_idstring | nullrequiredfeedback_due_hoursintegerrequiredscorecardobject | nullrequiredWhat interviewers rate at this step (null: no scorecard, only a recommendation and words).
2 fields
skillsobject[]required4 fields
idstringrequirednamestringrequiredpromptstring | nullrequiredlevelsstring[]required4–4 items.
overall_questionstring | nullrequired
template_idstring | nullrequiredinterviews"in_bizisy" | "outside"requiredHow interviews run for this job (its own choice, else the company default).
interviews_override"in_bizisy" | "outside"requiredanswer_daysintegerrequiredWorking days to answer each candidate (its own, else the company default).
answer_days_overrideinteger | nullrequiredfree_sitesbooleanrequiredaudience"public" | "internal_first" | "internal_only"requiredWho the job is for (Settings → Hiring → Internal jobs): public (the careers page, the feed and Me), internal_first (Me only for internal_days, then also public), internal_only (Me only: never the careers page, feed or job sites).
internal_daysinteger | nullrequiredinternal_first: days in Me before it goes public (null: the company default).
public_fromstring | nullrequiredinternal_first: when it went (or goes) public; null while internal.
listed_publiclybooleanrequiredShown on the careers page and the feed now.
referral_bonusobjectrequiredThis job's own referral bonus; null follows the company's (Settings → Hiring).
4 fields (one of several shapes)
Option 1
kind"none"required
Option 2
kind"amount"requiredamountnumberrequiredcurrencystringrequired
hiring_managerobject | nullrequired2 fields
idstringrequirednamestringrequired
questionsobject[]required6 fields
idstringrequiredtextstringrequiredkind"text" | "yes_no" | "choice"requiredoptionsstring[]requiredbooleanrequiredexternal_onlybooleanrequiredShown to outside candidates only, never to people who work here.
valid_throughstring | nullrequiredcareers_pathstringrequiredIts address on the company's careers page, once open.
readyobjectrequiredWhether it can be opened, and what is missing: title, description (what you'll do), pay_range, gaps (a [[…]] left from the draft).
2 fields
okbooleanrequiredmissing"title" | "description" | "pay_range" | "gaps"[]required
opened_atstring | nullrequiredclosed_atstring | nullrequiredclose_reason"filled" | "cancelled" | "other"requiredclose_replyobject | nullrequiredClosed with "reply to everyone still open": when the kind "not this time" goes out to them.
1 field
send_atstringrequired
created_atstringrequiredupdated_atstringrequiredwarningsobject[]requiredThe wording check (never blocks): words that put people off or exclude them, with suggestions.
4 fields
field"title" | "what_you_do" | "what_you_need" | "what_you_get" | "how_it_goes"requiredtermstringrequiredcategory"age" | "gender" | "family" | "origin" | "health" | "looks"requiredsuggestionsstring[]required
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/jobs.pause \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"job_id":"j1"}'const res = await fetch('https://api.bizisy.com/v1/hiring/jobs.pause', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"job_id": "j1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/jobs.pause",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"job_id": "j1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "j1",
"position_id": "pos1",
"slug": "line-cook",
"status": "paused",
"title": "Line cook",
"unit": {
"id": "u1",
"name": "Kitchen"
},
"location": {
"id": "l1",
"name": "Braga kitchen",
"city": "Braga",
"country": "PT"
},
"workplace": "on_site",
"country": "PT",
"contract_type": "permanent",
"weekly_hours": 40,
"employment_type": "full_time",
"salary": {
"min": 18000,
"max": 22000,
"currency": "EUR",
"period": "year",
"source": "position"
},
"salary_hidden": false,
"language": "en",
"post": {
"what_you_do": "Prepare the mise en place and cook the lunch service with a team of four.",
"what_you_need": "Two years in a professional kitchen and a food hygiene certificate.",
"what_you_get": "- Pay: €18,000–€22,000 a year\n- A permanent contract\n- Full time, 40 hours a week\n- On site in Braga\n\nMeals on shift.",
"how_it_goes": "Then an offer."
},
"process": {
"promise": "We answer within 5 working days.",
"steps": [
"Talking · 30 mins",
"Trial shift · 4 hrs"
]
},
"steps": [
{
"id": "talking",
"name": "Talking",
"kind": "call",
"minutes": 30,
"buffer_minutes": 15,
"place": "phone",
"address": null,
"video_link": null,
"interviewers_needed": 0,
"pool": {
"group_ids": [],
"person_ids": []
},
"scorecard_id": null,
"feedback_due_hours": 24,
"scorecard": null
},
{
"id": "trial",
"name": "Trial shift",
"kind": "trial",
"minutes": 240,
"buffer_minutes": 30,
"place": "on_site",
"address": "Rua do Souto 12, Braga",
"video_link": null,
"interviewers_needed": 1,
"pool": {
"group_ids": [
"g1"
],
"person_ids": [
"p2"
]
},
"scorecard_id": null,
"feedback_due_hours": 24,
"scorecard": {
"skills": [
{
"id": "practical",
"name": "Practical work",
"prompt": "Watch how they work: quality, pace, safety, asking for help.",
"levels": [
"Could not do the tasks safely or correctly.",
"Did the tasks with frequent help or mistakes.",
"Did the tasks well at a good pace; asked when unsure.",
"Quick, careful and independent; improved as it went on."
]
},
{
"id": "teamwork",
"name": "Working with others",
"prompt": "Ask about a time they disagreed with a colleague and what happened.",
"levels": [
"Blamed others or avoided the question.",
"Works with others, but the examples were thin.",
"Good examples of working with others and settling disagreements.",
"Lifts the team: shares credit, gives and takes feedback well."
]
}
],
"overall_question": "What would this person bring to the team, and what support would they need?"
}
}
],
"template_id": "simple",
"interviews": "outside",
"interviews_override": null,
"answer_days": 5,
"answer_days_override": null,
"free_sites": true,
"referral_bonus": null,
"audience": "public",
"internal_days": null,
"public_from": null,
"listed_publicly": true,
"hiring_manager": {
"id": "p2",
"name": "Rita Lopes"
},
"questions": [
{
"id": "right_to_work",
"text": "Do you have the right to work in the EU?",
"kind": "yes_no",
"required": true,
"external_only": true
}
],
"valid_through": null,
"careers_path": "/careers/line-cook",
"ready": {
"ok": true,
"missing": []
},
"opened_at": "2026-10-18T09:00:00.000Z",
"closed_at": null,
"close_reason": null,
"close_reply": null,
"created_at": "2026-10-17T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z",
"warnings": []
}
}Close a job#
POST/v1/hiring/jobs.closeWrite
Closes a draft, open or paused job: it leaves the careers page and the feed, and takes no more applicants; its interviews still to come and offered times are cancelled (the interviewers get the cancellation). reason: filled (someone was hired), cancelled (the role is no longer needed) or other. Filling or cancelling its position closes it by itself. reply_to_open true: everyone still open gets the kind "not this time" (H23) after reply_in_days (default the company's reply_days; reopening the job before then cancels it); on an already closed job (closed by a hire) it only schedules that reply. reply_to_open is refused over an API key or MCP (it emails candidates). A job that was published sends the hiring.job_closed webhook. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Closing with reply_to_open (it emails candidates) happens in the app only.
- MCP tool
hiring_jobs_closeon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
job_idstringrequired1–100 characters.
reason"filled" | "cancelled" | "other"requiredreply_to_openbooleanSend everyone still open the kind "not this time".
Default
false.reply_in_daysintegerFrom 0 to 14.
Returns
41 fields
idstringrequiredposition_idstringrequiredslugstringrequiredstatus"draft" | "open" | "paused" | "closed"requiredtitlestringrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
locationobject | nullrequired4 fields
idstringrequirednamestringrequiredcitystring | nullrequiredcountrystringrequired
workplace"on_site" | "hybrid" | "remote"requiredcountrystring | nullrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredweekly_hoursnumber | nullrequiredemployment_type"full_time" | "part_time" | "contract" | "temporary" | "internship"requiredsalaryobject | nullrequiredThe range the post shows (from the position's budget or band, or set on the job).
5 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredsource"position" | "band" | "job"required
salary_hiddenbooleanrequiredTrue over an API key or MCP before the job was first opened: the range is the budget until it is published.
language"en" | "pt" | "es" | "fr" | "de"requiredpostobjectrequired4 fields
what_you_dostringrequiredwhat_you_needstringrequiredwhat_you_getstringrequiredhow_it_goesstringrequired
processobjectrequiredWhat the post's "How it goes" shows above post.how_it_goes (the company's note), in the job's language: the answer promise and each step with its length, from answer_days and the steps. Change the steps to change it.
2 fields
promisestringrequiredstepsstring[]required
stepsobject[]required13 fields
idstringrequirednamestringrequiredkindstring (enum)requiredOne of:
call,interview,panel,task,trial,presentation,references,final.minutesnumber | nullrequiredbuffer_minutesintegerrequiredMinutes kept clear after the interview.
place"video" | "video_auto" | "phone" | "on_site" | "none"requiredaddressstring | nullrequiredIn person: the address.
video_linkstring | nullrequiredVideo (pasted): the meeting link.
interviewers_neededintegerrequiredpoolobjectrequired2 fields
group_idsstring[]requiredperson_idsstring[]required
scorecard_idstring | nullrequiredfeedback_due_hoursintegerrequiredscorecardobject | nullrequiredWhat interviewers rate at this step (null: no scorecard, only a recommendation and words).
2 fields
skillsobject[]required4 fields
idstringrequirednamestringrequiredpromptstring | nullrequiredlevelsstring[]required4–4 items.
overall_questionstring | nullrequired
template_idstring | nullrequiredinterviews"in_bizisy" | "outside"requiredHow interviews run for this job (its own choice, else the company default).
interviews_override"in_bizisy" | "outside"requiredanswer_daysintegerrequiredWorking days to answer each candidate (its own, else the company default).
answer_days_overrideinteger | nullrequiredfree_sitesbooleanrequiredaudience"public" | "internal_first" | "internal_only"requiredWho the job is for (Settings → Hiring → Internal jobs): public (the careers page, the feed and Me), internal_first (Me only for internal_days, then also public), internal_only (Me only: never the careers page, feed or job sites).
internal_daysinteger | nullrequiredinternal_first: days in Me before it goes public (null: the company default).
public_fromstring | nullrequiredinternal_first: when it went (or goes) public; null while internal.
listed_publiclybooleanrequiredShown on the careers page and the feed now.
referral_bonusobjectrequiredThis job's own referral bonus; null follows the company's (Settings → Hiring).
4 fields (one of several shapes)
Option 1
kind"none"required
Option 2
kind"amount"requiredamountnumberrequiredcurrencystringrequired
hiring_managerobject | nullrequired2 fields
idstringrequirednamestringrequired
questionsobject[]required6 fields
idstringrequiredtextstringrequiredkind"text" | "yes_no" | "choice"requiredoptionsstring[]requiredbooleanrequiredexternal_onlybooleanrequiredShown to outside candidates only, never to people who work here.
valid_throughstring | nullrequiredcareers_pathstringrequiredIts address on the company's careers page, once open.
readyobjectrequiredWhether it can be opened, and what is missing: title, description (what you'll do), pay_range, gaps (a [[…]] left from the draft).
2 fields
okbooleanrequiredmissing"title" | "description" | "pay_range" | "gaps"[]required
opened_atstring | nullrequiredclosed_atstring | nullrequiredclose_reason"filled" | "cancelled" | "other"requiredclose_replyobject | nullrequiredClosed with "reply to everyone still open": when the kind "not this time" goes out to them.
1 field
send_atstringrequired
created_atstringrequiredupdated_atstringrequiredwarningsobject[]requiredThe wording check (never blocks): words that put people off or exclude them, with suggestions.
4 fields
field"title" | "what_you_do" | "what_you_need" | "what_you_get" | "how_it_goes"requiredtermstringrequiredcategory"age" | "gender" | "family" | "origin" | "health" | "looks"requiredsuggestionsstring[]required
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/jobs.close \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"job_id":"j1","reason":"filled","reply_to_open":true,"reply_in_days":2}'const res = await fetch('https://api.bizisy.com/v1/hiring/jobs.close', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"job_id": "j1",
"reason": "filled",
"reply_to_open": true,
"reply_in_days": 2
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/jobs.close",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"job_id": "j1",
"reason": "filled",
"reply_to_open": True,
"reply_in_days": 2,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "j1",
"position_id": "pos1",
"slug": "line-cook",
"status": "closed",
"title": "Line cook",
"unit": {
"id": "u1",
"name": "Kitchen"
},
"location": {
"id": "l1",
"name": "Braga kitchen",
"city": "Braga",
"country": "PT"
},
"workplace": "on_site",
"country": "PT",
"contract_type": "permanent",
"weekly_hours": 40,
"employment_type": "full_time",
"salary": {
"min": 18000,
"max": 22000,
"currency": "EUR",
"period": "year",
"source": "position"
},
"salary_hidden": false,
"language": "en",
"post": {
"what_you_do": "Prepare the mise en place and cook the lunch service with a team of four.",
"what_you_need": "Two years in a professional kitchen and a food hygiene certificate.",
"what_you_get": "- Pay: €18,000–€22,000 a year\n- A permanent contract\n- Full time, 40 hours a week\n- On site in Braga\n\nMeals on shift.",
"how_it_goes": "Then an offer."
},
"process": {
"promise": "We answer within 5 working days.",
"steps": [
"Talking · 30 mins",
"Trial shift · 4 hrs"
]
},
"steps": [
{
"id": "talking",
"name": "Talking",
"kind": "call",
"minutes": 30,
"buffer_minutes": 15,
"place": "phone",
"address": null,
"video_link": null,
"interviewers_needed": 0,
"pool": {
"group_ids": [],
"person_ids": []
},
"scorecard_id": null,
"feedback_due_hours": 24,
"scorecard": null
},
{
"id": "trial",
"name": "Trial shift",
"kind": "trial",
"minutes": 240,
"buffer_minutes": 30,
"place": "on_site",
"address": "Rua do Souto 12, Braga",
"video_link": null,
"interviewers_needed": 1,
"pool": {
"group_ids": [
"g1"
],
"person_ids": [
"p2"
]
},
"scorecard_id": null,
"feedback_due_hours": 24,
"scorecard": {
"skills": [
{
"id": "practical",
"name": "Practical work",
"prompt": "Watch how they work: quality, pace, safety, asking for help.",
"levels": [
"Could not do the tasks safely or correctly.",
"Did the tasks with frequent help or mistakes.",
"Did the tasks well at a good pace; asked when unsure.",
"Quick, careful and independent; improved as it went on."
]
},
{
"id": "teamwork",
"name": "Working with others",
"prompt": "Ask about a time they disagreed with a colleague and what happened.",
"levels": [
"Blamed others or avoided the question.",
"Works with others, but the examples were thin.",
"Good examples of working with others and settling disagreements.",
"Lifts the team: shares credit, gives and takes feedback well."
]
}
],
"overall_question": "What would this person bring to the team, and what support would they need?"
}
}
],
"template_id": "simple",
"interviews": "outside",
"interviews_override": null,
"answer_days": 5,
"answer_days_override": null,
"free_sites": true,
"referral_bonus": null,
"audience": "public",
"internal_days": null,
"public_from": null,
"listed_publicly": true,
"hiring_manager": {
"id": "p2",
"name": "Rita Lopes"
},
"questions": [
{
"id": "right_to_work",
"text": "Do you have the right to work in the EU?",
"kind": "yes_no",
"required": true,
"external_only": true
}
],
"valid_through": null,
"careers_path": "/careers/line-cook",
"ready": {
"ok": true,
"missing": []
},
"opened_at": "2026-10-18T09:00:00.000Z",
"closed_at": "2026-11-02T09:00:00.000Z",
"close_reason": "filled",
"close_reply": null,
"created_at": "2026-10-17T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z",
"warnings": []
}
}Draft a job post from the position#
POST/v1/hiring/jobs.draft_postRead
Drafts the four sections of a job's post (what_you_do, what_you_need, what_you_get, how_it_goes) from its position's role profile, the job's pay range, contract, hours and place, the company's benefits text, in the job's language (how_it_goes is only a closing note: the post shows the answer promise and steps from the job) (or language: en, pt, es, fr, de). Fixed templates, no AI model, in Markdown-lite (paragraphs and "- " lists); what only the company knows is left as a [[…]] gap to fill. Saves nothing: send the text you keep with hiring_jobs_update. Owners, admins and HR, or the job's hiring manager.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
hiring_jobs_draft_poston HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
job_idstringrequired1–100 characters.
language"en" | "pt" | "es" | "fr" | "de"
Returns
language"en" | "pt" | "es" | "fr" | "de"requiredpostobjectrequired4 fields
what_you_dostringrequiredwhat_you_needstringrequiredwhat_you_getstringrequiredhow_it_goesstringrequired
gapsbooleanrequiredSome [[…]] text is left to fill.
warningsobject[]required4 fields
field"title" | "what_you_do" | "what_you_need" | "what_you_get" | "how_it_goes"requiredtermstringrequiredcategory"age" | "gender" | "family" | "origin" | "health" | "looks"requiredsuggestionsstring[]required
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/jobs.draft_post \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"job_id":"j1","language":"de"}'const res = await fetch('https://api.bizisy.com/v1/hiring/jobs.draft_post', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"job_id": "j1",
"language": "de"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/jobs.draft_post",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"job_id": "j1",
"language": "de",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"language": "de",
"post": {
"what_you_do": "Prepare the mise en place and cook the lunch service with a team of four.",
"what_you_need": "[[List what the job really needs: skills, experience, languages, licences. Leave out what is only nice to have.]]",
"what_you_get": "- Pay: €18,000–€22,000 a year\n- A permanent contract\n- Full time, 40 hours a week\n- On site in Braga\n\nMeals on shift.",
"how_it_goes": "Then an offer."
},
"gaps": true,
"warnings": []
}
}Check a job post's wording#
POST/v1/hiring/jobs.check_wordingRead
The wording check on a title and post (never blocks): words that put people off or exclude them by age, gender, family, origin, health or looks, per language (en, pt, es, fr, de), each with suggestions; in German and French also a title without (m/w/d) or (H/F). Give job_id to check a job as saved, with title or post to check edits to it; or language with title and post to check any text. Owners, admins and HR, or a hiring manager.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
hiring_jobs_check_wordingon HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
job_idstring1–100 characters.
language"en" | "pt" | "es" | "fr" | "de"titlestringUp to 120 characters.
postobject4 fields
what_you_dostringUp to 5000 characters.
what_you_needstringUp to 5000 characters.
what_you_getstringUp to 5000 characters.
how_it_goesstringUp to 5000 characters.
Returns
language"en" | "pt" | "es" | "fr" | "de"requiredwarningsobject[]required4 fields
field"title" | "what_you_do" | "what_you_need" | "what_you_get" | "how_it_goes"requiredtermstringrequiredcategory"age" | "gender" | "family" | "origin" | "health" | "looks"requiredsuggestionsstring[]required
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/jobs.check_wording \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"language": "de",
"title": "Koch",
"post": {
"what_you_do": "Ein junges Team."
}
}'const res = await fetch('https://api.bizisy.com/v1/hiring/jobs.check_wording', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"language": "de",
"title": "Koch",
"post": {
"what_you_do": "Ein junges Team."
}
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/jobs.check_wording",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"language": "de",
"title": "Koch",
"post": {
"what_you_do": "Ein junges Team.",
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"language": "de",
"warnings": [
{
"field": "title",
"term": "Koch",
"category": "gender",
"suggestions": [
"Koch (m/w/d)"
]
},
{
"field": "what_you_do",
"term": "junges Team",
"category": "age",
"suggestions": [
"motiviert",
"engagiert"
]
}
]
}
}List hiring plans#
POST/v1/hiring/templates.listRead
The hiring plans a job can start from (its steps between New and Offer, and its form questions): the built-ins — simple (one step "Talking", nobody else asked), office (Office roles), engineering, warehouse (Warehouse and shifts), sales — named in language (en, pt, es, fr, de; default the company's) until HR changes one, and the company's own plans. Archived plans only with include_archived. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
hiring_templates_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
language"en" | "pt" | "es" | "fr" | "de"include_archivedbooleanDefault
false.
Returns
An array of objects with 7 fields
An array of objects:
idstringrequiredA built-in plan's key (simple, office, engineering, warehouse, sales) or the company's own plan's id.
namestringrequiredbuiltinbooleanrequiredchangedbooleanrequiredA built-in plan HR has changed.
stepsobject[]required13 fields
idstringrequirednamestringrequiredkindstring (enum)requiredOne of:
call,interview,panel,task,trial,presentation,references,final.minutesnumber | nullrequiredbuffer_minutesintegerrequiredMinutes kept clear after the interview.
place"video" | "video_auto" | "phone" | "on_site" | "none"requiredaddressstring | nullrequiredIn person: the address.
video_linkstring | nullrequiredVideo (pasted): the meeting link.
interviewers_neededintegerrequiredpoolobjectrequired2 fields
group_idsstring[]requiredperson_idsstring[]required
scorecard_idstring | nullrequiredfeedback_due_hoursintegerrequiredscorecardobject | nullrequiredWhat interviewers rate at this step (null: no scorecard, only a recommendation and words).
2 fields
skillsobject[]required4 fields
idstringrequirednamestringrequiredpromptstring | nullrequiredlevelsstring[]required4–4 items.
overall_questionstring | nullrequired
questionsobject[]required6 fields
idstringrequiredtextstringrequiredkind"text" | "yes_no" | "choice"requiredoptionsstring[]requiredbooleanrequiredexternal_onlybooleanrequiredShown to outside candidates only, never to people who work here.
archivedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/templates.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"language":"pt","include_archived":true}'const res = await fetch('https://api.bizisy.com/v1/hiring/templates.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"language": "pt",
"include_archived": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/templates.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"language": "pt",
"include_archived": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"id": "simple",
"name": "Simple",
"builtin": true,
"changed": false,
"steps": [
{
"id": "talking",
"name": "Talking",
"kind": "call",
"minutes": 30,
"buffer_minutes": 15,
"place": "phone",
"address": null,
"video_link": null,
"interviewers_needed": 0,
"pool": {
"group_ids": [],
"person_ids": []
},
"scorecard_id": null,
"feedback_due_hours": 24,
"scorecard": null
}
],
"questions": [
{
"id": "right_to_work",
"text": "Do you have the right to work in the EU?",
"kind": "yes_no",
"required": true,
"external_only": true
}
],
"archived": false
}
]
}Create a hiring plan#
POST/v1/hiring/templates.createWrite
Saves a hiring plan for later jobs: name, steps (1 to 10, as in hiring_jobs_update) and questions (at most 2), or from_job_id to save a job's steps and questions as they are. At most 50 plans of the company's own. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
hiring_templates_createon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
namestringrequired1–60 characters.
stepsobject[]The steps between New and Offer, in order (1 to 10).
1–10 items.
12 fields
idstringKeep the id of an existing step to keep its candidates in it; leave it out for a new step.
1–40 characters.
namestringrequiredWhat the company and the candidate call it, e.g. "Phone call", "Trial shift".
1–60 characters.
kindstring (enum)requiredcall, interview, panel, task, trial, presentation, references or final.
One of:
call,interview,panel,task,trial,presentation,references,final.minutesinteger | nullHow long the interview lasts, 15 to 480 minutes (e.g. intro call 30, technical interview 120, trial day 480). Default by kind for steps with interviewers.
From 15 to 480.
buffer_minutesintegerMinutes kept clear after it, 0 to 60 (default 15).
From 0 to 60.
place"video" | "video_auto" | "phone" | "on_site" | "none"video (with the link HR pastes), video_auto (a Google Meet or Microsoft Teams link made by the company's connected calendar for each interview: hiring_interviews_calendar says which; booking is refused while no calendar is connected), phone, on_site (in person) or none (a task done at home). Default: by kind.
addressstring | nullIn person (on_site): the address the candidate and interviewers go to.
1–300 characters.
video_linkURL | nullVideo: the meeting link HR pastes (Meet, Teams, Zoom…); sent with the invitation.
Up to 500 characters.
interviewers_neededintegerColleagues who interview together at this step (0: nobody is asked). Default 0 for call, task and references, else 1.
From 0 to 5.
poolobjectWho may interview at this step: interview groups and people. Leave out to keep it as it is.
2 fields
group_idsstring[]Interview groups (hiring_pools_list).
Up to 20 items.
person_idsstring[]People (person ids).
Up to 50 items.
feedback_due_hoursintegerHours after the interview to send feedback (default 24).
From 1 to 336.
scorecardobject | nullWhat interviewers rate at this step: up to 8 skills, each with four anchored descriptions (1 to 4), and an optional overall question. null removes it; leave out to keep it.
2 fields
skillsobject[]requiredUp to 8 skills, each rated 1 to 4.
Up to 8 items.
4 fields
idstringKeep a skill's id to keep the ratings already given on it; leave it out for a new skill.
1–40 characters.
namestringrequiredWhat is rated, e.g. "Problem solving".
1–60 characters.
promptstring | nullWhat to ask or look for (shown to the interviewer).
1–300 characters.
levelsany[]requiredWhat each rating looks like, from 1 (clear concerns) to 4 (excellent): four short anchored descriptions.
4–4 items.
overall_questionstring | nullAn optional question every interviewer answers in their own words.
1–300 characters.
questionsobject[]At most 2 extra questions on the form (yes/no, a choice or short text).
Up to 2 items.
7 fields
idstring1–40 characters.
textstringrequired3–200 characters.
kind"text" | "yes_no" | "choice"requiredoptionsstring[]For kind choice: 2 to 6 answers.
1–60 characters. 2–6 items.
requiredbooleanDefault
false.external_onlybooleanOnly for candidates from outside the company: people who work here don't see it when they apply from My workspace (internal jobs). Default: true for right-to-work, work-permit, visa and residence questions, else false.
job_relatedtruerequiredConfirms the question is about the job itself (H14). Questions about pay history, age, family, health, religion or pregnancy are refused.
from_job_idstring1–100 characters.
Returns
7 fields
idstringrequiredA built-in plan's key (simple, office, engineering, warehouse, sales) or the company's own plan's id.
namestringrequiredbuiltinbooleanrequiredchangedbooleanrequiredA built-in plan HR has changed.
stepsobject[]required13 fields
idstringrequirednamestringrequiredkindstring (enum)requiredOne of:
call,interview,panel,task,trial,presentation,references,final.minutesnumber | nullrequiredbuffer_minutesintegerrequiredMinutes kept clear after the interview.
place"video" | "video_auto" | "phone" | "on_site" | "none"requiredaddressstring | nullrequiredIn person: the address.
video_linkstring | nullrequiredVideo (pasted): the meeting link.
interviewers_neededintegerrequiredpoolobjectrequired2 fields
group_idsstring[]requiredperson_idsstring[]required
scorecard_idstring | nullrequiredfeedback_due_hoursintegerrequiredscorecardobject | nullrequiredWhat interviewers rate at this step (null: no scorecard, only a recommendation and words).
2 fields
skillsobject[]required4 fields
idstringrequirednamestringrequiredpromptstring | nullrequiredlevelsstring[]required4–4 items.
overall_questionstring | nullrequired
questionsobject[]required6 fields
idstringrequiredtextstringrequiredkind"text" | "yes_no" | "choice"requiredoptionsstring[]requiredbooleanrequiredexternal_onlybooleanrequiredShown to outside candidates only, never to people who work here.
archivedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/templates.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Kitchen",
"steps": [
{
"name": "Talking",
"kind": "call"
}
],
"questions": []
}'const res = await fetch('https://api.bizisy.com/v1/hiring/templates.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"name": "Kitchen",
"steps": [
{
"name": "Talking",
"kind": "call"
}
],
"questions": []
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/templates.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "Kitchen",
"steps": [
{
"name": "Talking",
"kind": "call",
},
],
"questions": [],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "tpl1",
"name": "Kitchen",
"builtin": false,
"changed": false,
"steps": [
{
"id": "talking",
"name": "Talking",
"kind": "call",
"minutes": 30,
"buffer_minutes": 15,
"place": "phone",
"address": null,
"video_link": null,
"interviewers_needed": 0,
"pool": {
"group_ids": [],
"person_ids": []
},
"scorecard_id": null,
"feedback_due_hours": 24,
"scorecard": null
}
],
"questions": [
{
"id": "right_to_work",
"text": "Do you have the right to work in the EU?",
"kind": "yes_no",
"required": true,
"external_only": true
}
],
"archived": false
}
}Change a hiring plan#
POST/v1/hiring/templates.updateWrite
Changes a hiring plan (a built-in one too): name, steps (1 to 10), questions (at most 2). Jobs already made from it keep their own steps. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
hiring_templates_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
template_idstringrequired1–100 characters.
namestring1–60 characters.
stepsobject[]The steps between New and Offer, in order (1 to 10).
1–10 items.
12 fields
idstringKeep the id of an existing step to keep its candidates in it; leave it out for a new step.
1–40 characters.
namestringrequiredWhat the company and the candidate call it, e.g. "Phone call", "Trial shift".
1–60 characters.
kindstring (enum)requiredcall, interview, panel, task, trial, presentation, references or final.
One of:
call,interview,panel,task,trial,presentation,references,final.minutesinteger | nullHow long the interview lasts, 15 to 480 minutes (e.g. intro call 30, technical interview 120, trial day 480). Default by kind for steps with interviewers.
From 15 to 480.
buffer_minutesintegerMinutes kept clear after it, 0 to 60 (default 15).
From 0 to 60.
place"video" | "video_auto" | "phone" | "on_site" | "none"video (with the link HR pastes), video_auto (a Google Meet or Microsoft Teams link made by the company's connected calendar for each interview: hiring_interviews_calendar says which; booking is refused while no calendar is connected), phone, on_site (in person) or none (a task done at home). Default: by kind.
addressstring | nullIn person (on_site): the address the candidate and interviewers go to.
1–300 characters.
video_linkURL | nullVideo: the meeting link HR pastes (Meet, Teams, Zoom…); sent with the invitation.
Up to 500 characters.
interviewers_neededintegerColleagues who interview together at this step (0: nobody is asked). Default 0 for call, task and references, else 1.
From 0 to 5.
poolobjectWho may interview at this step: interview groups and people. Leave out to keep it as it is.
2 fields
group_idsstring[]Interview groups (hiring_pools_list).
Up to 20 items.
person_idsstring[]People (person ids).
Up to 50 items.
feedback_due_hoursintegerHours after the interview to send feedback (default 24).
From 1 to 336.
scorecardobject | nullWhat interviewers rate at this step: up to 8 skills, each with four anchored descriptions (1 to 4), and an optional overall question. null removes it; leave out to keep it.
2 fields
skillsobject[]requiredUp to 8 skills, each rated 1 to 4.
Up to 8 items.
4 fields
idstringKeep a skill's id to keep the ratings already given on it; leave it out for a new skill.
1–40 characters.
namestringrequiredWhat is rated, e.g. "Problem solving".
1–60 characters.
promptstring | nullWhat to ask or look for (shown to the interviewer).
1–300 characters.
levelsany[]requiredWhat each rating looks like, from 1 (clear concerns) to 4 (excellent): four short anchored descriptions.
4–4 items.
overall_questionstring | nullAn optional question every interviewer answers in their own words.
1–300 characters.
questionsobject[]At most 2 extra questions on the form (yes/no, a choice or short text).
Up to 2 items.
7 fields
idstring1–40 characters.
textstringrequired3–200 characters.
kind"text" | "yes_no" | "choice"requiredoptionsstring[]For kind choice: 2 to 6 answers.
1–60 characters. 2–6 items.
requiredbooleanDefault
false.external_onlybooleanOnly for candidates from outside the company: people who work here don't see it when they apply from My workspace (internal jobs). Default: true for right-to-work, work-permit, visa and residence questions, else false.
job_relatedtruerequiredConfirms the question is about the job itself (H14). Questions about pay history, age, family, health, religion or pregnancy are refused.
Returns
7 fields
idstringrequiredA built-in plan's key (simple, office, engineering, warehouse, sales) or the company's own plan's id.
namestringrequiredbuiltinbooleanrequiredchangedbooleanrequiredA built-in plan HR has changed.
stepsobject[]required13 fields
idstringrequirednamestringrequiredkindstring (enum)requiredOne of:
call,interview,panel,task,trial,presentation,references,final.minutesnumber | nullrequiredbuffer_minutesintegerrequiredMinutes kept clear after the interview.
place"video" | "video_auto" | "phone" | "on_site" | "none"requiredaddressstring | nullrequiredIn person: the address.
video_linkstring | nullrequiredVideo (pasted): the meeting link.
interviewers_neededintegerrequiredpoolobjectrequired2 fields
group_idsstring[]requiredperson_idsstring[]required
scorecard_idstring | nullrequiredfeedback_due_hoursintegerrequiredscorecardobject | nullrequiredWhat interviewers rate at this step (null: no scorecard, only a recommendation and words).
2 fields
skillsobject[]required4 fields
idstringrequirednamestringrequiredpromptstring | nullrequiredlevelsstring[]required4–4 items.
overall_questionstring | nullrequired
questionsobject[]required6 fields
idstringrequiredtextstringrequiredkind"text" | "yes_no" | "choice"requiredoptionsstring[]requiredbooleanrequiredexternal_onlybooleanrequiredShown to outside candidates only, never to people who work here.
archivedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/templates.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"template_id": "office",
"name": "Office",
"steps": [
{
"id": "call",
"name": "Quick call",
"kind": "call"
}
]
}'const res = await fetch('https://api.bizisy.com/v1/hiring/templates.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"template_id": "office",
"name": "Office",
"steps": [
{
"id": "call",
"name": "Quick call",
"kind": "call"
}
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/templates.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"template_id": "office",
"name": "Office",
"steps": [
{
"id": "call",
"name": "Quick call",
"kind": "call",
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "office",
"name": "Office",
"builtin": true,
"changed": true,
"steps": [
{
"id": "talking",
"name": "Talking",
"kind": "call",
"minutes": 30,
"buffer_minutes": 15,
"place": "phone",
"address": null,
"video_link": null,
"interviewers_needed": 0,
"pool": {
"group_ids": [],
"person_ids": []
},
"scorecard_id": null,
"feedback_due_hours": 24,
"scorecard": null
}
],
"questions": [
{
"id": "right_to_work",
"text": "Do you have the right to work in the EU?",
"kind": "yes_no",
"required": true,
"external_only": true
}
],
"archived": false
}
}Archive a hiring plan#
POST/v1/hiring/templates.archiveWrite
Archives a hiring plan (archived false brings it back): new jobs can no longer start from it; jobs made from it keep their steps. Built-in plans can be archived too. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
hiring_templates_archiveon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
template_idstringrequired1–100 characters.
archivedbooleanDefault
true.
Returns
7 fields
idstringrequiredA built-in plan's key (simple, office, engineering, warehouse, sales) or the company's own plan's id.
namestringrequiredbuiltinbooleanrequiredchangedbooleanrequiredA built-in plan HR has changed.
stepsobject[]required13 fields
idstringrequirednamestringrequiredkindstring (enum)requiredOne of:
call,interview,panel,task,trial,presentation,references,final.minutesnumber | nullrequiredbuffer_minutesintegerrequiredMinutes kept clear after the interview.
place"video" | "video_auto" | "phone" | "on_site" | "none"requiredaddressstring | nullrequiredIn person: the address.
video_linkstring | nullrequiredVideo (pasted): the meeting link.
interviewers_neededintegerrequiredpoolobjectrequired2 fields
group_idsstring[]requiredperson_idsstring[]required
scorecard_idstring | nullrequiredfeedback_due_hoursintegerrequiredscorecardobject | nullrequiredWhat interviewers rate at this step (null: no scorecard, only a recommendation and words).
2 fields
skillsobject[]required4 fields
idstringrequirednamestringrequiredpromptstring | nullrequiredlevelsstring[]required4–4 items.
overall_questionstring | nullrequired
questionsobject[]required6 fields
idstringrequiredtextstringrequiredkind"text" | "yes_no" | "choice"requiredoptionsstring[]requiredbooleanrequiredexternal_onlybooleanrequiredShown to outside candidates only, never to people who work here.
archivedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/templates.archive \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"template_id":"office","archived":false}'const res = await fetch('https://api.bizisy.com/v1/hiring/templates.archive', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"template_id": "office",
"archived": false
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/templates.archive",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"template_id": "office",
"archived": False,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "office",
"name": "Simple",
"builtin": true,
"changed": true,
"steps": [
{
"id": "talking",
"name": "Talking",
"kind": "call",
"minutes": 30,
"buffer_minutes": 15,
"place": "phone",
"address": null,
"video_link": null,
"interviewers_needed": 0,
"pool": {
"group_ids": [],
"person_ids": []
},
"scorecard_id": null,
"feedback_due_hours": 24,
"scorecard": null
}
],
"questions": [
{
"id": "right_to_work",
"text": "Do you have the right to work in the EU?",
"kind": "yes_no",
"required": true,
"external_only": true
}
],
"archived": false
}
}Get hiring settings#
POST/v1/hiring/settings.getRead
Settings → Hiring: the careers page (headline, about text, the cover photo (its images, focal point and size; set with hiring_settings_cover_start and hiring_settings_cover_set), whether benefits show and their text, the company's own privacy link if any, the contact for candidates' privacy questions), the candidate privacy notice Bizisy writes (privacy_notice: the employers it names as controller, the contact it shows, and what is missing for a fuller one), how interviews run by default (in_bizisy: with colleagues; outside: HR records them), the answer promise in working days (default 5), the days before a "not this time" email goes out (reply_days, default 2), how long applications not hired are kept after a job closes per country (defaults: PT, ES, FR, DE 6 months; NL 4 weeks; others 6 months; never above 24 months) and the period that applies to this company, candidate email text overrides by template key, and referrals (off by default) with the optional bonus (amount, currency, when it is earned: start, probation or months, who is excluded), and offers: when an offer needs approval (above_range, every_offer or off), who approves (hr or owner), the days an offer stays open and who signs offer letters. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
hiring_settings_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
13 fields
careersobjectrequired8 fields
headlinestring | nullrequiredThe careers page's headline; null: "Work with us at <company>" in the visitor's language.
aboutstring | nullrequiredcoverobject | nullrequiredThe careers page's cover photo behind the headline (hiring_settings_cover_set); null: none, the company's colour.
7 fields
imagesobjectrequiredPaths on the company's address: the 1600×600 and 800×300 crops (WebP and JPEG) the careers page shows, and the whole photo (to pick a focal point).
5 fields
large_webpstringrequiredlarge_jpegstringrequiredsmall_webpstringrequiredsmall_jpegstringrequiredsourcestringrequired
focalobjectrequiredThe point kept in view, 0–1 across and down the whole photo.
2 fields
xnumberrequiredynumberrequired
positionobjectrequiredWhere the focal point lands in the crops (0–1).
2 fields
xnumberrequiredynumberrequired
widthintegerrequiredheightintegerrequiredbytesintegerrequiredWhat the photo's files take in the company's storage.
updated_atstringrequired
cover_availablebooleanrequiredWhether this server stores cover photos (the cover actions work).
show_benefitsbooleanrequiredbenefitsstring | nullrequiredprivacy_urlstring | nullrequiredThe company's own privacy notice for candidates (https); null: candidates see the one Bizisy writes at <company address>/careers/privacy.
privacy_contact_emailstring | nullrequiredWho candidates write to about their data, in Bizisy's notice; null: none (the notice points candidates to their status page; never anyone's personal email by default).
privacy_noticeobjectrequiredThe candidate privacy notice Bizisy writes for the company (shown unless careers.privacy_url is set).
4 fields
employersobject[]requiredThe controller(s) the notice names: the employers (legal entities) of the open jobs, else the company's first legal entity, with their registered address when set.
4 fields
legal_namestringrequiredcountrystringrequiredtax_idstring | nullrequiredaddressobject | nullrequired5 fields
line1stringrequiredline2string | nullrequiredpostal_codestring | nullrequiredcitystringrequiredregionstring | nullrequired
contact_emailstring | nullrequiredThe contact the notice shows; null: none (the notice points candidates to their status page).
contact_from"settings"requiredsettings: careers.privacy_contact_email; null: none set.
missing"legal_entity" | "tax_id" | "address" | "contact_email"[]requiredWhat would make the notice fuller: a legal entity (Company → Legal entities), its tax id, its postal address (optional), a contact email for privacy questions (careers.privacy_contact_email). The notice works without them.
interviews"in_bizisy" | "outside"requiredanswer_daysintegerrequiredreply_daysintegerrequiredDays between deciding "not this time" and the kind email going out (0: at once).
retentionobjectrequiredThe company's own periods per country (ISO code).
retention_defaultsobjectrequiredBizisy's defaults per country; other countries: 6 months.
company_retentionobjectrequiredThe period that applies to this company (its country).
3 fields
countrystring | nullrequiredvalueintegerrequiredunit"weeks" | "months"required
emailsobjectrequiredreferralsobjectrequired2 fields
enabledbooleanrequiredbonusobjectrequired6 fields
enabledbooleanrequiredamountnumber | nullrequiredcurrencystringrequiredearned"start" | "probation" | "months"requiredmonthsinteger | nullrequiredexcluded"hr" | "hiring_manager"[]required
offersobjectrequired4 fields
approval"above_range" | "every_offer" | "off"requiredabove_range (default): offers above the job's published range need approval; every_offer; off.
approvers"hr" | "owner"requiredhr (default): owners, admins and HR; owner: owners only. Never the person who proposed the offer.
default_expiry_daysintegerrequiredDays a sent offer stays open (default 7).
signer_person_idstring | nullrequiredWho signs offer letters for the company; null: the job's hiring manager.
internalobjectrequired10 fields
enabledbooleanrequiredInternal jobs on (off by default): people who work here see jobs in My workspace → Jobs and apply from there.
default_audience"public" | "internal_first" | "internal_only"requiredWho new jobs are for: public (default), internal_first or internal_only.
internal_daysintegerrequiredinternal_first: days in Me before a job also goes public (default 7).
tell_manager"on_apply" | "on_interview" | "on_offer" | "at_transfer"requiredWhen the applicant's manager is told: on_apply, on_interview (default: when the application first moves into an interview-type step), on_offer, at_transfer. Earlier when the manager is on the job's hiring team, or approves job changes.
nudge_manager_talkbooleanrequiredThe form suggests talking to your manager first (a nudge, never a checkbox).
min_months_in_jobinteger | nullrequiredMinimum months in the current job before applying (null: none; 3, 6 or 12).
allow_in_probationbooleanrequiredPeople still in probation may apply (default true).
include_outsidersbooleanrequiredContractors and outsiders with a login also see internal jobs (default false).
max_live_per_personintegerrequiredLive internal applications per person (1–10, default 5).
sentencestringrequiredThe notice the apply form shows with this rule, for a sample manager.
updated_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/settings.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/hiring/settings.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/settings.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"careers": {
"headline": null,
"about": "We cook for 300 people a day in Braga.",
"cover": {
"images": {
"large_webp": "https://acme.bizisy.com/api/careers/cover/01k0000000000000000000000v/1600.webp",
"large_jpeg": "https://acme.bizisy.com/api/careers/cover/01k0000000000000000000000v/1600.jpg",
"small_webp": "https://acme.bizisy.com/api/careers/cover/01k0000000000000000000000v/800.webp",
"small_jpeg": "https://acme.bizisy.com/api/careers/cover/01k0000000000000000000000v/800.jpg",
"source": "https://acme.bizisy.com/api/careers/cover/01k0000000000000000000000v/source.webp"
},
"focal": {
"x": 0.4,
"y": 0.6
},
"position": {
"x": 0.45,
"y": 0.5
},
"width": 2400,
"height": 1600,
"bytes": 812000,
"updated_at": "2026-10-18T09:00:00.000Z"
},
"cover_available": true,
"show_benefits": true,
"benefits": "Meals on shift.",
"privacy_url": null,
"privacy_contact_email": null
},
"privacy_notice": {
"employers": [
{
"legal_name": "Acme Lda",
"country": "PT",
"tax_id": "PT509876543",
"address": {
"line1": "Rua do Souto 10",
"line2": null,
"postal_code": "4700-329",
"city": "Braga",
"region": null
}
}
],
"contact_email": null,
"contact_from": null,
"missing": [
"contact_email"
]
},
"interviews": "outside",
"answer_days": 5,
"reply_days": 2,
"retention": {},
"retention_defaults": {
"PT": {
"value": 6,
"unit": "months"
},
"NL": {
"value": 4,
"unit": "weeks"
}
},
"company_retention": {
"country": "PT",
"value": 6,
"unit": "months"
},
"emails": {},
"referrals": {
"enabled": true,
"bonus": {
"enabled": true,
"amount": 500,
"currency": "EUR",
"earned": "probation",
"months": null,
"excluded": [
"hr",
"hiring_manager"
]
}
},
"offers": {
"approval": "above_range",
"approvers": "hr",
"default_expiry_days": 7,
"signer_person_id": null
},
"internal": {
"enabled": true,
"default_audience": "public",
"internal_days": 7,
"tell_manager": "on_interview",
"nudge_manager_talk": true,
"min_months_in_job": null,
"allow_in_probation": true,
"include_outsiders": false,
"max_live_per_person": 5,
"sentence": "Ana Costa, your manager, will be told if you're invited to an interview. Until then, only HR and the hiring team see your application."
},
"updated_at": "2026-10-18T09:00:00.000Z"
}
}Change hiring settings#
POST/v1/hiring/settings.updateWrite
Changes Settings → Hiring; send only what changes. careers: headline (one line, ≤ 80 characters; null: "Work with us at <company>" in the visitor's language), about (≤ 3,000 characters), show_benefits, benefits (text, ≤ 2,000), privacy_url (https: the company's own privacy notice for candidates, shown instead of the one Bizisy writes; null: Bizisy's), privacy_contact_email (the contact for privacy questions in Bizisy's notice; null: none, the notice points candidates to their status page). interviews: in_bizisy (colleagues interview in Bizisy: interview groups, usual weeks, booking and candidate self-booking for steps with interviewers) or outside (HR records interviews held elsewhere); the default for jobs that don't choose their own; switching to outside is refused while such jobs have interviews booked or offered. answer_days: 1 to 30 working days. reply_days: 0 to 14 days before a "not this time" email goes out (cancellable until then). retention: periods per country code ({value, unit: weeks or months}, at most 24 months; null removes a country's own period so the default applies). emails: text overrides per template key (received, not_this_time, invite_to_book, booked, reminder, link_request, pool_renewal, referral_invite), {subject, body}; null removes one. referrals: enabled, and bonus {enabled, amount, currency, earned: start, probation or months (with months), excluded: hr and/or hiring_manager}. offers: approval (above_range: pay above the job's published range needs approval, the default; every_offer; off), approvers (hr: owners, admins and HR; owner: owners only; never the proposer), default_expiry_days (1 to 60), signer_person_id (a person who signs offer letters for the company; null: each job's hiring manager). internal (internal jobs, off by default): enabled, default_audience (public, internal_first, internal_only), internal_days (1 to 60), tell_manager (when an applicant's manager is told: on_apply, on_interview — the default —, on_offer, at_transfer), nudge_manager_talk, min_months_in_job (null, 3, 6 or 12), allow_in_probation, include_outsiders (contractors and outsiders with a login see internal jobs), max_live_per_person (1 to 10). Owners, admins and HR, signed in to Bizisy: refused over MCP or an API key (the bonus is money paid to people).
- Web app only
- Refused for API keys and connected apps. Hiring settings change in the app only (Settings → Hiring): they include the referral bonus.
- MCP tool
hiring_settings_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
careersobject6 fields
headlinestring | nullUp to 80 characters. Pattern
^[^\r\n]*$.aboutstring | nullUp to 3000 characters.
show_benefitsbooleanbenefitsstring | nullUp to 2000 characters.
privacy_urlURL | nullUp to 500 characters.
privacy_contact_emailemail | nullUp to 254 characters.
interviews"in_bizisy" | "outside"answer_daysintegerFrom 1 to 30.
reply_daysintegerFrom 0 to 14.
retentionobjectemailsobject8 fields
receivedobject | nullrequired2 fields
subjectstring | nullrequiredUp to 200 characters.
bodystring | nullrequiredUp to 5000 characters.
not_this_timeobject | nullrequired2 fields
subjectstring | nullrequiredUp to 200 characters.
bodystring | nullrequiredUp to 5000 characters.
invite_to_bookobject | nullrequired2 fields
subjectstring | nullrequiredUp to 200 characters.
bodystring | nullrequiredUp to 5000 characters.
bookedobject | nullrequired2 fields
subjectstring | nullrequiredUp to 200 characters.
bodystring | nullrequiredUp to 5000 characters.
reminderobject | nullrequired2 fields
subjectstring | nullrequiredUp to 200 characters.
bodystring | nullrequiredUp to 5000 characters.
link_requestobject | nullrequired2 fields
subjectstring | nullrequiredUp to 200 characters.
bodystring | nullrequiredUp to 5000 characters.
pool_renewalobject | nullrequired2 fields
subjectstring | nullrequiredUp to 200 characters.
bodystring | nullrequiredUp to 5000 characters.
referral_inviteobject | nullrequired2 fields
subjectstring | nullrequiredUp to 200 characters.
bodystring | nullrequiredUp to 5000 characters.
referralsobject2 fields
enabledbooleanbonusobject6 fields
enabledbooleanamountnumber | nullFrom 0 to 1000000.
currencyanyearned"start" | "probation" | "months"monthsinteger | nullFrom 1 to 24.
excluded"hr" | "hiring_manager"[]Up to 2 items.
offersobject4 fields
approval"above_range" | "every_offer" | "off"approvers"hr" | "owner"default_expiry_daysintegerFrom 1 to 60.
signer_person_idstring | null1–100 characters.
internalobject9 fields
enabledbooleandefault_audience"public" | "internal_first" | "internal_only"internal_daysintegerFrom 1 to 60.
tell_manager"on_apply" | "on_interview" | "on_offer" | "at_transfer"nudge_manager_talkbooleanmin_months_in_job3 | 6 | 12allow_in_probationbooleaninclude_outsidersbooleanmax_live_per_personintegerFrom 1 to 10.
Returns
13 fields
careersobjectrequired8 fields
headlinestring | nullrequiredThe careers page's headline; null: "Work with us at <company>" in the visitor's language.
aboutstring | nullrequiredcoverobject | nullrequiredThe careers page's cover photo behind the headline (hiring_settings_cover_set); null: none, the company's colour.
7 fields
imagesobjectrequiredPaths on the company's address: the 1600×600 and 800×300 crops (WebP and JPEG) the careers page shows, and the whole photo (to pick a focal point).
5 fields
large_webpstringrequiredlarge_jpegstringrequiredsmall_webpstringrequiredsmall_jpegstringrequiredsourcestringrequired
focalobjectrequiredThe point kept in view, 0–1 across and down the whole photo.
2 fields
xnumberrequiredynumberrequired
positionobjectrequiredWhere the focal point lands in the crops (0–1).
2 fields
xnumberrequiredynumberrequired
widthintegerrequiredheightintegerrequiredbytesintegerrequiredWhat the photo's files take in the company's storage.
updated_atstringrequired
cover_availablebooleanrequiredWhether this server stores cover photos (the cover actions work).
show_benefitsbooleanrequiredbenefitsstring | nullrequiredprivacy_urlstring | nullrequiredThe company's own privacy notice for candidates (https); null: candidates see the one Bizisy writes at <company address>/careers/privacy.
privacy_contact_emailstring | nullrequiredWho candidates write to about their data, in Bizisy's notice; null: none (the notice points candidates to their status page; never anyone's personal email by default).
privacy_noticeobjectrequiredThe candidate privacy notice Bizisy writes for the company (shown unless careers.privacy_url is set).
4 fields
employersobject[]requiredThe controller(s) the notice names: the employers (legal entities) of the open jobs, else the company's first legal entity, with their registered address when set.
4 fields
legal_namestringrequiredcountrystringrequiredtax_idstring | nullrequiredaddressobject | nullrequired5 fields
line1stringrequiredline2string | nullrequiredpostal_codestring | nullrequiredcitystringrequiredregionstring | nullrequired
contact_emailstring | nullrequiredThe contact the notice shows; null: none (the notice points candidates to their status page).
contact_from"settings"requiredsettings: careers.privacy_contact_email; null: none set.
missing"legal_entity" | "tax_id" | "address" | "contact_email"[]requiredWhat would make the notice fuller: a legal entity (Company → Legal entities), its tax id, its postal address (optional), a contact email for privacy questions (careers.privacy_contact_email). The notice works without them.
interviews"in_bizisy" | "outside"requiredanswer_daysintegerrequiredreply_daysintegerrequiredDays between deciding "not this time" and the kind email going out (0: at once).
retentionobjectrequiredThe company's own periods per country (ISO code).
retention_defaultsobjectrequiredBizisy's defaults per country; other countries: 6 months.
company_retentionobjectrequiredThe period that applies to this company (its country).
3 fields
countrystring | nullrequiredvalueintegerrequiredunit"weeks" | "months"required
emailsobjectrequiredreferralsobjectrequired2 fields
enabledbooleanrequiredbonusobjectrequired6 fields
enabledbooleanrequiredamountnumber | nullrequiredcurrencystringrequiredearned"start" | "probation" | "months"requiredmonthsinteger | nullrequiredexcluded"hr" | "hiring_manager"[]required
offersobjectrequired4 fields
approval"above_range" | "every_offer" | "off"requiredabove_range (default): offers above the job's published range need approval; every_offer; off.
approvers"hr" | "owner"requiredhr (default): owners, admins and HR; owner: owners only. Never the person who proposed the offer.
default_expiry_daysintegerrequiredDays a sent offer stays open (default 7).
signer_person_idstring | nullrequiredWho signs offer letters for the company; null: the job's hiring manager.
internalobjectrequired10 fields
enabledbooleanrequiredInternal jobs on (off by default): people who work here see jobs in My workspace → Jobs and apply from there.
default_audience"public" | "internal_first" | "internal_only"requiredWho new jobs are for: public (default), internal_first or internal_only.
internal_daysintegerrequiredinternal_first: days in Me before a job also goes public (default 7).
tell_manager"on_apply" | "on_interview" | "on_offer" | "at_transfer"requiredWhen the applicant's manager is told: on_apply, on_interview (default: when the application first moves into an interview-type step), on_offer, at_transfer. Earlier when the manager is on the job's hiring team, or approves job changes.
nudge_manager_talkbooleanrequiredThe form suggests talking to your manager first (a nudge, never a checkbox).
min_months_in_jobinteger | nullrequiredMinimum months in the current job before applying (null: none; 3, 6 or 12).
allow_in_probationbooleanrequiredPeople still in probation may apply (default true).
include_outsidersbooleanrequiredContractors and outsiders with a login also see internal jobs (default false).
max_live_per_personintegerrequiredLive internal applications per person (1–10, default 5).
sentencestringrequiredThe notice the apply form shows with this rule, for a sample manager.
updated_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/settings.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"careers": {
"about": "We cook for 300 people a day in Braga.",
"benefits": "Meals on shift.",
"show_benefits": true
},
"interviews": "outside",
"answer_days": 5,
"retention": {
"NL": null,
"PT": {
"value": 3,
"unit": "months"
}
},
"emails": {
"not_this_time": {
"subject": "Thank you",
"body": "We chose someone else this time."
}
},
"referrals": {
"enabled": true,
"bonus": {
"enabled": true,
"amount": 500,
"currency": "EUR",
"earned": "probation"
}
}
}'const res = await fetch('https://api.bizisy.com/v1/hiring/settings.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"careers": {
"about": "We cook for 300 people a day in Braga.",
"benefits": "Meals on shift.",
"show_benefits": true
},
"interviews": "outside",
"answer_days": 5,
"retention": {
"NL": null,
"PT": {
"value": 3,
"unit": "months"
}
},
"emails": {
"not_this_time": {
"subject": "Thank you",
"body": "We chose someone else this time."
}
},
"referrals": {
"enabled": true,
"bonus": {
"enabled": true,
"amount": 500,
"currency": "EUR",
"earned": "probation"
}
}
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/settings.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"careers": {
"about": "We cook for 300 people a day in Braga.",
"benefits": "Meals on shift.",
"show_benefits": True,
},
"interviews": "outside",
"answer_days": 5,
"retention": {
"NL": None,
"PT": {
"value": 3,
"unit": "months",
},
},
"emails": {
"not_this_time": {
"subject": "Thank you",
"body": "We chose someone else this time.",
},
},
"referrals": {
"enabled": True,
"bonus": {
"enabled": True,
"amount": 500,
"currency": "EUR",
"earned": "probation",
},
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"careers": {
"headline": null,
"about": "We cook for 300 people a day in Braga.",
"cover": {
"images": {
"large_webp": "https://acme.bizisy.com/api/careers/cover/01k0000000000000000000000v/1600.webp",
"large_jpeg": "https://acme.bizisy.com/api/careers/cover/01k0000000000000000000000v/1600.jpg",
"small_webp": "https://acme.bizisy.com/api/careers/cover/01k0000000000000000000000v/800.webp",
"small_jpeg": "https://acme.bizisy.com/api/careers/cover/01k0000000000000000000000v/800.jpg",
"source": "https://acme.bizisy.com/api/careers/cover/01k0000000000000000000000v/source.webp"
},
"focal": {
"x": 0.4,
"y": 0.6
},
"position": {
"x": 0.45,
"y": 0.5
},
"width": 2400,
"height": 1600,
"bytes": 812000,
"updated_at": "2026-10-18T09:00:00.000Z"
},
"cover_available": true,
"show_benefits": true,
"benefits": "Meals on shift.",
"privacy_url": null,
"privacy_contact_email": null
},
"privacy_notice": {
"employers": [
{
"legal_name": "Acme Lda",
"country": "PT",
"tax_id": "PT509876543",
"address": {
"line1": "Rua do Souto 10",
"line2": null,
"postal_code": "4700-329",
"city": "Braga",
"region": null
}
}
],
"contact_email": null,
"contact_from": null,
"missing": [
"contact_email"
]
},
"interviews": "outside",
"answer_days": 5,
"reply_days": 2,
"retention": {},
"retention_defaults": {
"PT": {
"value": 6,
"unit": "months"
},
"NL": {
"value": 4,
"unit": "weeks"
}
},
"company_retention": {
"country": "PT",
"value": 6,
"unit": "months"
},
"emails": {},
"referrals": {
"enabled": true,
"bonus": {
"enabled": true,
"amount": 500,
"currency": "EUR",
"earned": "probation",
"months": null,
"excluded": [
"hr",
"hiring_manager"
]
}
},
"offers": {
"approval": "above_range",
"approvers": "hr",
"default_expiry_days": 7,
"signer_person_id": null
},
"internal": {
"enabled": true,
"default_audience": "public",
"internal_days": 7,
"tell_manager": "on_interview",
"nudge_manager_talk": true,
"min_months_in_job": null,
"allow_in_probation": true,
"include_outsiders": false,
"max_live_per_person": 5,
"sentence": "Ana Costa, your manager, will be told if you're invited to an interview. Until then, only HR and the hiring team see your application."
},
"updated_at": "2026-10-18T09:00:00.000Z"
}
}Start uploading the careers page cover photo#
POST/v1/hiring/settings.cover_startWrite
Step 1 of 2 to set the careers page's cover photo (shown behind its headline, under a dark overlay so the text stays readable): send the file's name, size (at most 5 MB), content_type (image/jpeg, image/png or image/webp) and sha256 (lowercase hex). PUT the bytes to upload.url with exactly upload.headers within 15 minutes, then call hiring_settings_cover_set with the file_id and a focal point. Refused when the company's storage is full. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
hiring_settings_cover_starton HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
namestringrequired1–200 characters.
sizeintegerrequiredFrom 0 to 5000000.
content_type"image/jpeg" | "image/png" | "image/webp"requiredimage/jpeg, image/png or image/webp: checked against the bytes.
sha256stringrequiredPattern
^[0-9a-f]{64}$.
Returns
file_idstringrequireduploadobject | nullrequirednull on a dry run.
4 fields
urlstringrequiredmethod"PUT"requiredheadersobjectrequiredresumablefalserequired
expires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/settings.cover_start \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "team.jpg",
"size": 812000,
"content_type": "image/jpeg",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}'const res = await fetch('https://api.bizisy.com/v1/hiring/settings.cover_start', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"name": "team.jpg",
"size": 812000,
"content_type": "image/jpeg",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/settings.cover_start",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "team.jpg",
"size": 812000,
"content_type": "image/jpeg",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"file_id": "f1",
"upload": {
"url": "https://storage.example/upload",
"method": "PUT",
"headers": {
"content-type": "image/jpeg"
},
"resumable": false
},
"expires_at": "2026-10-18T09:15:00.000Z"
}
}Set the careers page cover photo#
POST/v1/hiring/settings.cover_setWrite
Step 2 of 2 (after hiring_settings_cover_start), or a new focal point for the current photo (leave out file_id). The photo is checked by its bytes (JPEG, PNG or WebP, at most 5 MB, at least 800×300 pixels, at most 24 megapixels), re-encoded without its metadata (EXIF and GPS dropped) and cropped to 8:3 around the focal point (focal_x, focal_y: 0–1 across and down the photo; 0.5, 0.5 is the centre): 1600×600 and 800×300, WebP and JPEG. It replaces the previous cover and counts in the company's storage. The careers page is public: use a photo of the workplace or the team that everyone in it agreed to show. At most 30 changes a day. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
hiring_settings_cover_seton HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
file_idstring1–64 characters.
focal_xnumberFrom 0 to 1. Default
0.5.focal_ynumberFrom 0 to 1. Default
0.5.
Returns
coverobjectrequired7 fields
imagesobjectrequiredPaths on the company's address: the 1600×600 and 800×300 crops (WebP and JPEG) the careers page shows, and the whole photo (to pick a focal point).
5 fields
large_webpstringrequiredlarge_jpegstringrequiredsmall_webpstringrequiredsmall_jpegstringrequiredsourcestringrequired
focalobjectrequiredThe point kept in view, 0–1 across and down the whole photo.
2 fields
xnumberrequiredynumberrequired
positionobjectrequiredWhere the focal point lands in the crops (0–1).
2 fields
xnumberrequiredynumberrequired
widthintegerrequiredheightintegerrequiredbytesintegerrequiredWhat the photo's files take in the company's storage.
updated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/settings.cover_set \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"file_id":"f1","focal_x":0.4,"focal_y":0.6}'const res = await fetch('https://api.bizisy.com/v1/hiring/settings.cover_set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"file_id": "f1",
"focal_x": 0.4,
"focal_y": 0.6
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/settings.cover_set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"file_id": "f1",
"focal_x": 0.4,
"focal_y": 0.6,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"cover": {
"images": {
"large_webp": "https://acme.bizisy.com/api/careers/cover/01k0000000000000000000000v/1600.webp",
"large_jpeg": "https://acme.bizisy.com/api/careers/cover/01k0000000000000000000000v/1600.jpg",
"small_webp": "https://acme.bizisy.com/api/careers/cover/01k0000000000000000000000v/800.webp",
"small_jpeg": "https://acme.bizisy.com/api/careers/cover/01k0000000000000000000000v/800.jpg",
"source": "https://acme.bizisy.com/api/careers/cover/01k0000000000000000000000v/source.webp"
},
"focal": {
"x": 0.4,
"y": 0.6
},
"position": {
"x": 0.45,
"y": 0.5
},
"width": 2400,
"height": 1600,
"bytes": 812000,
"updated_at": "2026-10-18T09:00:00.000Z"
}
}
}Remove the careers page cover photo#
POST/v1/hiring/settings.cover_removeDestructive
Removes the careers page's cover photo and deletes its files; the page shows the company's colour behind its headline again. Succeeds when there is none. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
hiring_settings_cover_removeon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
No input: send {}.
Returns
cover"null"required
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/settings.cover_remove \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/hiring/settings.cover_remove', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/settings.cover_remove",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"cover": null
}
}Preview a job's page#
POST/v1/hiring/jobs.preview_pageRead
The job's page on the careers page exactly as candidates would get it, with unsaved changes laid over the saved job: title, language (the post's), post sections (Markdown-lite, ≤ 5,000 characters each), workplace, salary {min, max, currency, period}, contract_type, weekly_hours, answer_days, valid_through and questions (at most 2, checked as when saving). "How it goes" shows the steps of the job's interview plan. page_language: the language of the page around the post (en, pt, es, fr, de; default the post's). focus: the part being edited, outlined (title, facts, what_you_do, what_you_need, what_you_get, how_it_goes, apply). Returns the page as HTML marked "Preview — not public", with no scripts, the apply form switched off and links that go nowhere. Saves nothing. Owners, admins and HR any job; a hiring manager their own, changing only the title, language, post and questions. In the app only; at most 60 previews a minute per person.
- Web app only
- Refused for API keys and connected apps. Live previews of a job's page show in the app only (Hiring → the job → Job post); machines read the job with hiring.jobs.get.
- MCP tool
hiring_jobs_preview_pageon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
job_idstringrequired1–100 characters.
page_language"en" | "pt" | "es" | "fr" | "de"focusstring (enum)One of:
title,facts,what_you_do,what_you_need,what_you_get,how_it_goes,apply.titlestringUp to 120 characters.
language"en" | "pt" | "es" | "fr" | "de"postobject4 fields
what_you_dostringUp to 5000 characters.
what_you_needstringUp to 5000 characters.
what_you_getstringUp to 5000 characters.
how_it_goesstringUp to 5000 characters.
workplace"on_site" | "hybrid" | "remote"salaryobject | null4 fields
minnumberrequiredFrom 0 to 100000000.
maxnumberrequiredFrom 0 to 100000000.
currencyanyrequiredperiod"year" | "month" | "hour"required
contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"weekly_hoursnumber | nullFrom 0 to 80.
answer_daysinteger | nullFrom 1 to 30.
valid_throughstring | nullPattern
^\d{4}-\d{2}-\d{2}$.questionsobject[]At most 2 extra questions on the form (yes/no, a choice or short text).
Up to 2 items.
7 fields
idstring1–40 characters.
textstringrequired3–200 characters.
kind"text" | "yes_no" | "choice"requiredoptionsstring[]For kind choice: 2 to 6 answers.
1–60 characters. 2–6 items.
requiredbooleanDefault
false.external_onlybooleanOnly for candidates from outside the company: people who work here don't see it when they apply from My workspace (internal jobs). Default: true for right-to-work, work-permit, visa and residence questions, else false.
job_relatedtruerequiredConfirms the question is about the job itself (H14). Questions about pay history, age, family, health, religion or pregnancy are refused.
Returns
htmlstringrequiredThe whole page as candidates would get it, as one HTML document (styles inline, no scripts): show it in a sandboxed frame.
language"en" | "pt" | "es" | "fr" | "de"requiredThe language the page is shown in.
pathstringrequiredWhere the page lives on the company's address once published (/careers or /careers/<job>).
examplebooleanrequiredTrue when a sample job, marked "Example", stands in for jobs the company has not opened yet.
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/jobs.preview_page \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"job_id": "j1",
"page_language": "pt",
"focus": "what_you_do",
"title": "Head cook",
"language": "en",
"post": {
"what_you_do": "Cook the **lunch** service."
},
"workplace": "hybrid",
"salary": {
"min": 20000,
"max": 24000,
"currency": "EUR",
"period": "year"
},
"contract_type": "permanent",
"weekly_hours": 40,
"answer_days": 3,
"valid_through": "2026-12-31",
"questions": [
{
"text": "Can you work weekends?",
"kind": "yes_no",
"required": true,
"job_related": true
}
]
}'const res = await fetch('https://api.bizisy.com/v1/hiring/jobs.preview_page', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"job_id": "j1",
"page_language": "pt",
"focus": "what_you_do",
"title": "Head cook",
"language": "en",
"post": {
"what_you_do": "Cook the **lunch** service."
},
"workplace": "hybrid",
"salary": {
"min": 20000,
"max": 24000,
"currency": "EUR",
"period": "year"
},
"contract_type": "permanent",
"weekly_hours": 40,
"answer_days": 3,
"valid_through": "2026-12-31",
"questions": [
{
"text": "Can you work weekends?",
"kind": "yes_no",
"required": true,
"job_related": true
}
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/jobs.preview_page",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"job_id": "j1",
"page_language": "pt",
"focus": "what_you_do",
"title": "Head cook",
"language": "en",
"post": {
"what_you_do": "Cook the **lunch** service.",
},
"workplace": "hybrid",
"salary": {
"min": 20000,
"max": 24000,
"currency": "EUR",
"period": "year",
},
"contract_type": "permanent",
"weekly_hours": 40,
"answer_days": 3,
"valid_through": "2026-12-31",
"questions": [
{
"text": "Can you work weekends?",
"kind": "yes_no",
"required": True,
"job_related": True,
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"html": "<!doctype html><html lang=\"en\"><body><div class=\"pv-banner\" role=\"note\">Preview — not public · applying is off</div></body></html>",
"language": "en",
"path": "/careers/line-cook",
"example": false
}
}Preview the careers page#
POST/v1/hiring/settings.preview_pageRead
The careers page (page careers, the default) or a job's page (page job: the newest open job, else a draft or paused one) exactly as candidates would get them, with unsaved Settings → Hiring changes laid over the saved ones: careers {headline (≤ 80 characters, one line), about (≤ 3,000), show_benefits, benefits (≤ 2,000)} and answer_days (1 to 30). The careers page lists the company's open jobs; with none, a sample job marked "Example" shows (example true). page_language: en, pt, es, fr or de (default the company's). focus: the part being edited, outlined (headline, about, benefits, promise). Returns the page as HTML marked "Preview — not public", with no scripts, the apply form switched off and links that go nowhere. Saves nothing. Owners, admins and HR, in the app only; at most 60 previews a minute per person.
- Web app only
- Refused for API keys and connected apps. Live previews of the careers page show in the app only (Settings → Hiring).
- MCP tool
hiring_settings_preview_pageon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
page"careers" | "job"Default
"careers".page_language"en" | "pt" | "es" | "fr" | "de"focus"headline" | "about" | "benefits" | "promise"careersobject4 fields
headlinestring | nullUp to 80 characters. Pattern
^[^\r\n]*$.aboutstring | nullUp to 3000 characters.
show_benefitsbooleanbenefitsstring | nullUp to 2000 characters.
answer_daysintegerFrom 1 to 30.
Returns
htmlstringrequiredThe whole page as candidates would get it, as one HTML document (styles inline, no scripts): show it in a sandboxed frame.
language"en" | "pt" | "es" | "fr" | "de"requiredThe language the page is shown in.
pathstringrequiredWhere the page lives on the company's address once published (/careers or /careers/<job>).
examplebooleanrequiredTrue when a sample job, marked "Example", stands in for jobs the company has not opened yet.
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/settings.preview_page \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"page": "job",
"page_language": "en",
"focus": "headline",
"careers": {
"headline": "Cook with us",
"about": "We cook for Braga.",
"show_benefits": true,
"benefits": "Meals on shift."
},
"answer_days": 5
}'const res = await fetch('https://api.bizisy.com/v1/hiring/settings.preview_page', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"page": "job",
"page_language": "en",
"focus": "headline",
"careers": {
"headline": "Cook with us",
"about": "We cook for Braga.",
"show_benefits": true,
"benefits": "Meals on shift."
},
"answer_days": 5
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/settings.preview_page",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"page": "job",
"page_language": "en",
"focus": "headline",
"careers": {
"headline": "Cook with us",
"about": "We cook for Braga.",
"show_benefits": True,
"benefits": "Meals on shift.",
},
"answer_days": 5,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"html": "<!doctype html><html lang=\"pt\"><body><div class=\"pv-banner\" role=\"note\">Pré-visualização — não é pública</div></body></html>",
"language": "pt",
"path": "/careers",
"example": true
}
}Preview an email to candidates#
POST/v1/hiring/settings.preview_emailRead
An email candidates get, rendered exactly as it is sent, with sample data: the candidate "Maria Santos", the company's real name, its newest job (else a sample one) and sample dates. template: application_received, status_link, cv_added, next_step, message, not_this_time, interview_times, interview_booked, interview_reminder, offer_sent, offer_reminder, offer_withdrawn, pool_joined, pool_renewal, referral_invite. language: en, pt, es, fr or de (default the company's). For not_this_time, subject and body preview the company's own text before it is saved (null or empty: Bizisy's kind text; leave them out for the saved text); the other emails are Bizisy's text and take no override. Returns the subject, the HTML (show it in a sandboxed frame) and the plain text. Nothing is sent or stored, and its links lead nowhere. Owners, admins and HR, in the app only; at most 60 previews a minute per person.
- Web app only
- Refused for API keys and connected apps. Previews of the emails to candidates show in the app only (Settings → Hiring → Candidates).
- MCP tool
hiring_settings_preview_emailon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
templatestring (enum)requiredOne of:
application_received,status_link,cv_added,next_step,message,not_this_time,interview_times,interview_booked,interview_reminder,offer_sent,offer_reminder,offer_withdrawn,pool_joined,pool_renewal,referral_invite.language"en" | "pt" | "es" | "fr" | "de"subjectstring | nullUp to 200 characters.
bodystring | nullUp to 5000 characters.
Returns
7 fields
templatestring (enum)requiredOne of:
application_received,status_link,cv_added,next_step,message,not_this_time,interview_times,interview_booked,interview_reminder,offer_sent,offer_reminder,offer_withdrawn,pool_joined,pool_renewal,referral_invite.language"en" | "pt" | "es" | "fr" | "de"requiredtostringrequiredThe sample recipient.
subjectstringrequiredhtmlstringrequiredThe whole email as one HTML document.
textstringrequiredThe plain-text part.
own_textbooleanrequiredThe company's own words (not_this_time with an override or a saved text).
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/settings.preview_email \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"template": "not_this_time",
"language": "pt",
"subject": "A sua candidatura",
"body": "Obrigado."
}'const res = await fetch('https://api.bizisy.com/v1/hiring/settings.preview_email', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"template": "not_this_time",
"language": "pt",
"subject": "A sua candidatura",
"body": "Obrigado."
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/settings.preview_email",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"template": "not_this_time",
"language": "pt",
"subject": "A sua candidatura",
"body": "Obrigado.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"template": "not_this_time",
"language": "pt",
"to": "Maria Santos <maria.santos@example.com>",
"subject": "A sua candidatura",
"html": "<!doctype html><html lang=\"en\"><body><h1>We received your application</h1></body></html>",
"text": "We received your application",
"own_text": false
}
}List a job's candidates#
POST/v1/hiring/applications.listRead
A job's candidates on its board: columns New, the job's steps (by the company's names), Offer and Hired, with counts and how many are overdue (past the answer promise: no move or message by the date promised, in working days). status: open (default: still in the process), not_this_time, hired or all; column: one column; overdue: only those past the promise; source: careers, share, referral, job_site, talent_pool or manual; q: part of a name or email. Each candidate: name, column, status, source, whether a colleague referred them, when they applied and last moved, the date the company answers by, overdue, a "not this time" waiting to be sent, notes, and feedback in for the interviews held ("Feedback 1 of 2"). Owners, admins and HR any job; a hiring manager their own jobs; anyone else not_found. Never rank or score candidates from this: the order is the board's (oldest move first). At most limit (default 200, at most 1,000); total counts them all.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
hiring_applications_liston HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
job_idstringrequired1–100 characters.
status"open" | "not_this_time" | "hired" | "all"Default
"open".columnstring1–40 characters.
overduebooleansourcestring (enum)One of:
careers,share,referral,job_site,talent_pool,manual,internal.qstring1–100 characters.
limitintegerFrom 1 to 1000. Default
200.
Returns
jobobjectrequired3 fields
idstringrequiredtitlestringrequiredstatus"draft" | "open" | "paused" | "closed"required
columnsobject[]requiredNew, the job's steps, Offer, Hired, with the open candidates in each (Hired: those hired).
5 fields
keystringrequirednamestring | nullrequiredkind"new" | "step" | "offer" | "hired"requiredcountintegerrequiredoverdueintegerrequired
countsobjectrequired5 fields
activeintegerrequiredoverdueintegerrequirednot_this_timeintegerrequiredhiredintegerrequiredwithdrawnintegerrequired
applicationsobject[]required16 fields
idstringrequiredcandidateobjectrequired2 fields
idstringrequirednamestringrequired
columnstringrequirednew, a step id, offer or hired.
status"active" | "hired" | "rejected" | "withdrawn"requiredactive (in the process), hired, or rejected ("not this time", told or about to be).
sourcestring (enum)requiredOne of:
careers,share,referral,job_site,talent_pool,manual,internal.referredbooleanrequiredA colleague's referral (referrals on).
applied_atstringrequiredmoved_atstringrequiredanswer_due_onstring | nullrequiredThe answer promise: the date the company answers by (working days from the last move or message).
overduebooleanrequiredStill open and the promised date has passed.
replyobject | nullrequired"Not this time": when the kind email goes out (cancellable until sent).
3 fields
send_atstringrequiredemailbooleanrequiredsentbooleanrequired
has_cvbooleanrequiredcv_unread"no_credits"requiredManage only (null on the hiring manager's side, My workspace): no_credits = the CV needed Document AI when it arrived and the company had no AI credits left, so its details were not read; read it with hiring_applications_read_cv (1 AI credit). The candidate never knows.
notesintegerrequiredfeedbackobject | nullrequiredFeedback in for the interviews held ("Feedback 1 of 2"); null before any interview was held.
2 fields
submittedintegerrequiredexpectedintegerrequired
internalobject | nullrequiredW7: someone who works here, applying from My workspace — their current job (title, team, location, time with the company). Never pay, reviews or ratings.
7 fields
titlestring | nullrequiredunitstring | nullrequiredlocationstring | nullrequiredtenureobject | nullrequired2 fields
yearsintegerrequiredmonthsintegerrequired
start_datestring | nullrequirednotestring | nullrequired"Why this job?" (the hiring team and HR).
person_idstring | nullrequiredHR only: the person in People.
totalintegerrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/applications.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"job_id": "j1",
"status": "all",
"column": "talking",
"overdue": true,
"source": "referral",
"q": "silva",
"limit": 50
}'const res = await fetch('https://api.bizisy.com/v1/hiring/applications.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"job_id": "j1",
"status": "all",
"column": "talking",
"overdue": true,
"source": "referral",
"q": "silva",
"limit": 50
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/applications.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"job_id": "j1",
"status": "all",
"column": "talking",
"overdue": True,
"source": "referral",
"q": "silva",
"limit": 50,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"job": {
"id": "j1",
"title": "Line cook",
"status": "open"
},
"columns": [
{
"key": "new",
"name": null,
"kind": "new",
"count": 1,
"overdue": 1
},
{
"key": "talking",
"name": "Talking",
"kind": "step",
"count": 1,
"overdue": 0
},
{
"key": "trial",
"name": "Trial shift",
"kind": "step",
"count": 0,
"overdue": 0
},
{
"key": "offer",
"name": null,
"kind": "offer",
"count": 0,
"overdue": 0
},
{
"key": "hired",
"name": null,
"kind": "hired",
"count": 0,
"overdue": 0
}
],
"counts": {
"active": 2,
"overdue": 1,
"not_this_time": 3,
"hired": 0,
"withdrawn": 1
},
"applications": [
{
"id": "a2",
"candidate": {
"id": "c2",
"name": "João Reis"
},
"column": "new",
"status": "active",
"source": "careers",
"referred": false,
"applied_at": "2026-10-08T09:00:00.000Z",
"moved_at": "2026-10-08T09:00:00.000Z",
"answer_due_on": "2026-10-15",
"overdue": true,
"reply": null,
"has_cv": true,
"cv_unread": null,
"notes": 0,
"feedback": null,
"internal": null
},
{
"id": "a1",
"candidate": {
"id": "c1",
"name": "Maria Silva"
},
"column": "talking",
"status": "active",
"source": "referral",
"referred": true,
"applied_at": "2026-10-12T09:00:00.000Z",
"moved_at": "2026-10-14T09:00:00.000Z",
"answer_due_on": "2026-10-21",
"overdue": false,
"reply": null,
"has_cv": true,
"cv_unread": null,
"notes": 2,
"feedback": {
"submitted": 1,
"expected": 2
},
"internal": null
}
],
"total": 2
}
}Get a candidate#
POST/v1/hiring/applications.getRead
One candidate's application: name, email, phone, the CV (a download link valid for 5 minutes, in the app only), their answers with the questions, where they are and when they must be answered by, the colleague who referred them, their other applications at the company (for jobs you see), and what happened: moves, emails sent to them, notes (private ones for HR only), interviews and the internal reason of a "not this time". Owners, admins and HR any job; a hiring manager their own jobs. feedback_by_step: the interviewers' sent feedback per step (recommendation, ratings 1–4 per skill, words, correction notes) with "2 of 2 in" counts; drafts never; a hiring manager who also interviews this candidate reads the others' once they sent their own. Over an API key or MCP: no pay expectation, no private notes, no file links. Never rank, score or judge candidates from this (no averages across candidates), and never guess at age, health, family, religion or origin.
- Who can call it
- Manage key any Manage role
Me key anyone - Keys and apps
- No pay expectations, private notes or file links.
- MCP tool
hiring_applications_geton HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
application_idstringrequired1–100 characters.
Returns
27 fields
idstringrequiredcandidateobjectrequired8 fields
idstringrequirednamestringrequiredemailstringrequiredphonestring | nullrequiredcitystring | nullrequiredlinksstring[]requiredlanguage"en" | "pt" | "es" | "fr" | "de"requiredpoolobject | nullrequiredIn the talent pool until then (their consent).
1 field
untilstringrequired
columnstringrequirednew, a step id, offer or hired.
status"active" | "hired" | "rejected" | "withdrawn"requiredactive (in the process), hired, or rejected ("not this time", told or about to be).
sourcestring (enum)requiredOne of:
careers,share,referral,job_site,talent_pool,manual,internal.referredbooleanrequiredA colleague's referral (referrals on).
applied_atstringrequiredmoved_atstringrequiredanswer_due_onstring | nullrequiredThe answer promise: the date the company answers by (working days from the last move or message).
overduebooleanrequiredStill open and the promised date has passed.
replyobject | nullrequired"Not this time": when the kind email goes out (cancellable until sent).
3 fields
send_atstringrequiredemailbooleanrequiredsentbooleanrequired
has_cvbooleanrequiredcv_unread"no_credits"requiredManage only (null on the hiring manager's side, My workspace): no_credits = the CV needed Document AI when it arrived and the company had no AI credits left, so its details were not read; read it with hiring_applications_read_cv (1 AI credit). The candidate never knows.
notesintegerrequiredfeedbackobject | nullrequiredFeedback in for the interviews held ("Feedback 1 of 2"); null before any interview was held.
2 fields
submittedintegerrequiredexpectedintegerrequired
internalobject | nullrequiredW7: someone who works here, applying from My workspace — their current job (title, team, location, time with the company). Never pay, reviews or ratings.
7 fields
titlestring | nullrequiredunitstring | nullrequiredlocationstring | nullrequiredtenureobject | nullrequired2 fields
yearsintegerrequiredmonthsintegerrequired
start_datestring | nullrequirednotestring | nullrequired"Why this job?" (the hiring team and HR).
person_idstring | nullrequiredHR only: the person in People.
jobobjectrequired4 fields
idstringrequiredtitlestringrequiredstatus"draft" | "open" | "paused" | "closed"requiredlanguage"en" | "pt" | "es" | "fr" | "de"required
source_sitestring | nullrequiredcvobject | nullrequired4 fields
idstringrequirednamestringrequiredsizenumberrequiredurlstring | nullrequiredA download link valid for 5 minutes (in the app only).
answersobject[]required3 fields
question_idstringrequiredquestionstringrequiredanswerstringrequired
pay_expectationobject | nullrequired3 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
pay_hiddenbooleanrequiredTrue over an API key or MCP: pay expectations stay in the app.
referrerobject | nullrequiredThe colleague who referred them (referrals on).
2 fields
idstringrequirednamestringrequired
reply_reasonstring | nullrequiredother_applicationsobject[]required5 fields
idstringrequiredjob_idstringrequiredjob_titlestringrequiredstatus"active" | "hired" | "rejected" | "withdrawn"requiredcolumnstringrequired
eventsobject[]required15 fields
idstringrequiredkindstring (enum)requiredOne of:
received,added,moved,message,note,interview,feedback,offer,hired,rejected,reopened,withdrawn.atstringrequiredbyobject | nullrequiredThe colleague who did it; null for the candidate, Bizisy or a machine.
2 fields
idstringrequirednamestringrequired
privatebooleanrequiredA note only HR sees.
minebooleanrequiredYours (you can delete your own notes).
textstring | nullrequiredA note, a message's text or the interview notes.
subjectstring | nullrequiredtemplatestring | nullrequiredFor emails to the candidate: received, step, message, not_this_time, added, link.
fromstring | nullrequiredtostring | nullrequiredMoves: the columns.
datestring | nullrequiredInterviews: when it was held.
step_idstring | nullrequiredfileobject | nullrequired4 fields
idstringrequirednamestringrequiredsizenumberrequiredurlstring | nullrequiredA download link valid for 5 minutes (in the app only).
reasonstring | nullrequired"Not this time": the internal reason (never told).
feedback_by_stepobject[]requiredI11: interviewers' sent feedback per step with "2 of 2 in" counts (each person's recommendation, ratings and words). Summarise it for HR; never average, score or rank across candidates.
5 fields
stepobjectrequired2 fields
idstringrequirednamestring | nullrequired
interviewsintegerrequiredInterviews held at this step.
expectedintegerrequiredFeedback expected: one per interviewer of each interview held.
submittedintegerrequiredFeedback sent.
entriesobject[]requiredThe feedback you may read (HR and the hiring manager: every one sent). Never averaged or compared across candidates.
17 fields
idstringrequiredinterview_idstringrequiredapplication_idstring | nullrequiredstepobjectrequired2 fields
idstringrequirednamestring | nullrequired
authorobject | nullrequiredWho wrote it; null once they were erased (show "A former colleague").
2 fields
idstringrequirednamestringrequired
author_erasedbooleanrequiredminebooleanrequiredYours.
status"draft" | "submitted"requireddraft: only its author sees it; submitted: final (correction notes may follow).
ratingsobject[]required1 (clear concerns) to 4 (excellent) per skill of the step's scorecard.
3 fields
skill_idstringrequirednamestringrequiredratingintegerrequiredFrom 1 to 4.
textstringrequiredoverallstring | nullrequiredThe answer to the scorecard's overall question.
recommendation"strong_no" | "no" | "yes" | "strong_yes"requireddue_atstringrequiredsubmitted_atstring | nullrequiredon_timeboolean | nullrequiredSent by the time it was due.
notesobject[]requiredCorrections added after sending.
2 fields
textstringrequiredatstringrequired
updated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/applications.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"application_id":"a1"}'const res = await fetch('https://api.bizisy.com/v1/hiring/applications.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"application_id": "a1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/applications.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"application_id": "a1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "a1",
"candidate": {
"id": "c1",
"name": "Maria Silva",
"email": "maria.silva@mail.pt",
"phone": "+351 912 345 678",
"city": null,
"links": [],
"language": "en",
"pool": null
},
"column": "talking",
"status": "active",
"source": "referral",
"referred": true,
"applied_at": "2026-10-12T09:00:00.000Z",
"moved_at": "2026-10-14T09:00:00.000Z",
"answer_due_on": "2026-10-21",
"overdue": false,
"reply": null,
"has_cv": true,
"cv_unread": null,
"notes": 2,
"feedback": {
"submitted": 1,
"expected": 2
},
"internal": null,
"job": {
"id": "j1",
"title": "Line cook",
"status": "open",
"language": "en"
},
"source_site": null,
"cv": {
"id": "f1",
"name": "maria-silva-cv.pdf",
"size": 182000,
"url": "https://storage.example/f1?sig=x"
},
"answers": [
{
"question_id": "right_to_work",
"question": "Do you have the right to work in the EU?",
"answer": "yes"
}
],
"pay_expectation": null,
"pay_hidden": false,
"referrer": {
"id": "p3",
"name": "Rui Gomes"
},
"reply_reason": null,
"other_applications": [],
"events": [
{
"id": "e1",
"kind": "received",
"at": "2026-10-12T09:00:00.000Z",
"by": null,
"private": false,
"mine": false,
"text": null,
"subject": null,
"template": null,
"from": null,
"to": null,
"date": null,
"step_id": null,
"file": null,
"reason": null
},
{
"id": "e2",
"kind": "moved",
"at": "2026-10-14T09:00:00.000Z",
"by": {
"id": "p2",
"name": "Rita Lopes"
},
"private": false,
"mine": false,
"text": null,
"subject": null,
"template": null,
"from": "new",
"to": "talking",
"date": null,
"step_id": null,
"file": null,
"reason": null
},
{
"id": "e3",
"kind": "note",
"at": "2026-10-14T09:05:00.000Z",
"by": {
"id": "p1",
"name": "Ana Costa"
},
"private": false,
"mine": true,
"text": "Ran the kitchen at Taberna for two years.",
"subject": null,
"template": null,
"from": null,
"to": null,
"date": null,
"step_id": null,
"file": null,
"reason": null
}
],
"feedback_by_step": [
{
"step": {
"id": "trial",
"name": "Trial shift"
},
"interviews": 1,
"expected": 2,
"submitted": 1,
"entries": [
{
"id": "o1:iv0:p4",
"interview_id": "iv0",
"application_id": "a1",
"step": {
"id": "trial",
"name": "Trial shift"
},
"author": {
"id": "p4",
"name": "Ivo Matos"
},
"author_erased": false,
"mine": false,
"status": "submitted",
"ratings": [
{
"skill_id": "practical",
"name": "Practical work",
"rating": 3
},
{
"skill_id": "teamwork",
"name": "Working with others",
"rating": 4
}
],
"text": "Kept her station clean through the rush; asked before plating the specials.",
"overall": "Calm and reliable; would need a week on the grill.",
"recommendation": "yes",
"due_at": "2026-10-17T13:00:00.000Z",
"submitted_at": "2026-10-16T15:20:00.000Z",
"on_time": true,
"notes": [],
"updated_at": "2026-10-16T15:20:00.000Z"
}
]
}
]
}
}Move candidates#
POST/v1/hiring/applications.moveWrite
Moves one or more open candidates of a job (at most 100) to another column: new, one of the job's steps (step id from hiring_jobs_get) or offer. Hired is reached only by hiring them (hiring_applications_hire_draft, then the hire). email true (to a step only): each gets the step's email in the job's language, with text when given (your own words, e.g. how to book). The answer promise starts again from today. Sends the hiring.application_moved webhook. Owners, admins and HR, or the job's hiring manager, signed in to Bizisy: refused over an API key or MCP.
- Web app only
- Refused for API keys and connected apps. Moving candidates happens in the app: a person decides.
- MCP tool
hiring_applications_moveon HR Assistant, My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
job_idstringrequired1–100 characters.
application_idsstring[]required1–100 characters. 1–100 items.
tostringrequirednew, a step id or offer.
1–40 characters.
emailbooleanDefault
false.textstringUp to 3000 characters.
Returns
movedintegerrequiredemailedintegerrequiredapplicationsobject[]required16 fields
idstringrequiredcandidateobjectrequired2 fields
idstringrequirednamestringrequired
columnstringrequirednew, a step id, offer or hired.
status"active" | "hired" | "rejected" | "withdrawn"requiredactive (in the process), hired, or rejected ("not this time", told or about to be).
sourcestring (enum)requiredOne of:
careers,share,referral,job_site,talent_pool,manual,internal.referredbooleanrequiredA colleague's referral (referrals on).
applied_atstringrequiredmoved_atstringrequiredanswer_due_onstring | nullrequiredThe answer promise: the date the company answers by (working days from the last move or message).
overduebooleanrequiredStill open and the promised date has passed.
replyobject | nullrequired"Not this time": when the kind email goes out (cancellable until sent).
3 fields
send_atstringrequiredemailbooleanrequiredsentbooleanrequired
has_cvbooleanrequiredcv_unread"no_credits"requiredManage only (null on the hiring manager's side, My workspace): no_credits = the CV needed Document AI when it arrived and the company had no AI credits left, so its details were not read; read it with hiring_applications_read_cv (1 AI credit). The candidate never knows.
notesintegerrequiredfeedbackobject | nullrequiredFeedback in for the interviews held ("Feedback 1 of 2"); null before any interview was held.
2 fields
submittedintegerrequiredexpectedintegerrequired
internalobject | nullrequiredW7: someone who works here, applying from My workspace — their current job (title, team, location, time with the company). Never pay, reviews or ratings.
7 fields
titlestring | nullrequiredunitstring | nullrequiredlocationstring | nullrequiredtenureobject | nullrequired2 fields
yearsintegerrequiredmonthsintegerrequired
start_datestring | nullrequirednotestring | nullrequired"Why this job?" (the hiring team and HR).
person_idstring | nullrequiredHR only: the person in People.
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/applications.move \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"job_id": "j1",
"application_ids": [
"a1",
"a2"
],
"to": "trial",
"email": true,
"text": "Pick a day for the trial shift: reply with two that suit you."
}'const res = await fetch('https://api.bizisy.com/v1/hiring/applications.move', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"job_id": "j1",
"application_ids": [
"a1",
"a2"
],
"to": "trial",
"email": true,
"text": "Pick a day for the trial shift: reply with two that suit you."
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/applications.move",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"job_id": "j1",
"application_ids": [
"a1",
"a2",
],
"to": "trial",
"email": True,
"text": "Pick a day for the trial shift: reply with two that suit you.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"moved": 1,
"emailed": 1,
"applications": [
{
"id": "a1",
"candidate": {
"id": "c1",
"name": "Maria Silva"
},
"column": "trial",
"status": "active",
"source": "referral",
"referred": true,
"applied_at": "2026-10-12T09:00:00.000Z",
"moved_at": "2026-10-14T09:00:00.000Z",
"answer_due_on": "2026-10-21",
"overdue": false,
"reply": null,
"has_cv": true,
"cv_unread": null,
"notes": 2,
"feedback": {
"submitted": 1,
"expected": 2
},
"internal": null
}
]
}
}Not this time#
POST/v1/hiring/applications.rejectWrite
Decides "not this time" for one or more open candidates of a job (at most 100): they leave the board at once and get the kind email (the company's text in Settings → Hiring, else Bizisy's, in the job's language) after delay_days (default the company's reply_days, 2; 0 sends it now; for many at once, those that do not fit go within the hour). Until it goes out you can take it back with hiring_applications_cancel_reject, and the candidate's page still shows them in the process. Their interviews still to come and offered times end at once for the interviewers and are cancelled (the interviewers get the cancellation; the candidate is not emailed about it; for many at once, the rest within the hour), and stay cancelled if you take it back. reason: internal only (≤ 500 characters), never told. email false: decided without an email (e.g. told by phone); their page shows the process closed on the same day. Owners, admins and HR, or the job's hiring manager, signed in to Bizisy: refused over an API key or MCP (a person decides, never an AI).
- Web app only
- Refused for API keys and connected apps. "Not this time" is decided in the app: a person decides, never an AI.
- MCP tool
hiring_applications_rejecton HR Assistant, My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
job_idstringrequired1–100 characters.
application_idsstring[]required1–100 characters. 1–100 items.
reasonstringUp to 500 characters.
emailbooleanDefault
true.delay_daysintegerFrom 0 to 14.
Returns
decidedintegerrequiredsend_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/applications.reject \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"job_id": "j1",
"application_ids": [
"a2"
],
"reason": "Looking for nights only.",
"email": true,
"delay_days": 3
}'const res = await fetch('https://api.bizisy.com/v1/hiring/applications.reject', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"job_id": "j1",
"application_ids": [
"a2"
],
"reason": "Looking for nights only.",
"email": true,
"delay_days": 3
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/applications.reject",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"job_id": "j1",
"application_ids": [
"a2",
],
"reason": "Looking for nights only.",
"email": True,
"delay_days": 3,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"decided": 1,
"send_at": "2026-10-20T09:00:00.000Z"
}
}Take back a "not this time"#
POST/v1/hiring/applications.cancel_rejectWrite
Takes back a "not this time" whose email has not gone out yet: the candidates are open again in the column they were in (the candidate never learnt of it). Once the email was sent it can't be taken back: write to them instead. Owners, admins and HR, or the job's hiring manager, signed in to Bizisy.
- Web app only
- Refused for API keys and connected apps. Taking back a "not this time" happens in the app.
- MCP tool
hiring_applications_cancel_rejecton HR Assistant, My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
job_idstringrequired1–100 characters.
application_idsstring[]required1–100 characters. 1–100 items.
Returns
reopenedintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/applications.cancel_reject \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"job_id":"j1","application_ids":["a2"]}'const res = await fetch('https://api.bizisy.com/v1/hiring/applications.cancel_reject', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"job_id": "j1",
"application_ids": [
"a2"
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/applications.cancel_reject",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"job_id": "j1",
"application_ids": [
"a2",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"reopened": 1
}
}Add a note on a candidate#
POST/v1/hiring/applications.noteWrite
Adds a note to a candidate (≤ 5,000 characters) for the job's hiring team. private true: only HR sees it (owners, admins and HR only can write one). The candidate never sees notes on their page; a formal access request (HR's export) includes them, so write what you would say to them. Owners, admins and HR, or the job's hiring manager.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
hiring_applications_noteon HR Assistant, My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
application_idstringrequired1–100 characters.
textstringrequired1–5000 characters.
privatebooleanDefault
false.
Returns
idstringrequiredapplication_idstringrequiredprivatebooleanrequiredatstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/applications.note \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"application_id":"a1","text":"Reference call pending.","private":true}'const res = await fetch('https://api.bizisy.com/v1/hiring/applications.note', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"application_id": "a1",
"text": "Reference call pending.",
"private": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/applications.note",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"application_id": "a1",
"text": "Reference call pending.",
"private": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "e4",
"application_id": "a1",
"private": true,
"at": "2026-10-18T09:00:00.000Z"
}
}Delete my note on a candidate#
POST/v1/hiring/applications.note_deleteDestructive
Deletes a note you wrote on a candidate (note_id from hiring_applications_get events, mine true). Nobody deletes another person's note. Owners, admins and HR, or the job's hiring manager.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
hiring_applications_note_deleteon HR Assistant, My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
application_idstringrequired1–100 characters.
note_idstringrequired1–100 characters.
Returns
deletedtruerequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/applications.note_delete \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"application_id":"a1","note_id":"e3"}'const res = await fetch('https://api.bizisy.com/v1/hiring/applications.note_delete', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"application_id": "a1",
"note_id": "e3"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/applications.note_delete",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"application_id": "a1",
"note_id": "e3",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"deleted": true
}
}Record an interview#
POST/v1/hiring/applications.record_interviewWrite
Records an interview held outside Bizisy (H7, interviews outside): the day (date, YYYY-MM-DD, at most a year back), the step (step_id from the job, optional), notes (≤ 5,000 characters) and a file (file_id from hiring_files_upload_url, optional). Counts as an answer to the candidate (the answer promise starts again). Notes and files are for the hiring team; a formal access request (HR's export) includes them. Owners, admins and HR, or the job's hiring manager.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
hiring_applications_record_interviewon HR Assistant, My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
application_idstringrequired1–100 characters.
datestringrequiredPattern
^\d{4}-\d{2}-\d{2}$.step_idstring1–40 characters.
notesstringUp to 5000 characters.
file_idstring1–100 characters.
Returns
idstringrequiredapplication_idstringrequireddatestringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/applications.record_interview \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"application_id": "a1",
"date": "2026-10-20",
"step_id": "talking",
"notes": "Knows the menu.",
"file_id": "f2"
}'const res = await fetch('https://api.bizisy.com/v1/hiring/applications.record_interview', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"application_id": "a1",
"date": "2026-10-20",
"step_id": "talking",
"notes": "Knows the menu.",
"file_id": "f2"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/applications.record_interview",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"application_id": "a1",
"date": "2026-10-20",
"step_id": "talking",
"notes": "Knows the menu.",
"file_id": "f2",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "e5",
"application_id": "a1",
"date": "2026-10-20"
}
}Write to a candidate#
POST/v1/hiring/applications.messageWrite
Emails a candidate from the hiring team: subject (≤ 150 characters) and text (≤ 5,000), in your words (write in the job's language). Replies go to the job's hiring manager's work email. It appears on their application page as a message, and counts as an answer (the answer promise starts again). At most 10 a day per candidate. Owners, admins and HR, or the job's hiring manager, signed in to Bizisy: refused over an API key or MCP (an AI may draft the text for the user to send).
- Web app only
- Refused for API keys and connected apps. Writing to candidates happens in the app; machines may draft the text.
- MCP tool
hiring_applications_messageon HR Assistant, My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
application_idstringrequired1–100 characters.
subjectstringrequired1–150 characters.
textstringrequired1–5000 characters.
Returns
application_idstringrequiredsentbooleanrequiredreply_to"hiring_manager" | "none"required
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/applications.message \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"application_id": "a1",
"subject": "Your trial shift",
"text": "Could you come on Tuesday at 10:00?"
}'const res = await fetch('https://api.bizisy.com/v1/hiring/applications.message', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"application_id": "a1",
"subject": "Your trial shift",
"text": "Could you come on Tuesday at 10:00?"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/applications.message",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"application_id": "a1",
"subject": "Your trial shift",
"text": "Could you come on Tuesday at 10:00?",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"application_id": "a1",
"sent": true,
"reply_to": "hiring_manager"
}
}Upload a candidate file#
POST/v1/hiring/files.upload_urlWrite
Starts the upload of a CV (to add a candidate with hiring_applications_add) or a file from an interview (hiring_applications_record_interview) for a job: PDF, Word (DOCX) or a picture (JPG, PNG, HEIC), at most 10 MB. Returns a signed upload (PUT the bytes within 15 minutes, exactly that size and type); an upload never used is deleted within the hour. Owners, admins and HR, or the job's hiring manager.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
hiring_files_upload_urlon HR Assistant, My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
job_idstringrequired1–100 characters.
namestringrequired1–200 characters.
sizeintegerrequiredFrom 1 to 10000000.
content_type"application/pdf" | "application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "image/jpeg" | "image/png" | "image/heic"requiredsha256stringrequiredPattern
^[0-9a-f]{64}$.
Returns
file_idstringrequireduploadobject | nullrequired4 fields
urlstringrequiredmethod"PUT"requiredheadersobjectrequiredresumablefalserequired
expires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/files.upload_url \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"job_id": "j1",
"name": "cv.pdf",
"size": 182000,
"content_type": "application/pdf",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}'const res = await fetch('https://api.bizisy.com/v1/hiring/files.upload_url', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"job_id": "j1",
"name": "cv.pdf",
"size": 182000,
"content_type": "application/pdf",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/files.upload_url",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"job_id": "j1",
"name": "cv.pdf",
"size": 182000,
"content_type": "application/pdf",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"file_id": "f3",
"upload": {
"url": "https://storage.example/upload/f3",
"method": "PUT",
"headers": {
"content-type": "application/pdf"
},
"resumable": false
},
"expires_at": "2026-10-18T09:15:00.000Z"
}
}Add a candidate#
POST/v1/hiring/applications.addWrite
Adds someone to a draft, open or paused job yourself (a CV someone sent you, a fair, an agency): the CV (file_id from hiring_files_upload_url), name, email (their emails go there) and phone (optional), into column (default new). They are told at once (GDPR art. 14): an email in the job's language says the company added their CV, why, how long it is kept, their rights and the link to their application page, where they can withdraw and delete it. The same email at the same job is refused (they are already a candidate). note: a first note for the team. At most 300 a day per company. Owners, admins and HR, signed in to Bizisy: refused over an API key or MCP.
- Web app only
- Refused for API keys and connected apps. Adding a candidate (it emails them) happens in the app.
- MCP tool
hiring_applications_addon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
job_idstringrequired1–100 characters.
file_idstringrequired1–100 characters.
namestringrequired1–120 characters.
emailemailrequiredUp to 254 characters.
phonestringUp to 40 characters. Pattern
^[+()\d\s./-]*$.columnstring1–40 characters. Default
"new".notestring1–5000 characters.
Returns
16 fields
idstringrequiredcandidateobjectrequired2 fields
idstringrequirednamestringrequired
columnstringrequirednew, a step id, offer or hired.
status"active" | "hired" | "rejected" | "withdrawn"requiredactive (in the process), hired, or rejected ("not this time", told or about to be).
sourcestring (enum)requiredOne of:
careers,share,referral,job_site,talent_pool,manual,internal.referredbooleanrequiredA colleague's referral (referrals on).
applied_atstringrequiredmoved_atstringrequiredanswer_due_onstring | nullrequiredThe answer promise: the date the company answers by (working days from the last move or message).
overduebooleanrequiredStill open and the promised date has passed.
replyobject | nullrequired"Not this time": when the kind email goes out (cancellable until sent).
3 fields
send_atstringrequiredemailbooleanrequiredsentbooleanrequired
has_cvbooleanrequiredcv_unread"no_credits"requiredManage only (null on the hiring manager's side, My workspace): no_credits = the CV needed Document AI when it arrived and the company had no AI credits left, so its details were not read; read it with hiring_applications_read_cv (1 AI credit). The candidate never knows.
notesintegerrequiredfeedbackobject | nullrequiredFeedback in for the interviews held ("Feedback 1 of 2"); null before any interview was held.
2 fields
submittedintegerrequiredexpectedintegerrequired
internalobject | nullrequiredW7: someone who works here, applying from My workspace — their current job (title, team, location, time with the company). Never pay, reviews or ratings.
7 fields
titlestring | nullrequiredunitstring | nullrequiredlocationstring | nullrequiredtenureobject | nullrequired2 fields
yearsintegerrequiredmonthsintegerrequired
start_datestring | nullrequirednotestring | nullrequired"Why this job?" (the hiring team and HR).
person_idstring | nullrequiredHR only: the person in People.
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/applications.add \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"job_id": "j1",
"file_id": "f3",
"name": "Joana Reis",
"email": "joana.reis@mail.pt",
"phone": "+351 912 000 111",
"column": "talking",
"note": "Met at the job fair."
}'const res = await fetch('https://api.bizisy.com/v1/hiring/applications.add', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"job_id": "j1",
"file_id": "f3",
"name": "Joana Reis",
"email": "joana.reis@mail.pt",
"phone": "+351 912 000 111",
"column": "talking",
"note": "Met at the job fair."
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/applications.add",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"job_id": "j1",
"file_id": "f3",
"name": "Joana Reis",
"email": "joana.reis@mail.pt",
"phone": "+351 912 000 111",
"column": "talking",
"note": "Met at the job fair.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "a3",
"candidate": {
"id": "c3",
"name": "Joana Reis"
},
"column": "talking",
"status": "active",
"source": "manual",
"referred": false,
"applied_at": "2026-10-08T09:00:00.000Z",
"moved_at": "2026-10-08T09:00:00.000Z",
"answer_due_on": "2026-10-23",
"overdue": false,
"reply": null,
"has_cv": true,
"cv_unread": null,
"notes": 0,
"feedback": null,
"internal": null
}
}Read a candidate's CV#
POST/v1/hiring/applications.read_cvWrite
Reads a candidate's CV again and suggests the name, email and phone it finds (nothing is changed or stored; compare them with what the candidate sent). Use it for a CV stored unread (cv_unread no_credits: it needed Document AI when the company had no AI credits left). PDF and Word text is read by Bizisy at no AI credit; a picture or a scan is read by Google Cloud Document AI and uses 1 AI credit (once per CV); ai_credits says the cost and what is left, and a dry run says the cost and reads nothing. With no AI credits left: conflict for people (an owner or admin buys AI credits in Settings → Plan & billing), credits_exhausted (402) for API keys and AI apps. Clears cv_unread once read. Owners, admins and HR, in Manage.
- Who can call it
- Manage key owner admin hr
- MCP tool
hiring_applications_read_cvon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
application_idstringrequired1–100 characters.
Returns
namestring | nullrequiredemailstring | nullrequiredphonestring | nullrequiredfoundbooleanrequiredfalse: nothing could be read (or a dry run, which reads nothing).
ai_creditsobjectrequired3 fields
costintegerrequiredAI credits this read used (0 when Bizisy read the text itself; on a dry run, what it would use).
leftinteger | nullrequiredAI credits the company has left; null when unlimited.
notestringrequiredThe same in words, e.g. "Uses 1 AI credit (12 left)".
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/applications.read_cv \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"application_id":"a1"}'const res = await fetch('https://api.bizisy.com/v1/hiring/applications.read_cv', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"application_id": "a1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/applications.read_cv",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"application_id": "a1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"name": "Maria Silva",
"email": "maria@example.test",
"phone": null,
"found": true,
"ai_credits": {
"cost": 1,
"left": 12,
"note": "Used 1 AI credit (12 left)"
}
}
}Prepare the hire of a candidate#
POST/v1/hiring/applications.hire_draftRead
What the hire wizard starts from for a candidate still in the process or at Offer: their names (split from the name they gave: first word, then the rest), personal email and phone, the job's title, team, location, contract and weekly hours, the position (its legal entity and the manager it reports to), a start date (the position's target start, else a Monday about 30 days ahead) and pay: the middle of the job's range, marked as a suggestion (HR changes it to what was agreed; hidden over an API key or MCP). With an offer accepted (or ready or sent), everything comes from the offer instead (start_date_source offer; pay as agreed, suggestion false) and offer carries its work email, contract end and probation end dates and why the hire did not run by itself ("Finish the hire"). Pass source to org_people_hire: every hire rule applies (pay approvals, invites, onboarding checklists), and the candidate becomes hired, linked to the new person (an accepted offer becomes theirs). Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- The pay suggestion is hidden; the hire itself happens in the app.
- MCP tool
hiring_applications_hire_drafton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
application_idstringrequired1–100 characters.
Returns
22 fields
application_idstringrequiredjob_idstringrequiredposition_idstring | nullrequiredThe job's position, while it is open or on hold: the hire fills it.
given_namestringrequiredfamily_namestringrequiredpersonal_emailstringrequiredpersonal_phonestring | nullrequiredtitlestringrequiredunit_idstring | nullrequiredlocation_idstring | nullrequiredlegal_entity_idstring | nullrequiredmanager_idstring | nullrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredweekly_hoursnumber | nullrequiredstart_datestringrequiredstart_date_source"position" | "suggested" | "offer"requiredposition: its target start; suggested: about 30 days from today (a notice period), a Monday; offer: the offer's.
payobject | nullrequiredA suggestion only (the middle of the job's range): change it to what was agreed.
5 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredsuggestionbooleanrequiredtrue: the middle of the range, change it; false: from the offer.
rangeobject | nullrequired2 fields
minnumberrequiredmaxnumberrequired
pay_hiddenbooleanrequiredinviteobjectrequiredThe sign-in invite on their first day (change it in the hire).
1 field
when"start" | "none"required
sourceobjectrequiredPass it to
org_people_hire: the candidate becomes hired, linked to the person.3 fields
kind"hiring"requiredjob_idstringrequiredapplication_idstringrequired
referrerobject | nullrequired2 fields
idstringrequirednamestringrequired
offerobject | nullrequiredPhase 3: the accepted (or last live) offer the draft is filled in from: its terms, the work email and dates. Finish the hire with these.
6 fields
idstringrequiredstatusstringrequiredwork_emailstring | nullrequiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredfailedstring | nullrequiredWhy the hire could not run by itself after the acceptance.
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/applications.hire_draft \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"application_id":"a1"}'const res = await fetch('https://api.bizisy.com/v1/hiring/applications.hire_draft', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"application_id": "a1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/applications.hire_draft",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"application_id": "a1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"application_id": "a1",
"job_id": "j1",
"position_id": "pos1",
"given_name": "Maria",
"family_name": "Silva",
"personal_email": "maria.silva@mail.pt",
"personal_phone": "+351 912 345 678",
"title": "Line cook",
"unit_id": "u1",
"location_id": "l1",
"legal_entity_id": "e1",
"manager_id": "p2",
"contract_type": "permanent",
"weekly_hours": 40,
"start_date": "2026-11-23",
"start_date_source": "suggested",
"pay": {
"amount": 20000,
"currency": "EUR",
"period": "year",
"suggestion": true,
"range": {
"min": 18000,
"max": 22000
}
},
"pay_hidden": false,
"invite": {
"when": "start"
},
"source": {
"kind": "hiring",
"job_id": "j1",
"application_id": "a1"
},
"referrer": {
"id": "p3",
"name": "Rui Gomes"
},
"offer": null
}
}Jobs at the company#
POST/v1/hiring/jobs.open_list_meRead
The company's open jobs for everyone who works there (My workspace → Jobs): title, team, place, contract, hours, the pay range the post shows and its careers page, how many people applied with your share link, and, when Referrals and the bonus are on, the referral bonus and whether it applies to you (HR and a job's hiring manager are excluded by default). referrals.enabled says whether you can refer someone (hiring_referrals_create); with the bonus on, referrals.earned says when a bonus is earned (start, probation, or months employed). Never candidates.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
hiring_jobs_open_list_meon My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
referralsobjectrequired4 fields
enabledbooleanrequiredbonusbooleanrequiredearned"start" | "probation" | "months"requiredWith the bonus on: when it is earned (the start date, the end of probation, or after months employed).
monthsinteger | nullrequired
jobsobject[]required20 fields
idstringrequiredslugstringrequiredtitlestringrequiredlanguage"en" | "pt" | "es" | "fr" | "de"requiredurlstringrequiredIts careers page (without your share code).
unitstring | nullrequiredlocationobject | nullrequired3 fields
namestringrequiredcitystring | nullrequiredcountrystringrequired
workplace"on_site" | "hybrid" | "remote"requiredemployment_type"full_time" | "part_time" | "contract" | "temporary" | "internship"requiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredweekly_hoursnumber | nullrequiredsalaryobject | nullrequiredThe range the post shows.
4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
posted_onstringrequiredbonusobject | nullrequiredThe referral bonus for this job (referrals and the bonus on); applies_to_you false when you are excluded (HR, or its hiring manager).
3 fields
amountnumberrequiredcurrencystringrequiredapplies_to_youbooleanrequired
my_applicantsintegerrequiredPeople who applied with your link (a count only).
audience"public" | "internal_first" | "internal_only"requiredpublic: open to all (careers page too); internal_first: for people who work here first, public later; internal_only: only for people who work here.
shareablebooleanrequiredOn the careers page now, so it can be shared and referred (internal posts can't).
can_applybooleanrequiredYou can apply from My workspace (hiring_internal_apply): internal jobs on and nothing blocks it.
blockedobject | nullrequiredWhy you can't apply now and from when (min_months, probation), or hiring_manager (you're hiring for it), view_only, limit (too many open), off (internal jobs off).
3 fields
rule"min_months" | "probation" | "hiring_manager" | "view_only" | "limit" | "off"requireduntilstring | nullrequiredmonthsinteger
my_applicationobject | nullrequiredYour live application to it, if any.
1 field
idstringrequired
internalobjectrequiredInternal jobs (Settings → Hiring): whether you can apply from My workspace, and the company's rules for applying.
3 fields
enabledbooleanrequiredmin_months_in_jobinteger | nullrequiredallow_in_probationbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/jobs.open_list_me \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/hiring/jobs.open_list_me', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/jobs.open_list_me",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"referrals": {
"enabled": true,
"bonus": true,
"earned": "probation",
"months": null
},
"jobs": [
{
"id": "j1",
"slug": "line-cook",
"title": "Line cook",
"language": "en",
"url": "https://acme.bizisy.com/careers/line-cook",
"unit": "Kitchen",
"location": {
"name": "Braga kitchen",
"city": "Braga",
"country": "PT"
},
"workplace": "on_site",
"employment_type": "full_time",
"contract_type": "permanent",
"weekly_hours": 40,
"salary": {
"min": 18000,
"max": 22000,
"currency": "EUR",
"period": "year"
},
"posted_on": "2026-10-18",
"bonus": {
"amount": 500,
"currency": "EUR",
"applies_to_you": true
},
"my_applicants": 2,
"audience": "public",
"shareable": true,
"can_apply": true,
"blocked": null,
"my_application": null
}
],
"internal": {
"enabled": true,
"min_months_in_job": null,
"allow_in_probation": true
}
}
}Share a job#
POST/v1/hiring/share.linkWrite
Your own link to an open job (it carries a short random code: the company sees how many people applied through your shares, you see the count only), with ready links to share it on LinkedIn, WhatsApp, Facebook, X or by email (they open the site with the text filled in; nothing is posted for you), the job's share picture, and a message to go with it in language (en, pt, es, fr, de; default the job's). With Referrals on, people who apply with your link are your referrals. Anyone with a person record in the company.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
hiring_share_linkon My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
job_idstringrequired1–100 characters.
language"en" | "pt" | "es" | "fr" | "de"
Returns
job_idstringrequiredcodestringrequiredurlstringrequiredimage_urlstringrequiredmessagestringrequiredlinksobjectrequired5 fields
linkedinstringrequiredwhatsappstringrequiredfacebookstringrequiredxstringrequiredemailstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
{
"data": {
"job_id": "j1",
"code": "k3Zq9vB2xYw",
"url": "https://acme.bizisy.com/careers/line-cook?r=k3Zq9vB2xYw",
"image_url": "https://acme.bizisy.com/careers/line-cook/share.png",
"message": "We're hiring: Line cook at Acme. Have a look, or pass it on to someone who would be great for it. https://acme.bizisy.com/careers/line-cook?r=k3Zq9vB2xYw",
"links": {
"linkedin": "https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Facme.bizisy.com%2Fcareers%2Fline-cook%3Fr%3Dk3Zq9vB2xYw",
"whatsapp": "https://wa.me/?text=We%E2%80%99re%20hiring",
"facebook": "https://www.facebook.com/sharer/sharer.php?u=https%3A%2F%2Facme.bizisy.com%2Fcareers%2Fline-cook%3Fr%3Dk3Zq9vB2xYw",
"x": "https://x.com/intent/post?text=We%E2%80%99re%20hiring&url=https%3A%2F%2Facme.bizisy.com%2Fcareers%2Fline-cook%3Fr%3Dk3Zq9vB2xYw",
"email": "mailto:?subject=Line%20cook&body=We%E2%80%99re%20hiring"
}
}
}Refer someone for a job#
POST/v1/hiring/referrals.createWrite
Refers someone for an open job (Referrals on in Settings → Hiring): their name, email, an optional note on why they would fit (≤ 300 characters, HR reads it), and consent true (they agreed to be contacted). They get one email, in the job's language: "<your name> thinks you'd be great for <job>", with the job's page and your link; whoever applies from it is your referral (the first within 6 months). At most 10 a day per person. You see their state as a word (hiring_referrals_mine), never notes or decisions before they are sent. Anyone with a person record in the company, signed in to Bizisy: refused over an API key or MCP (it emails someone outside the company).
- Web app only
- Refused for API keys and connected apps. Referring someone (it emails them) happens in the app.
- MCP tool
hiring_referrals_createon My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
job_idstringrequired1–100 characters.
namestringrequired1–120 characters.
emailemailrequiredUp to 254 characters.
notestringUp to 300 characters.
consenttruerequiredThey agreed to be contacted about this job.
Returns
idstringrequiredjob_idstringrequiredstate"invited"required
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/referrals.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"job_id": "j1",
"name": "Maria Silva",
"email": "maria.silva@mail.pt",
"note": "Ran the kitchen at Taberna.",
"consent": true
}'const res = await fetch('https://api.bizisy.com/v1/hiring/referrals.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"job_id": "j1",
"name": "Maria Silva",
"email": "maria.silva@mail.pt",
"note": "Ran the kitchen at Taberna.",
"consent": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/referrals.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"job_id": "j1",
"name": "Maria Silva",
"email": "maria.silva@mail.pt",
"note": "Ran the kitchen at Taberna.",
"consent": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "r2",
"job_id": "j1",
"state": "invited"
}
}My referrals#
POST/v1/hiring/referrals.mineRead
Your referrals and the people who applied with your links: the job, the name you gave (never who applied with your link), how you referred them (invite or link) and where it stands as a word only (invited, applied, in_process, hired, not_this_time once they were told, closed), with your bonus when one applies (amount, when it is earned, and whether it is waiting, due, in_payroll with the pay period it is in, paid or not due). Never notes, feedback or other candidates. Anyone with a person record in the company.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
hiring_referrals_mineon My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
enabledbooleanrequiredreferralsobject[]required7 fields
idstringrequiredjobobjectrequired2 fields
idstringrequiredtitlestringrequired
namestring | nullrequiredThe person you invited (null for someone who applied with your link: you never see who).
via"invite" | "link"requiredstate"invited" | "applied" | "in_process" | "hired" | "not_this_time" | "closed"requiredbonusobject | nullrequired7 fields
amountnumberrequiredcurrencystringrequiredstate"waiting" | "due" | "in_payroll" | "paid" | "not_due"requireddue_onstring | nullrequiredearned"start" | "probation" | "months"requiredmonthsinteger | nullrequiredpayrollobject | nullrequiredin_payroll (and paid through payroll): the pay period it is in, as its first and last day.
2 fields
startstringrequiredendstringrequired
created_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/referrals.mine \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/hiring/referrals.mine', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/referrals.mine",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"enabled": true,
"referrals": [
{
"id": "r1",
"job": {
"id": "j1",
"title": "Line cook"
},
"name": "Maria Silva",
"via": "invite",
"state": "in_process",
"bonus": null,
"created_at": "2026-10-10T09:00:00.000Z"
},
{
"id": "r3",
"job": {
"id": "j1",
"title": "Line cook"
},
"name": null,
"via": "link",
"state": "hired",
"bonus": {
"amount": 500,
"currency": "EUR",
"state": "in_payroll",
"due_on": "2027-02-02",
"earned": "probation",
"months": null,
"payroll": {
"start": "2027-02-01",
"end": "2027-02-28"
}
},
"created_at": "2026-10-10T09:00:00.000Z"
}
]
}
}List referrals#
POST/v1/hiring/referrals.listRead
Every referral in the company (HR): the job, who referred, the candidate (or, for an invitation not answered yet, the name the referrer gave and their note), invite or link, its state, and the bonus (amount, when earned, waiting, due, in_payroll, paid or not due; hidden over an API key or MCP). bonus: only those in a bonus state. With Payroll, a bonus that comes due goes into the referrer's pay period as a Referral bonus pay item (in_payroll, with that period) and becomes paid once the period is locked; due means HR pays it by hand (no Payroll, no pay schedule for the referrer, or the item was removed in payroll) and marks it paid with hiring_referrals_mark_paid. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Referral bonus amounts are hidden.
- MCP tool
hiring_referrals_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
job_idstring1–100 characters.
bonus"waiting" | "due" | "in_payroll" | "paid" | "not_due"limitintegerFrom 1 to 1000. Default
200.
Returns
referralsobject[]required11 fields
idstringrequiredjobobjectrequired2 fields
idstringrequiredtitlestringrequired
referrerobject | nullrequired2 fields
idstringrequirednamestringrequired
candidateobject | nullrequired3 fields
idstringrequirednamestringrequiredapplication_idstringrequired
contact_namestring | nullrequiredAn invitation not answered yet: the name the referrer gave.
notestring | nullrequiredvia"invite" | "link"requiredstate"invited" | "applied" | "in_process" | "hired" | "not_this_time" | "closed"requiredbonusobject | nullrequired8 fields
amountnumberrequiredcurrencystringrequiredstate"waiting" | "due" | "in_payroll" | "paid" | "not_due"requireddue_onstring | nullrequiredearned"start" | "probation" | "months"requiredmonthsinteger | nullrequiredpayrollobject | nullrequiredin_payroll (and paid through payroll): the pay period it is in, as its first and last day.
2 fields
startstringrequiredendstringrequired
paid_atstring | nullrequired
bonus_hiddenbooleanrequiredcreated_atstringrequired
totalintegerrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/referrals.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"job_id":"j1","bonus":"due","limit":50}'const res = await fetch('https://api.bizisy.com/v1/hiring/referrals.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"job_id": "j1",
"bonus": "due",
"limit": 50
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/referrals.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"job_id": "j1",
"bonus": "due",
"limit": 50,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"referrals": [
{
"id": "r1",
"job": {
"id": "j1",
"title": "Line cook"
},
"referrer": {
"id": "p3",
"name": "Rui Gomes"
},
"candidate": {
"id": "c1",
"name": "Maria Silva",
"application_id": "a1"
},
"contact_name": null,
"note": "Ran the kitchen at Taberna.",
"via": "invite",
"state": "hired",
"bonus": {
"amount": 500,
"currency": "EUR",
"state": "due",
"due_on": "2027-02-02",
"earned": "probation",
"months": null,
"payroll": null,
"paid_at": null
},
"bonus_hidden": false,
"created_at": "2026-10-10T09:00:00.000Z"
}
],
"total": 1
}
}Mark a referral bonus paid#
POST/v1/hiring/referrals.mark_paidWrite
Marks a due referral bonus as paid (after HR paid it by hand). Bonuses in payroll (in_payroll) become paid by themselves once their pay period is locked. The referrer sees "paid". Owners, admins and HR, signed in to Bizisy: refused over an API key or MCP (money paid to a person).
- Web app only
- Refused for API keys and connected apps. Referral bonuses are marked paid in the app only.
- MCP tool
hiring_referrals_mark_paidon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
referral_idstringrequired1–100 characters.
Returns
idstringrequiredstate"paid"requiredpaid_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/referrals.mark_paid \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"referral_id":"r1"}'const res = await fetch('https://api.bizisy.com/v1/hiring/referrals.mark_paid', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"referral_id": "r1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/referrals.mark_paid",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"referral_id": "r1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "r1",
"state": "paid",
"paid_at": "2027-02-10T09:00:00.000Z"
}
}Hiring: what needs you#
POST/v1/hiring/home.needs_youRead
For Home: the live jobs you are on the hiring team of (owners, admins and HR: every job; a hiring manager: their own) that have candidates waiting, with how many are in New and how many are past the answer promise (no move or message by the date promised), most overdue first; interviews to arrange again (offers nobody picked in 48 hours, candidates who asked for other times or cancelled); interview feedback past its due time; job offers waiting for your approval and sent offers ending within 2 days; and, for HR in the app, referral bonuses due and accepted offers whose hire you finish. Everyone else gets an empty list. Counts and job titles only.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
hiring_home_needs_youon HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
9 fields
jobsobject[]required5 fields
idstringrequiredtitlestringrequirednewintegerrequiredCandidates in New (not answered yet).
overdueintegerrequiredCandidates past the answer promise.
earliest_duestring | nullrequiredThe oldest promised date passed (YYYY-MM-DD).
overdueintegerrequirednewintegerrequiredbonuses_dueintegerrequiredinterviews_to_rebookintegerrequiredInterviews to arrange again: offers nobody picked in 48 hours, candidates who asked for other times or cancelled (hiring_interviews_list).
feedback_overdueintegerrequiredInterview feedback past its due time: interviewers who have not sent theirs (per interview held in the last 30 days; see the candidate's feedback_by_step).
offers_awaiting_approvalintegerrequiredJob offers waiting for your approval (hiring_offers_list with waiting_for_me true).
offers_expiringintegerrequiredSent job offers ending within 2 days on your jobs.
finish_hireintegerrequiredHR: candidates who accepted an offer whose hire you finish (hiring_applications_hire_draft is filled in from the offer), and internal moves that were not approved (finish or tell the person yourself).
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/home.needs_you \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/hiring/home.needs_you', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/home.needs_you",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"jobs": [
{
"id": "j1",
"title": "Line cook",
"new": 1,
"overdue": 1,
"earliest_due": "2026-10-15"
}
],
"overdue": 1,
"new": 1,
"bonuses_due": 1,
"interviews_to_rebook": 1,
"feedback_overdue": 1,
"offers_awaiting_approval": 1,
"offers_expiring": 1,
"finish_hire": 1
}
}Erase a candidate#
POST/v1/hiring/candidates.eraseDestructive
Deletes everything the company holds about a candidate (their request, or no reason to keep it): every application, the CVs and interview files, answers, notes, interviews (those to come are cancelled and the interviewers told), the feedback on them and the talent pool membership; what happened stays in the counts without personal data, and a referral keeps only that one was made. A hired candidate's person record in People is not touched (erase them there). Cannot be undone. Owners, admins and HR, signed in to Bizisy.
- Web app only
- Refused for API keys and connected apps. Erasing a candidate happens in the app only.
- MCP tool
hiring_candidates_eraseon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
candidate_idstringrequired1–100 characters.
Returns
erasedtruerequiredapplicationsintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/candidates.erase \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"candidate_id":"c2"}'const res = await fetch('https://api.bizisy.com/v1/hiring/candidates.erase', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"candidate_id": "c2"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/candidates.erase",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"candidate_id": "c2",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"erased": true,
"applications": 1
}
}Export a candidate's data#
POST/v1/hiring/candidates.exportRead
A candidate's data for their formal access request (GDPR art. 15), to send them: their details, the talent pool dates, every application (the job, when, where it stands, where they came from, their answers with the questions) with what happened (moves, emails sent to them, notes including HR's private ones, interviews recorded or booked with the feedback interviewers sent on each, the internal reason of a "not this time", every offer with its terms and the record of an acceptance) and download links to their CVs, interview files and offer letters (valid for 5 minutes). Colleagues are not named. Owners, admins and HR, signed in to Bizisy.
- Web app only
- Refused for API keys and connected apps. A candidate's data export happens in the app only.
- MCP tool
hiring_candidates_exporton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
candidate_idstringrequired1–100 characters.
Returns
candidateobjectrequiredapplicationsobject[]requiredfilesobject[]required4 fields
namestringrequiredsizenumberrequiredurlstring | nullrequiredexpires_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/candidates.export \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"candidate_id":"c1"}'const res = await fetch('https://api.bizisy.com/v1/hiring/candidates.export', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"candidate_id": "c1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/candidates.export",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"candidate_id": "c1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"candidate": {
"name": "Maria Silva",
"email": "maria.silva@mail.pt",
"phone": "+351 912 345 678",
"city": null,
"links": [],
"language": "en",
"first_seen": "2026-10-12T09:00:00.000Z",
"talent_pool": null
},
"applications": [
{
"job": "Line cook",
"applied_at": "2026-10-12T09:00:00.000Z",
"status": "active",
"column": "Talking",
"source": "referral",
"referred_by_a_colleague": true,
"answers": [
{
"question": "Do you have the right to work in the EU?",
"answer": "yes"
}
],
"answer_by": "2026-10-21",
"not_this_time": null,
"history": [
{
"kind": "received",
"at": "2026-10-12T09:00:00.000Z",
"by": null
}
]
}
],
"files": [
{
"name": "maria-silva-cv.pdf",
"size": 182000,
"url": "https://storage.example/f1?sig=x",
"expires_at": "2026-10-18T09:05:00.000Z"
}
]
}
}List interview groups#
POST/v1/hiring/pools.listRead
The company's interview groups (Settings → Hiring → Interview groups): named sets of people and teams a job's steps pick interviewers from. Each with its people (whether employed now), its teams (members today) and how many people it resolves to today; a team's members are read when the group is used, and people who leave, are terminated or erased drop out. include_archived: archived ones too. Owners, admins and HR, or a hiring manager of a job.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
hiring_pools_liston HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
include_archivedbooleanDefault
false.
Returns
poolsobject[]required8 fields
idstringrequirednamestringrequiredpeopleobject[]requiredThe people named in the group (erased people drop out).
3 fields
idstringrequirednamestringrequiredactivebooleanrequiredEmployed now (others are skipped when interviews are booked).
unitsobject[]required3 fields
idstringrequirednamestringrequiredmembersintegerrequiredPeople employed now whose team it is.
membersintegerrequiredEveryone it resolves to today: its people and its teams' members, employed now.
archivedbooleanrequiredcreated_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/pools.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"include_archived":true}'const res = await fetch('https://api.bizisy.com/v1/hiring/pools.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"include_archived": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/pools.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"include_archived": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"pools": [
{
"id": "g1",
"name": "Kitchen leads",
"people": [
{
"id": "p2",
"name": "Rita Lopes",
"active": true
},
{
"id": "p4",
"name": "Ivo Matos",
"active": true
}
],
"units": [
{
"id": "u1",
"name": "Kitchen",
"members": 6
}
],
"members": 7,
"archived": false,
"created_at": "2026-10-18T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z"
}
]
}
}How many people can run each interview step#
POST/v1/hiring/pools.capacityRead
For up to 10 steps, each given as its interview groups and people (as a job's Interview plan sets them, saved or not): how many people can run it today (employed now, with a usual week set, not paused and not capped at 0 interviews), how many open hours a week they have together (each person's usual week, capped by their weekly hour cap), and how many in the group have no usual week or are paused. Counts only, no names. Compare people with the step's interviewers_needed: fewer means it can't be booked. Owners, admins and HR, or a hiring manager of a job; API keys and AI apps may read it.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
hiring_pools_capacityon HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
stepsobject[]required1–10 items.
3 fields
keystringrequiredYour name for the step (its id, or any key): returned as is.
1–40 characters.
group_idsstring[]1–100 characters. Up to 20 items.
person_idsstring[]1–100 characters. Up to 50 items.
Returns
stepsobject[]required5 fields
keystringrequiredpeopleintegerrequiredPeople who can run it today.
hours_a_weeknumberrequiredTheir usual weeks together, each capped by their weekly hour cap.
without_weekintegerrequiredIn the group and employed, but without a usual week (nobody books them).
pausedintegerrequiredIn the group with a usual week, but paused (or capped at 0 interviews).
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/pools.capacity \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"steps": [
{
"key": "trial",
"group_ids": [
"g1"
],
"person_ids": [
"p2"
]
},
{
"key": "new-1"
}
]
}'const res = await fetch('https://api.bizisy.com/v1/hiring/pools.capacity', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"steps": [
{
"key": "trial",
"group_ids": [
"g1"
],
"person_ids": [
"p2"
]
},
{
"key": "new-1"
}
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/pools.capacity",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"steps": [
{
"key": "trial",
"group_ids": [
"g1",
],
"person_ids": [
"p2",
],
},
{
"key": "new-1",
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"steps": [
{
"key": "trial",
"people": 3,
"hours_a_week": 9.5,
"without_week": 1,
"paused": 0
},
{
"key": "new-1",
"people": 0,
"hours_a_week": 0,
"without_week": 0,
"paused": 0
}
]
}
}Create an interview group#
POST/v1/hiring/pools.createWrite
Creates an interview group a job's steps can pick interviewers from: name (≤ 60 characters), person_ids (people employed now or starting soon, at most 200) and unit_ids (teams, at most 20: their members when the group is used). At most 50 groups. Owners, admins and HR. Use dry_run first.
- Who can call it
- Manage key owner admin hr
- MCP tool
hiring_pools_createon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
namestringrequired1–60 characters.
person_idsstring[]People (person ids), at most 200.
1–100 characters. Up to 200 items.
unit_idsstring[]Teams (unit ids from
org_units_list), at most 20: their members today.1–100 characters. Up to 20 items.
Returns
8 fields
idstringrequirednamestringrequiredpeopleobject[]requiredThe people named in the group (erased people drop out).
3 fields
idstringrequirednamestringrequiredactivebooleanrequiredEmployed now (others are skipped when interviews are booked).
unitsobject[]required3 fields
idstringrequirednamestringrequiredmembersintegerrequiredPeople employed now whose team it is.
membersintegerrequiredEveryone it resolves to today: its people and its teams' members, employed now.
archivedbooleanrequiredcreated_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/pools.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"name":"Kitchen leads","person_ids":["p2","p4"]}'const res = await fetch('https://api.bizisy.com/v1/hiring/pools.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"name": "Kitchen leads",
"person_ids": [
"p2",
"p4"
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/pools.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "Kitchen leads",
"person_ids": [
"p2",
"p4",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "g1",
"name": "Kitchen leads",
"people": [
{
"id": "p2",
"name": "Rita Lopes",
"active": true
},
{
"id": "p4",
"name": "Ivo Matos",
"active": true
}
],
"units": [
{
"id": "u1",
"name": "Kitchen",
"members": 6
}
],
"members": 7,
"archived": false,
"created_at": "2026-10-18T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z"
}
}Change an interview group#
POST/v1/hiring/pools.updateWrite
Changes an interview group: name, person_ids (the whole list, at most 200) and unit_ids (the whole list, at most 20). Interviews already booked keep their people. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
hiring_pools_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
pool_idstringrequired1–100 characters.
namestring1–60 characters.
person_idsstring[]People (person ids), at most 200.
1–100 characters. Up to 200 items.
unit_idsstring[]Teams (unit ids from
org_units_list), at most 20: their members today.1–100 characters. Up to 20 items.
Returns
8 fields
idstringrequirednamestringrequiredpeopleobject[]requiredThe people named in the group (erased people drop out).
3 fields
idstringrequirednamestringrequiredactivebooleanrequiredEmployed now (others are skipped when interviews are booked).
unitsobject[]required3 fields
idstringrequirednamestringrequiredmembersintegerrequiredPeople employed now whose team it is.
membersintegerrequiredEveryone it resolves to today: its people and its teams' members, employed now.
archivedbooleanrequiredcreated_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/pools.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"pool_id": "g1",
"name": "Kitchen leads",
"person_ids": [
"p2",
"p4"
],
"unit_ids": [
"u1"
]
}'const res = await fetch('https://api.bizisy.com/v1/hiring/pools.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"pool_id": "g1",
"name": "Kitchen leads",
"person_ids": [
"p2",
"p4"
],
"unit_ids": [
"u1"
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/pools.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"pool_id": "g1",
"name": "Kitchen leads",
"person_ids": [
"p2",
"p4",
],
"unit_ids": [
"u1",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "g1",
"name": "Kitchen leads",
"people": [
{
"id": "p2",
"name": "Rita Lopes",
"active": true
},
{
"id": "p4",
"name": "Ivo Matos",
"active": true
}
],
"units": [
{
"id": "u1",
"name": "Kitchen",
"members": 6
}
],
"members": 7,
"archived": false,
"created_at": "2026-10-18T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z"
}
}Archive an interview group#
POST/v1/hiring/pools.archiveWrite
Archives an interview group (archived false brings it back): steps that name it no longer pick interviewers from it; interviews already booked keep their people. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
hiring_pools_archiveon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
pool_idstringrequired1–100 characters.
archivedbooleanDefault
true.
Returns
8 fields
idstringrequirednamestringrequiredpeopleobject[]requiredThe people named in the group (erased people drop out).
3 fields
idstringrequirednamestringrequiredactivebooleanrequiredEmployed now (others are skipped when interviews are booked).
unitsobject[]required3 fields
idstringrequirednamestringrequiredmembersintegerrequiredPeople employed now whose team it is.
membersintegerrequiredEveryone it resolves to today: its people and its teams' members, employed now.
archivedbooleanrequiredcreated_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/pools.archive \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"pool_id":"g1","archived":false}'const res = await fetch('https://api.bizisy.com/v1/hiring/pools.archive', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"pool_id": "g1",
"archived": false
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/pools.archive",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"pool_id": "g1",
"archived": False,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "g1",
"name": "Kitchen leads",
"people": [
{
"id": "p2",
"name": "Rita Lopes",
"active": true
},
{
"id": "p4",
"name": "Ivo Matos",
"active": true
}
],
"units": [
{
"id": "u1",
"name": "Kitchen",
"members": 6
}
],
"members": 7,
"archived": false,
"created_at": "2026-10-18T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z"
}
}Get an interviewing week#
POST/v1/hiring/availability.getRead
When a person can usually interview (My workspace → Interviewing): their windows of a usual week (day 1 Monday … 7 Sunday, HH:MM on the half hour, in their time zone: their location's, else the company's), the hours they cover, the weekly cap (interviews, and hours when set; default 2 interviews), the pause, and their load (this week's interviews and hours, this month's interviews). Bizisy books inside these windows, never on their time off or public holidays. Leave person_id out for your own; owners, admins and HR can read anyone's.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
hiring_availability_geton HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
person_idstring1–100 characters.
Returns
9 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
setbooleanrequiredThey have said when they can usually interview (without it nobody books them).
time_zonestringrequiredTheir time zone: their location's, else the company's. Windows are in it.
windowsobject[]required3 fields
dayintegerrequired1 Monday … 7 Sunday.
From 1 to 7.
fromstringrequiredPattern
^(?:[01]\d|2[0-3]):[03]0$|^24:00$.tostringrequiredPattern
^(?:[01]\d|2[0-3]):[03]0$|^24:00$.
hours_a_weeknumberrequiredHours the windows cover in a week.
capobjectrequired2 fields
interviewsintegerrequiredInterviews a week at most (0: none for now).
From 0 to 10.
hoursnumber | nullrequiredHours of interviews a week at most; null: no hour limit.
From 0 to 20.
paused_untilstring | nullrequiredNot asked until this day (inclusive).
loadobjectrequired2 fields
weekobjectrequiredThis ISO week: interviews booked or held, and their hours.
2 fields
interviewsintegerrequiredhoursnumberrequired
monthintegerrequiredInterviews held and booked this calendar month.
updated_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/availability.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"person_id":"p4"}'const res = await fetch('https://api.bizisy.com/v1/hiring/availability.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"person_id": "p4"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/availability.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"person_id": "p4",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person": {
"id": "p4",
"name": "Ivo Matos"
},
"set": true,
"time_zone": "Europe/Lisbon",
"windows": [
{
"day": 2,
"from": "10:00",
"to": "12:00"
},
{
"day": 4,
"from": "14:00",
"to": "17:00"
}
],
"hours_a_week": 5,
"cap": {
"interviews": 2,
"hours": 3
},
"paused_until": null,
"load": {
"week": {
"interviews": 1,
"hours": 1
},
"month": 3
},
"updated_at": "2026-10-18T09:00:00.000Z"
}
}Set an interviewing week#
POST/v1/hiring/availability.setWrite
Sets when a person can usually interview; send only what changes. windows: the whole usual week (at most 40 after merging; day 1 Monday … 7 Sunday, from and to on the half hour in their time zone, to up to 24:00; adjacent and overlapping windows merge; [] clears it, and then nobody books them). Windows say when, never how long: each interview lasts what its step says. cap: interviews a week (0 to 10; 0 pauses them) and hours a week (0 to 20, or null for no hour limit), whichever is reached first. paused_until: a day until which nobody asks them (null resumes). Interviews already booked stay. Leave person_id out for your own; owners, admins and HR can set anyone's (employed now or starting soon).
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
hiring_availability_seton HR Assistant, My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
person_idstring1–100 characters.
windowsobject[]Up to 336 items.
3 fields
dayintegerrequired1 Monday … 7 Sunday.
From 1 to 7.
fromstringrequiredPattern
^(?:[01]\d|2[0-3]):[03]0$|^24:00$.tostringrequiredPattern
^(?:[01]\d|2[0-3]):[03]0$|^24:00$.
capobject2 fields
interviewsintegerrequiredInterviews a week at most (0: none for now).
From 0 to 10.
hoursnumber | nullrequiredHours of interviews a week at most; null: no hour limit.
From 0 to 20.
paused_untilstring | nullPattern
^\d{4}-\d{2}-\d{2}$.
Returns
9 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
setbooleanrequiredThey have said when they can usually interview (without it nobody books them).
time_zonestringrequiredTheir time zone: their location's, else the company's. Windows are in it.
windowsobject[]required3 fields
dayintegerrequired1 Monday … 7 Sunday.
From 1 to 7.
fromstringrequiredPattern
^(?:[01]\d|2[0-3]):[03]0$|^24:00$.tostringrequiredPattern
^(?:[01]\d|2[0-3]):[03]0$|^24:00$.
hours_a_weeknumberrequiredHours the windows cover in a week.
capobjectrequired2 fields
interviewsintegerrequiredInterviews a week at most (0: none for now).
From 0 to 10.
hoursnumber | nullrequiredHours of interviews a week at most; null: no hour limit.
From 0 to 20.
paused_untilstring | nullrequiredNot asked until this day (inclusive).
loadobjectrequired2 fields
weekobjectrequiredThis ISO week: interviews booked or held, and their hours.
2 fields
interviewsintegerrequiredhoursnumberrequired
monthintegerrequiredInterviews held and booked this calendar month.
updated_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/availability.set \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"windows": [
{
"day": 2,
"from": "10:00",
"to": "12:00"
},
{
"day": 4,
"from": "14:00",
"to": "17:00"
}
],
"cap": {
"interviews": 2,
"hours": 3
}
}'const res = await fetch('https://api.bizisy.com/v1/hiring/availability.set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"windows": [
{
"day": 2,
"from": "10:00",
"to": "12:00"
},
{
"day": 4,
"from": "14:00",
"to": "17:00"
}
],
"cap": {
"interviews": 2,
"hours": 3
}
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/availability.set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"windows": [
{
"day": 2,
"from": "10:00",
"to": "12:00",
},
{
"day": 4,
"from": "14:00",
"to": "17:00",
},
],
"cap": {
"interviews": 2,
"hours": 3,
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person": {
"id": "p4",
"name": "Ivo Matos"
},
"set": true,
"time_zone": "Europe/Lisbon",
"windows": [
{
"day": 2,
"from": "10:00",
"to": "12:00"
},
{
"day": 4,
"from": "14:00",
"to": "17:00"
}
],
"hours_a_week": 5,
"cap": {
"interviews": 2,
"hours": 3
},
"paused_until": null,
"load": {
"week": {
"interviews": 1,
"hours": 1
},
"month": 3
},
"updated_at": "2026-10-18T09:00:00.000Z"
}
}Open times for an interview#
POST/v1/hiring/interviews.slotsRead
When a candidate can be interviewed at a step (default: the step they are in), with interviews in Bizisy for the job and interviewers_needed of at least 1. Every start on the half hour between 08:00 and 20:00 company time, from 24 hours ahead for 14 days (21 for interviews over 3 hours), where interviewers_needed people of the step's interview group each have the whole interview plus its buffer inside their usual week (their time zone), no time off or public holiday that day, no other interview or held time, and room under their weekly cap counting this interview. Each time lists everyone available and the suggested people (least loaded this month, then that week); the candidate's referrer is never asked. At most 60 times; people without a usual week are listed in missing_availability. Owners, admins and HR, or the job's hiring manager.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
hiring_interviews_slotson HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
application_idstringrequired1–100 characters.
step_idstring1–40 characters.
Returns
8 fields
application_idstringrequiredstepobjectrequired5 fields
idstringrequirednamestringrequiredminutesintegerrequiredbuffer_minutesintegerrequiredinterviewers_neededintegerrequired
time_zonestringrequiredThe company's time zone: date and time of each start are in it.
daysintegerrequiredDays looked ahead (14; 21 for interviews over 3 hours).
timesobject[]required6 fields
startstringrequiredendstringrequireddatestringrequiredtimestringrequiredpeoplestring[]requiredEveryone available then (person ids; names in people below).
suggestedstring[]requiredWho Bizisy suggests: the least loaded this month, then that week.
peopleobject[]required4 fields
idstringrequirednamestringrequiredtime_zonestringrequiredloadobjectrequiredInterviews held and booked this month and this week.
2 fields
monthintegerrequiredweekintegerrequired
missing_availabilityobject[]requiredIn the step's interview group but without a usual week set: nobody books them until they set one.
2 fields
idstringrequirednamestringrequired
referrer_excludedbooleanrequiredThe colleague who referred this candidate is left out (conflict of interest).
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/interviews.slots \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"application_id":"a1","step_id":"trial"}'const res = await fetch('https://api.bizisy.com/v1/hiring/interviews.slots', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"application_id": "a1",
"step_id": "trial"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/interviews.slots",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"application_id": "a1",
"step_id": "trial",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"application_id": "a1",
"step": {
"id": "trial",
"name": "Trial shift",
"minutes": 240,
"buffer_minutes": 30,
"interviewers_needed": 1
},
"time_zone": "Europe/Lisbon",
"days": 21,
"times": [
{
"start": "2026-10-27T09:00:00.000Z",
"end": "2026-10-27T13:00:00.000Z",
"date": "2026-10-27",
"time": "09:00",
"people": [
"p2",
"p4"
],
"suggested": [
"p4"
]
}
],
"people": [
{
"id": "p2",
"name": "Rita Lopes",
"time_zone": "Europe/Lisbon",
"load": {
"month": 4,
"week": 1
}
},
{
"id": "p4",
"name": "Ivo Matos",
"time_zone": "Europe/Lisbon",
"load": {
"month": 3,
"week": 1
}
}
],
"missing_availability": [
{
"id": "p5",
"name": "Bea Lima"
}
],
"referrer_excluded": false
}
}List interviews#
POST/v1/hiring/interviews.listRead
Interviews of one candidate (application_id) or of one job (job_id): booked ones with their time, place, people and whether they are over; offered times held for the candidate; requested (the candidate asked for other times), expired, cancelled and no-show ones. upcoming true: only those still to come (booked and not over, or offered and held). Newest first. Owners, admins and HR, or the job's hiring manager.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
hiring_interviews_liston HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
application_idstring1–100 characters.
job_idstring1–100 characters.
upcomingbooleanDefault
false.
Returns
interviewsobject[]required24 fields
idstringrequiredjob_idstringrequiredapplication_idstring | nullrequiredcandidateobject | nullrequiredThe candidate (their name as they applied).
2 fields
idstringrequirednamestringrequired
stepobjectrequired2 fields
idstringrequirednamestring | nullrequired
status"offered" | "booked" | "requested" | "expired" | "cancelled" | "no_show"requiredoffered (times held for the candidate), booked, requested (the candidate asked for other times), expired (the offer lapsed), cancelled, no_show.
heldbooleanrequiredBooked and already over.
minutesintegerrequiredbuffer_minutesintegerrequiredplaceobjectrequired4 fields
kind"video" | "video_auto" | "phone" | "on_site" | "none"requiredvideo (a link HR pasted), video_auto (a Google Meet or Teams link the connected calendar makes), phone, on_site, none.
addressstring | nullrequiredlinkstring | nullrequiredThe meeting link: pasted, or made by the calendar (video_auto; null until made).
link_source"google_meet" | "teams"requiredgoogle_meet or teams: the calendar made the link; null: pasted, or none yet.
calendarobject | nullrequiredHeld on the company's calendar (spec 2026-10-19-hiring-calendar-events); null: invitations by Bizisy's emails.
4 fields
connector"google_calendar" | "outlook_calendar"requirednamestringrequiredstate"pending" | "synced" | "fallback"requiredpending: going to the calendar; synced: on it, the provider sent the invitations; fallback: the calendar could not, so Bizisy emailed the invitations with a calendar file.
no_linkbooleanrequiredThe step asked for a video link and the calendar made none (a Microsoft account without Teams).
startstring | nullrequiredendstring | nullrequiredinterviewersobject[]required2 fields
idstringrequirednamestringrequired
offersobject[]requiredThe times offered (while offered).
3 fields
startstringrequiredendstringrequiredinterviewersobject[]required2 fields
idstringrequirednamestringrequired
hold_untilstring | nullrequiredOffered times are held until then.
reschedulesintegerrequiredchange_requestedobject | nullrequiredThe candidate asked for another time (status page).
2 fields
atstringrequirednotestring | nullrequired
needs_hrbooleanrequiredOn Home: the offer expired, or the candidate asked for other times.
booked_by"team" | "candidate"requiredcancelledobject | nullrequired2 fields
atstringrequiredby"team" | "candidate" | "system"required
erased_interviewersintegerrequiredcreated_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/interviews.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"job_id":"j1","upcoming":true}'const res = await fetch('https://api.bizisy.com/v1/hiring/interviews.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"job_id": "j1",
"upcoming": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/interviews.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"job_id": "j1",
"upcoming": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"interviews": [
{
"id": "iv1",
"job_id": "j1",
"application_id": "a1",
"candidate": {
"id": "c1",
"name": "Maria Silva"
},
"step": {
"id": "trial",
"name": "Trial shift"
},
"status": "booked",
"held": false,
"minutes": 240,
"buffer_minutes": 30,
"place": {
"kind": "on_site",
"address": "Rua do Souto 12, Braga",
"link": null,
"link_source": null
},
"calendar": null,
"start": "2026-10-27T09:00:00.000Z",
"end": "2026-10-27T13:00:00.000Z",
"interviewers": [
{
"id": "p4",
"name": "Ivo Matos"
}
],
"offers": [],
"hold_until": null,
"reschedules": 0,
"change_requested": null,
"needs_hr": false,
"booked_by": "team",
"cancelled": null,
"erased_interviewers": 0,
"created_at": "2026-10-18T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z"
},
{
"id": "iv2",
"job_id": "j1",
"application_id": "a1",
"candidate": {
"id": "c1",
"name": "Maria Silva"
},
"step": {
"id": "trial",
"name": "Trial shift"
},
"status": "offered",
"held": false,
"minutes": 240,
"buffer_minutes": 30,
"place": {
"kind": "on_site",
"address": "Rua do Souto 12, Braga",
"link": null,
"link_source": null
},
"calendar": null,
"start": null,
"end": null,
"interviewers": [],
"offers": [
{
"start": "2026-10-27T09:00:00.000Z",
"end": "2026-10-27T13:00:00.000Z",
"interviewers": [
{
"id": "p4",
"name": "Ivo Matos"
}
]
},
{
"start": "2026-10-29T13:00:00.000Z",
"end": "2026-10-29T17:00:00.000Z",
"interviewers": [
{
"id": "p2",
"name": "Rita Lopes"
}
]
}
],
"hold_until": "2026-10-20T09:00:00.000Z",
"reschedules": 0,
"change_requested": null,
"needs_hr": false,
"booked_by": null,
"cancelled": null,
"erased_interviewers": 0,
"created_at": "2026-10-18T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z"
},
{
"id": "iv3",
"job_id": "j1",
"application_id": "a1",
"candidate": {
"id": "c1",
"name": "Maria Silva"
},
"step": {
"id": "interview",
"name": "Interview"
},
"status": "booked",
"held": false,
"minutes": 60,
"buffer_minutes": 15,
"place": {
"kind": "video_auto",
"address": null,
"link": "https://meet.google.com/abc-defg-hij",
"link_source": "google_meet"
},
"calendar": {
"connector": "google_calendar",
"name": "Google Calendar",
"state": "synced",
"no_link": false
},
"start": "2026-10-28T10:00:00.000Z",
"end": "2026-10-28T11:00:00.000Z",
"interviewers": [
{
"id": "p4",
"name": "Ivo Matos"
}
],
"offers": [],
"hold_until": null,
"reschedules": 0,
"change_requested": null,
"needs_hr": false,
"booked_by": "team",
"cancelled": null,
"erased_interviewers": 0,
"created_at": "2026-10-18T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z"
}
]
}
}Book an interview#
POST/v1/hiring/interviews.bookWrite
Books an interview with a candidate at a step (default: the step they are in) at start (ISO date and time, on the half hour, 08:00–20:00 company time, at least 24 hours ahead, within 21 days) with interviewer_ids (at least the step's interviewers_needed, at most 5): each must be in the step's interview group, employed, not the candidate's referrer, and available for the whole interview plus its buffer in their usual week, away from time off and other interviews, under their weekly cap. Checked again as it saves: if someone was booked meanwhile it is refused, saying who and why. Emails the candidate (job's language; with message, the hiring team's personal line before the details) and each interviewer (their language and time zone) an invitation with a calendar file, adds a notice for the interviewers, records it on the candidate, and sends the hiring.interview_booked webhook. One booked or offered interview per candidate and step at a time. Owners, admins and HR, or the job's hiring manager, signed in to Bizisy: refused over an API key or MCP.
- Web app only
- Refused for API keys and connected apps. Booking an interview (it emails the candidate and the interviewers) happens in the app.
- MCP tool
hiring_interviews_bookon HR Assistant, My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
application_idstringrequired1–100 characters.
step_idstring1–40 characters.
startdate-timerequiredISO 8601 date and time (UTC).
interviewer_idsstring[]required1–100 characters. 1–5 items.
messagestring | nullA personal line for the candidate (plain text, paragraphs split by a blank line, at most 1000 characters), e.g. who they will meet: an extra paragraph in the candidate's email before the times, kept on the candidate's history and their status page. Never in the interviewers' emails.
Up to 1000 characters.
Returns
24 fields
idstringrequiredjob_idstringrequiredapplication_idstring | nullrequiredcandidateobject | nullrequiredThe candidate (their name as they applied).
2 fields
idstringrequirednamestringrequired
stepobjectrequired2 fields
idstringrequirednamestring | nullrequired
status"offered" | "booked" | "requested" | "expired" | "cancelled" | "no_show"requiredoffered (times held for the candidate), booked, requested (the candidate asked for other times), expired (the offer lapsed), cancelled, no_show.
heldbooleanrequiredBooked and already over.
minutesintegerrequiredbuffer_minutesintegerrequiredplaceobjectrequired4 fields
kind"video" | "video_auto" | "phone" | "on_site" | "none"requiredvideo (a link HR pasted), video_auto (a Google Meet or Teams link the connected calendar makes), phone, on_site, none.
addressstring | nullrequiredlinkstring | nullrequiredThe meeting link: pasted, or made by the calendar (video_auto; null until made).
link_source"google_meet" | "teams"requiredgoogle_meet or teams: the calendar made the link; null: pasted, or none yet.
calendarobject | nullrequiredHeld on the company's calendar (spec 2026-10-19-hiring-calendar-events); null: invitations by Bizisy's emails.
4 fields
connector"google_calendar" | "outlook_calendar"requirednamestringrequiredstate"pending" | "synced" | "fallback"requiredpending: going to the calendar; synced: on it, the provider sent the invitations; fallback: the calendar could not, so Bizisy emailed the invitations with a calendar file.
no_linkbooleanrequiredThe step asked for a video link and the calendar made none (a Microsoft account without Teams).
startstring | nullrequiredendstring | nullrequiredinterviewersobject[]required2 fields
idstringrequirednamestringrequired
offersobject[]requiredThe times offered (while offered).
3 fields
startstringrequiredendstringrequiredinterviewersobject[]required2 fields
idstringrequirednamestringrequired
hold_untilstring | nullrequiredOffered times are held until then.
reschedulesintegerrequiredchange_requestedobject | nullrequiredThe candidate asked for another time (status page).
2 fields
atstringrequirednotestring | nullrequired
needs_hrbooleanrequiredOn Home: the offer expired, or the candidate asked for other times.
booked_by"team" | "candidate"requiredcancelledobject | nullrequired2 fields
atstringrequiredby"team" | "candidate" | "system"required
erased_interviewersintegerrequiredcreated_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/interviews.book \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"application_id": "a1",
"start": "2026-10-27T09:00:00.000Z",
"interviewer_ids": [
"p4"
],
"message": "You will meet Rui, our head chef.\n\nBring your knives."
}'const res = await fetch('https://api.bizisy.com/v1/hiring/interviews.book', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"application_id": "a1",
"start": "2026-10-27T09:00:00.000Z",
"interviewer_ids": [
"p4"
],
"message": "You will meet Rui, our head chef.\n\nBring your knives."
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/interviews.book",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"application_id": "a1",
"start": "2026-10-27T09:00:00.000Z",
"interviewer_ids": [
"p4",
],
"message": "You will meet Rui, our head chef.\n\nBring your knives.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "iv1",
"job_id": "j1",
"application_id": "a1",
"candidate": {
"id": "c1",
"name": "Maria Silva"
},
"step": {
"id": "trial",
"name": "Trial shift"
},
"status": "booked",
"held": false,
"minutes": 240,
"buffer_minutes": 30,
"place": {
"kind": "on_site",
"address": "Rua do Souto 12, Braga",
"link": null,
"link_source": null
},
"calendar": null,
"start": "2026-10-27T09:00:00.000Z",
"end": "2026-10-27T13:00:00.000Z",
"interviewers": [
{
"id": "p4",
"name": "Ivo Matos"
}
],
"offers": [],
"hold_until": null,
"reschedules": 0,
"change_requested": null,
"needs_hr": false,
"booked_by": "team",
"cancelled": null,
"erased_interviewers": 0,
"created_at": "2026-10-18T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z"
}
}Offer interview times to a candidate#
POST/v1/hiring/interviews.offerWrite
Lets the candidate pick: up to 8 times (start each, from hiring_interviews_slots) for a step (default: the step they are in), each with interviewer_ids or, left out, the suggested people available then. The times are held for 48 hours (those people count as busy then); the candidate gets an email (with message, the hiring team's personal line before the times) with a fresh link to their application page (it replaces earlier links) and picks one there: the first time whose people (or other available people of the group) are still available is booked, the rest released. If nobody picks within 48 hours the offer expires and Home tells HR. At most 20 open offers per job; one booked or offered interview per candidate and step. Owners, admins and HR, or the job's hiring manager, signed in to Bizisy: refused over an API key or MCP.
- Web app only
- Refused for API keys and connected apps. Offering interview times (it emails the candidate) happens in the app.
- MCP tool
hiring_interviews_offeron HR Assistant, My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
application_idstringrequired1–100 characters.
step_idstring1–40 characters.
timesobject[]required1–8 items.
2 fields
startdate-timerequiredISO 8601 date and time (UTC).
interviewer_idsstring[]1–100 characters. 1–5 items.
messagestring | nullA personal line for the candidate (plain text, paragraphs split by a blank line, at most 1000 characters), e.g. who they will meet: an extra paragraph in the candidate's email before the times, kept on the candidate's history and their status page. Never in the interviewers' emails.
Up to 1000 characters.
Returns
25 fields
idstringrequiredjob_idstringrequiredapplication_idstring | nullrequiredcandidateobject | nullrequiredThe candidate (their name as they applied).
2 fields
idstringrequirednamestringrequired
stepobjectrequired2 fields
idstringrequirednamestring | nullrequired
status"offered" | "booked" | "requested" | "expired" | "cancelled" | "no_show"requiredoffered (times held for the candidate), booked, requested (the candidate asked for other times), expired (the offer lapsed), cancelled, no_show.
heldbooleanrequiredBooked and already over.
minutesintegerrequiredbuffer_minutesintegerrequiredplaceobjectrequired4 fields
kind"video" | "video_auto" | "phone" | "on_site" | "none"requiredvideo (a link HR pasted), video_auto (a Google Meet or Teams link the connected calendar makes), phone, on_site, none.
addressstring | nullrequiredlinkstring | nullrequiredThe meeting link: pasted, or made by the calendar (video_auto; null until made).
link_source"google_meet" | "teams"requiredgoogle_meet or teams: the calendar made the link; null: pasted, or none yet.
calendarobject | nullrequiredHeld on the company's calendar (spec 2026-10-19-hiring-calendar-events); null: invitations by Bizisy's emails.
4 fields
connector"google_calendar" | "outlook_calendar"requirednamestringrequiredstate"pending" | "synced" | "fallback"requiredpending: going to the calendar; synced: on it, the provider sent the invitations; fallback: the calendar could not, so Bizisy emailed the invitations with a calendar file.
no_linkbooleanrequiredThe step asked for a video link and the calendar made none (a Microsoft account without Teams).
startstring | nullrequiredendstring | nullrequiredinterviewersobject[]required2 fields
idstringrequirednamestringrequired
offersobject[]requiredThe times offered (while offered).
3 fields
startstringrequiredendstringrequiredinterviewersobject[]required2 fields
idstringrequirednamestringrequired
hold_untilstring | nullrequiredOffered times are held until then.
reschedulesintegerrequiredchange_requestedobject | nullrequiredThe candidate asked for another time (status page).
2 fields
atstringrequirednotestring | nullrequired
needs_hrbooleanrequiredOn Home: the offer expired, or the candidate asked for other times.
booked_by"team" | "candidate"requiredcancelledobject | nullrequired2 fields
atstringrequiredby"team" | "candidate" | "system"required
erased_interviewersintegerrequiredcreated_atstringrequiredupdated_atstringrequiredemailedbooleanrequiredThe candidate was emailed the times.
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/interviews.offer \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"application_id": "a1",
"times": [
{
"start": "2026-10-27T09:00:00.000Z"
},
{
"start": "2026-10-29T13:00:00.000Z",
"interviewer_ids": [
"p2"
]
}
]
}'const res = await fetch('https://api.bizisy.com/v1/hiring/interviews.offer', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"application_id": "a1",
"times": [
{
"start": "2026-10-27T09:00:00.000Z"
},
{
"start": "2026-10-29T13:00:00.000Z",
"interviewer_ids": [
"p2"
]
}
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/interviews.offer",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"application_id": "a1",
"times": [
{
"start": "2026-10-27T09:00:00.000Z",
},
{
"start": "2026-10-29T13:00:00.000Z",
"interviewer_ids": [
"p2",
],
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "iv2",
"job_id": "j1",
"application_id": "a1",
"candidate": {
"id": "c1",
"name": "Maria Silva"
},
"step": {
"id": "trial",
"name": "Trial shift"
},
"status": "offered",
"held": false,
"minutes": 240,
"buffer_minutes": 30,
"place": {
"kind": "on_site",
"address": "Rua do Souto 12, Braga",
"link": null,
"link_source": null
},
"calendar": null,
"start": null,
"end": null,
"interviewers": [],
"offers": [
{
"start": "2026-10-27T09:00:00.000Z",
"end": "2026-10-27T13:00:00.000Z",
"interviewers": [
{
"id": "p4",
"name": "Ivo Matos"
}
]
},
{
"start": "2026-10-29T13:00:00.000Z",
"end": "2026-10-29T17:00:00.000Z",
"interviewers": [
{
"id": "p2",
"name": "Rita Lopes"
}
]
}
],
"hold_until": "2026-10-20T09:00:00.000Z",
"reschedules": 0,
"change_requested": null,
"needs_hr": false,
"booked_by": null,
"cancelled": null,
"erased_interviewers": 0,
"created_at": "2026-10-18T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z",
"emailed": true
}
}Move an interview#
POST/v1/hiring/interviews.rescheduleWrite
Moves a booked interview that has not started to a new start (same rules as booking), with the same people or other interviewer_ids, each available then. Everyone gets the updated invitation (the same calendar event, a higher revision; message: a personal line in the candidate's email only); interviewers taken off get a cancellation. At most 3 moves per interview. Sends the hiring.interview_booked webhook (rescheduled true). Owners, admins and HR, or the job's hiring manager, signed in to Bizisy: refused over an API key or MCP.
- Web app only
- Refused for API keys and connected apps. Moving an interview (it emails everyone) happens in the app.
- MCP tool
hiring_interviews_rescheduleon HR Assistant, My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
interview_idstringrequired1–100 characters.
startdate-timerequiredISO 8601 date and time (UTC).
interviewer_idsstring[]1–100 characters. 1–5 items.
messagestring | nullA personal line for the candidate (plain text, paragraphs split by a blank line, at most 1000 characters), e.g. who they will meet: an extra paragraph in the candidate's email before the times, kept on the candidate's history and their status page. Never in the interviewers' emails.
Up to 1000 characters.
Returns
24 fields
idstringrequiredjob_idstringrequiredapplication_idstring | nullrequiredcandidateobject | nullrequiredThe candidate (their name as they applied).
2 fields
idstringrequirednamestringrequired
stepobjectrequired2 fields
idstringrequirednamestring | nullrequired
status"offered" | "booked" | "requested" | "expired" | "cancelled" | "no_show"requiredoffered (times held for the candidate), booked, requested (the candidate asked for other times), expired (the offer lapsed), cancelled, no_show.
heldbooleanrequiredBooked and already over.
minutesintegerrequiredbuffer_minutesintegerrequiredplaceobjectrequired4 fields
kind"video" | "video_auto" | "phone" | "on_site" | "none"requiredvideo (a link HR pasted), video_auto (a Google Meet or Teams link the connected calendar makes), phone, on_site, none.
addressstring | nullrequiredlinkstring | nullrequiredThe meeting link: pasted, or made by the calendar (video_auto; null until made).
link_source"google_meet" | "teams"requiredgoogle_meet or teams: the calendar made the link; null: pasted, or none yet.
calendarobject | nullrequiredHeld on the company's calendar (spec 2026-10-19-hiring-calendar-events); null: invitations by Bizisy's emails.
4 fields
connector"google_calendar" | "outlook_calendar"requirednamestringrequiredstate"pending" | "synced" | "fallback"requiredpending: going to the calendar; synced: on it, the provider sent the invitations; fallback: the calendar could not, so Bizisy emailed the invitations with a calendar file.
no_linkbooleanrequiredThe step asked for a video link and the calendar made none (a Microsoft account without Teams).
startstring | nullrequiredendstring | nullrequiredinterviewersobject[]required2 fields
idstringrequirednamestringrequired
offersobject[]requiredThe times offered (while offered).
3 fields
startstringrequiredendstringrequiredinterviewersobject[]required2 fields
idstringrequirednamestringrequired
hold_untilstring | nullrequiredOffered times are held until then.
reschedulesintegerrequiredchange_requestedobject | nullrequiredThe candidate asked for another time (status page).
2 fields
atstringrequirednotestring | nullrequired
needs_hrbooleanrequiredOn Home: the offer expired, or the candidate asked for other times.
booked_by"team" | "candidate"requiredcancelledobject | nullrequired2 fields
atstringrequiredby"team" | "candidate" | "system"required
erased_interviewersintegerrequiredcreated_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/interviews.reschedule \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"interview_id": "iv1",
"start": "2026-10-28T09:00:00.000Z",
"message": "Sorry for the change."
}'const res = await fetch('https://api.bizisy.com/v1/hiring/interviews.reschedule', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"interview_id": "iv1",
"start": "2026-10-28T09:00:00.000Z",
"message": "Sorry for the change."
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/interviews.reschedule",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"interview_id": "iv1",
"start": "2026-10-28T09:00:00.000Z",
"message": "Sorry for the change.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "iv1",
"job_id": "j1",
"application_id": "a1",
"candidate": {
"id": "c1",
"name": "Maria Silva"
},
"step": {
"id": "trial",
"name": "Trial shift"
},
"status": "booked",
"held": false,
"minutes": 240,
"buffer_minutes": 30,
"place": {
"kind": "on_site",
"address": "Rua do Souto 12, Braga",
"link": null,
"link_source": null
},
"calendar": null,
"start": "2026-10-28T09:00:00.000Z",
"end": "2026-10-28T13:00:00.000Z",
"interviewers": [
{
"id": "p4",
"name": "Ivo Matos"
}
],
"offers": [],
"hold_until": null,
"reschedules": 1,
"change_requested": null,
"needs_hr": false,
"booked_by": "team",
"cancelled": null,
"erased_interviewers": 0,
"created_at": "2026-10-18T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z"
}
}Cancel an interview#
POST/v1/hiring/interviews.cancelWrite
Cancels an interview: a booked one that has not ended (the candidate and the interviewers get a cancellation that takes it out of their calendars; sends the hiring.interview_cancelled webhook), or offered times (released at once; the candidate's page stops offering them), or one HR was told about (expired, or the candidate asked for other times). Owners, admins and HR, or the job's hiring manager, signed in to Bizisy: refused over an API key or MCP.
- Web app only
- Refused for API keys and connected apps. Cancelling an interview (it emails everyone) happens in the app.
- MCP tool
hiring_interviews_cancelon HR Assistant, My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
interview_idstringrequired1–100 characters.
Returns
24 fields
idstringrequiredjob_idstringrequiredapplication_idstring | nullrequiredcandidateobject | nullrequiredThe candidate (their name as they applied).
2 fields
idstringrequirednamestringrequired
stepobjectrequired2 fields
idstringrequirednamestring | nullrequired
status"offered" | "booked" | "requested" | "expired" | "cancelled" | "no_show"requiredoffered (times held for the candidate), booked, requested (the candidate asked for other times), expired (the offer lapsed), cancelled, no_show.
heldbooleanrequiredBooked and already over.
minutesintegerrequiredbuffer_minutesintegerrequiredplaceobjectrequired4 fields
kind"video" | "video_auto" | "phone" | "on_site" | "none"requiredvideo (a link HR pasted), video_auto (a Google Meet or Teams link the connected calendar makes), phone, on_site, none.
addressstring | nullrequiredlinkstring | nullrequiredThe meeting link: pasted, or made by the calendar (video_auto; null until made).
link_source"google_meet" | "teams"requiredgoogle_meet or teams: the calendar made the link; null: pasted, or none yet.
calendarobject | nullrequiredHeld on the company's calendar (spec 2026-10-19-hiring-calendar-events); null: invitations by Bizisy's emails.
4 fields
connector"google_calendar" | "outlook_calendar"requirednamestringrequiredstate"pending" | "synced" | "fallback"requiredpending: going to the calendar; synced: on it, the provider sent the invitations; fallback: the calendar could not, so Bizisy emailed the invitations with a calendar file.
no_linkbooleanrequiredThe step asked for a video link and the calendar made none (a Microsoft account without Teams).
startstring | nullrequiredendstring | nullrequiredinterviewersobject[]required2 fields
idstringrequirednamestringrequired
offersobject[]requiredThe times offered (while offered).
3 fields
startstringrequiredendstringrequiredinterviewersobject[]required2 fields
idstringrequirednamestringrequired
hold_untilstring | nullrequiredOffered times are held until then.
reschedulesintegerrequiredchange_requestedobject | nullrequiredThe candidate asked for another time (status page).
2 fields
atstringrequirednotestring | nullrequired
needs_hrbooleanrequiredOn Home: the offer expired, or the candidate asked for other times.
booked_by"team" | "candidate"requiredcancelledobject | nullrequired2 fields
atstringrequiredby"team" | "candidate" | "system"required
erased_interviewersintegerrequiredcreated_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/interviews.cancel \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"interview_id":"iv1"}'const res = await fetch('https://api.bizisy.com/v1/hiring/interviews.cancel', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"interview_id": "iv1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/interviews.cancel",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"interview_id": "iv1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "iv1",
"job_id": "j1",
"application_id": "a1",
"candidate": {
"id": "c1",
"name": "Maria Silva"
},
"step": {
"id": "trial",
"name": "Trial shift"
},
"status": "cancelled",
"held": false,
"minutes": 240,
"buffer_minutes": 30,
"place": {
"kind": "on_site",
"address": "Rua do Souto 12, Braga",
"link": null,
"link_source": null
},
"calendar": null,
"start": "2026-10-27T09:00:00.000Z",
"end": "2026-10-27T13:00:00.000Z",
"interviewers": [
{
"id": "p4",
"name": "Ivo Matos"
}
],
"offers": [],
"hold_until": null,
"reschedules": 0,
"change_requested": null,
"needs_hr": false,
"booked_by": "team",
"cancelled": {
"at": "2026-10-19T09:00:00.000Z",
"by": "team"
},
"erased_interviewers": 0,
"created_at": "2026-10-18T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z"
}
}Record that a candidate did not come#
POST/v1/hiring/interviews.no_showWrite
Records that the candidate did not come to a booked interview that has started (it still counts in the interviewers' load). Owners, admins and HR, signed in to Bizisy.
- Web app only
- Refused for API keys and connected apps. A no-show is recorded in the app.
- MCP tool
hiring_interviews_no_showon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
interview_idstringrequired1–100 characters.
Returns
24 fields
idstringrequiredjob_idstringrequiredapplication_idstring | nullrequiredcandidateobject | nullrequiredThe candidate (their name as they applied).
2 fields
idstringrequirednamestringrequired
stepobjectrequired2 fields
idstringrequirednamestring | nullrequired
status"offered" | "booked" | "requested" | "expired" | "cancelled" | "no_show"requiredoffered (times held for the candidate), booked, requested (the candidate asked for other times), expired (the offer lapsed), cancelled, no_show.
heldbooleanrequiredBooked and already over.
minutesintegerrequiredbuffer_minutesintegerrequiredplaceobjectrequired4 fields
kind"video" | "video_auto" | "phone" | "on_site" | "none"requiredvideo (a link HR pasted), video_auto (a Google Meet or Teams link the connected calendar makes), phone, on_site, none.
addressstring | nullrequiredlinkstring | nullrequiredThe meeting link: pasted, or made by the calendar (video_auto; null until made).
link_source"google_meet" | "teams"requiredgoogle_meet or teams: the calendar made the link; null: pasted, or none yet.
calendarobject | nullrequiredHeld on the company's calendar (spec 2026-10-19-hiring-calendar-events); null: invitations by Bizisy's emails.
4 fields
connector"google_calendar" | "outlook_calendar"requirednamestringrequiredstate"pending" | "synced" | "fallback"requiredpending: going to the calendar; synced: on it, the provider sent the invitations; fallback: the calendar could not, so Bizisy emailed the invitations with a calendar file.
no_linkbooleanrequiredThe step asked for a video link and the calendar made none (a Microsoft account without Teams).
startstring | nullrequiredendstring | nullrequiredinterviewersobject[]required2 fields
idstringrequirednamestringrequired
offersobject[]requiredThe times offered (while offered).
3 fields
startstringrequiredendstringrequiredinterviewersobject[]required2 fields
idstringrequirednamestringrequired
hold_untilstring | nullrequiredOffered times are held until then.
reschedulesintegerrequiredchange_requestedobject | nullrequiredThe candidate asked for another time (status page).
2 fields
atstringrequirednotestring | nullrequired
needs_hrbooleanrequiredOn Home: the offer expired, or the candidate asked for other times.
booked_by"team" | "candidate"requiredcancelledobject | nullrequired2 fields
atstringrequiredby"team" | "candidate" | "system"required
erased_interviewersintegerrequiredcreated_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/interviews.no_show \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"interview_id":"iv1"}'const res = await fetch('https://api.bizisy.com/v1/hiring/interviews.no_show', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"interview_id": "iv1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/interviews.no_show",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"interview_id": "iv1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "iv1",
"job_id": "j1",
"application_id": "a1",
"candidate": {
"id": "c1",
"name": "Maria Silva"
},
"step": {
"id": "trial",
"name": "Trial shift"
},
"status": "no_show",
"held": true,
"minutes": 240,
"buffer_minutes": 30,
"place": {
"kind": "on_site",
"address": "Rua do Souto 12, Braga",
"link": null,
"link_source": null
},
"calendar": null,
"start": "2026-10-27T09:00:00.000Z",
"end": "2026-10-27T13:00:00.000Z",
"interviewers": [
{
"id": "p4",
"name": "Ivo Matos"
}
],
"offers": [],
"hold_until": null,
"reschedules": 0,
"change_requested": null,
"needs_hr": false,
"booked_by": "team",
"cancelled": null,
"erased_interviewers": 0,
"created_at": "2026-10-18T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z"
}
}Which calendar sends interview invitations#
POST/v1/hiring/interviews.calendarRead
Where interviews booked now go out from: the company's connected calendar (connector google_calendar or outlook_calendar; the provider invites the candidate and the interviewers, and a step with place video_auto gets a Google Meet or Microsoft Teams link made for each interview, meeting google_meet or teams), or none (connector null: Bizisy emails everyone an invitation with a calendar file; video_auto steps can't be booked until a calendar is connected in Integrations (Google Calendar or Outlook Calendar)). Owners, admins and HR, or a hiring manager.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
hiring_interviews_calendaron HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
connector"google_calendar" | "outlook_calendar"requirednamestring | nullrequiredmeeting"google_meet" | "teams"required
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/interviews.calendar \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/hiring/interviews.calendar', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/interviews.calendar",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"connector": "google_calendar",
"name": "Google Calendar",
"meeting": "google_meet"
}
}Save my interview feedback#
POST/v1/hiring/feedback.saveWrite
Saves your feedback on an interview you give as a draft (autosave: send what changed; the same call again changes nothing): ratings 1 to 4 for skills of the step's scorecard, text (≤ 5,000 characters), overall (your answer to its overall question) and recommendation (strong_no, no, yes or strong_yes). A draft is yours alone: nobody else sees it, not even HR. Send it with hiring_feedback_submit. Only the interviewer, from the booking until 30 days after the interview; once sent it can't change (add a note with hiring_feedback_add_note). Signed in to Bizisy only: refused over an API key or MCP.
- Web app only
- Refused for API keys and connected apps. Feedback is written by the interviewer in the app.
- MCP tool
hiring_feedback_saveon My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
interview_idstringrequired1–100 characters.
ratingsobject[]1 (clear concerns) to 4 (excellent) for skills of the step's scorecard (skill ids from hiring_me_interview step.scorecard).
Up to 8 items.
2 fields
skill_idstringrequired1–40 characters.
ratingintegerrequiredFrom 1 to 4.
textstringWhat you saw, in your words (≤ 5,000 characters). The candidate can ask to read it.
Up to 5000 characters.
overallstring | nullYour answer to the scorecard's overall question.
Up to 2000 characters.
recommendation"strong_no" | "no" | "yes" | "strong_yes"strong_no, no, yes or strong_yes.
Returns
17 fields
idstringrequiredinterview_idstringrequiredapplication_idstring | nullrequiredstepobjectrequired2 fields
idstringrequirednamestring | nullrequired
authorobject | nullrequiredWho wrote it; null once they were erased (show "A former colleague").
2 fields
idstringrequirednamestringrequired
author_erasedbooleanrequiredminebooleanrequiredYours.
status"draft" | "submitted"requireddraft: only its author sees it; submitted: final (correction notes may follow).
ratingsobject[]required1 (clear concerns) to 4 (excellent) per skill of the step's scorecard.
3 fields
skill_idstringrequirednamestringrequiredratingintegerrequiredFrom 1 to 4.
textstringrequiredoverallstring | nullrequiredThe answer to the scorecard's overall question.
recommendation"strong_no" | "no" | "yes" | "strong_yes"requireddue_atstringrequiredsubmitted_atstring | nullrequiredon_timeboolean | nullrequiredSent by the time it was due.
notesobject[]requiredCorrections added after sending.
2 fields
textstringrequiredatstringrequired
updated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/feedback.save \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"interview_id": "ivb3",
"text": "Quick with the knife.",
"overall": "Calm.",
"recommendation": "yes"
}'const res = await fetch('https://api.bizisy.com/v1/hiring/feedback.save', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"interview_id": "ivb3",
"text": "Quick with the knife.",
"overall": "Calm.",
"recommendation": "yes"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/feedback.save",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"interview_id": "ivb3",
"text": "Quick with the knife.",
"overall": "Calm.",
"recommendation": "yes",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "o1:iv0:p4",
"interview_id": "iv0",
"application_id": "a1",
"step": {
"id": "trial",
"name": "Trial shift"
},
"author": {
"id": "p4",
"name": "Ivo Matos"
},
"author_erased": false,
"mine": true,
"status": "draft",
"ratings": [
{
"skill_id": "practical",
"name": "Practical work",
"rating": 3
}
],
"text": "Quick with the knife.",
"overall": "Calm.",
"recommendation": "yes",
"due_at": "2026-10-17T13:00:00.000Z",
"submitted_at": null,
"on_time": null,
"notes": [],
"updated_at": "2026-10-16T15:20:00.000Z"
}
}Send my interview feedback#
POST/v1/hiring/feedback.submitWrite
Sends your feedback on an interview you gave (it has started), with any last changes (the same fields as hiring_feedback_save): a rating for every skill of the step's scorecard and a recommendation are required. Sent is final; HR and the job's hiring manager read it, and the other interviewers of this candidate once they have sent theirs. Records whether it came in by the time it was due, and sends the hiring.feedback_submitted webhook (ids only). Only the interviewer, until 30 days after the interview. Signed in to Bizisy only: refused over an API key or MCP.
- Web app only
- Refused for API keys and connected apps. Feedback is sent by the interviewer in the app.
- MCP tool
hiring_feedback_submiton My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
interview_idstringrequired1–100 characters.
ratingsobject[]1 (clear concerns) to 4 (excellent) for skills of the step's scorecard (skill ids from hiring_me_interview step.scorecard).
Up to 8 items.
2 fields
skill_idstringrequired1–40 characters.
ratingintegerrequiredFrom 1 to 4.
textstringWhat you saw, in your words (≤ 5,000 characters). The candidate can ask to read it.
Up to 5000 characters.
overallstring | nullYour answer to the scorecard's overall question.
Up to 2000 characters.
recommendation"strong_no" | "no" | "yes" | "strong_yes"strong_no, no, yes or strong_yes.
Returns
17 fields
idstringrequiredinterview_idstringrequiredapplication_idstring | nullrequiredstepobjectrequired2 fields
idstringrequirednamestring | nullrequired
authorobject | nullrequiredWho wrote it; null once they were erased (show "A former colleague").
2 fields
idstringrequirednamestringrequired
author_erasedbooleanrequiredminebooleanrequiredYours.
status"draft" | "submitted"requireddraft: only its author sees it; submitted: final (correction notes may follow).
ratingsobject[]required1 (clear concerns) to 4 (excellent) per skill of the step's scorecard.
3 fields
skill_idstringrequirednamestringrequiredratingintegerrequiredFrom 1 to 4.
textstringrequiredoverallstring | nullrequiredThe answer to the scorecard's overall question.
recommendation"strong_no" | "no" | "yes" | "strong_yes"requireddue_atstringrequiredsubmitted_atstring | nullrequiredon_timeboolean | nullrequiredSent by the time it was due.
notesobject[]requiredCorrections added after sending.
2 fields
textstringrequiredatstringrequired
updated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/feedback.submit \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"interview_id": "ivb3",
"ratings": [
{
"skill_id": "practical",
"rating": 3
},
{
"skill_id": "teamwork",
"rating": 4
}
],
"text": "Kept her station clean through the rush.",
"recommendation": "yes"
}'const res = await fetch('https://api.bizisy.com/v1/hiring/feedback.submit', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"interview_id": "ivb3",
"ratings": [
{
"skill_id": "practical",
"rating": 3
},
{
"skill_id": "teamwork",
"rating": 4
}
],
"text": "Kept her station clean through the rush.",
"recommendation": "yes"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/feedback.submit",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"interview_id": "ivb3",
"ratings": [
{
"skill_id": "practical",
"rating": 3,
},
{
"skill_id": "teamwork",
"rating": 4,
},
],
"text": "Kept her station clean through the rush.",
"recommendation": "yes",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "o1:iv0:p4",
"interview_id": "iv0",
"application_id": "a1",
"step": {
"id": "trial",
"name": "Trial shift"
},
"author": {
"id": "p4",
"name": "Ivo Matos"
},
"author_erased": false,
"mine": true,
"status": "submitted",
"ratings": [
{
"skill_id": "practical",
"name": "Practical work",
"rating": 3
},
{
"skill_id": "teamwork",
"name": "Working with others",
"rating": 4
}
],
"text": "Kept her station clean through the rush.",
"overall": "Calm and reliable; would need a week on the grill.",
"recommendation": "yes",
"due_at": "2026-10-17T13:00:00.000Z",
"submitted_at": "2026-10-16T15:20:00.000Z",
"on_time": true,
"notes": [],
"updated_at": "2026-10-16T15:20:00.000Z"
}
}Add a correction to my feedback#
POST/v1/hiring/feedback.add_noteWrite
Adds a correction note (≤ 2,000 characters) to feedback you already sent; the feedback itself stays as sent, with the note under it for everyone who reads it. At most 5 notes. Only its author, until 30 days after the interview. Signed in to Bizisy only: refused over an API key or MCP.
- Web app only
- Refused for API keys and connected apps. Corrections to feedback are added by its author in the app.
- MCP tool
hiring_feedback_add_noteon My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
interview_idstringrequired1–100 characters.
textstringrequired1–2000 characters.
Returns
17 fields
idstringrequiredinterview_idstringrequiredapplication_idstring | nullrequiredstepobjectrequired2 fields
idstringrequirednamestring | nullrequired
authorobject | nullrequiredWho wrote it; null once they were erased (show "A former colleague").
2 fields
idstringrequirednamestringrequired
author_erasedbooleanrequiredminebooleanrequiredYours.
status"draft" | "submitted"requireddraft: only its author sees it; submitted: final (correction notes may follow).
ratingsobject[]required1 (clear concerns) to 4 (excellent) per skill of the step's scorecard.
3 fields
skill_idstringrequirednamestringrequiredratingintegerrequiredFrom 1 to 4.
textstringrequiredoverallstring | nullrequiredThe answer to the scorecard's overall question.
recommendation"strong_no" | "no" | "yes" | "strong_yes"requireddue_atstringrequiredsubmitted_atstring | nullrequiredon_timeboolean | nullrequiredSent by the time it was due.
notesobject[]requiredCorrections added after sending.
2 fields
textstringrequiredatstringrequired
updated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/feedback.add_note \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"interview_id":"iv0","text":"I meant 4 for teamwork."}'const res = await fetch('https://api.bizisy.com/v1/hiring/feedback.add_note', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"interview_id": "iv0",
"text": "I meant 4 for teamwork."
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/feedback.add_note",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"interview_id": "iv0",
"text": "I meant 4 for teamwork.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "o1:iv0:p4",
"interview_id": "iv0",
"application_id": "a1",
"step": {
"id": "trial",
"name": "Trial shift"
},
"author": {
"id": "p4",
"name": "Ivo Matos"
},
"author_erased": false,
"mine": true,
"status": "submitted",
"ratings": [
{
"skill_id": "practical",
"name": "Practical work",
"rating": 3
},
{
"skill_id": "teamwork",
"name": "Working with others",
"rating": 4
}
],
"text": "I meant 4 for teamwork.",
"overall": "Calm and reliable; would need a week on the grill.",
"recommendation": "yes",
"due_at": "2026-10-17T13:00:00.000Z",
"submitted_at": "2026-10-16T15:20:00.000Z",
"on_time": true,
"notes": [
{
"text": "I meant 4 for teamwork.",
"at": "2026-10-17T09:00:00.000Z"
}
],
"updated_at": "2026-10-16T15:20:00.000Z"
}
}My interviews#
POST/v1/hiring/me.interviewsRead
The interviews you give (My workspace → Interviewing): coming up (time, place and link, the job, the step, the candidate's name, who else interviews), the ones held in the last 30 days with your feedback (none, draft or sent; due time; overdue), counts for Home (feedback to give, overdue, interviews today in your time zone), and times held for a candidate that may become yours (offers: the time and job only, never the candidate until they pick). Open one with hiring_me_interview for the CV, answers, the job post and the scorecard. Your own only. Signed in to Bizisy only: refused over an API key or MCP.
- Web app only
- Refused for API keys and connected apps. An interviewer's own interviews are read in the app (My workspace → Interviewing).
- MCP tool
hiring_me_interviewson My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
interviewerbooleanrequiredYou interview here: in an interview group, named on a job's step, with a usual week, or with interviews (My workspace shows Interviewing).
coming_upobject[]required13 fields
idstringrequiredstatus"booked" | "no_show"requiredbooked (to come or held), or no_show (the candidate did not come: no feedback needed).
heldbooleanrequiredIt has ended.
jobobjectrequired2 fields
idstringrequiredtitlestringrequired
stepobjectrequired3 fields
idstringrequirednamestring | nullrequiredkindstring (enum)requiredOne of:
call,interview,panel,task,trial,presentation,references,final.
candidateobjectrequiredOnly the name: the kit (hiring_me_interview) has the CV and answers.
1 field
namestringrequired
startstringrequiredendstringrequiredminutesintegerrequiredplaceobjectrequired4 fields
kind"video" | "video_auto" | "phone" | "on_site" | "none"requiredvideo (a link HR pasted), video_auto (a Google Meet or Teams link the connected calendar makes), phone, on_site, none.
addressstring | nullrequiredlinkstring | nullrequiredThe meeting link: pasted, or made by the calendar (video_auto; null until made).
link_source"google_meet" | "teams"requiredgoogle_meet or teams: the calendar made the link; null: pasted, or none yet.
withobject[]requiredThe other interviewers.
2 fields
idstringrequirednamestringrequired
feedbackobject | nullrequiredYour feedback: null until the interview has ended (and for no-shows).
4 fields
status"none" | "draft" | "submitted"requireddue_atstringrequiredoverduebooleanrequiredNot sent and past its due time.
on_timeboolean | nullrequired
access_untilstringrequiredYou can open this candidate until then (30 days after the interview).
pastobject[]required13 fields
idstringrequiredstatus"booked" | "no_show"requiredbooked (to come or held), or no_show (the candidate did not come: no feedback needed).
heldbooleanrequiredIt has ended.
jobobjectrequired2 fields
idstringrequiredtitlestringrequired
stepobjectrequired3 fields
idstringrequirednamestring | nullrequiredkindstring (enum)requiredOne of:
call,interview,panel,task,trial,presentation,references,final.
candidateobjectrequiredOnly the name: the kit (hiring_me_interview) has the CV and answers.
1 field
namestringrequired
startstringrequiredendstringrequiredminutesintegerrequiredplaceobjectrequired4 fields
kind"video" | "video_auto" | "phone" | "on_site" | "none"requiredvideo (a link HR pasted), video_auto (a Google Meet or Teams link the connected calendar makes), phone, on_site, none.
addressstring | nullrequiredlinkstring | nullrequiredThe meeting link: pasted, or made by the calendar (video_auto; null until made).
link_source"google_meet" | "teams"requiredgoogle_meet or teams: the calendar made the link; null: pasted, or none yet.
withobject[]requiredThe other interviewers.
2 fields
idstringrequirednamestringrequired
feedbackobject | nullrequiredYour feedback: null until the interview has ended (and for no-shows).
4 fields
status"none" | "draft" | "submitted"requireddue_atstringrequiredoverduebooleanrequiredNot sent and past its due time.
on_timeboolean | nullrequired
access_untilstringrequiredYou can open this candidate until then (30 days after the interview).
held_for_youobject[]required5 fields
startstringrequiredendstringrequiredjobobjectrequired2 fields
idstringrequiredtitlestringrequired
stepobjectrequired2 fields
idstringrequirednamestring | nullrequired
untilstringrequiredThe hold ends then unless the candidate picks it.
countsobjectrequired3 fields
feedback_to_giveintegerrequiredfeedback_overdueintegerrequiredtodayintegerrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/me.interviews \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/hiring/me.interviews', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/me.interviews",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"interviewer": true,
"coming_up": [
{
"id": "iv1",
"status": "booked",
"held": false,
"job": {
"id": "j1",
"title": "Line cook"
},
"step": {
"id": "trial",
"name": "Trial shift",
"kind": "trial"
},
"candidate": {
"name": "Maria Silva"
},
"start": "2026-10-27T09:00:00.000Z",
"end": "2026-10-27T13:00:00.000Z",
"minutes": 240,
"place": {
"kind": "on_site",
"address": "Rua do Souto 12, Braga",
"link": null,
"link_source": null
},
"with": [
{
"id": "p2",
"name": "Rita Lopes"
}
],
"feedback": null,
"access_until": "2026-11-26T13:00:00.000Z"
}
],
"past": [
{
"id": "iv0",
"status": "booked",
"held": true,
"job": {
"id": "j1",
"title": "Line cook"
},
"step": {
"id": "trial",
"name": "Trial shift",
"kind": "trial"
},
"candidate": {
"name": "João Reis"
},
"start": "2026-10-16T09:00:00.000Z",
"end": "2026-10-16T13:00:00.000Z",
"minutes": 240,
"place": {
"kind": "on_site",
"address": "Rua do Souto 12, Braga",
"link": null,
"link_source": null
},
"with": [],
"feedback": {
"status": "draft",
"due_at": "2026-10-17T13:00:00.000Z",
"overdue": true,
"on_time": null
},
"access_until": "2026-11-15T13:00:00.000Z"
}
],
"held_for_you": [
{
"start": "2026-10-29T13:00:00.000Z",
"end": "2026-10-29T17:00:00.000Z",
"job": {
"id": "j1",
"title": "Line cook"
},
"step": {
"id": "trial",
"name": "Trial shift"
},
"until": "2026-10-20T09:00:00.000Z"
}
],
"counts": {
"feedback_to_give": 1,
"feedback_overdue": 1,
"today": 0
}
}
}My interview kit#
POST/v1/hiring/me.interviewRead
One interview you give, to prepare and give feedback: the candidate's name, their CV (a download link valid for 5 minutes) and answers to the job's questions, the job post, the step (length, place, link or address, its scorecard: skills with what each rating 1–4 looks like, and the overall question), your feedback (draft or sent), and the other interviewers' sent feedback on this candidate once you have sent yours for every interview of yours with them (others_hidden says so). Only while the interview is booked, from the booking until 30 days after it; never the pay expectation, notes, the referrer or other candidates. Signed in to Bizisy only: refused over an API key or MCP.
- Web app only
- Refused for API keys and connected apps. Interview kits (the candidate's CV and answers) are for the interviewer in the app.
- MCP tool
hiring_me_interviewon My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
interview_idstringrequired1–100 characters.
Returns
7 fields
interviewobjectrequired13 fields
idstringrequiredstatus"booked" | "no_show"requiredbooked (to come or held), or no_show (the candidate did not come: no feedback needed).
heldbooleanrequiredIt has ended.
jobobjectrequired2 fields
idstringrequiredtitlestringrequired
stepobjectrequired3 fields
idstringrequirednamestring | nullrequiredkindstring (enum)requiredOne of:
call,interview,panel,task,trial,presentation,references,final.
candidateobjectrequiredOnly the name: the kit (hiring_me_interview) has the CV and answers.
1 field
namestringrequired
startstringrequiredendstringrequiredminutesintegerrequiredplaceobjectrequired4 fields
kind"video" | "video_auto" | "phone" | "on_site" | "none"requiredvideo (a link HR pasted), video_auto (a Google Meet or Teams link the connected calendar makes), phone, on_site, none.
addressstring | nullrequiredlinkstring | nullrequiredThe meeting link: pasted, or made by the calendar (video_auto; null until made).
link_source"google_meet" | "teams"requiredgoogle_meet or teams: the calendar made the link; null: pasted, or none yet.
withobject[]requiredThe other interviewers.
2 fields
idstringrequirednamestringrequired
feedbackobject | nullrequiredYour feedback: null until the interview has ended (and for no-shows).
4 fields
status"none" | "draft" | "submitted"requireddue_atstringrequiredoverduebooleanrequiredNot sent and past its due time.
on_timeboolean | nullrequired
access_untilstringrequiredYou can open this candidate until then (30 days after the interview).
candidateobjectrequired3 fields
namestringrequiredcvobject | nullrequired3 fields
namestringrequiredsizenumberrequiredurlstring | nullrequired
answersobject[]required2 fields
questionstringrequiredanswerstringrequired
jobobjectrequired5 fields
idstringrequiredtitlestringrequiredlanguage"en" | "pt" | "es" | "fr" | "de"requiredpostobjectrequired4 fields
what_you_dostringrequiredwhat_you_needstringrequiredwhat_you_getstringrequiredhow_it_goesstringrequired
processobjectrequired"How it goes" above post.how_it_goes, in the job's language: the answer promise and the steps with their length.
2 fields
promisestringrequiredstepsstring[]required
stepobjectrequired5 fields
idstringrequirednamestring | nullrequiredkindstring (enum)requiredOne of:
call,interview,panel,task,trial,presentation,references,final.minutesintegerrequiredscorecardobject | nullrequired2 fields
skillsobject[]required4 fields
idstringrequirednamestringrequiredpromptstring | nullrequiredlevelsstring[]required4–4 items.
overall_questionstring | nullrequired
my_feedbackobject | nullrequired17 fields
idstringrequiredinterview_idstringrequiredapplication_idstring | nullrequiredstepobjectrequired2 fields
idstringrequirednamestring | nullrequired
authorobject | nullrequiredWho wrote it; null once they were erased (show "A former colleague").
2 fields
idstringrequirednamestringrequired
author_erasedbooleanrequiredminebooleanrequiredYours.
status"draft" | "submitted"requireddraft: only its author sees it; submitted: final (correction notes may follow).
ratingsobject[]required1 (clear concerns) to 4 (excellent) per skill of the step's scorecard.
3 fields
skill_idstringrequirednamestringrequiredratingintegerrequiredFrom 1 to 4.
textstringrequiredoverallstring | nullrequiredThe answer to the scorecard's overall question.
recommendation"strong_no" | "no" | "yes" | "strong_yes"requireddue_atstringrequiredsubmitted_atstring | nullrequiredon_timeboolean | nullrequiredSent by the time it was due.
notesobject[]requiredCorrections added after sending.
2 fields
textstringrequiredatstringrequired
updated_atstringrequired
othersobject[]requiredThe other interviewers' sent feedback on this candidate (empty while others_hidden).
17 fields
idstringrequiredinterview_idstringrequiredapplication_idstring | nullrequiredstepobjectrequired2 fields
idstringrequirednamestring | nullrequired
authorobject | nullrequiredWho wrote it; null once they were erased (show "A former colleague").
2 fields
idstringrequirednamestringrequired
author_erasedbooleanrequiredminebooleanrequiredYours.
status"draft" | "submitted"requireddraft: only its author sees it; submitted: final (correction notes may follow).
ratingsobject[]required1 (clear concerns) to 4 (excellent) per skill of the step's scorecard.
3 fields
skill_idstringrequirednamestringrequiredratingintegerrequiredFrom 1 to 4.
textstringrequiredoverallstring | nullrequiredThe answer to the scorecard's overall question.
recommendation"strong_no" | "no" | "yes" | "strong_yes"requireddue_atstringrequiredsubmitted_atstring | nullrequiredon_timeboolean | nullrequiredSent by the time it was due.
notesobject[]requiredCorrections added after sending.
2 fields
textstringrequiredatstringrequired
updated_atstringrequired
others_hiddenbooleanrequiredSend your feedback first: then you see theirs (independent scoring).
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/me.interview \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"interview_id":"iv1"}'const res = await fetch('https://api.bizisy.com/v1/hiring/me.interview', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"interview_id": "iv1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/me.interview",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"interview_id": "iv1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"interview": {
"id": "iv1",
"status": "booked",
"held": false,
"job": {
"id": "j1",
"title": "Line cook"
},
"step": {
"id": "trial",
"name": "Trial shift",
"kind": "trial"
},
"candidate": {
"name": "Maria Silva"
},
"start": "2026-10-27T09:00:00.000Z",
"end": "2026-10-27T13:00:00.000Z",
"minutes": 240,
"place": {
"kind": "on_site",
"address": "Rua do Souto 12, Braga",
"link": null,
"link_source": null
},
"with": [
{
"id": "p2",
"name": "Rita Lopes"
}
],
"feedback": null,
"access_until": "2026-11-26T13:00:00.000Z"
},
"candidate": {
"name": "Maria Silva",
"cv": {
"name": "maria-silva-cv.pdf",
"size": 182000,
"url": "https://storage.example/f1?sig=x"
},
"answers": [
{
"question": "Do you have the right to work in the EU?",
"answer": "yes"
}
]
},
"job": {
"id": "j1",
"title": "Line cook",
"language": "en",
"post": {
"what_you_do": "Prepare the mise en place and cook the lunch service with a team of four.",
"what_you_need": "Two years in a professional kitchen and a food hygiene certificate.",
"what_you_get": "- Pay: €18,000–€22,000 a year\n- A permanent contract\n- Full time, 40 hours a week\n- On site in Braga\n\nMeals on shift.",
"how_it_goes": "Then an offer."
},
"process": {
"promise": "We answer within 5 working days.",
"steps": [
"Talking · 30 mins",
"Trial shift · 4 hrs"
]
}
},
"step": {
"id": "trial",
"name": "Trial shift",
"kind": "trial",
"minutes": 240,
"scorecard": {
"skills": [
{
"id": "practical",
"name": "Practical work",
"prompt": "Watch how they work: quality, pace, safety, asking for help.",
"levels": [
"Could not do the tasks safely or correctly.",
"Did the tasks with frequent help or mistakes.",
"Did the tasks well at a good pace; asked when unsure.",
"Quick, careful and independent; improved as it went on."
]
},
{
"id": "teamwork",
"name": "Working with others",
"prompt": "Ask about a time they disagreed with a colleague and what happened.",
"levels": [
"Blamed others or avoided the question.",
"Works with others, but the examples were thin.",
"Good examples of working with others and settling disagreements.",
"Lifts the team: shares credit, gives and takes feedback well."
]
}
],
"overall_question": "What would this person bring to the team, and what support would they need?"
}
},
"my_feedback": null,
"others": [],
"others_hidden": true
}
}Who helps us hire#
POST/v1/hiring/contribution.reportRead
Who helps the company hire, per person and per team, over a period (quarter: this calendar quarter, default; year: this calendar year; custom: from and to, at most 2 years): interviews held (ended in the period; no-shows included) and their hours, feedback due and sent on time (with the percentage), people hired in the period they interviewed, people they referred and how many were hired, jobs they shared and the applicants from their links, thanks HR sent them, and their load (interviews this month and week) next to their weekly cap. People shown: everyone in an interview group, with a usual week, or with something in the period. Owners, admins and HR see everyone; a manager the people below them; otherwise refused (see your own with hiring_me_contribution). Never candidates' names; never averages or scores of candidates.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
hiring_contribution_reporton HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
period"quarter" | "year" | "custom"quarter (default: this calendar quarter), year (this calendar year) or custom (from and to, at most 2 years).
Default
"quarter".fromstringcustom: the first day (YYYY-MM-DD).
Pattern
^\d{4}-\d{2}-\d{2}$.tostringcustom: the last day (YYYY-MM-DD).
Pattern
^\d{4}-\d{2}-\d{2}$.
Returns
periodobjectrequired3 fields
kind"quarter" | "year" | "custom"requiredfromstringrequiredtostringrequired
scope"everyone" | "reports" | "self"requiredeveryone (owners, admins, HR), reports (a manager: the people below them) or self.
peopleobject[]required12 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
interviews_heldintegerrequiredInterviews they gave that ended in the period (no-shows included: they were there).
hoursnumberrequiredThose interviews' length in hours (minutes / 60).
feedbackobjectrequired3 fields
dueintegerrequiredFeedback due in the period on interviews they gave (no-shows excluded).
on_timeintegerrequiredSent by the time it was due.
on_time_pctnumber | nullrequiredon_time / due as a percentage (whole number); null when nothing was due.
hires_interviewedintegerrequiredPeople hired in the period whom they interviewed (at any step).
referralsintegerrequiredPeople they referred in the period.
referral_hiresintegerrequiredOf those referrals, how many were hired.
sharesintegerrequiredJobs they shared with their own link in the period.
applicants_from_sharesintegerrequiredPeople who applied in the period through their share links.
thanksintegerrequiredThanks HR sent them in the period.
loadobjectrequired4 fields
monthintegerrequiredInterviews booked or held this calendar month (their time zone).
weekintegerrequiredInterviews booked or held this week.
capobject | nullrequiredTheir weekly cap; null without a usual week.
2 fields
interviewsintegerrequiredhoursnumber | nullrequired
paused_untilstring | nullrequired
unitsobject[]required11 fields
unitobject | nullrequirednull: people without a team.
2 fields
idstringrequirednamestringrequired
peopleintegerrequiredinterviews_heldintegerrequiredInterviews they gave that ended in the period (no-shows included: they were there).
hoursnumberrequiredThose interviews' length in hours (minutes / 60).
feedbackobjectrequired3 fields
dueintegerrequiredFeedback due in the period on interviews they gave (no-shows excluded).
on_timeintegerrequiredSent by the time it was due.
on_time_pctnumber | nullrequiredon_time / due as a percentage (whole number); null when nothing was due.
hires_interviewedintegerrequiredPeople hired in the period whom they interviewed (at any step).
referralsintegerrequiredPeople they referred in the period.
referral_hiresintegerrequiredOf those referrals, how many were hired.
sharesintegerrequiredJobs they shared with their own link in the period.
applicants_from_sharesintegerrequiredPeople who applied in the period through their share links.
thanksintegerrequiredThanks HR sent them in the period.
totalsobjectrequired9 fields
interviews_heldintegerrequiredInterviews they gave that ended in the period (no-shows included: they were there).
hoursnumberrequiredThose interviews' length in hours (minutes / 60).
feedbackobjectrequired3 fields
dueintegerrequiredFeedback due in the period on interviews they gave (no-shows excluded).
on_timeintegerrequiredSent by the time it was due.
on_time_pctnumber | nullrequiredon_time / due as a percentage (whole number); null when nothing was due.
hires_interviewedintegerrequiredPeople hired in the period whom they interviewed (at any step).
referralsintegerrequiredPeople they referred in the period.
referral_hiresintegerrequiredOf those referrals, how many were hired.
sharesintegerrequiredJobs they shared with their own link in the period.
applicants_from_sharesintegerrequiredPeople who applied in the period through their share links.
thanksintegerrequiredThanks HR sent them in the period.
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/contribution.report \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"period":"custom","from":"2026-01-01","to":"2026-06-30"}'const res = await fetch('https://api.bizisy.com/v1/hiring/contribution.report', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"period": "custom",
"from": "2026-01-01",
"to": "2026-06-30"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/contribution.report",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"period": "custom",
"from": "2026-01-01",
"to": "2026-06-30",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"period": {
"kind": "quarter",
"from": "2026-10-01",
"to": "2026-12-31"
},
"scope": "everyone",
"people": [
{
"person": {
"id": "p4",
"name": "Ivo Matos"
},
"unit": {
"id": "u1",
"name": "Kitchen"
},
"interviews_held": 6,
"hours": 14,
"feedback": {
"due": 6,
"on_time": 5,
"on_time_pct": 83
},
"hires_interviewed": 1,
"referrals": 2,
"referral_hires": 1,
"shares": 3,
"applicants_from_shares": 4,
"thanks": 1,
"load": {
"month": 3,
"week": 1,
"cap": {
"interviews": 2,
"hours": 3
},
"paused_until": null
}
},
{
"person": {
"id": "p2",
"name": "Rita Lopes"
},
"unit": {
"id": "u1",
"name": "Kitchen"
},
"interviews_held": 2,
"hours": 2,
"feedback": {
"due": 2,
"on_time": 2,
"on_time_pct": 100
},
"hires_interviewed": 0,
"referrals": 0,
"referral_hires": 0,
"shares": 1,
"applicants_from_shares": 0,
"thanks": 0,
"load": {
"month": 1,
"week": 0,
"cap": null,
"paused_until": null
}
}
],
"units": [
{
"unit": {
"id": "u1",
"name": "Kitchen"
},
"people": 2,
"interviews_held": 8,
"hours": 16,
"feedback": {
"due": 8,
"on_time": 7,
"on_time_pct": 88
},
"hires_interviewed": 1,
"referrals": 2,
"referral_hires": 1,
"shares": 4,
"applicants_from_shares": 4,
"thanks": 1
}
],
"totals": {
"interviews_held": 8,
"hours": 16,
"feedback": {
"due": 8,
"on_time": 7,
"on_time_pct": 88
},
"hires_interviewed": 1,
"referrals": 2,
"referral_hires": 1,
"shares": 4,
"applicants_from_shares": 4,
"thanks": 1
}
}
}My part in hiring#
POST/v1/hiring/me.contributionRead
Your own part in hiring (My workspace → Interviewing), over a period (year: this calendar year, default; quarter; custom: from and to, at most 2 years): interviews you held and their hours, feedback on time, people hired whom you interviewed, your referrals and hires from them, the jobs you shared and the applicants from your links, thanks you received, and your load this month next to your weekly cap. Yours only; never candidates' names.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
hiring_me_contributionon My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
period"quarter" | "year" | "custom"quarter (default: this calendar quarter), year (this calendar year) or custom (from and to, at most 2 years).
Default
"year".fromstringcustom: the first day (YYYY-MM-DD).
Pattern
^\d{4}-\d{2}-\d{2}$.tostringcustom: the last day (YYYY-MM-DD).
Pattern
^\d{4}-\d{2}-\d{2}$.
Returns
periodobjectrequired3 fields
kind"quarter" | "year" | "custom"requiredfromstringrequiredtostringrequired
meobjectrequired12 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
interviews_heldintegerrequiredInterviews they gave that ended in the period (no-shows included: they were there).
hoursnumberrequiredThose interviews' length in hours (minutes / 60).
feedbackobjectrequired3 fields
dueintegerrequiredFeedback due in the period on interviews they gave (no-shows excluded).
on_timeintegerrequiredSent by the time it was due.
on_time_pctnumber | nullrequiredon_time / due as a percentage (whole number); null when nothing was due.
hires_interviewedintegerrequiredPeople hired in the period whom they interviewed (at any step).
referralsintegerrequiredPeople they referred in the period.
referral_hiresintegerrequiredOf those referrals, how many were hired.
sharesintegerrequiredJobs they shared with their own link in the period.
applicants_from_sharesintegerrequiredPeople who applied in the period through their share links.
thanksintegerrequiredThanks HR sent them in the period.
loadobjectrequired4 fields
monthintegerrequiredInterviews booked or held this calendar month (their time zone).
weekintegerrequiredInterviews booked or held this week.
capobject | nullrequiredTheir weekly cap; null without a usual week.
2 fields
interviewsintegerrequiredhoursnumber | nullrequired
paused_untilstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/me.contribution \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"period":"quarter"}'const res = await fetch('https://api.bizisy.com/v1/hiring/me.contribution', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"period": "quarter"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/me.contribution",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"period": "quarter",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"period": {
"kind": "year",
"from": "2026-01-01",
"to": "2026-12-31"
},
"me": {
"person": {
"id": "p4",
"name": "Ivo Matos"
},
"unit": {
"id": "u1",
"name": "Kitchen"
},
"interviews_held": 6,
"hours": 14,
"feedback": {
"due": 6,
"on_time": 5,
"on_time_pct": 83
},
"hires_interviewed": 1,
"referrals": 2,
"referral_hires": 1,
"shares": 3,
"applicants_from_shares": 4,
"thanks": 1,
"load": {
"month": 3,
"week": 1,
"cap": {
"interviews": 2,
"hours": 3
},
"paused_until": null
}
}
}
}Download who helps us hire#
POST/v1/hiring/contribution.exportRead
Who helps us hire as a CSV file (the same period and figures as hiring_contribution_report: one line per person, then per team, then the total), headers in lang (en, pt, es, fr, de; default the company's). Owners, admins and HR. Never candidates' names.
- Who can call it
- Manage key owner admin hr
- MCP tool
hiring_contribution_exporton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
period"quarter" | "year" | "custom"quarter (default: this calendar quarter), year (this calendar year) or custom (from and to, at most 2 years).
Default
"quarter".fromstringcustom: the first day (YYYY-MM-DD).
Pattern
^\d{4}-\d{2}-\d{2}$.tostringcustom: the last day (YYYY-MM-DD).
Pattern
^\d{4}-\d{2}-\d{2}$.lang"en" | "pt" | "es" | "fr" | "de"
Returns
fileobjectrequired6 fields
namestringrequiredcontent_typestringrequiredencoding"utf8" | "base64"requiredcontentstringrequiredbytesintegerrequiredsha256stringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/contribution.export \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"period":"year","lang":"pt"}'const res = await fetch('https://api.bizisy.com/v1/hiring/contribution.export', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"period": "year",
"lang": "pt"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/contribution.export",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"period": "year",
"lang": "pt",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"file": {
"name": "who-helps-us-hire-2026-10-01-2026-12-31.csv",
"content_type": "text/csv; charset=utf-8",
"encoding": "utf8",
"content": "Person,Team,Interviews held,Hours\r\nIvo Matos,Kitchen,6,14\r\n",
"bytes": 60,
"sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
}
}
}Say thanks for helping hire#
POST/v1/hiring/contribution.thankWrite
Thanks a colleague for helping hire for a job (from Who helps us hire, or after a hire): they get an in-app notice and an email ("<your name> thanks you for interviewing for <job>"), and with copy_manager their manager gets a copy. The reason is what they did for that job: interviewing (an interview held), referring (a referral) or sharing (applicants from their link); someone who did none of these for the job (or yourself) is refused. At most one thanks per person per job; it counts on the report. At most 100 a day per company. Owners, admins and HR, signed in to Bizisy: refused over an API key or MCP (it emails people).
- Web app only
- Refused for API keys and connected apps. Saying thanks (it emails people) happens in the app.
- MCP tool
hiring_contribution_thankon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
person_idstringrequired1–100 characters.
job_idstringrequired1–100 characters.
copy_managerbooleanDefault
false.
Returns
person_idstringrequiredjob_idstringrequiredreason"interviewing" | "referring" | "sharing"requiredemailedbooleanrequiredmanager_copiedbooleanrequiredatstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/contribution.thank \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"person_id":"p4","job_id":"j1","copy_manager":true}'const res = await fetch('https://api.bizisy.com/v1/hiring/contribution.thank', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p4",
"job_id": "j1",
"copy_manager": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/contribution.thank",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p4",
"job_id": "j1",
"copy_manager": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person_id": "p4",
"job_id": "j1",
"reason": "interviewing",
"emailed": true,
"manager_copied": false,
"at": "2026-10-18T09:00:00.000Z"
}
}Start an offer#
POST/v1/hiring/offers.draftWrite
Starts an offer to a candidate still in the process (one live offer per candidate and job; at most 10 versions), filled in from the job and its position: title, employer (the position's legal entity), team, place, manager, start date (the position's target start, else a Monday about 30 days ahead), contract (fixed-term: an end date a year on), probation (suggested by the employer's country: PT 90 days, 180 for complex roles, 240 for directors, 15–30 for fixed-term; ES 2 months, 6 for qualified technicians, 3 in companies under 25; elsewhere at most 6 months per Directive 2019/1152 — suggestions lists them; HR picks), weekly hours, pay (the middle of the published range as a suggestion; 14 payments a year in PT and ES), benefits (Settings → Hiring), the expiry (today plus the company's default, 7 days) and the signer (Settings → Hiring, else the job's hiring manager). Send changes in terms. Nothing reaches the candidate until it is sent. Owners, admins and HR any job, a job's hiring manager their own, signed in to Bizisy: refused over an API key or MCP (an AI may suggest the terms for the user to enter).
- Web app only
- Refused for API keys and connected apps. Offers are made in the app; machines may suggest the terms.
- MCP tool
hiring_offers_drafton HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
application_idstringrequired1–100 characters.
termsobject21 fields
titlestring1–120 characters.
start_datestringPattern
^\d{4}-\d{2}-\d{2}$.contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"end_datestring | nullPattern
^\d{4}-\d{2}-\d{2}$.probationobject | null2 fields
valueintegerrequiredFrom 1 to 366.
unit"days" | "months"required
weekly_hoursnumber | nullFrom 1 to 60.
payobject4 fields
amountnumberrequiredFrom 0 to 10000000.
currencyanyrequiredperiod"year" | "month" | "hour"requiredpayments_per_year12 | 13 | 14
benefitsstring | nullUp to 2000 characters.
benefit_idsstring[]Catalogue benefits the hire will have (benefits_offers_options for the offer's legal entity); the letter writes them out, then the benefits text.
1–100 characters. Up to 30 items.
placestring | nullUp to 200 characters.
expires_onstringPattern
^\d{4}-\d{2}-\d{2}$.notestring | nullUp to 1000 characters.
signer_person_idstring | nullWho signs for the company (a person working there); null: the job's hiring manager.
1–100 characters.
signer_titlestring | nullUp to 120 characters.
work_emailemail | nullUp to 254 characters.
invite"start" | "none"unit_idstring | null1–100 characters.
location_idstring | null1–100 characters.
manager_idstring | null1–100 characters.
language"en" | "pt" | "es" | "fr" | "de"The letter's and the offer page's language (default the job's).
new_paybooleanTransfers only (an offer to someone who works here): true when the offer changes their pay to terms.pay; false keeps their pay. HR only.
Returns
29 fields
idstringrequiredversionintegerrequiredsupersedesstring | nullrequiredapplication_idstring | nullrequiredjob_idstringrequiredcandidateobject | nullrequired2 fields
idstringrequirednamestringrequired
statusstring (enum)requireddraft, awaiting_approval, ready (approved or no approval needed: send it), sent, accepted_pending_hire (accepted; the hire runs or waits for HR), accepted (hired), declined, expired, withdrawn.
One of:
draft,awaiting_approval,ready,sent,accepted_pending_hire,accepted,declined,expired,withdrawn.language"en" | "pt" | "es" | "fr" | "de"requiredletter_kind"permanent" | "fixed_term"requiredtermsobjectrequired25 fields
titlestringrequiredlegal_entity_idstring | nullrequiredemployerstring | nullrequiredemployer_countrystring | nullrequiredunit_idstring | nullrequiredlocation_idstring | nullrequiredmanager_idstring | nullrequiredposition_idstring | nullrequiredplacestring | nullrequiredstart_datestringrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredend_datestring | nullrequiredprobationobject | nullrequired2 fields
valueintegerrequiredunit"days" | "months"required
weekly_hoursnumber | nullrequiredpayobject | nullrequiredPay tier: HR and the job's hiring manager; null over an API key or MCP.
4 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredpayments_per_yearinteger | nullrequired
benefitsstring | nullrequiredHR's own words about benefits (appended after the catalogue's).
benefit_idsstring[]requiredCatalogue benefits named on the offer (benefits_offers_options).
benefit_linesstring[]requiredThose benefits as the letter writes them, in its language, frozen when the offer was saved.
expires_onstringrequirednotestring | nullrequiredsigner_person_idstring | nullrequiredsigner_namestring | nullrequiredsigner_titlestring | nullrequiredwork_emailstring | nullrequiredThe new work email the hire is made with (never on the letter).
invite"start" | "none"requiredThe sign-in invite: on their first day (start) or none.
pay_hiddenbooleanrequiredTrue over an API key or MCP: pay stays in the app.
rangeobject | nullrequiredThe job's published range the pay is checked against (pay tier).
4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
range_check"none" | "within" | "below" | "above"requiredbelow is refused on submit; above needs approval (unless approval is off).
approvalobject | nullrequired6 fields
reason"above_range" | "every_offer"requiredapprovers"hr" | "owner"requiredstate"pending" | "approved" | "rejected"requiredasked_atstringrequireddecidedobject | nullrequired4 fields
atstringrequiredbyobject | nullrequired2 fields
idstringrequirednamestringrequired
commentstring | nullrequiredautomaticbooleanrequired
can_decidebooleanrequiredYou may approve or send it back (an approver, not its proposer, signed in to Bizisy).
approval_contextobject | nullrequiredFor an approver: the published range, the band of the position's level and how many hold the title.
3 fields
rangeobject | nullrequired4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
bandobject | nullrequired5 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredsource"title" | "level"required
title_holdersinteger | nullrequiredHow many people hold the position's title today (never their names or pay).
proposed_byobject | nullrequired2 fields
idstringrequirednamestringrequired
sentobject | nullrequired3 fields
atstringrequiredexpires_atstringrequiredremindedbooleanrequired
acceptanceobject | nullrequired3 fields
atstringrequiredtyped_namestringrequiredsha256stringrequired
declinedobject | nullrequired3 fields
atstringrequiredreasonstring | nullrequiredkindstring (enum)requiredThe reason the candidate picked: pay, other_offer, role, location, start_date, personal or other; null: none.
One of:
pay,other_offer,role,location,start_date,personal,other.
withdrawnobject | nullrequired3 fields
atstringrequiredrevisedbooleanrequiredtoldbooleanrequired
expired_atstring | nullrequiredhireobjectrequired4 fields
person_idstring | nullrequiredfailedobject | nullrequired2 fields
atstringrequiredreasonstringrequired
finishbooleanrequiredThe candidate accepted and HR must finish the hire (hiring_applications_hire_draft is filled in from the offer).
in_documentsbooleanrequiredThe signed offer is in the person's documents.
filesobjectrequired2 fields
letterobject | nullrequiredThe letter as sent (a 5-minute link, in the app only).
1 field
urlstring | nullrequired
signedobject | nullrequiredThe signed copy with the acceptance record (a 5-minute link, in the app only, while it is kept in Hiring).
1 field
urlstring | nullrequired
questionsintegerrequiredkind"hire" | "transfer"requiredtransfer: to someone who works here (W7 D8): accepted in My workspace, then a job change under Settings → Approval rules.
transferobject | nullrequired5 fields
new_paybooleanrequiredThe offer changes their pay (else their pay stays).
state"none" | "waiting" | "approved" | "applied" | "rejected" | "cancelled"requirednone: not accepted yet; waiting: accepted, the job change waits for approval; approved/applied: done; rejected/cancelled: not approved (HR tells them).
approval_idstring | nullrequiredwaiting_forstring | nullrequiredwaiting: the step it waits for (manager, hr).
approversstring[]required
created_atstringrequiredupdated_atstringrequiredsuggestionsobjectrequired4 fields
probationobject[]requiredProbation periods the law of the employer's country suggests (PT: 90/180/240 days by role, 15–30 for fixed-term; ES: 2 months, 6 for qualified technicians, 3 in companies under 25; elsewhere at most 6 months). HR picks.
3 fields
keystring (enum)requiredOne of:
general,complex,director,qualified,small_company,fixed_long,fixed_short,directive.valueintegerrequiredunit"days" | "months"required
countrystring | nullrequiredpay_from_rangebooleanrequiredThe pay is the middle of the published range: a suggestion; change it to what was agreed.
start_date_source"position" | "suggested" | "offer"required
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/offers.draft \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"application_id": "a1",
"terms": {
"start_date": "2026-12-01",
"work_email": "maria.silva@acme.pt",
"probation": {
"value": 180,
"unit": "days"
}
}
}'const res = await fetch('https://api.bizisy.com/v1/hiring/offers.draft', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"application_id": "a1",
"terms": {
"start_date": "2026-12-01",
"work_email": "maria.silva@acme.pt",
"probation": {
"value": 180,
"unit": "days"
}
}
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/offers.draft",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"application_id": "a1",
"terms": {
"start_date": "2026-12-01",
"work_email": "maria.silva@acme.pt",
"probation": {
"value": 180,
"unit": "days",
},
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "o1",
"version": 1,
"supersedes": null,
"application_id": "a1",
"job_id": "j1",
"candidate": {
"id": "c1",
"name": "Maria Silva"
},
"status": "draft",
"language": "en",
"letter_kind": "permanent",
"terms": {
"title": "Line cook",
"legal_entity_id": "e1",
"employer": "Acme Lda",
"employer_country": "PT",
"unit_id": "u1",
"location_id": "l1",
"manager_id": "p2",
"position_id": "pos1",
"place": "Braga kitchen, Braga",
"start_date": "2026-12-01",
"contract_type": "permanent",
"end_date": null,
"probation": {
"value": 90,
"unit": "days"
},
"weekly_hours": 40,
"pay": {
"amount": 1500,
"currency": "EUR",
"period": "month",
"payments_per_year": 14
},
"benefits": "Meals on shift.",
"benefit_ids": [],
"benefit_lines": [],
"expires_on": "2026-10-25",
"note": null,
"signer_person_id": "p2",
"signer_name": "Rita Lopes",
"signer_title": "Head chef",
"work_email": "maria.silva@acme.pt",
"invite": "start"
},
"pay_hidden": false,
"range": {
"min": 18000,
"max": 22000,
"currency": "EUR",
"period": "year"
},
"range_check": "within",
"approval": null,
"approval_context": null,
"proposed_by": {
"id": "p2",
"name": "Rita Lopes"
},
"sent": null,
"acceptance": null,
"declined": null,
"withdrawn": null,
"expired_at": null,
"hire": {
"person_id": null,
"failed": null,
"finish": false,
"in_documents": false
},
"files": {
"letter": null,
"signed": null
},
"questions": 0,
"kind": "hire",
"transfer": null,
"created_at": "2026-10-18T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z",
"suggestions": {
"probation": [
{
"key": "general",
"value": 90,
"unit": "days"
},
{
"key": "complex",
"value": 180,
"unit": "days"
},
{
"key": "director",
"value": 240,
"unit": "days"
}
],
"country": "PT",
"pay_from_range": true,
"start_date_source": "suggested"
}
}
}Change an offer#
POST/v1/hiring/offers.updateWrite
Changes an offer not sent yet; send only what changes in terms (null clears): title, start_date, contract_type, end_date (fixed-term, temporary and internship), probation {value, unit: days or months} (at most what the employer's country allows), weekly_hours, pay {amount, currency, period: year, month or hour, payments_per_year: 12, 13 or 14}, benefits, place, expires_on, note (to the candidate, not in the letter), signer_person_id (null: the job's hiring manager) and signer_title, work_email (the new work email the hire is made with), invite (start or none), unit_id, location_id, manager_id, language (the letter's). An offer waiting for approval or approved goes back to draft: submit it again. A sent offer is not changed: revise it (hiring_offers_revise). Owners, admins and HR, or the job's hiring manager, signed in to Bizisy.
- Web app only
- Refused for API keys and connected apps. Offers are changed in the app.
- MCP tool
hiring_offers_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
offer_idstringrequired1–100 characters.
termsobjectrequired21 fields
titlestring1–120 characters.
start_datestringPattern
^\d{4}-\d{2}-\d{2}$.contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"end_datestring | nullPattern
^\d{4}-\d{2}-\d{2}$.probationobject | null2 fields
valueintegerrequiredFrom 1 to 366.
unit"days" | "months"required
weekly_hoursnumber | nullFrom 1 to 60.
payobject4 fields
amountnumberrequiredFrom 0 to 10000000.
currencyanyrequiredperiod"year" | "month" | "hour"requiredpayments_per_year12 | 13 | 14
benefitsstring | nullUp to 2000 characters.
benefit_idsstring[]Catalogue benefits the hire will have (benefits_offers_options for the offer's legal entity); the letter writes them out, then the benefits text.
1–100 characters. Up to 30 items.
placestring | nullUp to 200 characters.
expires_onstringPattern
^\d{4}-\d{2}-\d{2}$.notestring | nullUp to 1000 characters.
signer_person_idstring | nullWho signs for the company (a person working there); null: the job's hiring manager.
1–100 characters.
signer_titlestring | nullUp to 120 characters.
work_emailemail | nullUp to 254 characters.
invite"start" | "none"unit_idstring | null1–100 characters.
location_idstring | null1–100 characters.
manager_idstring | null1–100 characters.
language"en" | "pt" | "es" | "fr" | "de"The letter's and the offer page's language (default the job's).
new_paybooleanTransfers only (an offer to someone who works here): true when the offer changes their pay to terms.pay; false keeps their pay. HR only.
Returns
28 fields
idstringrequiredversionintegerrequiredsupersedesstring | nullrequiredapplication_idstring | nullrequiredjob_idstringrequiredcandidateobject | nullrequired2 fields
idstringrequirednamestringrequired
statusstring (enum)requireddraft, awaiting_approval, ready (approved or no approval needed: send it), sent, accepted_pending_hire (accepted; the hire runs or waits for HR), accepted (hired), declined, expired, withdrawn.
One of:
draft,awaiting_approval,ready,sent,accepted_pending_hire,accepted,declined,expired,withdrawn.language"en" | "pt" | "es" | "fr" | "de"requiredletter_kind"permanent" | "fixed_term"requiredtermsobjectrequired25 fields
titlestringrequiredlegal_entity_idstring | nullrequiredemployerstring | nullrequiredemployer_countrystring | nullrequiredunit_idstring | nullrequiredlocation_idstring | nullrequiredmanager_idstring | nullrequiredposition_idstring | nullrequiredplacestring | nullrequiredstart_datestringrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredend_datestring | nullrequiredprobationobject | nullrequired2 fields
valueintegerrequiredunit"days" | "months"required
weekly_hoursnumber | nullrequiredpayobject | nullrequiredPay tier: HR and the job's hiring manager; null over an API key or MCP.
4 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredpayments_per_yearinteger | nullrequired
benefitsstring | nullrequiredHR's own words about benefits (appended after the catalogue's).
benefit_idsstring[]requiredCatalogue benefits named on the offer (benefits_offers_options).
benefit_linesstring[]requiredThose benefits as the letter writes them, in its language, frozen when the offer was saved.
expires_onstringrequirednotestring | nullrequiredsigner_person_idstring | nullrequiredsigner_namestring | nullrequiredsigner_titlestring | nullrequiredwork_emailstring | nullrequiredThe new work email the hire is made with (never on the letter).
invite"start" | "none"requiredThe sign-in invite: on their first day (start) or none.
pay_hiddenbooleanrequiredTrue over an API key or MCP: pay stays in the app.
rangeobject | nullrequiredThe job's published range the pay is checked against (pay tier).
4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
range_check"none" | "within" | "below" | "above"requiredbelow is refused on submit; above needs approval (unless approval is off).
approvalobject | nullrequired6 fields
reason"above_range" | "every_offer"requiredapprovers"hr" | "owner"requiredstate"pending" | "approved" | "rejected"requiredasked_atstringrequireddecidedobject | nullrequired4 fields
atstringrequiredbyobject | nullrequired2 fields
idstringrequirednamestringrequired
commentstring | nullrequiredautomaticbooleanrequired
can_decidebooleanrequiredYou may approve or send it back (an approver, not its proposer, signed in to Bizisy).
approval_contextobject | nullrequiredFor an approver: the published range, the band of the position's level and how many hold the title.
3 fields
rangeobject | nullrequired4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
bandobject | nullrequired5 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredsource"title" | "level"required
title_holdersinteger | nullrequiredHow many people hold the position's title today (never their names or pay).
proposed_byobject | nullrequired2 fields
idstringrequirednamestringrequired
sentobject | nullrequired3 fields
atstringrequiredexpires_atstringrequiredremindedbooleanrequired
acceptanceobject | nullrequired3 fields
atstringrequiredtyped_namestringrequiredsha256stringrequired
declinedobject | nullrequired3 fields
atstringrequiredreasonstring | nullrequiredkindstring (enum)requiredThe reason the candidate picked: pay, other_offer, role, location, start_date, personal or other; null: none.
One of:
pay,other_offer,role,location,start_date,personal,other.
withdrawnobject | nullrequired3 fields
atstringrequiredrevisedbooleanrequiredtoldbooleanrequired
expired_atstring | nullrequiredhireobjectrequired4 fields
person_idstring | nullrequiredfailedobject | nullrequired2 fields
atstringrequiredreasonstringrequired
finishbooleanrequiredThe candidate accepted and HR must finish the hire (hiring_applications_hire_draft is filled in from the offer).
in_documentsbooleanrequiredThe signed offer is in the person's documents.
filesobjectrequired2 fields
letterobject | nullrequiredThe letter as sent (a 5-minute link, in the app only).
1 field
urlstring | nullrequired
signedobject | nullrequiredThe signed copy with the acceptance record (a 5-minute link, in the app only, while it is kept in Hiring).
1 field
urlstring | nullrequired
questionsintegerrequiredkind"hire" | "transfer"requiredtransfer: to someone who works here (W7 D8): accepted in My workspace, then a job change under Settings → Approval rules.
transferobject | nullrequired5 fields
new_paybooleanrequiredThe offer changes their pay (else their pay stays).
state"none" | "waiting" | "approved" | "applied" | "rejected" | "cancelled"requirednone: not accepted yet; waiting: accepted, the job change waits for approval; approved/applied: done; rejected/cancelled: not approved (HR tells them).
approval_idstring | nullrequiredwaiting_forstring | nullrequiredwaiting: the step it waits for (manager, hr).
approversstring[]required
created_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/offers.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"offer_id": "o1",
"terms": {
"pay": {
"amount": 1500,
"currency": "EUR",
"period": "month",
"payments_per_year": 14
},
"note": "We loved the trial shift."
}
}'const res = await fetch('https://api.bizisy.com/v1/hiring/offers.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"offer_id": "o1",
"terms": {
"pay": {
"amount": 1500,
"currency": "EUR",
"period": "month",
"payments_per_year": 14
},
"note": "We loved the trial shift."
}
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/offers.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"offer_id": "o1",
"terms": {
"pay": {
"amount": 1500,
"currency": "EUR",
"period": "month",
"payments_per_year": 14,
},
"note": "We loved the trial shift.",
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "o1",
"version": 1,
"supersedes": null,
"application_id": "a1",
"job_id": "j1",
"candidate": {
"id": "c1",
"name": "Maria Silva"
},
"status": "draft",
"language": "en",
"letter_kind": "permanent",
"terms": {
"title": "Line cook",
"legal_entity_id": "e1",
"employer": "Acme Lda",
"employer_country": "PT",
"unit_id": "u1",
"location_id": "l1",
"manager_id": "p2",
"position_id": "pos1",
"place": "Braga kitchen, Braga",
"start_date": "2026-12-01",
"contract_type": "permanent",
"end_date": null,
"probation": {
"value": 90,
"unit": "days"
},
"weekly_hours": 40,
"pay": {
"amount": 1500,
"currency": "EUR",
"period": "month",
"payments_per_year": 14
},
"benefits": "Meals on shift.",
"benefit_ids": [],
"benefit_lines": [],
"expires_on": "2026-10-25",
"note": null,
"signer_person_id": "p2",
"signer_name": "Rita Lopes",
"signer_title": "Head chef",
"work_email": "maria.silva@acme.pt",
"invite": "start"
},
"pay_hidden": false,
"range": {
"min": 18000,
"max": 22000,
"currency": "EUR",
"period": "year"
},
"range_check": "within",
"approval": null,
"approval_context": null,
"proposed_by": {
"id": "p2",
"name": "Rita Lopes"
},
"sent": null,
"acceptance": null,
"declined": null,
"withdrawn": null,
"expired_at": null,
"hire": {
"person_id": null,
"failed": null,
"finish": false,
"in_documents": false
},
"files": {
"letter": null,
"signed": null
},
"questions": 0,
"kind": "hire",
"transfer": null,
"created_at": "2026-10-18T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z"
}
}Check an offer against the range#
POST/v1/hiring/offers.submitWrite
Checks a draft offer and readies it to send (O2): pay below the job's published range is refused (the range shown to candidates binds, art. 5 Directive 2023/970); above its maximum it needs approval (Settings → Hiring → Offer approval: above_range, the default; every_offer: always; off: never), from owners, admins and HR or owners only, never the person who submits it (when nobody else could approve, it is approved by itself and says so). The approvers get an email and see it in Approvals and on Home. Also refused: no pay, a fixed-term contract without an end date, a start date or expiry in the past, an expiry after the first day. Result: status awaiting_approval or ready (send it with hiring_offers_send). Owners, admins and HR, or the job's hiring manager, signed in to Bizisy.
- Web app only
- Refused for API keys and connected apps. Offers are checked and sent for approval in the app.
- MCP tool
hiring_offers_submiton HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
offer_idstringrequired1–100 characters.
Returns
28 fields
idstringrequiredversionintegerrequiredsupersedesstring | nullrequiredapplication_idstring | nullrequiredjob_idstringrequiredcandidateobject | nullrequired2 fields
idstringrequirednamestringrequired
statusstring (enum)requireddraft, awaiting_approval, ready (approved or no approval needed: send it), sent, accepted_pending_hire (accepted; the hire runs or waits for HR), accepted (hired), declined, expired, withdrawn.
One of:
draft,awaiting_approval,ready,sent,accepted_pending_hire,accepted,declined,expired,withdrawn.language"en" | "pt" | "es" | "fr" | "de"requiredletter_kind"permanent" | "fixed_term"requiredtermsobjectrequired25 fields
titlestringrequiredlegal_entity_idstring | nullrequiredemployerstring | nullrequiredemployer_countrystring | nullrequiredunit_idstring | nullrequiredlocation_idstring | nullrequiredmanager_idstring | nullrequiredposition_idstring | nullrequiredplacestring | nullrequiredstart_datestringrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredend_datestring | nullrequiredprobationobject | nullrequired2 fields
valueintegerrequiredunit"days" | "months"required
weekly_hoursnumber | nullrequiredpayobject | nullrequiredPay tier: HR and the job's hiring manager; null over an API key or MCP.
4 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredpayments_per_yearinteger | nullrequired
benefitsstring | nullrequiredHR's own words about benefits (appended after the catalogue's).
benefit_idsstring[]requiredCatalogue benefits named on the offer (benefits_offers_options).
benefit_linesstring[]requiredThose benefits as the letter writes them, in its language, frozen when the offer was saved.
expires_onstringrequirednotestring | nullrequiredsigner_person_idstring | nullrequiredsigner_namestring | nullrequiredsigner_titlestring | nullrequiredwork_emailstring | nullrequiredThe new work email the hire is made with (never on the letter).
invite"start" | "none"requiredThe sign-in invite: on their first day (start) or none.
pay_hiddenbooleanrequiredTrue over an API key or MCP: pay stays in the app.
rangeobject | nullrequiredThe job's published range the pay is checked against (pay tier).
4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
range_check"none" | "within" | "below" | "above"requiredbelow is refused on submit; above needs approval (unless approval is off).
approvalobject | nullrequired6 fields
reason"above_range" | "every_offer"requiredapprovers"hr" | "owner"requiredstate"pending" | "approved" | "rejected"requiredasked_atstringrequireddecidedobject | nullrequired4 fields
atstringrequiredbyobject | nullrequired2 fields
idstringrequirednamestringrequired
commentstring | nullrequiredautomaticbooleanrequired
can_decidebooleanrequiredYou may approve or send it back (an approver, not its proposer, signed in to Bizisy).
approval_contextobject | nullrequiredFor an approver: the published range, the band of the position's level and how many hold the title.
3 fields
rangeobject | nullrequired4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
bandobject | nullrequired5 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredsource"title" | "level"required
title_holdersinteger | nullrequiredHow many people hold the position's title today (never their names or pay).
proposed_byobject | nullrequired2 fields
idstringrequirednamestringrequired
sentobject | nullrequired3 fields
atstringrequiredexpires_atstringrequiredremindedbooleanrequired
acceptanceobject | nullrequired3 fields
atstringrequiredtyped_namestringrequiredsha256stringrequired
declinedobject | nullrequired3 fields
atstringrequiredreasonstring | nullrequiredkindstring (enum)requiredThe reason the candidate picked: pay, other_offer, role, location, start_date, personal or other; null: none.
One of:
pay,other_offer,role,location,start_date,personal,other.
withdrawnobject | nullrequired3 fields
atstringrequiredrevisedbooleanrequiredtoldbooleanrequired
expired_atstring | nullrequiredhireobjectrequired4 fields
person_idstring | nullrequiredfailedobject | nullrequired2 fields
atstringrequiredreasonstringrequired
finishbooleanrequiredThe candidate accepted and HR must finish the hire (hiring_applications_hire_draft is filled in from the offer).
in_documentsbooleanrequiredThe signed offer is in the person's documents.
filesobjectrequired2 fields
letterobject | nullrequiredThe letter as sent (a 5-minute link, in the app only).
1 field
urlstring | nullrequired
signedobject | nullrequiredThe signed copy with the acceptance record (a 5-minute link, in the app only, while it is kept in Hiring).
1 field
urlstring | nullrequired
questionsintegerrequiredkind"hire" | "transfer"requiredtransfer: to someone who works here (W7 D8): accepted in My workspace, then a job change under Settings → Approval rules.
transferobject | nullrequired5 fields
new_paybooleanrequiredThe offer changes their pay (else their pay stays).
state"none" | "waiting" | "approved" | "applied" | "rejected" | "cancelled"requirednone: not accepted yet; waiting: accepted, the job change waits for approval; approved/applied: done; rejected/cancelled: not approved (HR tells them).
approval_idstring | nullrequiredwaiting_forstring | nullrequiredwaiting: the step it waits for (manager, hr).
approversstring[]required
created_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/offers.submit \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"offer_id":"o1"}'const res = await fetch('https://api.bizisy.com/v1/hiring/offers.submit', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"offer_id": "o1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/offers.submit",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"offer_id": "o1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "o1",
"version": 1,
"supersedes": null,
"application_id": "a1",
"job_id": "j1",
"candidate": {
"id": "c1",
"name": "Maria Silva"
},
"status": "awaiting_approval",
"language": "en",
"letter_kind": "permanent",
"terms": {
"title": "Line cook",
"legal_entity_id": "e1",
"employer": "Acme Lda",
"employer_country": "PT",
"unit_id": "u1",
"location_id": "l1",
"manager_id": "p2",
"position_id": "pos1",
"place": "Braga kitchen, Braga",
"start_date": "2026-12-01",
"contract_type": "permanent",
"end_date": null,
"probation": {
"value": 90,
"unit": "days"
},
"weekly_hours": 40,
"pay": {
"amount": 1700,
"currency": "EUR",
"period": "month",
"payments_per_year": 14
},
"benefits": "Meals on shift.",
"benefit_ids": [],
"benefit_lines": [],
"expires_on": "2026-10-25",
"note": null,
"signer_person_id": "p2",
"signer_name": "Rita Lopes",
"signer_title": "Head chef",
"work_email": "maria.silva@acme.pt",
"invite": "start"
},
"pay_hidden": false,
"range": {
"min": 18000,
"max": 22000,
"currency": "EUR",
"period": "year"
},
"range_check": "above",
"approval": {
"reason": "above_range",
"approvers": "hr",
"state": "pending",
"asked_at": "2026-10-18T09:10:00.000Z",
"decided": null,
"can_decide": true
},
"approval_context": {
"range": {
"min": 18000,
"max": 22000,
"currency": "EUR",
"period": "year"
},
"band": {
"min": 17000,
"max": 24000,
"currency": "EUR",
"period": "year",
"source": "level"
},
"title_holders": 4
},
"proposed_by": {
"id": "p2",
"name": "Rita Lopes"
},
"sent": null,
"acceptance": null,
"declined": null,
"withdrawn": null,
"expired_at": null,
"hire": {
"person_id": null,
"failed": null,
"finish": false,
"in_documents": false
},
"files": {
"letter": null,
"signed": null
},
"questions": 0,
"kind": "hire",
"transfer": null,
"created_at": "2026-10-18T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z"
}
}Approve an offer#
POST/v1/hiring/offers.decideWrite
Approves an offer waiting for approval, or sends it back (decision reject, with a comment saying what to change: it goes back to draft). Shown to the approver: the pay, the job's published range, the band of the position's level and how many people hold the title (never their names or pay). Who: the approvers of Settings → Hiring (owners, admins and HR, or owners only), never the person who proposed it. The proposer gets an email. Signed in to Bizisy only: refused over an API key or MCP.
- Web app only
- Refused for API keys and connected apps. Offers are approved in the app: a person decides.
- MCP tool
hiring_offers_decideon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
offer_idstringrequired1–100 characters.
decision"approve" | "reject"requiredcommentstringUp to 500 characters.
Returns
28 fields
idstringrequiredversionintegerrequiredsupersedesstring | nullrequiredapplication_idstring | nullrequiredjob_idstringrequiredcandidateobject | nullrequired2 fields
idstringrequirednamestringrequired
statusstring (enum)requireddraft, awaiting_approval, ready (approved or no approval needed: send it), sent, accepted_pending_hire (accepted; the hire runs or waits for HR), accepted (hired), declined, expired, withdrawn.
One of:
draft,awaiting_approval,ready,sent,accepted_pending_hire,accepted,declined,expired,withdrawn.language"en" | "pt" | "es" | "fr" | "de"requiredletter_kind"permanent" | "fixed_term"requiredtermsobjectrequired25 fields
titlestringrequiredlegal_entity_idstring | nullrequiredemployerstring | nullrequiredemployer_countrystring | nullrequiredunit_idstring | nullrequiredlocation_idstring | nullrequiredmanager_idstring | nullrequiredposition_idstring | nullrequiredplacestring | nullrequiredstart_datestringrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredend_datestring | nullrequiredprobationobject | nullrequired2 fields
valueintegerrequiredunit"days" | "months"required
weekly_hoursnumber | nullrequiredpayobject | nullrequiredPay tier: HR and the job's hiring manager; null over an API key or MCP.
4 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredpayments_per_yearinteger | nullrequired
benefitsstring | nullrequiredHR's own words about benefits (appended after the catalogue's).
benefit_idsstring[]requiredCatalogue benefits named on the offer (benefits_offers_options).
benefit_linesstring[]requiredThose benefits as the letter writes them, in its language, frozen when the offer was saved.
expires_onstringrequirednotestring | nullrequiredsigner_person_idstring | nullrequiredsigner_namestring | nullrequiredsigner_titlestring | nullrequiredwork_emailstring | nullrequiredThe new work email the hire is made with (never on the letter).
invite"start" | "none"requiredThe sign-in invite: on their first day (start) or none.
pay_hiddenbooleanrequiredTrue over an API key or MCP: pay stays in the app.
rangeobject | nullrequiredThe job's published range the pay is checked against (pay tier).
4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
range_check"none" | "within" | "below" | "above"requiredbelow is refused on submit; above needs approval (unless approval is off).
approvalobject | nullrequired6 fields
reason"above_range" | "every_offer"requiredapprovers"hr" | "owner"requiredstate"pending" | "approved" | "rejected"requiredasked_atstringrequireddecidedobject | nullrequired4 fields
atstringrequiredbyobject | nullrequired2 fields
idstringrequirednamestringrequired
commentstring | nullrequiredautomaticbooleanrequired
can_decidebooleanrequiredYou may approve or send it back (an approver, not its proposer, signed in to Bizisy).
approval_contextobject | nullrequiredFor an approver: the published range, the band of the position's level and how many hold the title.
3 fields
rangeobject | nullrequired4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
bandobject | nullrequired5 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredsource"title" | "level"required
title_holdersinteger | nullrequiredHow many people hold the position's title today (never their names or pay).
proposed_byobject | nullrequired2 fields
idstringrequirednamestringrequired
sentobject | nullrequired3 fields
atstringrequiredexpires_atstringrequiredremindedbooleanrequired
acceptanceobject | nullrequired3 fields
atstringrequiredtyped_namestringrequiredsha256stringrequired
declinedobject | nullrequired3 fields
atstringrequiredreasonstring | nullrequiredkindstring (enum)requiredThe reason the candidate picked: pay, other_offer, role, location, start_date, personal or other; null: none.
One of:
pay,other_offer,role,location,start_date,personal,other.
withdrawnobject | nullrequired3 fields
atstringrequiredrevisedbooleanrequiredtoldbooleanrequired
expired_atstring | nullrequiredhireobjectrequired4 fields
person_idstring | nullrequiredfailedobject | nullrequired2 fields
atstringrequiredreasonstringrequired
finishbooleanrequiredThe candidate accepted and HR must finish the hire (hiring_applications_hire_draft is filled in from the offer).
in_documentsbooleanrequiredThe signed offer is in the person's documents.
filesobjectrequired2 fields
letterobject | nullrequiredThe letter as sent (a 5-minute link, in the app only).
1 field
urlstring | nullrequired
signedobject | nullrequiredThe signed copy with the acceptance record (a 5-minute link, in the app only, while it is kept in Hiring).
1 field
urlstring | nullrequired
questionsintegerrequiredkind"hire" | "transfer"requiredtransfer: to someone who works here (W7 D8): accepted in My workspace, then a job change under Settings → Approval rules.
transferobject | nullrequired5 fields
new_paybooleanrequiredThe offer changes their pay (else their pay stays).
state"none" | "waiting" | "approved" | "applied" | "rejected" | "cancelled"requirednone: not accepted yet; waiting: accepted, the job change waits for approval; approved/applied: done; rejected/cancelled: not approved (HR tells them).
approval_idstring | nullrequiredwaiting_forstring | nullrequiredwaiting: the step it waits for (manager, hr).
approversstring[]required
created_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/offers.decide \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"offer_id": "o1",
"decision": "reject",
"comment": "Within the range, please."
}'const res = await fetch('https://api.bizisy.com/v1/hiring/offers.decide', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"offer_id": "o1",
"decision": "reject",
"comment": "Within the range, please."
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/offers.decide",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"offer_id": "o1",
"decision": "reject",
"comment": "Within the range, please.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "o1",
"version": 1,
"supersedes": null,
"application_id": "a1",
"job_id": "j1",
"candidate": {
"id": "c1",
"name": "Maria Silva"
},
"status": "ready",
"language": "en",
"letter_kind": "permanent",
"terms": {
"title": "Line cook",
"legal_entity_id": "e1",
"employer": "Acme Lda",
"employer_country": "PT",
"unit_id": "u1",
"location_id": "l1",
"manager_id": "p2",
"position_id": "pos1",
"place": "Braga kitchen, Braga",
"start_date": "2026-12-01",
"contract_type": "permanent",
"end_date": null,
"probation": {
"value": 90,
"unit": "days"
},
"weekly_hours": 40,
"pay": {
"amount": 1700,
"currency": "EUR",
"period": "month",
"payments_per_year": 14
},
"benefits": "Meals on shift.",
"benefit_ids": [],
"benefit_lines": [],
"expires_on": "2026-10-25",
"note": null,
"signer_person_id": "p2",
"signer_name": "Rita Lopes",
"signer_title": "Head chef",
"work_email": "maria.silva@acme.pt",
"invite": "start"
},
"pay_hidden": false,
"range": {
"min": 18000,
"max": 22000,
"currency": "EUR",
"period": "year"
},
"range_check": "above",
"approval": {
"reason": "above_range",
"approvers": "hr",
"state": "approved",
"asked_at": "2026-10-18T09:10:00.000Z",
"decided": {
"at": "2026-10-18T10:00:00.000Z",
"by": {
"id": "p1",
"name": "Ana Costa"
},
"comment": null,
"automatic": false
},
"can_decide": false
},
"approval_context": null,
"proposed_by": {
"id": "p2",
"name": "Rita Lopes"
},
"sent": null,
"acceptance": null,
"declined": null,
"withdrawn": null,
"expired_at": null,
"hire": {
"person_id": null,
"failed": null,
"finish": false,
"in_documents": false
},
"files": {
"letter": null,
"signed": null
},
"questions": 0,
"kind": "hire",
"transfer": null,
"created_at": "2026-10-18T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z"
}
}Send an offer#
POST/v1/hiring/offers.sendWrite
Sends a ready offer (approved, or no approval needed: hiring_offers_submit first): the letter is written from the company's template for its language and contract (Settings → Hiring → Offer letters; else Bizisy's), rendered to PDF with the company's logo and colour, and kept; the candidate gets an email with the link to their offer page (valid until 30 days after the offer ends), where they read it, accept it by typing their full name, ask a question or decline. The candidate moves to the Offer column; a reminder goes 2 days before the offer ends, and HR is told when it ends unanswered. Sends the hiring.offer_sent webhook. Owners, admins and HR, or the job's hiring manager, signed in to Bizisy: refused over an API key or MCP.
- Web app only
- Refused for API keys and connected apps. Sending an offer (it emails the candidate) happens in the app.
- MCP tool
hiring_offers_sendon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
offer_idstringrequired1–100 characters.
Returns
28 fields
idstringrequiredversionintegerrequiredsupersedesstring | nullrequiredapplication_idstring | nullrequiredjob_idstringrequiredcandidateobject | nullrequired2 fields
idstringrequirednamestringrequired
statusstring (enum)requireddraft, awaiting_approval, ready (approved or no approval needed: send it), sent, accepted_pending_hire (accepted; the hire runs or waits for HR), accepted (hired), declined, expired, withdrawn.
One of:
draft,awaiting_approval,ready,sent,accepted_pending_hire,accepted,declined,expired,withdrawn.language"en" | "pt" | "es" | "fr" | "de"requiredletter_kind"permanent" | "fixed_term"requiredtermsobjectrequired25 fields
titlestringrequiredlegal_entity_idstring | nullrequiredemployerstring | nullrequiredemployer_countrystring | nullrequiredunit_idstring | nullrequiredlocation_idstring | nullrequiredmanager_idstring | nullrequiredposition_idstring | nullrequiredplacestring | nullrequiredstart_datestringrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredend_datestring | nullrequiredprobationobject | nullrequired2 fields
valueintegerrequiredunit"days" | "months"required
weekly_hoursnumber | nullrequiredpayobject | nullrequiredPay tier: HR and the job's hiring manager; null over an API key or MCP.
4 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredpayments_per_yearinteger | nullrequired
benefitsstring | nullrequiredHR's own words about benefits (appended after the catalogue's).
benefit_idsstring[]requiredCatalogue benefits named on the offer (benefits_offers_options).
benefit_linesstring[]requiredThose benefits as the letter writes them, in its language, frozen when the offer was saved.
expires_onstringrequirednotestring | nullrequiredsigner_person_idstring | nullrequiredsigner_namestring | nullrequiredsigner_titlestring | nullrequiredwork_emailstring | nullrequiredThe new work email the hire is made with (never on the letter).
invite"start" | "none"requiredThe sign-in invite: on their first day (start) or none.
pay_hiddenbooleanrequiredTrue over an API key or MCP: pay stays in the app.
rangeobject | nullrequiredThe job's published range the pay is checked against (pay tier).
4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
range_check"none" | "within" | "below" | "above"requiredbelow is refused on submit; above needs approval (unless approval is off).
approvalobject | nullrequired6 fields
reason"above_range" | "every_offer"requiredapprovers"hr" | "owner"requiredstate"pending" | "approved" | "rejected"requiredasked_atstringrequireddecidedobject | nullrequired4 fields
atstringrequiredbyobject | nullrequired2 fields
idstringrequirednamestringrequired
commentstring | nullrequiredautomaticbooleanrequired
can_decidebooleanrequiredYou may approve or send it back (an approver, not its proposer, signed in to Bizisy).
approval_contextobject | nullrequiredFor an approver: the published range, the band of the position's level and how many hold the title.
3 fields
rangeobject | nullrequired4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
bandobject | nullrequired5 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredsource"title" | "level"required
title_holdersinteger | nullrequiredHow many people hold the position's title today (never their names or pay).
proposed_byobject | nullrequired2 fields
idstringrequirednamestringrequired
sentobject | nullrequired3 fields
atstringrequiredexpires_atstringrequiredremindedbooleanrequired
acceptanceobject | nullrequired3 fields
atstringrequiredtyped_namestringrequiredsha256stringrequired
declinedobject | nullrequired3 fields
atstringrequiredreasonstring | nullrequiredkindstring (enum)requiredThe reason the candidate picked: pay, other_offer, role, location, start_date, personal or other; null: none.
One of:
pay,other_offer,role,location,start_date,personal,other.
withdrawnobject | nullrequired3 fields
atstringrequiredrevisedbooleanrequiredtoldbooleanrequired
expired_atstring | nullrequiredhireobjectrequired4 fields
person_idstring | nullrequiredfailedobject | nullrequired2 fields
atstringrequiredreasonstringrequired
finishbooleanrequiredThe candidate accepted and HR must finish the hire (hiring_applications_hire_draft is filled in from the offer).
in_documentsbooleanrequiredThe signed offer is in the person's documents.
filesobjectrequired2 fields
letterobject | nullrequiredThe letter as sent (a 5-minute link, in the app only).
1 field
urlstring | nullrequired
signedobject | nullrequiredThe signed copy with the acceptance record (a 5-minute link, in the app only, while it is kept in Hiring).
1 field
urlstring | nullrequired
questionsintegerrequiredkind"hire" | "transfer"requiredtransfer: to someone who works here (W7 D8): accepted in My workspace, then a job change under Settings → Approval rules.
transferobject | nullrequired5 fields
new_paybooleanrequiredThe offer changes their pay (else their pay stays).
state"none" | "waiting" | "approved" | "applied" | "rejected" | "cancelled"requirednone: not accepted yet; waiting: accepted, the job change waits for approval; approved/applied: done; rejected/cancelled: not approved (HR tells them).
approval_idstring | nullrequiredwaiting_forstring | nullrequiredwaiting: the step it waits for (manager, hr).
approversstring[]required
created_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/offers.send \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"offer_id":"o1"}'const res = await fetch('https://api.bizisy.com/v1/hiring/offers.send', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"offer_id": "o1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/offers.send",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"offer_id": "o1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "o1",
"version": 1,
"supersedes": null,
"application_id": "a1",
"job_id": "j1",
"candidate": {
"id": "c1",
"name": "Maria Silva"
},
"status": "sent",
"language": "en",
"letter_kind": "permanent",
"terms": {
"title": "Line cook",
"legal_entity_id": "e1",
"employer": "Acme Lda",
"employer_country": "PT",
"unit_id": "u1",
"location_id": "l1",
"manager_id": "p2",
"position_id": "pos1",
"place": "Braga kitchen, Braga",
"start_date": "2026-12-01",
"contract_type": "permanent",
"end_date": null,
"probation": {
"value": 90,
"unit": "days"
},
"weekly_hours": 40,
"pay": {
"amount": 1700,
"currency": "EUR",
"period": "month",
"payments_per_year": 14
},
"benefits": "Meals on shift.",
"benefit_ids": [],
"benefit_lines": [],
"expires_on": "2026-10-25",
"note": null,
"signer_person_id": "p2",
"signer_name": "Rita Lopes",
"signer_title": "Head chef",
"work_email": "maria.silva@acme.pt",
"invite": "start"
},
"pay_hidden": false,
"range": {
"min": 18000,
"max": 22000,
"currency": "EUR",
"period": "year"
},
"range_check": "above",
"approval": {
"reason": "above_range",
"approvers": "hr",
"state": "approved",
"asked_at": "2026-10-18T09:10:00.000Z",
"decided": {
"at": "2026-10-18T10:00:00.000Z",
"by": {
"id": "p1",
"name": "Ana Costa"
},
"comment": null,
"automatic": false
},
"can_decide": false
},
"approval_context": null,
"proposed_by": {
"id": "p2",
"name": "Rita Lopes"
},
"sent": {
"at": "2026-10-18T10:05:00.000Z",
"expires_at": "2026-10-25T23:00:00.000Z",
"reminded": false
},
"acceptance": null,
"declined": null,
"withdrawn": null,
"expired_at": null,
"hire": {
"person_id": null,
"failed": null,
"finish": false,
"in_documents": false
},
"files": {
"letter": {
"url": "https://storage.example/ofr_o1?sig=x"
},
"signed": null
},
"questions": 0,
"kind": "hire",
"transfer": null,
"created_at": "2026-10-18T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z"
}
}Withdraw an offer#
POST/v1/hiring/offers.withdrawWrite
Withdraws an offer not accepted yet (a draft, one waiting for approval, ready, or sent). A sent offer can no longer be accepted, and the candidate is emailed that it was withdrawn (tell false: told another way, e.g. by phone). The candidate stays in the Offer column: make a new offer or tell them not this time. Owners, admins and HR, or the job's hiring manager, signed in to Bizisy.
- Web app only
- Refused for API keys and connected apps. Withdrawing an offer (it emails the candidate) happens in the app.
- MCP tool
hiring_offers_withdrawon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
offer_idstringrequired1–100 characters.
tellbooleanDefault
true.
Returns
28 fields
idstringrequiredversionintegerrequiredsupersedesstring | nullrequiredapplication_idstring | nullrequiredjob_idstringrequiredcandidateobject | nullrequired2 fields
idstringrequirednamestringrequired
statusstring (enum)requireddraft, awaiting_approval, ready (approved or no approval needed: send it), sent, accepted_pending_hire (accepted; the hire runs or waits for HR), accepted (hired), declined, expired, withdrawn.
One of:
draft,awaiting_approval,ready,sent,accepted_pending_hire,accepted,declined,expired,withdrawn.language"en" | "pt" | "es" | "fr" | "de"requiredletter_kind"permanent" | "fixed_term"requiredtermsobjectrequired25 fields
titlestringrequiredlegal_entity_idstring | nullrequiredemployerstring | nullrequiredemployer_countrystring | nullrequiredunit_idstring | nullrequiredlocation_idstring | nullrequiredmanager_idstring | nullrequiredposition_idstring | nullrequiredplacestring | nullrequiredstart_datestringrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredend_datestring | nullrequiredprobationobject | nullrequired2 fields
valueintegerrequiredunit"days" | "months"required
weekly_hoursnumber | nullrequiredpayobject | nullrequiredPay tier: HR and the job's hiring manager; null over an API key or MCP.
4 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredpayments_per_yearinteger | nullrequired
benefitsstring | nullrequiredHR's own words about benefits (appended after the catalogue's).
benefit_idsstring[]requiredCatalogue benefits named on the offer (benefits_offers_options).
benefit_linesstring[]requiredThose benefits as the letter writes them, in its language, frozen when the offer was saved.
expires_onstringrequirednotestring | nullrequiredsigner_person_idstring | nullrequiredsigner_namestring | nullrequiredsigner_titlestring | nullrequiredwork_emailstring | nullrequiredThe new work email the hire is made with (never on the letter).
invite"start" | "none"requiredThe sign-in invite: on their first day (start) or none.
pay_hiddenbooleanrequiredTrue over an API key or MCP: pay stays in the app.
rangeobject | nullrequiredThe job's published range the pay is checked against (pay tier).
4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
range_check"none" | "within" | "below" | "above"requiredbelow is refused on submit; above needs approval (unless approval is off).
approvalobject | nullrequired6 fields
reason"above_range" | "every_offer"requiredapprovers"hr" | "owner"requiredstate"pending" | "approved" | "rejected"requiredasked_atstringrequireddecidedobject | nullrequired4 fields
atstringrequiredbyobject | nullrequired2 fields
idstringrequirednamestringrequired
commentstring | nullrequiredautomaticbooleanrequired
can_decidebooleanrequiredYou may approve or send it back (an approver, not its proposer, signed in to Bizisy).
approval_contextobject | nullrequiredFor an approver: the published range, the band of the position's level and how many hold the title.
3 fields
rangeobject | nullrequired4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
bandobject | nullrequired5 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredsource"title" | "level"required
title_holdersinteger | nullrequiredHow many people hold the position's title today (never their names or pay).
proposed_byobject | nullrequired2 fields
idstringrequirednamestringrequired
sentobject | nullrequired3 fields
atstringrequiredexpires_atstringrequiredremindedbooleanrequired
acceptanceobject | nullrequired3 fields
atstringrequiredtyped_namestringrequiredsha256stringrequired
declinedobject | nullrequired3 fields
atstringrequiredreasonstring | nullrequiredkindstring (enum)requiredThe reason the candidate picked: pay, other_offer, role, location, start_date, personal or other; null: none.
One of:
pay,other_offer,role,location,start_date,personal,other.
withdrawnobject | nullrequired3 fields
atstringrequiredrevisedbooleanrequiredtoldbooleanrequired
expired_atstring | nullrequiredhireobjectrequired4 fields
person_idstring | nullrequiredfailedobject | nullrequired2 fields
atstringrequiredreasonstringrequired
finishbooleanrequiredThe candidate accepted and HR must finish the hire (hiring_applications_hire_draft is filled in from the offer).
in_documentsbooleanrequiredThe signed offer is in the person's documents.
filesobjectrequired2 fields
letterobject | nullrequiredThe letter as sent (a 5-minute link, in the app only).
1 field
urlstring | nullrequired
signedobject | nullrequiredThe signed copy with the acceptance record (a 5-minute link, in the app only, while it is kept in Hiring).
1 field
urlstring | nullrequired
questionsintegerrequiredkind"hire" | "transfer"requiredtransfer: to someone who works here (W7 D8): accepted in My workspace, then a job change under Settings → Approval rules.
transferobject | nullrequired5 fields
new_paybooleanrequiredThe offer changes their pay (else their pay stays).
state"none" | "waiting" | "approved" | "applied" | "rejected" | "cancelled"requirednone: not accepted yet; waiting: accepted, the job change waits for approval; approved/applied: done; rejected/cancelled: not approved (HR tells them).
approval_idstring | nullrequiredwaiting_forstring | nullrequiredwaiting: the step it waits for (manager, hr).
approversstring[]required
created_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/offers.withdraw \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"offer_id":"o1","tell":false}'const res = await fetch('https://api.bizisy.com/v1/hiring/offers.withdraw', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"offer_id": "o1",
"tell": false
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/offers.withdraw",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"offer_id": "o1",
"tell": False,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "o1",
"version": 1,
"supersedes": null,
"application_id": "a1",
"job_id": "j1",
"candidate": {
"id": "c1",
"name": "Maria Silva"
},
"status": "withdrawn",
"language": "en",
"letter_kind": "permanent",
"terms": {
"title": "Line cook",
"legal_entity_id": "e1",
"employer": "Acme Lda",
"employer_country": "PT",
"unit_id": "u1",
"location_id": "l1",
"manager_id": "p2",
"position_id": "pos1",
"place": "Braga kitchen, Braga",
"start_date": "2026-12-01",
"contract_type": "permanent",
"end_date": null,
"probation": {
"value": 90,
"unit": "days"
},
"weekly_hours": 40,
"pay": {
"amount": 1700,
"currency": "EUR",
"period": "month",
"payments_per_year": 14
},
"benefits": "Meals on shift.",
"benefit_ids": [],
"benefit_lines": [],
"expires_on": "2026-10-25",
"note": null,
"signer_person_id": "p2",
"signer_name": "Rita Lopes",
"signer_title": "Head chef",
"work_email": "maria.silva@acme.pt",
"invite": "start"
},
"pay_hidden": false,
"range": {
"min": 18000,
"max": 22000,
"currency": "EUR",
"period": "year"
},
"range_check": "above",
"approval": {
"reason": "above_range",
"approvers": "hr",
"state": "approved",
"asked_at": "2026-10-18T09:10:00.000Z",
"decided": {
"at": "2026-10-18T10:00:00.000Z",
"by": {
"id": "p1",
"name": "Ana Costa"
},
"comment": null,
"automatic": false
},
"can_decide": false
},
"approval_context": null,
"proposed_by": {
"id": "p2",
"name": "Rita Lopes"
},
"sent": {
"at": "2026-10-18T10:05:00.000Z",
"expires_at": "2026-10-25T23:00:00.000Z",
"reminded": false
},
"acceptance": null,
"declined": null,
"withdrawn": {
"at": "2026-10-19T09:00:00.000Z",
"revised": false,
"told": true
},
"expired_at": null,
"hire": {
"person_id": null,
"failed": null,
"finish": false,
"in_documents": false
},
"files": {
"letter": {
"url": "https://storage.example/ofr_o1?sig=x"
},
"signed": null
},
"questions": 0,
"kind": "hire",
"transfer": null,
"created_at": "2026-10-18T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z"
}
}Revise a sent offer#
POST/v1/hiring/offers.reviseWrite
Revises a sent offer that was not answered: it is withdrawn (its link stops working and the candidate is emailed that an updated offer follows) and a new version starts as a draft with the same terms (change them, submit and send it: the candidate gets "Your updated job offer"). Owners, admins and HR, or the job's hiring manager, signed in to Bizisy.
- Web app only
- Refused for API keys and connected apps. Revising an offer (it emails the candidate) happens in the app.
- MCP tool
hiring_offers_reviseon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
offer_idstringrequired1–100 characters.
Returns
28 fields
idstringrequiredversionintegerrequiredsupersedesstring | nullrequiredapplication_idstring | nullrequiredjob_idstringrequiredcandidateobject | nullrequired2 fields
idstringrequirednamestringrequired
statusstring (enum)requireddraft, awaiting_approval, ready (approved or no approval needed: send it), sent, accepted_pending_hire (accepted; the hire runs or waits for HR), accepted (hired), declined, expired, withdrawn.
One of:
draft,awaiting_approval,ready,sent,accepted_pending_hire,accepted,declined,expired,withdrawn.language"en" | "pt" | "es" | "fr" | "de"requiredletter_kind"permanent" | "fixed_term"requiredtermsobjectrequired25 fields
titlestringrequiredlegal_entity_idstring | nullrequiredemployerstring | nullrequiredemployer_countrystring | nullrequiredunit_idstring | nullrequiredlocation_idstring | nullrequiredmanager_idstring | nullrequiredposition_idstring | nullrequiredplacestring | nullrequiredstart_datestringrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredend_datestring | nullrequiredprobationobject | nullrequired2 fields
valueintegerrequiredunit"days" | "months"required
weekly_hoursnumber | nullrequiredpayobject | nullrequiredPay tier: HR and the job's hiring manager; null over an API key or MCP.
4 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredpayments_per_yearinteger | nullrequired
benefitsstring | nullrequiredHR's own words about benefits (appended after the catalogue's).
benefit_idsstring[]requiredCatalogue benefits named on the offer (benefits_offers_options).
benefit_linesstring[]requiredThose benefits as the letter writes them, in its language, frozen when the offer was saved.
expires_onstringrequirednotestring | nullrequiredsigner_person_idstring | nullrequiredsigner_namestring | nullrequiredsigner_titlestring | nullrequiredwork_emailstring | nullrequiredThe new work email the hire is made with (never on the letter).
invite"start" | "none"requiredThe sign-in invite: on their first day (start) or none.
pay_hiddenbooleanrequiredTrue over an API key or MCP: pay stays in the app.
rangeobject | nullrequiredThe job's published range the pay is checked against (pay tier).
4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
range_check"none" | "within" | "below" | "above"requiredbelow is refused on submit; above needs approval (unless approval is off).
approvalobject | nullrequired6 fields
reason"above_range" | "every_offer"requiredapprovers"hr" | "owner"requiredstate"pending" | "approved" | "rejected"requiredasked_atstringrequireddecidedobject | nullrequired4 fields
atstringrequiredbyobject | nullrequired2 fields
idstringrequirednamestringrequired
commentstring | nullrequiredautomaticbooleanrequired
can_decidebooleanrequiredYou may approve or send it back (an approver, not its proposer, signed in to Bizisy).
approval_contextobject | nullrequiredFor an approver: the published range, the band of the position's level and how many hold the title.
3 fields
rangeobject | nullrequired4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
bandobject | nullrequired5 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredsource"title" | "level"required
title_holdersinteger | nullrequiredHow many people hold the position's title today (never their names or pay).
proposed_byobject | nullrequired2 fields
idstringrequirednamestringrequired
sentobject | nullrequired3 fields
atstringrequiredexpires_atstringrequiredremindedbooleanrequired
acceptanceobject | nullrequired3 fields
atstringrequiredtyped_namestringrequiredsha256stringrequired
declinedobject | nullrequired3 fields
atstringrequiredreasonstring | nullrequiredkindstring (enum)requiredThe reason the candidate picked: pay, other_offer, role, location, start_date, personal or other; null: none.
One of:
pay,other_offer,role,location,start_date,personal,other.
withdrawnobject | nullrequired3 fields
atstringrequiredrevisedbooleanrequiredtoldbooleanrequired
expired_atstring | nullrequiredhireobjectrequired4 fields
person_idstring | nullrequiredfailedobject | nullrequired2 fields
atstringrequiredreasonstringrequired
finishbooleanrequiredThe candidate accepted and HR must finish the hire (hiring_applications_hire_draft is filled in from the offer).
in_documentsbooleanrequiredThe signed offer is in the person's documents.
filesobjectrequired2 fields
letterobject | nullrequiredThe letter as sent (a 5-minute link, in the app only).
1 field
urlstring | nullrequired
signedobject | nullrequiredThe signed copy with the acceptance record (a 5-minute link, in the app only, while it is kept in Hiring).
1 field
urlstring | nullrequired
questionsintegerrequiredkind"hire" | "transfer"requiredtransfer: to someone who works here (W7 D8): accepted in My workspace, then a job change under Settings → Approval rules.
transferobject | nullrequired5 fields
new_paybooleanrequiredThe offer changes their pay (else their pay stays).
state"none" | "waiting" | "approved" | "applied" | "rejected" | "cancelled"requirednone: not accepted yet; waiting: accepted, the job change waits for approval; approved/applied: done; rejected/cancelled: not approved (HR tells them).
approval_idstring | nullrequiredwaiting_forstring | nullrequiredwaiting: the step it waits for (manager, hr).
approversstring[]required
created_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/offers.revise \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"offer_id":"o1"}'const res = await fetch('https://api.bizisy.com/v1/hiring/offers.revise', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"offer_id": "o1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/offers.revise",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"offer_id": "o1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "o2",
"version": 2,
"supersedes": "o1",
"application_id": "a1",
"job_id": "j1",
"candidate": {
"id": "c1",
"name": "Maria Silva"
},
"status": "draft",
"language": "en",
"letter_kind": "permanent",
"terms": {
"title": "Line cook",
"legal_entity_id": "e1",
"employer": "Acme Lda",
"employer_country": "PT",
"unit_id": "u1",
"location_id": "l1",
"manager_id": "p2",
"position_id": "pos1",
"place": "Braga kitchen, Braga",
"start_date": "2026-12-01",
"contract_type": "permanent",
"end_date": null,
"probation": {
"value": 90,
"unit": "days"
},
"weekly_hours": 40,
"pay": {
"amount": 1500,
"currency": "EUR",
"period": "month",
"payments_per_year": 14
},
"benefits": "Meals on shift.",
"benefit_ids": [],
"benefit_lines": [],
"expires_on": "2026-10-25",
"note": null,
"signer_person_id": "p2",
"signer_name": "Rita Lopes",
"signer_title": "Head chef",
"work_email": "maria.silva@acme.pt",
"invite": "start"
},
"pay_hidden": false,
"range": {
"min": 18000,
"max": 22000,
"currency": "EUR",
"period": "year"
},
"range_check": "within",
"approval": null,
"approval_context": null,
"proposed_by": {
"id": "p2",
"name": "Rita Lopes"
},
"sent": null,
"acceptance": null,
"declined": null,
"withdrawn": null,
"expired_at": null,
"hire": {
"person_id": null,
"failed": null,
"finish": false,
"in_documents": false
},
"files": {
"letter": null,
"signed": null
},
"questions": 0,
"kind": "hire",
"transfer": null,
"created_at": "2026-10-18T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z"
}
}Get an offer#
POST/v1/hiring/offers.getRead
One offer: its status (draft, awaiting_approval, ready, sent, accepted_pending_hire, accepted, declined, expired, withdrawn), version, terms, the range check against the job's published range, the approval (who decided, the comment; can_decide: you may decide it) with the approver's context (the range, the band of the position's level, how many hold the title: never names or pay), when it was sent and ends, the acceptance (the name typed, when, the letter's SHA-256), a decline's reason, the hire (finish: HR must finish it) and links to the letter and the signed copy (5 minutes, in the app only). suggestions: the probation periods of the employer's country. Owners, admins and HR any job; a job's hiring manager their own. Over an API key or MCP: no pay, no range, no files.
- Who can call it
- Manage key any Manage role
- Keys and apps
- No pay, range, approver context or file links.
- MCP tool
hiring_offers_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
offer_idstringrequired1–100 characters.
Returns
29 fields
idstringrequiredversionintegerrequiredsupersedesstring | nullrequiredapplication_idstring | nullrequiredjob_idstringrequiredcandidateobject | nullrequired2 fields
idstringrequirednamestringrequired
statusstring (enum)requireddraft, awaiting_approval, ready (approved or no approval needed: send it), sent, accepted_pending_hire (accepted; the hire runs or waits for HR), accepted (hired), declined, expired, withdrawn.
One of:
draft,awaiting_approval,ready,sent,accepted_pending_hire,accepted,declined,expired,withdrawn.language"en" | "pt" | "es" | "fr" | "de"requiredletter_kind"permanent" | "fixed_term"requiredtermsobjectrequired25 fields
titlestringrequiredlegal_entity_idstring | nullrequiredemployerstring | nullrequiredemployer_countrystring | nullrequiredunit_idstring | nullrequiredlocation_idstring | nullrequiredmanager_idstring | nullrequiredposition_idstring | nullrequiredplacestring | nullrequiredstart_datestringrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredend_datestring | nullrequiredprobationobject | nullrequired2 fields
valueintegerrequiredunit"days" | "months"required
weekly_hoursnumber | nullrequiredpayobject | nullrequiredPay tier: HR and the job's hiring manager; null over an API key or MCP.
4 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredpayments_per_yearinteger | nullrequired
benefitsstring | nullrequiredHR's own words about benefits (appended after the catalogue's).
benefit_idsstring[]requiredCatalogue benefits named on the offer (benefits_offers_options).
benefit_linesstring[]requiredThose benefits as the letter writes them, in its language, frozen when the offer was saved.
expires_onstringrequirednotestring | nullrequiredsigner_person_idstring | nullrequiredsigner_namestring | nullrequiredsigner_titlestring | nullrequiredwork_emailstring | nullrequiredThe new work email the hire is made with (never on the letter).
invite"start" | "none"requiredThe sign-in invite: on their first day (start) or none.
pay_hiddenbooleanrequiredTrue over an API key or MCP: pay stays in the app.
rangeobject | nullrequiredThe job's published range the pay is checked against (pay tier).
4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
range_check"none" | "within" | "below" | "above"requiredbelow is refused on submit; above needs approval (unless approval is off).
approvalobject | nullrequired6 fields
reason"above_range" | "every_offer"requiredapprovers"hr" | "owner"requiredstate"pending" | "approved" | "rejected"requiredasked_atstringrequireddecidedobject | nullrequired4 fields
atstringrequiredbyobject | nullrequired2 fields
idstringrequirednamestringrequired
commentstring | nullrequiredautomaticbooleanrequired
can_decidebooleanrequiredYou may approve or send it back (an approver, not its proposer, signed in to Bizisy).
approval_contextobject | nullrequiredFor an approver: the published range, the band of the position's level and how many hold the title.
3 fields
rangeobject | nullrequired4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
bandobject | nullrequired5 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredsource"title" | "level"required
title_holdersinteger | nullrequiredHow many people hold the position's title today (never their names or pay).
proposed_byobject | nullrequired2 fields
idstringrequirednamestringrequired
sentobject | nullrequired3 fields
atstringrequiredexpires_atstringrequiredremindedbooleanrequired
acceptanceobject | nullrequired3 fields
atstringrequiredtyped_namestringrequiredsha256stringrequired
declinedobject | nullrequired3 fields
atstringrequiredreasonstring | nullrequiredkindstring (enum)requiredThe reason the candidate picked: pay, other_offer, role, location, start_date, personal or other; null: none.
One of:
pay,other_offer,role,location,start_date,personal,other.
withdrawnobject | nullrequired3 fields
atstringrequiredrevisedbooleanrequiredtoldbooleanrequired
expired_atstring | nullrequiredhireobjectrequired4 fields
person_idstring | nullrequiredfailedobject | nullrequired2 fields
atstringrequiredreasonstringrequired
finishbooleanrequiredThe candidate accepted and HR must finish the hire (hiring_applications_hire_draft is filled in from the offer).
in_documentsbooleanrequiredThe signed offer is in the person's documents.
filesobjectrequired2 fields
letterobject | nullrequiredThe letter as sent (a 5-minute link, in the app only).
1 field
urlstring | nullrequired
signedobject | nullrequiredThe signed copy with the acceptance record (a 5-minute link, in the app only, while it is kept in Hiring).
1 field
urlstring | nullrequired
questionsintegerrequiredkind"hire" | "transfer"requiredtransfer: to someone who works here (W7 D8): accepted in My workspace, then a job change under Settings → Approval rules.
transferobject | nullrequired5 fields
new_paybooleanrequiredThe offer changes their pay (else their pay stays).
state"none" | "waiting" | "approved" | "applied" | "rejected" | "cancelled"requirednone: not accepted yet; waiting: accepted, the job change waits for approval; approved/applied: done; rejected/cancelled: not approved (HR tells them).
approval_idstring | nullrequiredwaiting_forstring | nullrequiredwaiting: the step it waits for (manager, hr).
approversstring[]required
created_atstringrequiredupdated_atstringrequiredsuggestionsobjectrequired4 fields
probationobject[]requiredProbation periods the law of the employer's country suggests (PT: 90/180/240 days by role, 15–30 for fixed-term; ES: 2 months, 6 for qualified technicians, 3 in companies under 25; elsewhere at most 6 months). HR picks.
3 fields
keystring (enum)requiredOne of:
general,complex,director,qualified,small_company,fixed_long,fixed_short,directive.valueintegerrequiredunit"days" | "months"required
countrystring | nullrequiredpay_from_rangebooleanrequiredThe pay is the middle of the published range: a suggestion; change it to what was agreed.
start_date_source"position" | "suggested" | "offer"required
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/offers.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"offer_id":"o1"}'const res = await fetch('https://api.bizisy.com/v1/hiring/offers.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"offer_id": "o1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/offers.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"offer_id": "o1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "o1",
"version": 1,
"supersedes": null,
"application_id": "a1",
"job_id": "j1",
"candidate": {
"id": "c1",
"name": "Maria Silva"
},
"status": "awaiting_approval",
"language": "en",
"letter_kind": "permanent",
"terms": {
"title": "Line cook",
"legal_entity_id": "e1",
"employer": "Acme Lda",
"employer_country": "PT",
"unit_id": "u1",
"location_id": "l1",
"manager_id": "p2",
"position_id": "pos1",
"place": "Braga kitchen, Braga",
"start_date": "2026-12-01",
"contract_type": "permanent",
"end_date": null,
"probation": {
"value": 90,
"unit": "days"
},
"weekly_hours": 40,
"pay": {
"amount": 1700,
"currency": "EUR",
"period": "month",
"payments_per_year": 14
},
"benefits": "Meals on shift.",
"benefit_ids": [],
"benefit_lines": [],
"expires_on": "2026-10-25",
"note": null,
"signer_person_id": "p2",
"signer_name": "Rita Lopes",
"signer_title": "Head chef",
"work_email": "maria.silva@acme.pt",
"invite": "start"
},
"pay_hidden": false,
"range": {
"min": 18000,
"max": 22000,
"currency": "EUR",
"period": "year"
},
"range_check": "above",
"approval": {
"reason": "above_range",
"approvers": "hr",
"state": "pending",
"asked_at": "2026-10-18T09:10:00.000Z",
"decided": null,
"can_decide": true
},
"approval_context": {
"range": {
"min": 18000,
"max": 22000,
"currency": "EUR",
"period": "year"
},
"band": {
"min": 17000,
"max": 24000,
"currency": "EUR",
"period": "year",
"source": "level"
},
"title_holders": 4
},
"proposed_by": {
"id": "p2",
"name": "Rita Lopes"
},
"sent": null,
"acceptance": null,
"declined": null,
"withdrawn": null,
"expired_at": null,
"hire": {
"person_id": null,
"failed": null,
"finish": false,
"in_documents": false
},
"files": {
"letter": null,
"signed": null
},
"questions": 0,
"kind": "hire",
"transfer": null,
"created_at": "2026-10-18T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z",
"suggestions": {
"probation": [
{
"key": "general",
"value": 90,
"unit": "days"
},
{
"key": "complex",
"value": 180,
"unit": "days"
},
{
"key": "director",
"value": 240,
"unit": "days"
}
],
"country": "PT",
"pay_from_range": true,
"start_date_source": "suggested"
}
}
}List offers#
POST/v1/hiring/offers.listRead
Offers of the jobs you are on the hiring team of (owners, admins and HR: every job; a hiring manager: their own), newest first: by application_id (every version), job_id, or status (e.g. awaiting_approval, sent, accepted_pending_hire); waiting_for_me: those you may approve now. Each with its candidate, status, version, terms and dates as hiring_offers_get (without links or the approver's context). Over an API key or MCP: no pay. At most limit (default 100, at most 500).
- Who can call it
- Manage key any Manage role
- Keys and apps
- No pay.
- MCP tool
hiring_offers_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
application_idstring1–100 characters.
job_idstring1–100 characters.
statusstring (enum)One of:
draft,awaiting_approval,ready,sent,accepted_pending_hire,accepted,declined,expired,withdrawn.waiting_for_mebooleanlimitintegerFrom 1 to 500. Default
100.
Returns
offersobject[]required28 fields
idstringrequiredversionintegerrequiredsupersedesstring | nullrequiredapplication_idstring | nullrequiredjob_idstringrequiredcandidateobject | nullrequired2 fields
idstringrequirednamestringrequired
statusstring (enum)requireddraft, awaiting_approval, ready (approved or no approval needed: send it), sent, accepted_pending_hire (accepted; the hire runs or waits for HR), accepted (hired), declined, expired, withdrawn.
One of:
draft,awaiting_approval,ready,sent,accepted_pending_hire,accepted,declined,expired,withdrawn.language"en" | "pt" | "es" | "fr" | "de"requiredletter_kind"permanent" | "fixed_term"requiredtermsobjectrequired25 fields
titlestringrequiredlegal_entity_idstring | nullrequiredemployerstring | nullrequiredemployer_countrystring | nullrequiredunit_idstring | nullrequiredlocation_idstring | nullrequiredmanager_idstring | nullrequiredposition_idstring | nullrequiredplacestring | nullrequiredstart_datestringrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredend_datestring | nullrequiredprobationobject | nullrequired2 fields
valueintegerrequiredunit"days" | "months"required
weekly_hoursnumber | nullrequiredpayobject | nullrequiredPay tier: HR and the job's hiring manager; null over an API key or MCP.
4 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredpayments_per_yearinteger | nullrequired
benefitsstring | nullrequiredHR's own words about benefits (appended after the catalogue's).
benefit_idsstring[]requiredCatalogue benefits named on the offer (benefits_offers_options).
benefit_linesstring[]requiredThose benefits as the letter writes them, in its language, frozen when the offer was saved.
expires_onstringrequirednotestring | nullrequiredsigner_person_idstring | nullrequiredsigner_namestring | nullrequiredsigner_titlestring | nullrequiredwork_emailstring | nullrequiredThe new work email the hire is made with (never on the letter).
invite"start" | "none"requiredThe sign-in invite: on their first day (start) or none.
pay_hiddenbooleanrequiredTrue over an API key or MCP: pay stays in the app.
rangeobject | nullrequiredThe job's published range the pay is checked against (pay tier).
4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
range_check"none" | "within" | "below" | "above"requiredbelow is refused on submit; above needs approval (unless approval is off).
approvalobject | nullrequired6 fields
reason"above_range" | "every_offer"requiredapprovers"hr" | "owner"requiredstate"pending" | "approved" | "rejected"requiredasked_atstringrequireddecidedobject | nullrequired4 fields
atstringrequiredbyobject | nullrequired2 fields
idstringrequirednamestringrequired
commentstring | nullrequiredautomaticbooleanrequired
can_decidebooleanrequiredYou may approve or send it back (an approver, not its proposer, signed in to Bizisy).
approval_contextobject | nullrequiredFor an approver: the published range, the band of the position's level and how many hold the title.
3 fields
rangeobject | nullrequired4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
bandobject | nullrequired5 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredsource"title" | "level"required
title_holdersinteger | nullrequiredHow many people hold the position's title today (never their names or pay).
proposed_byobject | nullrequired2 fields
idstringrequirednamestringrequired
sentobject | nullrequired3 fields
atstringrequiredexpires_atstringrequiredremindedbooleanrequired
acceptanceobject | nullrequired3 fields
atstringrequiredtyped_namestringrequiredsha256stringrequired
declinedobject | nullrequired3 fields
atstringrequiredreasonstring | nullrequiredkindstring (enum)requiredThe reason the candidate picked: pay, other_offer, role, location, start_date, personal or other; null: none.
One of:
pay,other_offer,role,location,start_date,personal,other.
withdrawnobject | nullrequired3 fields
atstringrequiredrevisedbooleanrequiredtoldbooleanrequired
expired_atstring | nullrequiredhireobjectrequired4 fields
person_idstring | nullrequiredfailedobject | nullrequired2 fields
atstringrequiredreasonstringrequired
finishbooleanrequiredThe candidate accepted and HR must finish the hire (hiring_applications_hire_draft is filled in from the offer).
in_documentsbooleanrequiredThe signed offer is in the person's documents.
filesobjectrequired2 fields
letterobject | nullrequiredThe letter as sent (a 5-minute link, in the app only).
1 field
urlstring | nullrequired
signedobject | nullrequiredThe signed copy with the acceptance record (a 5-minute link, in the app only, while it is kept in Hiring).
1 field
urlstring | nullrequired
questionsintegerrequiredkind"hire" | "transfer"requiredtransfer: to someone who works here (W7 D8): accepted in My workspace, then a job change under Settings → Approval rules.
transferobject | nullrequired5 fields
new_paybooleanrequiredThe offer changes their pay (else their pay stays).
state"none" | "waiting" | "approved" | "applied" | "rejected" | "cancelled"requirednone: not accepted yet; waiting: accepted, the job change waits for approval; approved/applied: done; rejected/cancelled: not approved (HR tells them).
approval_idstring | nullrequiredwaiting_forstring | nullrequiredwaiting: the step it waits for (manager, hr).
approversstring[]required
created_atstringrequiredupdated_atstringrequired
totalintegerrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/offers.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"job_id":"j1","status":"sent","limit":50}'const res = await fetch('https://api.bizisy.com/v1/hiring/offers.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"job_id": "j1",
"status": "sent",
"limit": 50
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/offers.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"job_id": "j1",
"status": "sent",
"limit": 50,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"offers": [
{
"id": "o1",
"version": 1,
"supersedes": null,
"application_id": "a1",
"job_id": "j1",
"candidate": {
"id": "c1",
"name": "Maria Silva"
},
"status": "sent",
"language": "en",
"letter_kind": "permanent",
"terms": {
"title": "Line cook",
"legal_entity_id": "e1",
"employer": "Acme Lda",
"employer_country": "PT",
"unit_id": "u1",
"location_id": "l1",
"manager_id": "p2",
"position_id": "pos1",
"place": "Braga kitchen, Braga",
"start_date": "2026-12-01",
"contract_type": "permanent",
"end_date": null,
"probation": {
"value": 90,
"unit": "days"
},
"weekly_hours": 40,
"pay": {
"amount": 1700,
"currency": "EUR",
"period": "month",
"payments_per_year": 14
},
"benefits": "Meals on shift.",
"benefit_ids": [],
"benefit_lines": [],
"expires_on": "2026-10-25",
"note": null,
"signer_person_id": "p2",
"signer_name": "Rita Lopes",
"signer_title": "Head chef",
"work_email": "maria.silva@acme.pt",
"invite": "start"
},
"pay_hidden": false,
"range": {
"min": 18000,
"max": 22000,
"currency": "EUR",
"period": "year"
},
"range_check": "above",
"approval": {
"reason": "above_range",
"approvers": "hr",
"state": "approved",
"asked_at": "2026-10-18T09:10:00.000Z",
"decided": {
"at": "2026-10-18T10:00:00.000Z",
"by": {
"id": "p1",
"name": "Ana Costa"
},
"comment": null,
"automatic": false
},
"can_decide": false
},
"approval_context": null,
"proposed_by": {
"id": "p2",
"name": "Rita Lopes"
},
"sent": {
"at": "2026-10-18T10:05:00.000Z",
"expires_at": "2026-10-25T23:00:00.000Z",
"reminded": false
},
"acceptance": null,
"declined": null,
"withdrawn": null,
"expired_at": null,
"hire": {
"person_id": null,
"failed": null,
"finish": false,
"in_documents": false
},
"files": {
"letter": {
"url": "https://storage.example/ofr_o1?sig=x"
},
"signed": null
},
"questions": 0,
"kind": "hire",
"transfer": null,
"created_at": "2026-10-18T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z"
},
{
"id": "o0",
"version": 1,
"supersedes": null,
"application_id": "a1",
"job_id": "j1",
"candidate": {
"id": "c1",
"name": "Maria Silva"
},
"status": "declined",
"language": "en",
"letter_kind": "permanent",
"terms": {
"title": "Line cook",
"legal_entity_id": "e1",
"employer": "Acme Lda",
"employer_country": "PT",
"unit_id": "u1",
"location_id": "l1",
"manager_id": "p2",
"position_id": "pos1",
"place": "Braga kitchen, Braga",
"start_date": "2026-12-01",
"contract_type": "permanent",
"end_date": null,
"probation": {
"value": 90,
"unit": "days"
},
"weekly_hours": 40,
"pay": {
"amount": 1500,
"currency": "EUR",
"period": "month",
"payments_per_year": 14
},
"benefits": "Meals on shift.",
"benefit_ids": [],
"benefit_lines": [],
"expires_on": "2026-10-25",
"note": null,
"signer_person_id": "p2",
"signer_name": "Rita Lopes",
"signer_title": "Head chef",
"work_email": "maria.silva@acme.pt",
"invite": "start"
},
"pay_hidden": false,
"range": {
"min": 18000,
"max": 22000,
"currency": "EUR",
"period": "year"
},
"range_check": "within",
"approval": null,
"approval_context": null,
"proposed_by": {
"id": "p2",
"name": "Rita Lopes"
},
"sent": null,
"acceptance": null,
"declined": {
"at": "2026-10-10T09:00:00.000Z",
"reason": "I took another job.",
"kind": "other_offer"
},
"withdrawn": null,
"expired_at": null,
"hire": {
"person_id": null,
"failed": null,
"finish": false,
"in_documents": false
},
"files": {
"letter": null,
"signed": null
},
"questions": 0,
"kind": "hire",
"transfer": null,
"created_at": "2026-10-18T09:00:00.000Z",
"updated_at": "2026-10-18T09:00:00.000Z"
}
],
"total": 2
}
}Benefits an offer can name#
POST/v1/hiring/offers.benefitsRead
For an offer you may see: the catalogue benefits everyone at its legal entity gets (names, who pays, amount per unit) and the flexible budget, to name on the letter (benefit_ids in hiring_offers_update). Empty when Benefits is off or no legal entity is set. Owners, admins and HR any job; a job's hiring manager their own; in the app.
- Who can call it
- Manage key any Manage role
- MCP tool
hiring_offers_benefitson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
offer_idstringrequired1–100 characters.
Returns
itemsobject[]required7 fields
idstringrequirednamestringrequiredfunding"employer" | "flex" | "sacrifice" | "employee"requiredamount_centsintegerrequiredunit"day" | "month" | "year"requiredfor_everyonebooleanrequiredwait_daysintegerrequired
flexible_budgetobject | nullrequired2 fields
budget_centsintegerrequiredperiod"month" | "year"required
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/offers.benefits \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"offer_id":"o1"}'const res = await fetch('https://api.bizisy.com/v1/hiring/offers.benefits', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"offer_id": "o1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/offers.benefits",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"offer_id": "o1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"items": [
{
"id": "b1",
"name": "Meal allowance on a meal card",
"funding": "employer",
"amount_cents": 1046,
"unit": "day",
"for_everyone": true,
"wait_days": 0
}
],
"flexible_budget": {
"budget_cents": 180000,
"period": "year"
}
}
}List offer letters#
POST/v1/hiring/letters.listRead
Settings → Hiring → Offer letters: the letter for each language (en, pt, es, fr, de) and contract kind (permanent; fixed_term, also used for temporary and internship contracts), whether it is the company's own (custom) or Bizisy's, and the placeholders a letter may use. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
hiring_letters_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
lettersobject[]required7 fields
language"en" | "pt" | "es" | "fr" | "de"requiredkind"permanent" | "fixed_term"requiredtitlestringrequiredbodystringrequiredcustombooleanrequiredThe company's own letter (false: Bizisy's).
updated_atstring | nullrequiredpending_approvalbooleanWith Documents on and approval required to publish templates: the change waits for an approver (the letter in use stays the published one).
placeholdersstring[]requiredtemplatesobject | nullWith the Documents module on: the company's offer-letter template per kind (null id: none yet, Bizisy's letters are used); edit them in Settings → Documents → Templates. null when Documents is off.
2 fields
permanentobjectrequired2 fields
idstring | nullrequiredpending_approvalbooleanrequired
fixed_termobjectrequired2 fields
idstring | nullrequiredpending_approvalbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/letters.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/hiring/letters.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/letters.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"letters": [
{
"language": "en",
"kind": "permanent",
"title": "Offer of employment",
"body": "Dear {{candidate_name}},\n\nWe are pleased to offer you the position of {{job_title}} with {{employer}}.\n\n- Start date: {{start_date}}\n- Pay: {{pay}}\n\nKind regards,\n{{signer_name}}",
"custom": true,
"updated_at": "2026-10-18T09:00:00.000Z"
},
{
"language": "en",
"kind": "fixed_term",
"title": "Offer of employment",
"body": "Dear {{candidate_name}},\n\nWe are pleased to offer you the position of {{job_title}} with {{employer}}.\n\n- Start date: {{start_date}}\n- Pay: {{pay}}\n\nKind regards,\n{{signer_name}}",
"custom": false,
"updated_at": null
}
],
"placeholders": [
"candidate_name",
"job_title",
"employer",
"start_date",
"contract",
"end_date",
"probation",
"hours",
"place",
"pay",
"benefits",
"expires_on",
"signer_name",
"signer_title",
"company"
],
"templates": {
"permanent": {
"id": "tpl_offer",
"pending_approval": false
},
"fixed_term": {
"id": null,
"pending_approval": false
}
}
}
}Get an offer letter#
POST/v1/hiring/letters.getRead
One offer letter (language, kind): its title and body (paragraphs separated by a blank line; lines starting with "- " make a list, "Label: value" lines show the label in bold), whether it is the company's own, and Bizisy's default to compare or go back to. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
hiring_letters_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
language"en" | "pt" | "es" | "fr" | "de"requiredkind"permanent" | "fixed_term"requiredpermanent (also freelance), or fixed_term (also temporary and internship contracts).
Returns
9 fields
language"en" | "pt" | "es" | "fr" | "de"requiredkind"permanent" | "fixed_term"requiredtitlestringrequiredbodystringrequiredcustombooleanrequiredThe company's own letter (false: Bizisy's).
updated_atstring | nullrequiredpending_approvalbooleanWith Documents on and approval required to publish templates: the change waits for an approver (the letter in use stays the published one).
defaultobjectrequired2 fields
titlestringrequiredbodystringrequired
placeholdersstring[]required
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/letters.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"language":"pt","kind":"permanent"}'const res = await fetch('https://api.bizisy.com/v1/hiring/letters.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"language": "pt",
"kind": "permanent"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/letters.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"language": "pt",
"kind": "permanent",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"language": "pt",
"kind": "permanent",
"title": "Offer of employment",
"body": "Dear {{candidate_name}},\n\nWe are pleased to offer you the position of {{job_title}} with {{employer}}.\n\n- Start date: {{start_date}}\n- Pay: {{pay}}\n\nKind regards,\n{{signer_name}}",
"custom": true,
"updated_at": "2026-10-18T09:00:00.000Z",
"default": {
"title": "Offer of employment",
"body": "Dear {{candidate_name}},\n\nWe are pleased to offer you the position of {{job_title}} with {{employer}}.\n\n- Start date: {{start_date}}\n- Pay: {{pay}}\n\nKind regards,\n{{signer_name}}"
},
"placeholders": [
"candidate_name",
"job_title",
"employer",
"start_date",
"contract",
"end_date",
"probation",
"hours",
"place",
"pay",
"benefits",
"expires_on",
"signer_name",
"signer_title",
"company"
]
}
}Change an offer letter#
POST/v1/hiring/letters.updateWrite
Saves the company's own offer letter for a language and contract kind: title (≤ 120 characters) and body (≤ 10,000); placeholders {{name}} from {{candidate_name}} {{job_title}} {{employer}} {{employer_address}} {{start_date}} {{contract}} {{end_date}} {{probation}} {{hours}} {{place}} {{pay}} {{benefits}} {{expires_on}} {{signer_name}} {{signer_title}} {{company}} (any other is refused). Offers sent from now use it; sent ones keep their letter. Keep it legally neutral: the employment contract carries the full terms. Owners, admins and HR, signed in to Bizisy: refused over an API key or MCP (an AI may draft the text for the user to paste).
- Web app only
- Refused for API keys and connected apps. Offer letters change in the app only (Settings → Hiring → Offer letters); machines may draft the text.
- MCP tool
hiring_letters_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
language"en" | "pt" | "es" | "fr" | "de"requiredkind"permanent" | "fixed_term"requiredpermanent (also freelance), or fixed_term (also temporary and internship contracts).
titlestringrequired1–120 characters.
bodystringrequired1–10000 characters.
Returns
7 fields
language"en" | "pt" | "es" | "fr" | "de"requiredkind"permanent" | "fixed_term"requiredtitlestringrequiredbodystringrequiredcustombooleanrequiredThe company's own letter (false: Bizisy's).
updated_atstring | nullrequiredpending_approvalbooleanWith Documents on and approval required to publish templates: the change waits for an approver (the letter in use stays the published one).
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/letters.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"language": "en",
"kind": "permanent",
"title": "Offer of employment",
"body": "Dear {{candidate_name}},\n\nWe are pleased to offer you the position of {{job_title}} with {{employer}}.\n\n- Start date: {{start_date}}\n- Pay: {{pay}}\n\nKind regards,\n{{signer_name}}"
}'const res = await fetch('https://api.bizisy.com/v1/hiring/letters.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"language": "en",
"kind": "permanent",
"title": "Offer of employment",
"body": "Dear {{candidate_name}},\n\nWe are pleased to offer you the position of {{job_title}} with {{employer}}.\n\n- Start date: {{start_date}}\n- Pay: {{pay}}\n\nKind regards,\n{{signer_name}}"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/letters.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"language": "en",
"kind": "permanent",
"title": "Offer of employment",
"body": "Dear {{candidate_name}},\n\nWe are pleased to offer you the position of {{job_title}} with {{employer}}.\n\n- Start date: {{start_date}}\n- Pay: {{pay}}\n\nKind regards,\n{{signer_name}}",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"language": "en",
"kind": "permanent",
"title": "Offer of employment",
"body": "Dear {{candidate_name}},\n\nWe are pleased to offer you the position of {{job_title}} with {{employer}}.\n\n- Start date: {{start_date}}\n- Pay: {{pay}}\n\nKind regards,\n{{signer_name}}",
"custom": true,
"updated_at": "2026-10-18T09:00:00.000Z"
}
}Go back to Bizisy's offer letter#
POST/v1/hiring/letters.resetWrite
Deletes the company's own offer letter for a language and contract kind: Bizisy's is used again from the next offer sent. Owners, admins and HR, signed in to Bizisy.
- Web app only
- Refused for API keys and connected apps. Offer letters change in the app only.
- MCP tool
hiring_letters_reseton HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
language"en" | "pt" | "es" | "fr" | "de"requiredkind"permanent" | "fixed_term"requiredpermanent (also freelance), or fixed_term (also temporary and internship contracts).
Returns
7 fields
language"en" | "pt" | "es" | "fr" | "de"requiredkind"permanent" | "fixed_term"requiredtitlestringrequiredbodystringrequiredcustombooleanrequiredThe company's own letter (false: Bizisy's).
updated_atstring | nullrequiredpending_approvalbooleanWith Documents on and approval required to publish templates: the change waits for an approver (the letter in use stays the published one).
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/letters.reset \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"language":"en","kind":"fixed_term"}'const res = await fetch('https://api.bizisy.com/v1/hiring/letters.reset', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"language": "en",
"kind": "fixed_term"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/letters.reset",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"language": "en",
"kind": "fixed_term",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"language": "en",
"kind": "fixed_term",
"title": "Offer of employment",
"body": "Dear {{candidate_name}},\n\nWe are pleased to offer you the position of {{job_title}} with {{employer}}.\n\n- Start date: {{start_date}}\n- Pay: {{pay}}\n\nKind regards,\n{{signer_name}}",
"custom": false,
"updated_at": null
}
}Preview an offer letter#
POST/v1/hiring/letters.previewRead
The PDF a candidate would get (base64), from a letter (language and kind; title and body to preview unsaved text, else the saved one) filled in with an offer's terms (offer_id: one you may see) or sample ones. Unknown placeholders are refused as on save. Owners, admins and HR; a job's hiring manager for their offers (with offer_id). Signed in to Bizisy only: refused over an API key or MCP (rendering a PDF is costly; hiring_letters_get lists the placeholders).
- Who can call it
- Manage key any Manage role
- Keys and apps
- Sample terms only: previews of a real offer stay in the app.
- MCP tool
hiring_letters_previewon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
language"en" | "pt" | "es" | "fr" | "de"kind"permanent" | "fixed_term"permanent (also freelance), or fixed_term (also temporary and internship contracts).
titlestring1–120 characters.
bodystring1–10000 characters.
offer_idstring1–100 characters.
Returns
pdf_base64stringrequiredtitlestringrequiredtextstringrequiredThe letter's text as filled in.
language"en" | "pt" | "es" | "fr" | "de"requiredkind"permanent" | "fixed_term"required
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/letters.preview \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"language": "en",
"kind": "permanent",
"title": "Our offer",
"body": "Dear {{candidate_name}}"
}'const res = await fetch('https://api.bizisy.com/v1/hiring/letters.preview', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"language": "en",
"kind": "permanent",
"title": "Our offer",
"body": "Dear {{candidate_name}}"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/letters.preview",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"language": "en",
"kind": "permanent",
"title": "Our offer",
"body": "Dear {{candidate_name}}",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"pdf_base64": "JVBERi0xLjcK",
"title": "Our offer",
"text": "Dear Joana,\n\nWe are pleased to offer you the position of Line cook with Acme Lda.",
"language": "en",
"kind": "permanent"
}
}The handoff after a hire#
POST/v1/hiring/handoff.getRead
After a candidate is hired (an accepted offer or the hire wizard): what started for the new person — their first day and manager, onboarding checklists (task counts and the next open tasks), the sign-in invite, equipment registered to them (when the equipment register is on), the probation end and the reminder before it, whether 1:1s are on and booked — the welcome page's buddy field and buddy, and how many candidates are still open on the job. can and can.why_not say which last steps the caller may take with hiring_handoff_apply (name a buddy, book a first 1:1, close the job and reply to everyone still open). Owners, admins and HR any job; a job's hiring manager their own (invite, probation and the next tasks only when they are the new person's manager). Refused (conflict) before the hire. Never pay.
- Who can call it
- Manage key any Manage role
- MCP tool
hiring_handoff_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
application_idstringrequired1–100 characters.
Returns
10 fields
application_idstringrequiredjobobjectrequired5 fields
idstringrequiredtitlestringrequiredstatus"draft" | "open" | "paused" | "closed"requiredopen_applicationsintegerrequiredCandidates still in the process for this job (they get "not this time" when the job closes with a reply).
replies_scheduledbooleanrequiredClosed with a reply to everyone still open (it goes out after the reply days).
personobject | nullrequirednull: the person was erased.
5 fields
idstringrequirednamestringrequiredstatus"active" | "pre_hire" | "terminated" | "none"requiredstart_datestring | nullrequiredmanagerobject | nullrequiredTheir manager on their first day.
2 fields
idstringrequirednamestringrequired
onboardingobject | nullrequired6 fields
checklistsintegerrequiredtasksintegerrequireddoneintegerrequiredopenintegerrequiredoverdueintegerrequirednextobject[]requiredThe next open tasks (up to 6); empty for a hiring manager who is not their manager.
3 fields
titlestringrequireddue_datestringrequiredassignee"hr" | "manager" | "person" | "member"required
inviteobject | nullrequiredTheir sign-in invite: signed_in, invited (sent), scheduled (on a day, e.g. their first), not_sent (it could not go: HR checks it on their profile) or none. null for a hiring manager who is not their manager.
2 fields
status"signed_in" | "invited" | "scheduled" | "not_sent" | "none"requiredonstring | nullrequired
equipmentobjectrequired3 fields
onbooleanrequiredThe equipment register is on.
registeredbooleanrequiredThe company has registered equipment.
holdingintegerrequiredItems registered to them.
probationobject | nullrequiredThe probation end and the reminder to HR and the manager lead_days before it (Settings → Reminders); null without one, or for a hiring manager who is not their manager.
2 fields
end_datestringrequiredreminderobjectrequired3 fields
onbooleanrequiredlead_daysintegerrequireddatestring | nullrequired
one_on_oneobjectrequired4 fields
onbooleanrequired1:1s are on (Settings → Modules).
bookedbooleanrequiredseries_idstring | nullrequiredfirst_datestring | nullrequired
buddyobjectrequired3 fields
fieldobject | nullrequiredThe welcome page's buddy field (Settings → Welcome page); null: none chosen.
2 fields
keystringrequiredlabelstringrequired
currentobject | nullrequired2 fields
idstringrequirednamestringrequired
can_setbooleanrequired
canobjectrequired4 fields
buddybooleanrequiredfirst_one_on_onebooleanrequiredclose_jobbooleanrequiredwhy_notobjectrequired3 fields
buddystring | nullrequiredfirst_one_on_onestring | nullrequiredclose_jobstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/handoff.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"application_id":"e1"}'const res = await fetch('https://api.bizisy.com/v1/hiring/handoff.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"application_id": "e1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/handoff.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"application_id": "e1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"application_id": "a1",
"job": {
"id": "j1",
"title": "Line cook",
"status": "closed",
"open_applications": 3,
"replies_scheduled": false
},
"person": {
"id": "p9",
"name": "Maria Silva",
"status": "pre_hire",
"start_date": "2026-12-01",
"manager": {
"id": "p2",
"name": "Rita Lopes"
}
},
"onboarding": {
"checklists": 1,
"tasks": 11,
"done": 2,
"open": 9,
"overdue": 0,
"next": [
{
"title": "Order equipment and accounts",
"due_date": "2026-11-26",
"assignee": "manager"
},
{
"title": "Create their work account",
"due_date": "2026-11-28",
"assignee": "hr"
}
]
},
"invite": {
"status": "scheduled",
"on": "2026-12-01"
},
"equipment": {
"on": true,
"registered": true,
"holding": 0
},
"probation": {
"end_date": "2027-02-28",
"reminder": {
"on": true,
"lead_days": 14,
"date": "2027-02-14"
}
},
"one_on_one": {
"on": true,
"booked": false,
"series_id": null,
"first_date": null
},
"buddy": {
"field": {
"key": "buddy",
"label": "Buddy"
},
"current": null,
"can_set": true
},
"can": {
"buddy": true,
"first_one_on_one": true,
"close_job": true,
"why_not": {
"buddy": null,
"first_one_on_one": null,
"close_job": null
}
}
}
}Finish the handoff after a hire#
POST/v1/hiring/handoff.applyWrite
The last steps after a hire, each optional: buddy_id names the new person's buddy in the welcome page's buddy field (null clears it; a colleague who works here; HR, or their manager for a field of the public or job tier); first_one_on_one true books a monthly 1:1 between them and their manager, the first 2 working days after their start at 10:00 with the agenda "First 1:1 with a new hire" (when 1:1s are on; an existing one is kept); close_job true closes the job as filled (HR), with reply_to_open sending everyone still open the kind "not this time" after the company's reply days. Owners, admins and HR, or the job's hiring manager (not close_job). In the app only (it names people and emails candidates).
- Web app only
- Refused for API keys and connected apps. The handoff after a hire (a buddy, the first 1:1, closing the job with replies) is finished in the app.
- MCP tool
hiring_handoff_applyon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
application_idstringrequired1–100 characters.
buddy_idstring | null1–100 characters.
first_one_on_onebooleanclose_jobbooleanreply_to_openbooleanWith close_job: send everyone still open the kind "not this time".
Returns
doneobjectrequired4 fields
buddybooleanrequiredfirst_one_on_oneobject | nullrequired4 fields
series_idstringrequiredfirst_datestringrequiredtimestring | nullrequiredstartedbooleanrequired
job_closedbooleanrequiredreplies_tointegerrequired
handoffobjectrequired10 fields
application_idstringrequiredjobobjectrequired5 fields
idstringrequiredtitlestringrequiredstatus"draft" | "open" | "paused" | "closed"requiredopen_applicationsintegerrequiredCandidates still in the process for this job (they get "not this time" when the job closes with a reply).
replies_scheduledbooleanrequiredClosed with a reply to everyone still open (it goes out after the reply days).
personobject | nullrequirednull: the person was erased.
5 fields
idstringrequirednamestringrequiredstatus"active" | "pre_hire" | "terminated" | "none"requiredstart_datestring | nullrequiredmanagerobject | nullrequiredTheir manager on their first day.
2 fields
idstringrequirednamestringrequired
onboardingobject | nullrequired6 fields
checklistsintegerrequiredtasksintegerrequireddoneintegerrequiredopenintegerrequiredoverdueintegerrequirednextobject[]requiredThe next open tasks (up to 6); empty for a hiring manager who is not their manager.
3 fields
titlestringrequireddue_datestringrequiredassignee"hr" | "manager" | "person" | "member"required
inviteobject | nullrequiredTheir sign-in invite: signed_in, invited (sent), scheduled (on a day, e.g. their first), not_sent (it could not go: HR checks it on their profile) or none. null for a hiring manager who is not their manager.
2 fields
status"signed_in" | "invited" | "scheduled" | "not_sent" | "none"requiredonstring | nullrequired
equipmentobjectrequired3 fields
onbooleanrequiredThe equipment register is on.
registeredbooleanrequiredThe company has registered equipment.
holdingintegerrequiredItems registered to them.
probationobject | nullrequiredThe probation end and the reminder to HR and the manager lead_days before it (Settings → Reminders); null without one, or for a hiring manager who is not their manager.
2 fields
end_datestringrequiredreminderobjectrequired3 fields
onbooleanrequiredlead_daysintegerrequireddatestring | nullrequired
one_on_oneobjectrequired4 fields
onbooleanrequired1:1s are on (Settings → Modules).
bookedbooleanrequiredseries_idstring | nullrequiredfirst_datestring | nullrequired
buddyobjectrequired3 fields
fieldobject | nullrequiredThe welcome page's buddy field (Settings → Welcome page); null: none chosen.
2 fields
keystringrequiredlabelstringrequired
currentobject | nullrequired2 fields
idstringrequirednamestringrequired
can_setbooleanrequired
canobjectrequired4 fields
buddybooleanrequiredfirst_one_on_onebooleanrequiredclose_jobbooleanrequiredwhy_notobjectrequired3 fields
buddystring | nullrequiredfirst_one_on_onestring | nullrequiredclose_jobstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/handoff.apply \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"application_id": "e1",
"first_one_on_one": true,
"close_job": true,
"reply_to_open": true
}'const res = await fetch('https://api.bizisy.com/v1/hiring/handoff.apply', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"application_id": "e1",
"first_one_on_one": true,
"close_job": true,
"reply_to_open": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/handoff.apply",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"application_id": "e1",
"first_one_on_one": True,
"close_job": True,
"reply_to_open": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"done": {
"buddy": true,
"first_one_on_one": {
"series_id": "org1:p9:p2",
"first_date": "2026-12-03",
"time": "10:00",
"started": true
},
"job_closed": false,
"replies_to": 3
},
"handoff": {
"application_id": "a1",
"job": {
"id": "j1",
"title": "Line cook",
"status": "closed",
"open_applications": 3,
"replies_scheduled": true
},
"person": {
"id": "p9",
"name": "Maria Silva",
"status": "pre_hire",
"start_date": "2026-12-01",
"manager": {
"id": "p2",
"name": "Rita Lopes"
}
},
"onboarding": {
"checklists": 1,
"tasks": 11,
"done": 2,
"open": 9,
"overdue": 0,
"next": [
{
"title": "Order equipment and accounts",
"due_date": "2026-11-26",
"assignee": "manager"
},
{
"title": "Create their work account",
"due_date": "2026-11-28",
"assignee": "hr"
}
]
},
"invite": {
"status": "scheduled",
"on": "2026-12-01"
},
"equipment": {
"on": true,
"registered": true,
"holding": 0
},
"probation": {
"end_date": "2027-02-28",
"reminder": {
"on": true,
"lead_days": 14,
"date": "2027-02-14"
}
},
"one_on_one": {
"on": true,
"booked": true,
"series_id": "org1:p9:p2",
"first_date": "2026-12-03"
},
"buddy": {
"field": {
"key": "buddy",
"label": "Buddy"
},
"current": {
"id": "p4",
"name": "Ivo Matos"
},
"can_set": true
},
"can": {
"buddy": true,
"first_one_on_one": false,
"close_job": false,
"why_not": {
"buddy": null,
"first_one_on_one": "A 1:1 with their manager is already set up.",
"close_job": "The job is closed."
}
}
}
}
}Hiring report#
POST/v1/hiring/reports.overviewRead
How hiring is going over a period (last_90_days by default, this_year, or custom from/to up to 2 years; days in the company's time zone): applicants and hires (including candidates whose data retention has since deleted: applicants_deleted), the median days to hire (applying → accepting the offer, or → the hire without one), answered on time (the first answer by the date promised), offers sent, accepted, declined (with the reasons candidates picked, never their words) and expired with the acceptance rate, sources (careers page, each job site reading the feed, coworkers' shares, referrals, the talent pool, added by HR) with applicants and hires, the median days candidates spent in New, each kind of step and Offer, and a line per job (applicants, interviewed, hires, time to hire, days open, answered on time, offers, its steps). Owners, admins and HR see every job; a hiring manager the jobs they hire for. Never candidates' names. Use it to summarise how hiring goes and where candidates wait longest; never to judge candidates.
- Who can call it
- Manage key any Manage role
- MCP tool
hiring_reports_overviewon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
period"last_90_days" | "this_year" | "custom"last_90_days (default: the 90 days up to today), this_year (from 1 January) or custom (from and to, at most 2 years).
Default
"last_90_days".fromstringcustom: the first day (YYYY-MM-DD).
Pattern
^\d{4}-\d{2}-\d{2}$.tostringcustom: the last day (YYYY-MM-DD).
Pattern
^\d{4}-\d{2}-\d{2}$.
Returns
periodobjectrequired4 fields
kind"last_90_days" | "this_year" | "custom"requiredfromstringrequiredtostringrequiredtimezonestringrequired
scope"all_jobs" | "my_jobs"requiredall_jobs (owners, admins and HR) or my_jobs (a hiring manager: the jobs they hire for).
summaryobjectrequired8 fields
applicantsintegerrequiredApplications received or added in the period (including those whose data retention has since deleted).
applicants_deletedintegerrequiredOf those, how many retention deleted (counted here only; not in sources, times or steps).
hiresintegerrequiredPeople hired in the period from Hiring (including deleted candidates' records).
time_to_hire_daysnumber | nullrequiredMedian days from applying to accepting the offer (or to the hire without an offer), one decimal.
time_to_hire_hiresintegerrequiredHires the median is over (those Bizisy still keeps).
answered_on_timeobjectrequired3 fields
dueintegerrequiredApplicants of the period whose first answer was due (answered, or the date passed unanswered).
on_timeintegerrequiredAnswered (moved, written to, interviewed, told "not this time" or hired) by the date promised.
pctnumber | nullrequiredon_time / due as a whole percentage; null when nothing was due.
offersobjectrequired6 fields
sentintegerrequiredOffers sent in the period (a revised offer counts once).
acceptedintegerrequireddeclinedintegerrequiredexpiredintegerrequiredacceptance_pctnumber | nullrequiredaccepted / (accepted + declined + expired) as a whole percentage; null when none was answered or ended.
decline_reasonsobject[]requiredThe reasons candidates picked when declining (never their words).
2 fields
reasonstring (enum)requiredOne of:
pay,other_offer,role,location,start_date,personal,other,not_given.countintegerrequired
open_jobsintegerrequiredJobs open today.
sourcesobject[]required4 fields
sourcestring (enum)requiredcareers (the careers page), job_site (a site reading the job feed: site), share (a coworker's share link), referral, talent_pool, manual (added by HR).
One of:
careers,share,referral,job_site,talent_pool,manual,internal.sitestring | nullrequiredapplicantsintegerrequiredhiresintegerrequired
stepsobject[]requiredAcross the jobs: New, each kind of step (a job's steps grouped by kind), Offer.
3 fields
keystring (enum)requirednew, a step kind (call, interview, panel, task, trial, presentation, references, final) or offer.
One of:
new,call,interview,panel,task,trial,presentation,references,final,offer.median_daysnumber | nullrequiredThe median days candidates spent there (one decimal); null when nobody left it in the period.
staysintegerrequiredHow many times candidates left it in the period (the median is over these).
jobsobject[]required13 fields
idstringrequiredtitlestringrequiredstatus"draft" | "open" | "paused" | "closed"requiredopened_onstring | nullrequiredclosed_onstring | nullrequireddays_openinteger | nullrequiredDays from opening to closing (or today while open); null for a job never opened.
applicantsintegerrequiredinterviewedintegerrequiredApplicants of the period who moved past New (to a step, the offer or hired).
hiresintegerrequiredtime_to_hire_daysnumber | nullrequiredThe median days to hire of its hires in the period; null without one.
answered_on_time_pctnumber | nullrequiredoffersobjectrequired3 fields
sentintegerrequiredacceptedintegerrequireddeclinedintegerrequired
stepsobject[]required5 fields
keystringrequirednew, offer, or the step's id.
median_daysnumber | nullrequiredThe median days candidates spent there (one decimal); null when nobody left it in the period.
staysintegerrequiredHow many times candidates left it in the period (the median is over these).
namestring | nullrequiredThe step's name (null for New and Offer).
kindstring (enum)requiredOne of:
new,call,interview,panel,task,trial,presentation,references,final,offer.
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/reports.overview \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"period":"custom","from":"2026-01-01","to":"2026-06-30"}'const res = await fetch('https://api.bizisy.com/v1/hiring/reports.overview', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"period": "custom",
"from": "2026-01-01",
"to": "2026-06-30"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/reports.overview",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"period": "custom",
"from": "2026-01-01",
"to": "2026-06-30",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"period": {
"kind": "last_90_days",
"from": "2026-07-21",
"to": "2026-10-18",
"timezone": "Europe/Lisbon"
},
"scope": "all_jobs",
"summary": {
"applicants": 64,
"applicants_deleted": 12,
"hires": 3,
"time_to_hire_days": 24.5,
"time_to_hire_hires": 3,
"answered_on_time": {
"due": 52,
"on_time": 47,
"pct": 90
},
"offers": {
"sent": 4,
"accepted": 3,
"declined": 1,
"expired": 0,
"acceptance_pct": 75,
"decline_reasons": [
{
"reason": "other_offer",
"count": 1
}
]
},
"open_jobs": 2
},
"sources": [
{
"source": "careers",
"site": null,
"applicants": 30,
"hires": 1
},
{
"source": "job_site",
"site": "indeed",
"applicants": 18,
"hires": 1
},
{
"source": "share",
"site": null,
"applicants": 9,
"hires": 0
},
{
"source": "referral",
"site": null,
"applicants": 4,
"hires": 1
},
{
"source": "manual",
"site": null,
"applicants": 3,
"hires": 0
}
],
"steps": [
{
"key": "new",
"median_days": 2.5,
"stays": 50
},
{
"key": "call",
"median_days": 4,
"stays": 20
},
{
"key": "trial",
"median_days": 6.5,
"stays": 8
},
{
"key": "offer",
"median_days": 3,
"stays": 4
}
],
"jobs": [
{
"id": "j1",
"title": "Line cook",
"status": "closed",
"opened_on": "2026-08-03",
"closed_on": "2026-10-02",
"days_open": 60,
"applicants": 40,
"interviewed": 12,
"hires": 2,
"time_to_hire_days": 22,
"answered_on_time_pct": 92,
"offers": {
"sent": 3,
"accepted": 2,
"declined": 1
},
"steps": [
{
"key": "new",
"name": null,
"kind": "new",
"median_days": 2,
"stays": 35
},
{
"key": "trial",
"name": "Trial shift",
"kind": "trial",
"median_days": 6.5,
"stays": 8
},
{
"key": "offer",
"name": null,
"kind": "offer",
"median_days": 3,
"stays": 3
}
]
}
]
}
}Download the hiring report#
POST/v1/hiring/reports.exportRead
The hiring report as a CSV file (the same period and figures as hiring_reports_overview: the summary, decline reasons, sources, steps, then a line per job), headers in lang (en, pt, es, fr, de; default the company's). Owners, admins and HR. Never candidates' names.
- Who can call it
- Manage key owner admin hr
- MCP tool
hiring_reports_exporton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
period"last_90_days" | "this_year" | "custom"last_90_days (default: the 90 days up to today), this_year (from 1 January) or custom (from and to, at most 2 years).
Default
"last_90_days".fromstringcustom: the first day (YYYY-MM-DD).
Pattern
^\d{4}-\d{2}-\d{2}$.tostringcustom: the last day (YYYY-MM-DD).
Pattern
^\d{4}-\d{2}-\d{2}$.lang"en" | "pt" | "es" | "fr" | "de"
Returns
fileobjectrequired6 fields
namestringrequiredcontent_typestringrequiredencoding"utf8" | "base64"requiredcontentstringrequiredbytesintegerrequiredsha256stringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/reports.export \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"period":"this_year","lang":"pt"}'const res = await fetch('https://api.bizisy.com/v1/hiring/reports.export', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"period": "this_year",
"lang": "pt"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/reports.export",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"period": "this_year",
"lang": "pt",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"file": {
"name": "hiring-report-2026-07-21-2026-10-18.csv",
"content_type": "text/csv; charset=utf-8",
"encoding": "utf8",
"content": "Hiring report,2026-07-21 – 2026-10-18\r\nApplicants,64\r\n",
"bytes": 58,
"sha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
}
}
}Apply for a job inside the company (form)#
POST/v1/hiring/internal.apply_formRead
What the apply form shows for an open job (spec 2026-11-13-internal-mobility D4, D5, D7): your name, work email and current job (pre-filled), the job's questions except those for outside candidates only (the right to work…: you work here), whether you can apply now (blocked: why — min_months, probation, hiring_manager, view_only, limit or off — and from when), and when your manager is told: rule (on_apply, on_interview, on_offer, at_transfer), your manager, why earlier when it is (hiring_team: they are on the job's hiring team), and the sentence the form says. The person themselves, in My workspace.
- Who can call it
- Me key anyone
- MCP tool
hiring_internal_apply_formon My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
job_idstringrequired1–100 characters.
Returns
7 fields
jobobjectrequired5 fields
idstringrequiredtitlestringrequiredaudience"public" | "internal_first" | "internal_only"requiredanswer_daysintegerrequiredquestionsobject[]required5 fields
idstringrequiredtextstringrequiredkind"text" | "yes_no" | "choice"requiredoptionsstring[]requiredbooleanrequired
meobject | nullrequired4 fields
namestringrequiredwork_emailstringrequiredtitlestring | nullrequiredunitstring | nullrequired
blockedobject | nullrequired4 fields
rule"min_months" | "probation" | "hiring_manager" | "view_only" | "limit" | "off"requireduntilstring | nullrequiredmonthsintegermaxinteger
noticeobjectrequired5 fields
rule"on_apply" | "on_interview" | "on_offer" | "at_transfer"requiredmanagerobject | nullrequired2 fields
idstringrequirednamestringrequired
why"rule" | "hiring_team" | "approval"requiredtold_nowbooleanrequiredsentencestringrequired
nudge_manager_talkbooleanrequiredalreadystring | nullrequiredYour live application to this job, if any (one per job).
max_noteintegerrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/internal.apply_form \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"job_id":"j1"}'const res = await fetch('https://api.bizisy.com/v1/hiring/internal.apply_form', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"job_id": "j1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/internal.apply_form",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"job_id": "j1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"job": {
"id": "j1",
"title": "Team lead",
"audience": "internal_only",
"answer_days": 5,
"questions": [
{
"id": "weekends",
"text": "Can you work weekend shifts?",
"kind": "yes_no",
"required": false
}
]
},
"me": {
"name": "Rita Lopes",
"work_email": "rita@acme.pt",
"title": "Customer care agent",
"unit": "Customer care"
},
"blocked": null,
"notice": {
"rule": "on_interview",
"manager": {
"id": "p1",
"name": "Ana Costa"
},
"why": null,
"told_now": false,
"sentence": "Ana Costa, your manager, will be told if you're invited to an interview. Until then, only HR and the hiring team see your application."
},
"nudge_manager_talk": true,
"already": null,
"max_note": 1000
}
}Apply for a job inside the company#
POST/v1/hiring/internal.applyWrite
Applies for an open job as someone who works here (spec 2026-11-13-internal-mobility D7): the job's questions (answers), and an optional "Why this job?" note (≤ 1000 characters, read by HR and the hiring team). Your name, work email and current job come from People; no pay expectation is asked. One live application per job; at most the company's limit of live internal applications (default 5) and 3 a day. Refused when the company's rules block it (minimum months in your job, probation: the error says from when). Returns the date the company answers by and when your manager is told (notice.sentence). Your manager learns nothing before then; withdrawing before then means they never learn. The person themselves, signed in to Bizisy: refused over an API key or MCP (an AI never applies for a person).
- Web app only
- Refused for API keys and connected apps. People apply for jobs inside the company themselves, in My workspace; an AI never applies for them.
- MCP tool
hiring_internal_applyon My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
job_idstringrequired1–100 characters.
answersobject[]Up to 5 items.
2 fields
question_idstringrequired1–40 characters.
answerstringrequiredUp to 500 characters.
notestringUp to 1000 characters.
cv_file_idstringAn optional CV uploaded with hiring_internal_cv_upload_url.
1–100 characters.
Returns
application_idstringrequiredanswer_bystringrequirednoticeobjectrequired5 fields
rule"on_apply" | "on_interview" | "on_offer" | "at_transfer"requiredmanagerobject | nullrequired2 fields
idstringrequirednamestringrequired
why"rule" | "hiring_team" | "approval"requiredtold_nowbooleanrequiredsentencestringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/internal.apply \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"job_id": "j1",
"answers": [
{
"question_id": "right_to_work",
"answer": "yes"
}
],
"note": "I have led the weekend shift for a year."
}'const res = await fetch('https://api.bizisy.com/v1/hiring/internal.apply', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"job_id": "j1",
"answers": [
{
"question_id": "right_to_work",
"answer": "yes"
}
],
"note": "I have led the weekend shift for a year."
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/internal.apply",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"job_id": "j1",
"answers": [
{
"question_id": "right_to_work",
"answer": "yes",
},
],
"note": "I have led the weekend shift for a year.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"application_id": "a9",
"answer_by": "2026-11-17",
"notice": {
"rule": "on_interview",
"manager": {
"id": "p1",
"name": "Ana Costa"
},
"why": null,
"told_now": false,
"sentence": "Ana Costa, your manager, will be told if you're invited to an interview. Until then, only HR and the hiring team see your application."
}
}
}My applications inside the company#
POST/v1/hiring/internal.mineRead
Your internal applications (My workspace → Jobs → My applications): the job, a stage word (applied, interviewing, offer, moved, not_this_time, withdrawn, closed), when you applied, the date the company answers by, your note, whether you can still withdraw, and an offer sent to you (its terms; the new pay when it changes; whether it waits for approval). Never notes, feedback or other candidates. The person themselves.
- Who can call it
- Me key anyone
- MCP tool
hiring_internal_mineon My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
applicationsobject[]required9 fields
idstringrequiredjobobjectrequired4 fields
idstringrequiredtitlestringrequiredunitstring | nullrequiredlocationstring | nullrequired
stagestring (enum)requiredOne of:
applied,interviewing,offer,moved,not_this_time,withdrawn,closed.applied_atstringrequiredupdated_atstringrequiredanswer_bystring | nullrequirednotestring | nullrequiredcan_withdrawbooleanrequiredofferobject | nullrequired11 fields
idstringrequiredstatus"sent" | "accepted_pending_hire" | "accepted" | "declined" | "expired" | "withdrawn"requiredtitlestringrequiredteamstring | nullrequiredplacestring | nullrequiredstart_datestringrequiredexpires_onstringrequiredweekly_hoursnumber | nullrequiredpayobject | nullrequiredThe new pay when the offer changes it (only you, HR and approvers see it).
3 fields
amountnumberrequiredcurrencystringrequiredperiodstringrequired
notestring | nullrequiredtransfer"none" | "waiting" | "approved" | "applied" | "rejected" | "cancelled"requiredwaiting: accepted, waiting for approval; applied/approved: agreed.
enabledbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/internal.mine \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/hiring/internal.mine', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/internal.mine",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"applications": [
{
"id": "a9",
"job": {
"id": "j1",
"title": "Team lead",
"unit": "Customer care",
"location": "Porto"
},
"stage": "offer",
"applied_at": "2026-11-02T09:00:00.000Z",
"updated_at": "2026-11-10T09:00:00.000Z",
"answer_by": "2026-11-17",
"note": "I have led the weekend shift for a year.",
"can_withdraw": true,
"offer": {
"id": "o9",
"status": "sent",
"title": "Team lead",
"team": "Customer care",
"place": "Porto office",
"start_date": "2026-12-01",
"expires_on": "2026-11-20",
"weekly_hours": 40,
"pay": null,
"note": null,
"transfer": "none"
}
}
],
"enabled": true
}
}Withdraw my application inside the company#
POST/v1/hiring/internal.withdrawWrite
Withdraws one of your internal applications before the move is agreed: you leave the job's process at once, interviews to come are cancelled (the interviewers are told), an offer not yet accepted ends, and the hiring team sees "withdrawn". Your manager learns about it only if they had already been told you applied. It stays in My applications as withdrawn for 30 days, then it is deleted. The person themselves, signed in to Bizisy.
- Web app only
- Refused for API keys and connected apps. The person withdraws in My workspace.
- MCP tool
hiring_internal_withdrawon My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
application_idstringrequired1–100 characters.
Returns
application_idstringrequiredstage"withdrawn"required
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/internal.withdraw \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"application_id":"a9"}'const res = await fetch('https://api.bizisy.com/v1/hiring/internal.withdraw', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"application_id": "a9"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/internal.withdraw",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"application_id": "a9",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"application_id": "a9",
"stage": "withdrawn"
}
}My team's applications inside the company#
POST/v1/hiring/internal.manager_viewRead
For managers (My team): the internal applications of people who report to you, but only once the company's rule says you are told (spec 2026-11-13-internal-mobility D5) — before that, nothing, not even a count. Per application: the person, the job and a stage word (applied, interviewing, offer, moved, not_this_time, withdrawn, closed). Never notes, feedback, scorecards or other candidates.
- Who can call it
- Me key anyone
- MCP tool
hiring_internal_manager_viewon My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
applicationsobject[]required5 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
job_titlestringrequiredstagestring (enum)requiredOne of:
applied,interviewing,offer,moved,not_this_time,withdrawn,closed.told_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/internal.manager_view \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/hiring/internal.manager_view', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/internal.manager_view",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"applications": [
{
"id": "a9",
"person": {
"id": "p9",
"name": "Rita Lopes"
},
"job_title": "Team lead",
"stage": "interviewing",
"told_at": "2026-11-05T09:00:00.000Z"
}
]
}
}Upload a CV to apply inside the company#
POST/v1/hiring/internal.cv_upload_urlWrite
Starts the upload of an optional CV for an internal application (hiring_internal_apply with cv_file_id): PDF, Word (DOCX) or a picture (JPG, PNG, HEIC), at most 10 MB; a signed upload (PUT the bytes within 15 minutes, exactly that size and type), checked by content when you apply; an upload never used is deleted within the hour. For an open job you can apply for from My workspace; at most 10 uploads a day. The person themselves, signed in to Bizisy.
- Web app only
- Refused for API keys and connected apps. The person uploads their CV in My workspace when they apply.
- MCP tool
hiring_internal_cv_upload_urlon My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
job_idstringrequired1–100 characters.
namestringrequired1–200 characters.
sizeintegerrequiredFrom 1 to 10000000.
content_type"application/pdf" | "application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "image/jpeg" | "image/png" | "image/heic"requiredsha256stringrequiredPattern
^[0-9a-f]{64}$.
Returns
file_idstringrequireduploadobject | nullrequired4 fields
urlstringrequiredmethod"PUT"requiredheadersobjectrequiredresumablefalserequired
expires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/internal.cv_upload_url \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"job_id": "j1",
"name": "cv.pdf",
"size": 12000,
"content_type": "application/pdf",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}'const res = await fetch('https://api.bizisy.com/v1/hiring/internal.cv_upload_url', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"job_id": "j1",
"name": "cv.pdf",
"size": 12000,
"content_type": "application/pdf",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/internal.cv_upload_url",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"job_id": "j1",
"name": "cv.pdf",
"size": 12000,
"content_type": "application/pdf",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"file_id": "f9",
"upload": {
"url": "https://storage.example/up/f9",
"method": "PUT",
"headers": {
"content-type": "application/pdf"
},
"resumable": false
},
"expires_at": "2026-11-12T09:15:00.000Z"
}
}Accept my offer for a job inside the company#
POST/v1/hiring/offers.accept_internalWrite
Accepts a transfer offer sent to you (accept true): your acceptance is recorded (when, the letter's fingerprint), the hiring team is told, and your job change follows under the company's approval rules — at once when no approval is needed, else once approved (My applications shows "Waiting for approval"). The person themselves, signed in to Bizisy: refused over an API key or MCP.
- Web app only
- Refused for API keys and connected apps. The person accepts their offer in My workspace.
- MCP tool
hiring_offers_accept_internalon My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
offer_idstringrequired1–100 characters.
accepttruerequired
Returns
state"accepted"requiredaccepted_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/offers.accept_internal \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"offer_id":"o9","accept":true}'const res = await fetch('https://api.bizisy.com/v1/hiring/offers.accept_internal', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"offer_id": "o9",
"accept": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/offers.accept_internal",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"offer_id": "o9",
"accept": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"state": "accepted",
"accepted_at": "2026-11-12T09:00:00.000Z"
}
}Decline my offer for a job inside the company#
POST/v1/hiring/offers.decline_internalWrite
Declines a transfer offer sent to you, with an optional reason (kind: pay, other_offer, role, location, start_date, personal, other; text ≤ 500 characters, read by the hiring team). Your job stays as it is; your manager learns nothing new. The person themselves, signed in to Bizisy.
- Web app only
- Refused for API keys and connected apps. The person declines their offer in My workspace.
- MCP tool
hiring_offers_decline_internalon My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
offer_idstringrequired1–100 characters.
kindstring (enum)One of:
pay,other_offer,role,location,start_date,personal,other.reasonstringUp to 500 characters.
Returns
state"declined"required
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/offers.decline_internal \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"offer_id":"o9","kind":"role"}'const res = await fetch('https://api.bizisy.com/v1/hiring/offers.decline_internal', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"offer_id": "o9",
"kind": "role"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/offers.decline_internal",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"offer_id": "o9",
"kind": "role",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"state": "declined"
}
}Finish an internal move#
POST/v1/hiring/offers.finish_transferWrite
For an accepted offer to someone who works here whose job change did not happen by itself, or was not approved: runs the job change again as you (org.people.transfer_internal), under Settings → Approval rules — applied at once, or a new request for approval. Refused for a move to another legal entity or a person whose last day is recorded (do it by hand in People). Owners, admins and HR, signed in to Bizisy.
- Web app only
- Refused for API keys and connected apps. HR finishes an internal move in the Bizisy app.
- MCP tool
hiring_offers_finish_transferon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
offer_idstringrequired1–100 characters.
Returns
state"applied" | "waiting"required
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/hiring/offers.finish_transfer \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"offer_id":"o9"}'const res = await fetch('https://api.bizisy.com/v1/hiring/offers.finish_transfer', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"offer_id": "o9"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/hiring/offers.finish_transfer",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"offer_id": "o9",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"state": "waiting"
}
}Something missing or wrong on this page? Write to hello@bizisy.com.