Skip to content

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_list on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • status"live" | "draft" | "open" | "paused" | "closed" | "all"

    Default "live".

  • position_idstring

    1–100 characters.

  • limitinteger

    From 1 to 500. Default 100.

Returns

  • jobsobject[]required
    41 fields
    • idstringrequired
    • position_idstringrequired
    • slugstringrequired
    • status"draft" | "open" | "paused" | "closed"required
    • titlestringrequired
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • locationobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • citystring | nullrequired
      • countrystringrequired
    • workplace"on_site" | "hybrid" | "remote"required
    • countrystring | nullrequired
    • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
    • weekly_hoursnumber | nullrequired
    • employment_type"full_time" | "part_time" | "contract" | "temporary" | "internship"required
    • salaryobject | nullrequired

      The range the post shows (from the position's budget or band, or set on the job).

      5 fields
      • minnumberrequired
      • maxnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
      • source"position" | "band" | "job"required
    • salary_hiddenbooleanrequired

      True 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"required
    • postobjectrequired
      4 fields
      • what_you_dostringrequired
      • what_you_needstringrequired
      • what_you_getstringrequired
      • how_it_goesstringrequired
    • processobjectrequired

      What 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
      • promisestringrequired
      • stepsstring[]required
    • stepsobject[]required
      13 fields
      • idstringrequired
      • namestringrequired
      • kindstring (enum)required

        One of: call, interview, panel, task, trial, presentation, references, final.

      • minutesnumber | nullrequired
      • buffer_minutesintegerrequired

        Minutes kept clear after the interview.

      • place"video" | "video_auto" | "phone" | "on_site" | "none"required
      • addressstring | nullrequired

        In person: the address.

      • video_linkstring | nullrequired

        Video (pasted): the meeting link.

      • interviewers_neededintegerrequired
      • poolobjectrequired
        2 fields
        • group_idsstring[]required
        • person_idsstring[]required
      • scorecard_idstring | nullrequired
      • feedback_due_hoursintegerrequired
      • scorecardobject | nullrequired

        What interviewers rate at this step (null: no scorecard, only a recommendation and words).

        2 fields
        • skillsobject[]required
          4 fields
          • idstringrequired
          • namestringrequired
          • promptstring | nullrequired
          • levelsstring[]required

            4–4 items.

        • overall_questionstring | nullrequired
    • template_idstring | nullrequired
    • interviews"in_bizisy" | "outside"required

      How interviews run for this job (its own choice, else the company default).

    • interviews_override"in_bizisy" | "outside"required
    • answer_daysintegerrequired

      Working days to answer each candidate (its own, else the company default).

    • answer_days_overrideinteger | nullrequired
    • free_sitesbooleanrequired
    • audience"public" | "internal_first" | "internal_only"required

      Who 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 | nullrequired

      internal_first: days in Me before it goes public (null: the company default).

    • public_fromstring | nullrequired

      internal_first: when it went (or goes) public; null while internal.

    • listed_publiclybooleanrequired

      Shown on the careers page and the feed now.

    • referral_bonusobjectrequired

      This 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"required
      • amountnumberrequired
      • currencystringrequired
    • hiring_managerobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • questionsobject[]required
      6 fields
      • idstringrequired
      • textstringrequired
      • kind"text" | "yes_no" | "choice"required
      • optionsstring[]
      • requiredbooleanrequired
      • external_onlybooleanrequired

        Shown to outside candidates only, never to people who work here.

    • valid_throughstring | nullrequired
    • careers_pathstringrequired

      Its address on the company's careers page, once open.

    • readyobjectrequired

      Whether it can be opened, and what is missing: title, description (what you'll do), pay_range, gaps (a [[…]] left from the draft).

      2 fields
      • okbooleanrequired
      • missing"title" | "description" | "pay_range" | "gaps"[]required
    • opened_atstring | nullrequired
    • closed_atstring | nullrequired
    • close_reason"filled" | "cancelled" | "other"required
    • close_replyobject | nullrequired

      Closed with "reply to everyone still open": when the kind "not this time" goes out to them.

      1 field
      • send_atstringrequired
    • created_atstringrequired
    • updated_atstringrequired
    • pipelineobjectrequired
      7 fields
      • newintegerrequired

        Candidates in New, not answered yet.

      • in_stepsintegerrequired

        Candidates in one of the job's steps.

      • offerintegerrequired
      • hiredintegerrequired
      • not_this_timeintegerrequired

        Told (or about to be told) "not this time".

      • overdueintegerrequired

        Still open and past the answer promise.

      • appliedintegerrequired

        Everyone who applied or was added, withdrawn ones included.

  • totalintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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}'
Response
{
  "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_get on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • job_idstringrequired

    1–100 characters.

Returns

41 fields
  • idstringrequired
  • position_idstringrequired
  • slugstringrequired
  • status"draft" | "open" | "paused" | "closed"required
  • titlestringrequired
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • locationobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • citystring | nullrequired
    • countrystringrequired
  • workplace"on_site" | "hybrid" | "remote"required
  • countrystring | nullrequired
  • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
  • weekly_hoursnumber | nullrequired
  • employment_type"full_time" | "part_time" | "contract" | "temporary" | "internship"required
  • salaryobject | nullrequired

    The range the post shows (from the position's budget or band, or set on the job).

    5 fields
    • minnumberrequired
    • maxnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
    • source"position" | "band" | "job"required
  • salary_hiddenbooleanrequired

    True 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"required
  • postobjectrequired
    4 fields
    • what_you_dostringrequired
    • what_you_needstringrequired
    • what_you_getstringrequired
    • how_it_goesstringrequired
  • processobjectrequired

    What 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
    • promisestringrequired
    • stepsstring[]required
  • stepsobject[]required
    13 fields
    • idstringrequired
    • namestringrequired
    • kindstring (enum)required

      One of: call, interview, panel, task, trial, presentation, references, final.

    • minutesnumber | nullrequired
    • buffer_minutesintegerrequired

      Minutes kept clear after the interview.

    • place"video" | "video_auto" | "phone" | "on_site" | "none"required
    • addressstring | nullrequired

      In person: the address.

    • video_linkstring | nullrequired

      Video (pasted): the meeting link.

    • interviewers_neededintegerrequired
    • poolobjectrequired
      2 fields
      • group_idsstring[]required
      • person_idsstring[]required
    • scorecard_idstring | nullrequired
    • feedback_due_hoursintegerrequired
    • scorecardobject | nullrequired

      What interviewers rate at this step (null: no scorecard, only a recommendation and words).

      2 fields
      • skillsobject[]required
        4 fields
        • idstringrequired
        • namestringrequired
        • promptstring | nullrequired
        • levelsstring[]required

          4–4 items.

      • overall_questionstring | nullrequired
  • template_idstring | nullrequired
  • interviews"in_bizisy" | "outside"required

    How interviews run for this job (its own choice, else the company default).

  • interviews_override"in_bizisy" | "outside"required
  • answer_daysintegerrequired

    Working days to answer each candidate (its own, else the company default).

  • answer_days_overrideinteger | nullrequired
  • free_sitesbooleanrequired
  • audience"public" | "internal_first" | "internal_only"required

    Who 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 | nullrequired

    internal_first: days in Me before it goes public (null: the company default).

  • public_fromstring | nullrequired

    internal_first: when it went (or goes) public; null while internal.

  • listed_publiclybooleanrequired

    Shown on the careers page and the feed now.

  • referral_bonusobjectrequired

    This 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"required
    • amountnumberrequired
    • currencystringrequired
  • hiring_managerobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • questionsobject[]required
    6 fields
    • idstringrequired
    • textstringrequired
    • kind"text" | "yes_no" | "choice"required
    • optionsstring[]
    • requiredbooleanrequired
    • external_onlybooleanrequired

      Shown to outside candidates only, never to people who work here.

  • valid_throughstring | nullrequired
  • careers_pathstringrequired

    Its address on the company's careers page, once open.

  • readyobjectrequired

    Whether it can be opened, and what is missing: title, description (what you'll do), pay_range, gaps (a [[…]] left from the draft).

    2 fields
    • okbooleanrequired
    • missing"title" | "description" | "pay_range" | "gaps"[]required
  • opened_atstring | nullrequired
  • closed_atstring | nullrequired
  • close_reason"filled" | "cancelled" | "other"required
  • close_replyobject | nullrequired

    Closed with "reply to everyone still open": when the kind "not this time" goes out to them.

    1 field
    • send_atstringrequired
  • created_atstringrequired
  • updated_atstringrequired
  • warningsobject[]required

    The 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"required
    • termstringrequired
    • category"age" | "gender" | "family" | "origin" | "health" | "looks"required
    • suggestionsstring[]required

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/hiring/jobs.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_id":"j1"}'
Response
{
  "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_create on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • template_idstring

    1–100 characters.

  • language"en" | "pt" | "es" | "fr" | "de"
  • slugstring

    2–80 characters. Pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$.

  • hiring_manager_idstring | null

    1–100 characters.

  • draftboolean

    Default 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 | null

    From 1 to 60.

Returns

41 fields
  • idstringrequired
  • position_idstringrequired
  • slugstringrequired
  • status"draft" | "open" | "paused" | "closed"required
  • titlestringrequired
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • locationobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • citystring | nullrequired
    • countrystringrequired
  • workplace"on_site" | "hybrid" | "remote"required
  • countrystring | nullrequired
  • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
  • weekly_hoursnumber | nullrequired
  • employment_type"full_time" | "part_time" | "contract" | "temporary" | "internship"required
  • salaryobject | nullrequired

    The range the post shows (from the position's budget or band, or set on the job).

    5 fields
    • minnumberrequired
    • maxnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
    • source"position" | "band" | "job"required
  • salary_hiddenbooleanrequired

    True 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"required
  • postobjectrequired
    4 fields
    • what_you_dostringrequired
    • what_you_needstringrequired
    • what_you_getstringrequired
    • how_it_goesstringrequired
  • processobjectrequired

    What 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
    • promisestringrequired
    • stepsstring[]required
  • stepsobject[]required
    13 fields
    • idstringrequired
    • namestringrequired
    • kindstring (enum)required

      One of: call, interview, panel, task, trial, presentation, references, final.

    • minutesnumber | nullrequired
    • buffer_minutesintegerrequired

      Minutes kept clear after the interview.

    • place"video" | "video_auto" | "phone" | "on_site" | "none"required
    • addressstring | nullrequired

      In person: the address.

    • video_linkstring | nullrequired

      Video (pasted): the meeting link.

    • interviewers_neededintegerrequired
    • poolobjectrequired
      2 fields
      • group_idsstring[]required
      • person_idsstring[]required
    • scorecard_idstring | nullrequired
    • feedback_due_hoursintegerrequired
    • scorecardobject | nullrequired

      What interviewers rate at this step (null: no scorecard, only a recommendation and words).

      2 fields
      • skillsobject[]required
        4 fields
        • idstringrequired
        • namestringrequired
        • promptstring | nullrequired
        • levelsstring[]required

          4–4 items.

      • overall_questionstring | nullrequired
  • template_idstring | nullrequired
  • interviews"in_bizisy" | "outside"required

    How interviews run for this job (its own choice, else the company default).

  • interviews_override"in_bizisy" | "outside"required
  • answer_daysintegerrequired

    Working days to answer each candidate (its own, else the company default).

  • answer_days_overrideinteger | nullrequired
  • free_sitesbooleanrequired
  • audience"public" | "internal_first" | "internal_only"required

    Who 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 | nullrequired

    internal_first: days in Me before it goes public (null: the company default).

  • public_fromstring | nullrequired

    internal_first: when it went (or goes) public; null while internal.

  • listed_publiclybooleanrequired

    Shown on the careers page and the feed now.

  • referral_bonusobjectrequired

    This 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"required
    • amountnumberrequired
    • currencystringrequired
  • hiring_managerobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • questionsobject[]required
    6 fields
    • idstringrequired
    • textstringrequired
    • kind"text" | "yes_no" | "choice"required
    • optionsstring[]
    • requiredbooleanrequired
    • external_onlybooleanrequired

      Shown to outside candidates only, never to people who work here.

  • valid_throughstring | nullrequired
  • careers_pathstringrequired

    Its address on the company's careers page, once open.

  • readyobjectrequired

    Whether it can be opened, and what is missing: title, description (what you'll do), pay_range, gaps (a [[…]] left from the draft).

    2 fields
    • okbooleanrequired
    • missing"title" | "description" | "pay_range" | "gaps"[]required
  • opened_atstring | nullrequired
  • closed_atstring | nullrequired
  • close_reason"filled" | "cancelled" | "other"required
  • close_replyobject | nullrequired

    Closed with "reply to everyone still open": when the kind "not this time" goes out to them.

    1 field
    • send_atstringrequired
  • created_atstringrequired
  • updated_atstringrequired
  • warningsobject[]required

    The 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"required
    • termstringrequired
    • category"age" | "gender" | "family" | "origin" | "health" | "looks"required
    • suggestionsstring[]required

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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
}'
Response
{
  "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_update on HR Assistant, My Workplace
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • titlestring

    1–120 characters.

  • slugstring

    2–80 characters. Pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$.

  • unit_idstring | null

    1–100 characters.

  • location_idstring | null

    1–100 characters.

  • workplace"on_site" | "hybrid" | "remote"
  • countryany | null
  • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"
  • weekly_hoursnumber | null

    From 0 to 80.

  • salaryobject | null
    4 fields
    • minnumberrequired

      From 0 to 100000000.

    • maxnumberrequired

      From 0 to 100000000.

    • currencyanyrequired
    • period"year" | "month" | "hour"required
  • language"en" | "pt" | "es" | "fr" | "de"
  • postobject
    4 fields
    • what_you_dostring

      Up to 5000 characters.

    • what_you_needstring

      Up to 5000 characters.

    • what_you_getstring

      Up to 5000 characters.

    • how_it_goesstring

      Up to 5000 characters.

  • stepsobject[]

    The steps between New and Offer, in order (1 to 10).

    1–10 items.

    12 fields
    • idstring

      Keep the id of an existing step to keep its candidates in it; leave it out for a new step.

      1–40 characters.

    • namestringrequired

      What the company and the candidate call it, e.g. "Phone call", "Trial shift".

      1–60 characters.

    • kindstring (enum)required

      call, interview, panel, task, trial, presentation, references or final.

      One of: call, interview, panel, task, trial, presentation, references, final.

    • minutesinteger | null

      How 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_minutesinteger

      Minutes 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 | null

      In person (on_site): the address the candidate and interviewers go to.

      1–300 characters.

    • video_linkURL | null

      Video: the meeting link HR pastes (Meet, Teams, Zoom…); sent with the invitation.

      Up to 500 characters.

    • interviewers_neededinteger

      Colleagues who interview together at this step (0: nobody is asked). Default 0 for call, task and references, else 1.

      From 0 to 5.

    • poolobject

      Who 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_hoursinteger

      Hours after the interview to send feedback (default 24).

      From 1 to 336.

    • scorecardobject | null

      What 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[]required

        Up to 8 skills, each rated 1 to 4.

        Up to 8 items.

        4 fields
        • idstring

          Keep a skill's id to keep the ratings already given on it; leave it out for a new skill.

          1–40 characters.

        • namestringrequired

          What is rated, e.g. "Problem solving".

          1–60 characters.

        • promptstring | null

          What to ask or look for (shown to the interviewer).

          1–300 characters.

        • levelsany[]required

          What each rating looks like, from 1 (clear concerns) to 4 (excellent): four short anchored descriptions.

          4–4 items.

      • overall_questionstring | null

        An optional question every interviewer answers in their own words.

        1–300 characters.

  • interviews"in_bizisy" | "outside"
  • answer_daysinteger | null

    From 1 to 30.

  • free_sitesboolean
  • referral_bonusobject
    4 fields (one of several shapes)

    Option 1

    • kind"none"required

    Option 2

    • kind"amount"required
    • amountnumberrequired

      From 0 to 1000000.

    • currencyanyrequired
  • hiring_manager_idstring | null

    1–100 characters.

  • questionsobject[]

    At most 2 extra questions on the form (yes/no, a choice or short text).

    Up to 2 items.

    7 fields
    • idstring

      1–40 characters.

    • textstringrequired

      3–200 characters.

    • kind"text" | "yes_no" | "choice"required
    • optionsstring[]

      For kind choice: 2 to 6 answers.

      1–60 characters. 2–6 items.

    • requiredboolean

      Default false.

    • external_onlyboolean

      Only 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_relatedtruerequired

      Confirms the question is about the job itself (H14). Questions about pay history, age, family, health, religion or pregnancy are refused.

  • valid_throughstring | null

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • audience"public" | "internal_first" | "internal_only"
  • internal_daysinteger | null

    From 1 to 60.

Returns

41 fields
  • idstringrequired
  • position_idstringrequired
  • slugstringrequired
  • status"draft" | "open" | "paused" | "closed"required
  • titlestringrequired
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • locationobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • citystring | nullrequired
    • countrystringrequired
  • workplace"on_site" | "hybrid" | "remote"required
  • countrystring | nullrequired
  • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
  • weekly_hoursnumber | nullrequired
  • employment_type"full_time" | "part_time" | "contract" | "temporary" | "internship"required
  • salaryobject | nullrequired

    The range the post shows (from the position's budget or band, or set on the job).

    5 fields
    • minnumberrequired
    • maxnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
    • source"position" | "band" | "job"required
  • salary_hiddenbooleanrequired

    True 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"required
  • postobjectrequired
    4 fields
    • what_you_dostringrequired
    • what_you_needstringrequired
    • what_you_getstringrequired
    • how_it_goesstringrequired
  • processobjectrequired

    What 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
    • promisestringrequired
    • stepsstring[]required
  • stepsobject[]required
    13 fields
    • idstringrequired
    • namestringrequired
    • kindstring (enum)required

      One of: call, interview, panel, task, trial, presentation, references, final.

    • minutesnumber | nullrequired
    • buffer_minutesintegerrequired

      Minutes kept clear after the interview.

    • place"video" | "video_auto" | "phone" | "on_site" | "none"required
    • addressstring | nullrequired

      In person: the address.

    • video_linkstring | nullrequired

      Video (pasted): the meeting link.

    • interviewers_neededintegerrequired
    • poolobjectrequired
      2 fields
      • group_idsstring[]required
      • person_idsstring[]required
    • scorecard_idstring | nullrequired
    • feedback_due_hoursintegerrequired
    • scorecardobject | nullrequired

      What interviewers rate at this step (null: no scorecard, only a recommendation and words).

      2 fields
      • skillsobject[]required
        4 fields
        • idstringrequired
        • namestringrequired
        • promptstring | nullrequired
        • levelsstring[]required

          4–4 items.

      • overall_questionstring | nullrequired
  • template_idstring | nullrequired
  • interviews"in_bizisy" | "outside"required

    How interviews run for this job (its own choice, else the company default).

  • interviews_override"in_bizisy" | "outside"required
  • answer_daysintegerrequired

    Working days to answer each candidate (its own, else the company default).

  • answer_days_overrideinteger | nullrequired
  • free_sitesbooleanrequired
  • audience"public" | "internal_first" | "internal_only"required

    Who 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 | nullrequired

    internal_first: days in Me before it goes public (null: the company default).

  • public_fromstring | nullrequired

    internal_first: when it went (or goes) public; null while internal.

  • listed_publiclybooleanrequired

    Shown on the careers page and the feed now.

  • referral_bonusobjectrequired

    This 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"required
    • amountnumberrequired
    • currencystringrequired
  • hiring_managerobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • questionsobject[]required
    6 fields
    • idstringrequired
    • textstringrequired
    • kind"text" | "yes_no" | "choice"required
    • optionsstring[]
    • requiredbooleanrequired
    • external_onlybooleanrequired

      Shown to outside candidates only, never to people who work here.

  • valid_throughstring | nullrequired
  • careers_pathstringrequired

    Its address on the company's careers page, once open.

  • readyobjectrequired

    Whether it can be opened, and what is missing: title, description (what you'll do), pay_range, gaps (a [[…]] left from the draft).

    2 fields
    • okbooleanrequired
    • missing"title" | "description" | "pay_range" | "gaps"[]required
  • opened_atstring | nullrequired
  • closed_atstring | nullrequired
  • close_reason"filled" | "cancelled" | "other"required
  • close_replyobject | nullrequired

    Closed with "reply to everyone still open": when the kind "not this time" goes out to them.

    1 field
    • send_atstringrequired
  • created_atstringrequired
  • updated_atstringrequired
  • warningsobject[]required

    The 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"required
    • termstringrequired
    • category"age" | "gender" | "family" | "origin" | "health" | "looks"required
    • suggestionsstring[]required

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
}'
Response
{
  "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_open on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

Returns

41 fields
  • idstringrequired
  • position_idstringrequired
  • slugstringrequired
  • status"draft" | "open" | "paused" | "closed"required
  • titlestringrequired
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • locationobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • citystring | nullrequired
    • countrystringrequired
  • workplace"on_site" | "hybrid" | "remote"required
  • countrystring | nullrequired
  • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
  • weekly_hoursnumber | nullrequired
  • employment_type"full_time" | "part_time" | "contract" | "temporary" | "internship"required
  • salaryobject | nullrequired

    The range the post shows (from the position's budget or band, or set on the job).

    5 fields
    • minnumberrequired
    • maxnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
    • source"position" | "band" | "job"required
  • salary_hiddenbooleanrequired

    True 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"required
  • postobjectrequired
    4 fields
    • what_you_dostringrequired
    • what_you_needstringrequired
    • what_you_getstringrequired
    • how_it_goesstringrequired
  • processobjectrequired

    What 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
    • promisestringrequired
    • stepsstring[]required
  • stepsobject[]required
    13 fields
    • idstringrequired
    • namestringrequired
    • kindstring (enum)required

      One of: call, interview, panel, task, trial, presentation, references, final.

    • minutesnumber | nullrequired
    • buffer_minutesintegerrequired

      Minutes kept clear after the interview.

    • place"video" | "video_auto" | "phone" | "on_site" | "none"required
    • addressstring | nullrequired

      In person: the address.

    • video_linkstring | nullrequired

      Video (pasted): the meeting link.

    • interviewers_neededintegerrequired
    • poolobjectrequired
      2 fields
      • group_idsstring[]required
      • person_idsstring[]required
    • scorecard_idstring | nullrequired
    • feedback_due_hoursintegerrequired
    • scorecardobject | nullrequired

      What interviewers rate at this step (null: no scorecard, only a recommendation and words).

      2 fields
      • skillsobject[]required
        4 fields
        • idstringrequired
        • namestringrequired
        • promptstring | nullrequired
        • levelsstring[]required

          4–4 items.

      • overall_questionstring | nullrequired
  • template_idstring | nullrequired
  • interviews"in_bizisy" | "outside"required

    How interviews run for this job (its own choice, else the company default).

  • interviews_override"in_bizisy" | "outside"required
  • answer_daysintegerrequired

    Working days to answer each candidate (its own, else the company default).

  • answer_days_overrideinteger | nullrequired
  • free_sitesbooleanrequired
  • audience"public" | "internal_first" | "internal_only"required

    Who 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 | nullrequired

    internal_first: days in Me before it goes public (null: the company default).

  • public_fromstring | nullrequired

    internal_first: when it went (or goes) public; null while internal.

  • listed_publiclybooleanrequired

    Shown on the careers page and the feed now.

  • referral_bonusobjectrequired

    This 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"required
    • amountnumberrequired
    • currencystringrequired
  • hiring_managerobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • questionsobject[]required
    6 fields
    • idstringrequired
    • textstringrequired
    • kind"text" | "yes_no" | "choice"required
    • optionsstring[]
    • requiredbooleanrequired
    • external_onlybooleanrequired

      Shown to outside candidates only, never to people who work here.

  • valid_throughstring | nullrequired
  • careers_pathstringrequired

    Its address on the company's careers page, once open.

  • readyobjectrequired

    Whether it can be opened, and what is missing: title, description (what you'll do), pay_range, gaps (a [[…]] left from the draft).

    2 fields
    • okbooleanrequired
    • missing"title" | "description" | "pay_range" | "gaps"[]required
  • opened_atstring | nullrequired
  • closed_atstring | nullrequired
  • close_reason"filled" | "cancelled" | "other"required
  • close_replyobject | nullrequired

    Closed with "reply to everyone still open": when the kind "not this time" goes out to them.

    1 field
    • send_atstringrequired
  • created_atstringrequired
  • updated_atstringrequired
  • warningsobject[]required

    The 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"required
    • termstringrequired
    • category"age" | "gender" | "family" | "origin" | "health" | "looks"required
    • suggestionsstring[]required

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_pause on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

Returns

41 fields
  • idstringrequired
  • position_idstringrequired
  • slugstringrequired
  • status"draft" | "open" | "paused" | "closed"required
  • titlestringrequired
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • locationobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • citystring | nullrequired
    • countrystringrequired
  • workplace"on_site" | "hybrid" | "remote"required
  • countrystring | nullrequired
  • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
  • weekly_hoursnumber | nullrequired
  • employment_type"full_time" | "part_time" | "contract" | "temporary" | "internship"required
  • salaryobject | nullrequired

    The range the post shows (from the position's budget or band, or set on the job).

    5 fields
    • minnumberrequired
    • maxnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
    • source"position" | "band" | "job"required
  • salary_hiddenbooleanrequired

    True 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"required
  • postobjectrequired
    4 fields
    • what_you_dostringrequired
    • what_you_needstringrequired
    • what_you_getstringrequired
    • how_it_goesstringrequired
  • processobjectrequired

    What 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
    • promisestringrequired
    • stepsstring[]required
  • stepsobject[]required
    13 fields
    • idstringrequired
    • namestringrequired
    • kindstring (enum)required

      One of: call, interview, panel, task, trial, presentation, references, final.

    • minutesnumber | nullrequired
    • buffer_minutesintegerrequired

      Minutes kept clear after the interview.

    • place"video" | "video_auto" | "phone" | "on_site" | "none"required
    • addressstring | nullrequired

      In person: the address.

    • video_linkstring | nullrequired

      Video (pasted): the meeting link.

    • interviewers_neededintegerrequired
    • poolobjectrequired
      2 fields
      • group_idsstring[]required
      • person_idsstring[]required
    • scorecard_idstring | nullrequired
    • feedback_due_hoursintegerrequired
    • scorecardobject | nullrequired

      What interviewers rate at this step (null: no scorecard, only a recommendation and words).

      2 fields
      • skillsobject[]required
        4 fields
        • idstringrequired
        • namestringrequired
        • promptstring | nullrequired
        • levelsstring[]required

          4–4 items.

      • overall_questionstring | nullrequired
  • template_idstring | nullrequired
  • interviews"in_bizisy" | "outside"required

    How interviews run for this job (its own choice, else the company default).

  • interviews_override"in_bizisy" | "outside"required
  • answer_daysintegerrequired

    Working days to answer each candidate (its own, else the company default).

  • answer_days_overrideinteger | nullrequired
  • free_sitesbooleanrequired
  • audience"public" | "internal_first" | "internal_only"required

    Who 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 | nullrequired

    internal_first: days in Me before it goes public (null: the company default).

  • public_fromstring | nullrequired

    internal_first: when it went (or goes) public; null while internal.

  • listed_publiclybooleanrequired

    Shown on the careers page and the feed now.

  • referral_bonusobjectrequired

    This 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"required
    • amountnumberrequired
    • currencystringrequired
  • hiring_managerobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • questionsobject[]required
    6 fields
    • idstringrequired
    • textstringrequired
    • kind"text" | "yes_no" | "choice"required
    • optionsstring[]
    • requiredbooleanrequired
    • external_onlybooleanrequired

      Shown to outside candidates only, never to people who work here.

  • valid_throughstring | nullrequired
  • careers_pathstringrequired

    Its address on the company's careers page, once open.

  • readyobjectrequired

    Whether it can be opened, and what is missing: title, description (what you'll do), pay_range, gaps (a [[…]] left from the draft).

    2 fields
    • okbooleanrequired
    • missing"title" | "description" | "pay_range" | "gaps"[]required
  • opened_atstring | nullrequired
  • closed_atstring | nullrequired
  • close_reason"filled" | "cancelled" | "other"required
  • close_replyobject | nullrequired

    Closed with "reply to everyone still open": when the kind "not this time" goes out to them.

    1 field
    • send_atstringrequired
  • created_atstringrequired
  • updated_atstringrequired
  • warningsobject[]required

    The 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"required
    • termstringrequired
    • category"age" | "gender" | "family" | "origin" | "health" | "looks"required
    • suggestionsstring[]required

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_close on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • reason"filled" | "cancelled" | "other"required
  • reply_to_openboolean

    Send everyone still open the kind "not this time".

    Default false.

  • reply_in_daysinteger

    From 0 to 14.

Returns

41 fields
  • idstringrequired
  • position_idstringrequired
  • slugstringrequired
  • status"draft" | "open" | "paused" | "closed"required
  • titlestringrequired
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • locationobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • citystring | nullrequired
    • countrystringrequired
  • workplace"on_site" | "hybrid" | "remote"required
  • countrystring | nullrequired
  • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
  • weekly_hoursnumber | nullrequired
  • employment_type"full_time" | "part_time" | "contract" | "temporary" | "internship"required
  • salaryobject | nullrequired

    The range the post shows (from the position's budget or band, or set on the job).

    5 fields
    • minnumberrequired
    • maxnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
    • source"position" | "band" | "job"required
  • salary_hiddenbooleanrequired

    True 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"required
  • postobjectrequired
    4 fields
    • what_you_dostringrequired
    • what_you_needstringrequired
    • what_you_getstringrequired
    • how_it_goesstringrequired
  • processobjectrequired

    What 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
    • promisestringrequired
    • stepsstring[]required
  • stepsobject[]required
    13 fields
    • idstringrequired
    • namestringrequired
    • kindstring (enum)required

      One of: call, interview, panel, task, trial, presentation, references, final.

    • minutesnumber | nullrequired
    • buffer_minutesintegerrequired

      Minutes kept clear after the interview.

    • place"video" | "video_auto" | "phone" | "on_site" | "none"required
    • addressstring | nullrequired

      In person: the address.

    • video_linkstring | nullrequired

      Video (pasted): the meeting link.

    • interviewers_neededintegerrequired
    • poolobjectrequired
      2 fields
      • group_idsstring[]required
      • person_idsstring[]required
    • scorecard_idstring | nullrequired
    • feedback_due_hoursintegerrequired
    • scorecardobject | nullrequired

      What interviewers rate at this step (null: no scorecard, only a recommendation and words).

      2 fields
      • skillsobject[]required
        4 fields
        • idstringrequired
        • namestringrequired
        • promptstring | nullrequired
        • levelsstring[]required

          4–4 items.

      • overall_questionstring | nullrequired
  • template_idstring | nullrequired
  • interviews"in_bizisy" | "outside"required

    How interviews run for this job (its own choice, else the company default).

  • interviews_override"in_bizisy" | "outside"required
  • answer_daysintegerrequired

    Working days to answer each candidate (its own, else the company default).

  • answer_days_overrideinteger | nullrequired
  • free_sitesbooleanrequired
  • audience"public" | "internal_first" | "internal_only"required

    Who 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 | nullrequired

    internal_first: days in Me before it goes public (null: the company default).

  • public_fromstring | nullrequired

    internal_first: when it went (or goes) public; null while internal.

  • listed_publiclybooleanrequired

    Shown on the careers page and the feed now.

  • referral_bonusobjectrequired

    This 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"required
    • amountnumberrequired
    • currencystringrequired
  • hiring_managerobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • questionsobject[]required
    6 fields
    • idstringrequired
    • textstringrequired
    • kind"text" | "yes_no" | "choice"required
    • optionsstring[]
    • requiredbooleanrequired
    • external_onlybooleanrequired

      Shown to outside candidates only, never to people who work here.

  • valid_throughstring | nullrequired
  • careers_pathstringrequired

    Its address on the company's careers page, once open.

  • readyobjectrequired

    Whether it can be opened, and what is missing: title, description (what you'll do), pay_range, gaps (a [[…]] left from the draft).

    2 fields
    • okbooleanrequired
    • missing"title" | "description" | "pay_range" | "gaps"[]required
  • opened_atstring | nullrequired
  • closed_atstring | nullrequired
  • close_reason"filled" | "cancelled" | "other"required
  • close_replyobject | nullrequired

    Closed with "reply to everyone still open": when the kind "not this time" goes out to them.

    1 field
    • send_atstringrequired
  • created_atstringrequired
  • updated_atstringrequired
  • warningsobject[]required

    The 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"required
    • termstringrequired
    • category"age" | "gender" | "family" | "origin" | "health" | "looks"required
    • suggestionsstring[]required

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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}'
Response
{
  "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_post on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • job_idstringrequired

    1–100 characters.

  • language"en" | "pt" | "es" | "fr" | "de"

Returns

  • language"en" | "pt" | "es" | "fr" | "de"required
  • postobjectrequired
    4 fields
    • what_you_dostringrequired
    • what_you_needstringrequired
    • what_you_getstringrequired
    • how_it_goesstringrequired
  • gapsbooleanrequired

    Some [[…]] text is left to fill.

  • warningsobject[]required
    4 fields
    • field"title" | "what_you_do" | "what_you_need" | "what_you_get" | "how_it_goes"required
    • termstringrequired
    • category"age" | "gender" | "family" | "origin" | "health" | "looks"required
    • suggestionsstring[]required

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_wording on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • job_idstring

    1–100 characters.

  • language"en" | "pt" | "es" | "fr" | "de"
  • titlestring

    Up to 120 characters.

  • postobject
    4 fields
    • what_you_dostring

      Up to 5000 characters.

    • what_you_needstring

      Up to 5000 characters.

    • what_you_getstring

      Up to 5000 characters.

    • how_it_goesstring

      Up to 5000 characters.

Returns

  • language"en" | "pt" | "es" | "fr" | "de"required
  • warningsobject[]required
    4 fields
    • field"title" | "what_you_do" | "what_you_need" | "what_you_get" | "how_it_goes"required
    • termstringrequired
    • category"age" | "gender" | "family" | "origin" | "health" | "looks"required
    • suggestionsstring[]required

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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."
  }
}'
Response
{
  "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_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • language"en" | "pt" | "es" | "fr" | "de"
  • include_archivedboolean

    Default false.

Returns

An array of objects with 7 fields

An array of objects:

  • idstringrequired

    A built-in plan's key (simple, office, engineering, warehouse, sales) or the company's own plan's id.

  • namestringrequired
  • builtinbooleanrequired
  • changedbooleanrequired

    A built-in plan HR has changed.

  • stepsobject[]required
    13 fields
    • idstringrequired
    • namestringrequired
    • kindstring (enum)required

      One of: call, interview, panel, task, trial, presentation, references, final.

    • minutesnumber | nullrequired
    • buffer_minutesintegerrequired

      Minutes kept clear after the interview.

    • place"video" | "video_auto" | "phone" | "on_site" | "none"required
    • addressstring | nullrequired

      In person: the address.

    • video_linkstring | nullrequired

      Video (pasted): the meeting link.

    • interviewers_neededintegerrequired
    • poolobjectrequired
      2 fields
      • group_idsstring[]required
      • person_idsstring[]required
    • scorecard_idstring | nullrequired
    • feedback_due_hoursintegerrequired
    • scorecardobject | nullrequired

      What interviewers rate at this step (null: no scorecard, only a recommendation and words).

      2 fields
      • skillsobject[]required
        4 fields
        • idstringrequired
        • namestringrequired
        • promptstring | nullrequired
        • levelsstring[]required

          4–4 items.

      • overall_questionstring | nullrequired
  • questionsobject[]required
    6 fields
    • idstringrequired
    • textstringrequired
    • kind"text" | "yes_no" | "choice"required
    • optionsstring[]
    • requiredbooleanrequired
    • external_onlybooleanrequired

      Shown to outside candidates only, never to people who work here.

  • archivedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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}'
Response
{
  "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_create on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • namestringrequired

    1–60 characters.

  • stepsobject[]

    The steps between New and Offer, in order (1 to 10).

    1–10 items.

    12 fields
    • idstring

      Keep the id of an existing step to keep its candidates in it; leave it out for a new step.

      1–40 characters.

    • namestringrequired

      What the company and the candidate call it, e.g. "Phone call", "Trial shift".

      1–60 characters.

    • kindstring (enum)required

      call, interview, panel, task, trial, presentation, references or final.

      One of: call, interview, panel, task, trial, presentation, references, final.

    • minutesinteger | null

      How 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_minutesinteger

      Minutes 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 | null

      In person (on_site): the address the candidate and interviewers go to.

      1–300 characters.

    • video_linkURL | null

      Video: the meeting link HR pastes (Meet, Teams, Zoom…); sent with the invitation.

      Up to 500 characters.

    • interviewers_neededinteger

      Colleagues who interview together at this step (0: nobody is asked). Default 0 for call, task and references, else 1.

      From 0 to 5.

    • poolobject

      Who 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_hoursinteger

      Hours after the interview to send feedback (default 24).

      From 1 to 336.

    • scorecardobject | null

      What 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[]required

        Up to 8 skills, each rated 1 to 4.

        Up to 8 items.

        4 fields
        • idstring

          Keep a skill's id to keep the ratings already given on it; leave it out for a new skill.

          1–40 characters.

        • namestringrequired

          What is rated, e.g. "Problem solving".

          1–60 characters.

        • promptstring | null

          What to ask or look for (shown to the interviewer).

          1–300 characters.

        • levelsany[]required

          What each rating looks like, from 1 (clear concerns) to 4 (excellent): four short anchored descriptions.

          4–4 items.

      • overall_questionstring | null

        An 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
    • idstring

      1–40 characters.

    • textstringrequired

      3–200 characters.

    • kind"text" | "yes_no" | "choice"required
    • optionsstring[]

      For kind choice: 2 to 6 answers.

      1–60 characters. 2–6 items.

    • requiredboolean

      Default false.

    • external_onlyboolean

      Only 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_relatedtruerequired

      Confirms the question is about the job itself (H14). Questions about pay history, age, family, health, religion or pregnancy are refused.

  • from_job_idstring

    1–100 characters.

Returns

7 fields
  • idstringrequired

    A built-in plan's key (simple, office, engineering, warehouse, sales) or the company's own plan's id.

  • namestringrequired
  • builtinbooleanrequired
  • changedbooleanrequired

    A built-in plan HR has changed.

  • stepsobject[]required
    13 fields
    • idstringrequired
    • namestringrequired
    • kindstring (enum)required

      One of: call, interview, panel, task, trial, presentation, references, final.

    • minutesnumber | nullrequired
    • buffer_minutesintegerrequired

      Minutes kept clear after the interview.

    • place"video" | "video_auto" | "phone" | "on_site" | "none"required
    • addressstring | nullrequired

      In person: the address.

    • video_linkstring | nullrequired

      Video (pasted): the meeting link.

    • interviewers_neededintegerrequired
    • poolobjectrequired
      2 fields
      • group_idsstring[]required
      • person_idsstring[]required
    • scorecard_idstring | nullrequired
    • feedback_due_hoursintegerrequired
    • scorecardobject | nullrequired

      What interviewers rate at this step (null: no scorecard, only a recommendation and words).

      2 fields
      • skillsobject[]required
        4 fields
        • idstringrequired
        • namestringrequired
        • promptstring | nullrequired
        • levelsstring[]required

          4–4 items.

      • overall_questionstring | nullrequired
  • questionsobject[]required
    6 fields
    • idstringrequired
    • textstringrequired
    • kind"text" | "yes_no" | "choice"required
    • optionsstring[]
    • requiredbooleanrequired
    • external_onlybooleanrequired

      Shown 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
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": []
}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • template_idstringrequired

    1–100 characters.

  • namestring

    1–60 characters.

  • stepsobject[]

    The steps between New and Offer, in order (1 to 10).

    1–10 items.

    12 fields
    • idstring

      Keep the id of an existing step to keep its candidates in it; leave it out for a new step.

      1–40 characters.

    • namestringrequired

      What the company and the candidate call it, e.g. "Phone call", "Trial shift".

      1–60 characters.

    • kindstring (enum)required

      call, interview, panel, task, trial, presentation, references or final.

      One of: call, interview, panel, task, trial, presentation, references, final.

    • minutesinteger | null

      How 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_minutesinteger

      Minutes 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 | null

      In person (on_site): the address the candidate and interviewers go to.

      1–300 characters.

    • video_linkURL | null

      Video: the meeting link HR pastes (Meet, Teams, Zoom…); sent with the invitation.

      Up to 500 characters.

    • interviewers_neededinteger

      Colleagues who interview together at this step (0: nobody is asked). Default 0 for call, task and references, else 1.

      From 0 to 5.

    • poolobject

      Who 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_hoursinteger

      Hours after the interview to send feedback (default 24).

      From 1 to 336.

    • scorecardobject | null

      What 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[]required

        Up to 8 skills, each rated 1 to 4.

        Up to 8 items.

        4 fields
        • idstring

          Keep a skill's id to keep the ratings already given on it; leave it out for a new skill.

          1–40 characters.

        • namestringrequired

          What is rated, e.g. "Problem solving".

          1–60 characters.

        • promptstring | null

          What to ask or look for (shown to the interviewer).

          1–300 characters.

        • levelsany[]required

          What each rating looks like, from 1 (clear concerns) to 4 (excellent): four short anchored descriptions.

          4–4 items.

      • overall_questionstring | null

        An 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
    • idstring

      1–40 characters.

    • textstringrequired

      3–200 characters.

    • kind"text" | "yes_no" | "choice"required
    • optionsstring[]

      For kind choice: 2 to 6 answers.

      1–60 characters. 2–6 items.

    • requiredboolean

      Default false.

    • external_onlyboolean

      Only 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_relatedtruerequired

      Confirms the question is about the job itself (H14). Questions about pay history, age, family, health, religion or pregnancy are refused.

Returns

7 fields
  • idstringrequired

    A built-in plan's key (simple, office, engineering, warehouse, sales) or the company's own plan's id.

  • namestringrequired
  • builtinbooleanrequired
  • changedbooleanrequired

    A built-in plan HR has changed.

  • stepsobject[]required
    13 fields
    • idstringrequired
    • namestringrequired
    • kindstring (enum)required

      One of: call, interview, panel, task, trial, presentation, references, final.

    • minutesnumber | nullrequired
    • buffer_minutesintegerrequired

      Minutes kept clear after the interview.

    • place"video" | "video_auto" | "phone" | "on_site" | "none"required
    • addressstring | nullrequired

      In person: the address.

    • video_linkstring | nullrequired

      Video (pasted): the meeting link.

    • interviewers_neededintegerrequired
    • poolobjectrequired
      2 fields
      • group_idsstring[]required
      • person_idsstring[]required
    • scorecard_idstring | nullrequired
    • feedback_due_hoursintegerrequired
    • scorecardobject | nullrequired

      What interviewers rate at this step (null: no scorecard, only a recommendation and words).

      2 fields
      • skillsobject[]required
        4 fields
        • idstringrequired
        • namestringrequired
        • promptstring | nullrequired
        • levelsstring[]required

          4–4 items.

      • overall_questionstring | nullrequired
  • questionsobject[]required
    6 fields
    • idstringrequired
    • textstringrequired
    • kind"text" | "yes_no" | "choice"required
    • optionsstring[]
    • requiredbooleanrequired
    • external_onlybooleanrequired

      Shown 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
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"
    }
  ]
}'
Response
{
  "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_archive on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • template_idstringrequired

    1–100 characters.

  • archivedboolean

    Default true.

Returns

7 fields
  • idstringrequired

    A built-in plan's key (simple, office, engineering, warehouse, sales) or the company's own plan's id.

  • namestringrequired
  • builtinbooleanrequired
  • changedbooleanrequired

    A built-in plan HR has changed.

  • stepsobject[]required
    13 fields
    • idstringrequired
    • namestringrequired
    • kindstring (enum)required

      One of: call, interview, panel, task, trial, presentation, references, final.

    • minutesnumber | nullrequired
    • buffer_minutesintegerrequired

      Minutes kept clear after the interview.

    • place"video" | "video_auto" | "phone" | "on_site" | "none"required
    • addressstring | nullrequired

      In person: the address.

    • video_linkstring | nullrequired

      Video (pasted): the meeting link.

    • interviewers_neededintegerrequired
    • poolobjectrequired
      2 fields
      • group_idsstring[]required
      • person_idsstring[]required
    • scorecard_idstring | nullrequired
    • feedback_due_hoursintegerrequired
    • scorecardobject | nullrequired

      What interviewers rate at this step (null: no scorecard, only a recommendation and words).

      2 fields
      • skillsobject[]required
        4 fields
        • idstringrequired
        • namestringrequired
        • promptstring | nullrequired
        • levelsstring[]required

          4–4 items.

      • overall_questionstring | nullrequired
  • questionsobject[]required
    6 fields
    • idstringrequired
    • textstringrequired
    • kind"text" | "yes_no" | "choice"required
    • optionsstring[]
    • requiredbooleanrequired
    • external_onlybooleanrequired

      Shown 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
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}'
Response
{
  "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_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

13 fields
  • careersobjectrequired
    8 fields
    • headlinestring | nullrequired

      The careers page's headline; null: "Work with us at <company>" in the visitor's language.

    • aboutstring | nullrequired
    • coverobject | nullrequired

      The careers page's cover photo behind the headline (hiring_settings_cover_set); null: none, the company's colour.

      7 fields
      • imagesobjectrequired

        Paths 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_webpstringrequired
        • large_jpegstringrequired
        • small_webpstringrequired
        • small_jpegstringrequired
        • sourcestringrequired
      • focalobjectrequired

        The point kept in view, 0–1 across and down the whole photo.

        2 fields
        • xnumberrequired
        • ynumberrequired
      • positionobjectrequired

        Where the focal point lands in the crops (0–1).

        2 fields
        • xnumberrequired
        • ynumberrequired
      • widthintegerrequired
      • heightintegerrequired
      • bytesintegerrequired

        What the photo's files take in the company's storage.

      • updated_atstringrequired
    • cover_availablebooleanrequired

      Whether this server stores cover photos (the cover actions work).

    • show_benefitsbooleanrequired
    • benefitsstring | nullrequired
    • privacy_urlstring | nullrequired

      The company's own privacy notice for candidates (https); null: candidates see the one Bizisy writes at <company address>/careers/privacy.

    • privacy_contact_emailstring | nullrequired

      Who 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_noticeobjectrequired

    The candidate privacy notice Bizisy writes for the company (shown unless careers.privacy_url is set).

    4 fields
    • employersobject[]required

      The 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_namestringrequired
      • countrystringrequired
      • tax_idstring | nullrequired
      • addressobject | nullrequired
        5 fields
        • line1stringrequired
        • line2string | nullrequired
        • postal_codestring | nullrequired
        • citystringrequired
        • regionstring | nullrequired
    • contact_emailstring | nullrequired

      The contact the notice shows; null: none (the notice points candidates to their status page).

    • contact_from"settings"required

      settings: careers.privacy_contact_email; null: none set.

    • missing"legal_entity" | "tax_id" | "address" | "contact_email"[]required

      What 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"required
  • answer_daysintegerrequired
  • reply_daysintegerrequired

    Days between deciding "not this time" and the kind email going out (0: at once).

  • retentionobjectrequired

    The company's own periods per country (ISO code).

  • retention_defaultsobjectrequired

    Bizisy's defaults per country; other countries: 6 months.

  • company_retentionobjectrequired

    The period that applies to this company (its country).

    3 fields
    • countrystring | nullrequired
    • valueintegerrequired
    • unit"weeks" | "months"required
  • emailsobjectrequired
  • referralsobjectrequired
    2 fields
    • enabledbooleanrequired
    • bonusobjectrequired
      6 fields
      • enabledbooleanrequired
      • amountnumber | nullrequired
      • currencystringrequired
      • earned"start" | "probation" | "months"required
      • monthsinteger | nullrequired
      • excluded"hr" | "hiring_manager"[]required
  • offersobjectrequired
    4 fields
    • approval"above_range" | "every_offer" | "off"required

      above_range (default): offers above the job's published range need approval; every_offer; off.

    • approvers"hr" | "owner"required

      hr (default): owners, admins and HR; owner: owners only. Never the person who proposed the offer.

    • default_expiry_daysintegerrequired

      Days a sent offer stays open (default 7).

    • signer_person_idstring | nullrequired

      Who signs offer letters for the company; null: the job's hiring manager.

  • internalobjectrequired
    10 fields
    • enabledbooleanrequired

      Internal 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"required

      Who new jobs are for: public (default), internal_first or internal_only.

    • internal_daysintegerrequired

      internal_first: days in Me before a job also goes public (default 7).

    • tell_manager"on_apply" | "on_interview" | "on_offer" | "at_transfer"required

      When 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_talkbooleanrequired

      The form suggests talking to your manager first (a nudge, never a checkbox).

    • min_months_in_jobinteger | nullrequired

      Minimum months in the current job before applying (null: none; 3, 6 or 12).

    • allow_in_probationbooleanrequired

      People still in probation may apply (default true).

    • include_outsidersbooleanrequired

      Contractors and outsiders with a login also see internal jobs (default false).

    • max_live_per_personintegerrequired

      Live internal applications per person (1–10, default 5).

    • sentencestringrequired

      The 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
curl https://api.bizisy.com/v1/hiring/settings.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs 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

  • careersobject
    6 fields
    • headlinestring | null

      Up to 80 characters. Pattern ^[^\r\n]*$.

    • aboutstring | null

      Up to 3000 characters.

    • show_benefitsboolean
    • benefitsstring | null

      Up to 2000 characters.

    • privacy_urlURL | null

      Up to 500 characters.

    • privacy_contact_emailemail | null

      Up to 254 characters.

  • interviews"in_bizisy" | "outside"
  • answer_daysinteger

    From 1 to 30.

  • reply_daysinteger

    From 0 to 14.

  • retentionobject
  • emailsobject
    8 fields
    • receivedobject | nullrequired
      2 fields
      • subjectstring | nullrequired

        Up to 200 characters.

      • bodystring | nullrequired

        Up to 5000 characters.

    • not_this_timeobject | nullrequired
      2 fields
      • subjectstring | nullrequired

        Up to 200 characters.

      • bodystring | nullrequired

        Up to 5000 characters.

    • invite_to_bookobject | nullrequired
      2 fields
      • subjectstring | nullrequired

        Up to 200 characters.

      • bodystring | nullrequired

        Up to 5000 characters.

    • bookedobject | nullrequired
      2 fields
      • subjectstring | nullrequired

        Up to 200 characters.

      • bodystring | nullrequired

        Up to 5000 characters.

    • reminderobject | nullrequired
      2 fields
      • subjectstring | nullrequired

        Up to 200 characters.

      • bodystring | nullrequired

        Up to 5000 characters.

    • link_requestobject | nullrequired
      2 fields
      • subjectstring | nullrequired

        Up to 200 characters.

      • bodystring | nullrequired

        Up to 5000 characters.

    • pool_renewalobject | nullrequired
      2 fields
      • subjectstring | nullrequired

        Up to 200 characters.

      • bodystring | nullrequired

        Up to 5000 characters.

    • referral_inviteobject | nullrequired
      2 fields
      • subjectstring | nullrequired

        Up to 200 characters.

      • bodystring | nullrequired

        Up to 5000 characters.

  • referralsobject
    2 fields
    • enabledboolean
    • bonusobject
      6 fields
      • enabledboolean
      • amountnumber | null

        From 0 to 1000000.

      • currencyany
      • earned"start" | "probation" | "months"
      • monthsinteger | null

        From 1 to 24.

      • excluded"hr" | "hiring_manager"[]

        Up to 2 items.

  • offersobject
    4 fields
    • approval"above_range" | "every_offer" | "off"
    • approvers"hr" | "owner"
    • default_expiry_daysinteger

      From 1 to 60.

    • signer_person_idstring | null

      1–100 characters.

  • internalobject
    9 fields
    • enabledboolean
    • default_audience"public" | "internal_first" | "internal_only"
    • internal_daysinteger

      From 1 to 60.

    • tell_manager"on_apply" | "on_interview" | "on_offer" | "at_transfer"
    • nudge_manager_talkboolean
    • min_months_in_job3 | 6 | 12
    • allow_in_probationboolean
    • include_outsidersboolean
    • max_live_per_personinteger

      From 1 to 10.

Returns

13 fields
  • careersobjectrequired
    8 fields
    • headlinestring | nullrequired

      The careers page's headline; null: "Work with us at <company>" in the visitor's language.

    • aboutstring | nullrequired
    • coverobject | nullrequired

      The careers page's cover photo behind the headline (hiring_settings_cover_set); null: none, the company's colour.

      7 fields
      • imagesobjectrequired

        Paths 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_webpstringrequired
        • large_jpegstringrequired
        • small_webpstringrequired
        • small_jpegstringrequired
        • sourcestringrequired
      • focalobjectrequired

        The point kept in view, 0–1 across and down the whole photo.

        2 fields
        • xnumberrequired
        • ynumberrequired
      • positionobjectrequired

        Where the focal point lands in the crops (0–1).

        2 fields
        • xnumberrequired
        • ynumberrequired
      • widthintegerrequired
      • heightintegerrequired
      • bytesintegerrequired

        What the photo's files take in the company's storage.

      • updated_atstringrequired
    • cover_availablebooleanrequired

      Whether this server stores cover photos (the cover actions work).

    • show_benefitsbooleanrequired
    • benefitsstring | nullrequired
    • privacy_urlstring | nullrequired

      The company's own privacy notice for candidates (https); null: candidates see the one Bizisy writes at <company address>/careers/privacy.

    • privacy_contact_emailstring | nullrequired

      Who 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_noticeobjectrequired

    The candidate privacy notice Bizisy writes for the company (shown unless careers.privacy_url is set).

    4 fields
    • employersobject[]required

      The 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_namestringrequired
      • countrystringrequired
      • tax_idstring | nullrequired
      • addressobject | nullrequired
        5 fields
        • line1stringrequired
        • line2string | nullrequired
        • postal_codestring | nullrequired
        • citystringrequired
        • regionstring | nullrequired
    • contact_emailstring | nullrequired

      The contact the notice shows; null: none (the notice points candidates to their status page).

    • contact_from"settings"required

      settings: careers.privacy_contact_email; null: none set.

    • missing"legal_entity" | "tax_id" | "address" | "contact_email"[]required

      What 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"required
  • answer_daysintegerrequired
  • reply_daysintegerrequired

    Days between deciding "not this time" and the kind email going out (0: at once).

  • retentionobjectrequired

    The company's own periods per country (ISO code).

  • retention_defaultsobjectrequired

    Bizisy's defaults per country; other countries: 6 months.

  • company_retentionobjectrequired

    The period that applies to this company (its country).

    3 fields
    • countrystring | nullrequired
    • valueintegerrequired
    • unit"weeks" | "months"required
  • emailsobjectrequired
  • referralsobjectrequired
    2 fields
    • enabledbooleanrequired
    • bonusobjectrequired
      6 fields
      • enabledbooleanrequired
      • amountnumber | nullrequired
      • currencystringrequired
      • earned"start" | "probation" | "months"required
      • monthsinteger | nullrequired
      • excluded"hr" | "hiring_manager"[]required
  • offersobjectrequired
    4 fields
    • approval"above_range" | "every_offer" | "off"required

      above_range (default): offers above the job's published range need approval; every_offer; off.

    • approvers"hr" | "owner"required

      hr (default): owners, admins and HR; owner: owners only. Never the person who proposed the offer.

    • default_expiry_daysintegerrequired

      Days a sent offer stays open (default 7).

    • signer_person_idstring | nullrequired

      Who signs offer letters for the company; null: the job's hiring manager.

  • internalobjectrequired
    10 fields
    • enabledbooleanrequired

      Internal 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"required

      Who new jobs are for: public (default), internal_first or internal_only.

    • internal_daysintegerrequired

      internal_first: days in Me before a job also goes public (default 7).

    • tell_manager"on_apply" | "on_interview" | "on_offer" | "at_transfer"required

      When 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_talkbooleanrequired

      The form suggests talking to your manager first (a nudge, never a checkbox).

    • min_months_in_jobinteger | nullrequired

      Minimum months in the current job before applying (null: none; 3, 6 or 12).

    • allow_in_probationbooleanrequired

      People still in probation may apply (default true).

    • include_outsidersbooleanrequired

      Contractors and outsiders with a login also see internal jobs (default false).

    • max_live_per_personintegerrequired

      Live internal applications per person (1–10, default 5).

    • sentencestringrequired

      The 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
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"
    }
  }
}'
Response
{
  "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_start on HR Assistant
Preview
?dry_run=true runs 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

  • namestringrequired

    1–200 characters.

  • sizeintegerrequired

    From 0 to 5000000.

  • content_type"image/jpeg" | "image/png" | "image/webp"required

    image/jpeg, image/png or image/webp: checked against the bytes.

  • sha256stringrequired

    Pattern ^[0-9a-f]{64}$.

Returns

  • file_idstringrequired
  • uploadobject | nullrequired

    null on a dry run.

    4 fields
    • urlstringrequired
    • method"PUT"required
    • headersobjectrequired
    • resumablefalserequired
  • expires_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
}'
Response
{
  "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_set on HR Assistant
Preview
?dry_run=true runs 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_idstring

    1–64 characters.

  • focal_xnumber

    From 0 to 1. Default 0.5.

  • focal_ynumber

    From 0 to 1. Default 0.5.

Returns

  • coverobjectrequired
    7 fields
    • imagesobjectrequired

      Paths 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_webpstringrequired
      • large_jpegstringrequired
      • small_webpstringrequired
      • small_jpegstringrequired
      • sourcestringrequired
    • focalobjectrequired

      The point kept in view, 0–1 across and down the whole photo.

      2 fields
      • xnumberrequired
      • ynumberrequired
    • positionobjectrequired

      Where the focal point lands in the crops (0–1).

      2 fields
      • xnumberrequired
      • ynumberrequired
    • widthintegerrequired
    • heightintegerrequired
    • bytesintegerrequired

      What 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
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}'
Response
{
  "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_remove on HR Assistant
Preview
?dry_run=true runs 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
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 '{}'
Response
{
  "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_page on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • job_idstringrequired

    1–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.

  • titlestring

    Up to 120 characters.

  • language"en" | "pt" | "es" | "fr" | "de"
  • postobject
    4 fields
    • what_you_dostring

      Up to 5000 characters.

    • what_you_needstring

      Up to 5000 characters.

    • what_you_getstring

      Up to 5000 characters.

    • how_it_goesstring

      Up to 5000 characters.

  • workplace"on_site" | "hybrid" | "remote"
  • salaryobject | null
    4 fields
    • minnumberrequired

      From 0 to 100000000.

    • maxnumberrequired

      From 0 to 100000000.

    • currencyanyrequired
    • period"year" | "month" | "hour"required
  • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"
  • weekly_hoursnumber | null

    From 0 to 80.

  • answer_daysinteger | null

    From 1 to 30.

  • valid_throughstring | null

    Pattern ^\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
    • idstring

      1–40 characters.

    • textstringrequired

      3–200 characters.

    • kind"text" | "yes_no" | "choice"required
    • optionsstring[]

      For kind choice: 2 to 6 answers.

      1–60 characters. 2–6 items.

    • requiredboolean

      Default false.

    • external_onlyboolean

      Only 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_relatedtruerequired

      Confirms the question is about the job itself (H14). Questions about pay history, age, family, health, religion or pregnancy are refused.

Returns

  • htmlstringrequired

    The 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"required

    The language the page is shown in.

  • pathstringrequired

    Where the page lives on the company's address once published (/careers or /careers/<job>).

  • examplebooleanrequired

    True 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
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
    }
  ]
}'
Response
{
  "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_page on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • page"careers" | "job"

    Default "careers".

  • page_language"en" | "pt" | "es" | "fr" | "de"
  • focus"headline" | "about" | "benefits" | "promise"
  • careersobject
    4 fields
    • headlinestring | null

      Up to 80 characters. Pattern ^[^\r\n]*$.

    • aboutstring | null

      Up to 3000 characters.

    • show_benefitsboolean
    • benefitsstring | null

      Up to 2000 characters.

  • answer_daysinteger

    From 1 to 30.

Returns

  • htmlstringrequired

    The 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"required

    The language the page is shown in.

  • pathstringrequired

    Where the page lives on the company's address once published (/careers or /careers/<job>).

  • examplebooleanrequired

    True 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
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
}'
Response
{
  "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_email on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • templatestring (enum)required

    One 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 | null

    Up to 200 characters.

  • bodystring | null

    Up to 5000 characters.

Returns

7 fields
  • templatestring (enum)required

    One 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"required
  • tostringrequired

    The sample recipient.

  • subjectstringrequired
  • htmlstringrequired

    The whole email as one HTML document.

  • textstringrequired

    The plain-text part.

  • own_textbooleanrequired

    The 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
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."
}'
Response
{
  "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_list on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • job_idstringrequired

    1–100 characters.

  • status"open" | "not_this_time" | "hired" | "all"

    Default "open".

  • columnstring

    1–40 characters.

  • overdueboolean
  • sourcestring (enum)

    One of: careers, share, referral, job_site, talent_pool, manual, internal.

  • qstring

    1–100 characters.

  • limitinteger

    From 1 to 1000. Default 200.

Returns

  • jobobjectrequired
    3 fields
    • idstringrequired
    • titlestringrequired
    • status"draft" | "open" | "paused" | "closed"required
  • columnsobject[]required

    New, the job's steps, Offer, Hired, with the open candidates in each (Hired: those hired).

    5 fields
    • keystringrequired
    • namestring | nullrequired
    • kind"new" | "step" | "offer" | "hired"required
    • countintegerrequired
    • overdueintegerrequired
  • countsobjectrequired
    5 fields
    • activeintegerrequired
    • overdueintegerrequired
    • not_this_timeintegerrequired
    • hiredintegerrequired
    • withdrawnintegerrequired
  • applicationsobject[]required
    16 fields
    • idstringrequired
    • candidateobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • columnstringrequired

      new, a step id, offer or hired.

    • status"active" | "hired" | "rejected" | "withdrawn"required

      active (in the process), hired, or rejected ("not this time", told or about to be).

    • sourcestring (enum)required

      One of: careers, share, referral, job_site, talent_pool, manual, internal.

    • referredbooleanrequired

      A colleague's referral (referrals on).

    • applied_atstringrequired
    • moved_atstringrequired
    • answer_due_onstring | nullrequired

      The answer promise: the date the company answers by (working days from the last move or message).

    • overduebooleanrequired

      Still open and the promised date has passed.

    • replyobject | nullrequired

      "Not this time": when the kind email goes out (cancellable until sent).

      3 fields
      • send_atstringrequired
      • emailbooleanrequired
      • sentbooleanrequired
    • has_cvbooleanrequired
    • cv_unread"no_credits"required

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

    • notesintegerrequired
    • feedbackobject | nullrequired

      Feedback in for the interviews held ("Feedback 1 of 2"); null before any interview was held.

      2 fields
      • submittedintegerrequired
      • expectedintegerrequired
    • internalobject | nullrequired

      W7: 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 | nullrequired
      • unitstring | nullrequired
      • locationstring | nullrequired
      • tenureobject | nullrequired
        2 fields
        • yearsintegerrequired
        • monthsintegerrequired
      • start_datestring | nullrequired
      • notestring | nullrequired

        "Why this job?" (the hiring team and HR).

      • person_idstring | nullrequired

        HR only: the person in People.

  • totalintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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
}'
Response
{
  "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_get on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • application_idstringrequired

    1–100 characters.

Returns

27 fields
  • idstringrequired
  • candidateobjectrequired
    8 fields
    • idstringrequired
    • namestringrequired
    • emailstringrequired
    • phonestring | nullrequired
    • citystring | nullrequired
    • linksstring[]required
    • language"en" | "pt" | "es" | "fr" | "de"required
    • poolobject | nullrequired

      In the talent pool until then (their consent).

      1 field
      • untilstringrequired
  • columnstringrequired

    new, a step id, offer or hired.

  • status"active" | "hired" | "rejected" | "withdrawn"required

    active (in the process), hired, or rejected ("not this time", told or about to be).

  • sourcestring (enum)required

    One of: careers, share, referral, job_site, talent_pool, manual, internal.

  • referredbooleanrequired

    A colleague's referral (referrals on).

  • applied_atstringrequired
  • moved_atstringrequired
  • answer_due_onstring | nullrequired

    The answer promise: the date the company answers by (working days from the last move or message).

  • overduebooleanrequired

    Still open and the promised date has passed.

  • replyobject | nullrequired

    "Not this time": when the kind email goes out (cancellable until sent).

    3 fields
    • send_atstringrequired
    • emailbooleanrequired
    • sentbooleanrequired
  • has_cvbooleanrequired
  • cv_unread"no_credits"required

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

  • notesintegerrequired
  • feedbackobject | nullrequired

    Feedback in for the interviews held ("Feedback 1 of 2"); null before any interview was held.

    2 fields
    • submittedintegerrequired
    • expectedintegerrequired
  • internalobject | nullrequired

    W7: 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 | nullrequired
    • unitstring | nullrequired
    • locationstring | nullrequired
    • tenureobject | nullrequired
      2 fields
      • yearsintegerrequired
      • monthsintegerrequired
    • start_datestring | nullrequired
    • notestring | nullrequired

      "Why this job?" (the hiring team and HR).

    • person_idstring | nullrequired

      HR only: the person in People.

  • jobobjectrequired
    4 fields
    • idstringrequired
    • titlestringrequired
    • status"draft" | "open" | "paused" | "closed"required
    • language"en" | "pt" | "es" | "fr" | "de"required
  • source_sitestring | nullrequired
  • cvobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • sizenumberrequired
    • urlstring | nullrequired

      A download link valid for 5 minutes (in the app only).

  • answersobject[]required
    3 fields
    • question_idstringrequired
    • questionstringrequired
    • answerstringrequired
  • pay_expectationobject | nullrequired
    3 fields
    • amountnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
  • pay_hiddenbooleanrequired

    True over an API key or MCP: pay expectations stay in the app.

  • referrerobject | nullrequired

    The colleague who referred them (referrals on).

    2 fields
    • idstringrequired
    • namestringrequired
  • reply_reasonstring | nullrequired
  • other_applicationsobject[]required
    5 fields
    • idstringrequired
    • job_idstringrequired
    • job_titlestringrequired
    • status"active" | "hired" | "rejected" | "withdrawn"required
    • columnstringrequired
  • eventsobject[]required
    15 fields
    • idstringrequired
    • kindstring (enum)required

      One of: received, added, moved, message, note, interview, feedback, offer, hired, rejected, reopened, withdrawn.

    • atstringrequired
    • byobject | nullrequired

      The colleague who did it; null for the candidate, Bizisy or a machine.

      2 fields
      • idstringrequired
      • namestringrequired
    • privatebooleanrequired

      A note only HR sees.

    • minebooleanrequired

      Yours (you can delete your own notes).

    • textstring | nullrequired

      A note, a message's text or the interview notes.

    • subjectstring | nullrequired
    • templatestring | nullrequired

      For emails to the candidate: received, step, message, not_this_time, added, link.

    • fromstring | nullrequired
    • tostring | nullrequired

      Moves: the columns.

    • datestring | nullrequired

      Interviews: when it was held.

    • step_idstring | nullrequired
    • fileobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • sizenumberrequired
      • urlstring | nullrequired

        A download link valid for 5 minutes (in the app only).

    • reasonstring | nullrequired

      "Not this time": the internal reason (never told).

  • feedback_by_stepobject[]required

    I11: 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
    • stepobjectrequired
      2 fields
      • idstringrequired
      • namestring | nullrequired
    • interviewsintegerrequired

      Interviews held at this step.

    • expectedintegerrequired

      Feedback expected: one per interviewer of each interview held.

    • submittedintegerrequired

      Feedback sent.

    • entriesobject[]required

      The feedback you may read (HR and the hiring manager: every one sent). Never averaged or compared across candidates.

      17 fields
      • idstringrequired
      • interview_idstringrequired
      • application_idstring | nullrequired
      • stepobjectrequired
        2 fields
        • idstringrequired
        • namestring | nullrequired
      • authorobject | nullrequired

        Who wrote it; null once they were erased (show "A former colleague").

        2 fields
        • idstringrequired
        • namestringrequired
      • author_erasedbooleanrequired
      • minebooleanrequired

        Yours.

      • status"draft" | "submitted"required

        draft: only its author sees it; submitted: final (correction notes may follow).

      • ratingsobject[]required

        1 (clear concerns) to 4 (excellent) per skill of the step's scorecard.

        3 fields
        • skill_idstringrequired
        • namestringrequired
        • ratingintegerrequired

          From 1 to 4.

      • textstringrequired
      • overallstring | nullrequired

        The answer to the scorecard's overall question.

      • recommendation"strong_no" | "no" | "yes" | "strong_yes"required
      • due_atstringrequired
      • submitted_atstring | nullrequired
      • on_timeboolean | nullrequired

        Sent by the time it was due.

      • notesobject[]required

        Corrections added after sending.

        2 fields
        • textstringrequired
        • atstringrequired
      • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/hiring/applications.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"application_id":"a1"}'
Response
{
  "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_move on HR Assistant, My Workplace
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • application_idsstring[]required

    1–100 characters. 1–100 items.

  • tostringrequired

    new, a step id or offer.

    1–40 characters.

  • emailboolean

    Default false.

  • textstring

    Up to 3000 characters.

Returns

  • movedintegerrequired
  • emailedintegerrequired
  • applicationsobject[]required
    16 fields
    • idstringrequired
    • candidateobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • columnstringrequired

      new, a step id, offer or hired.

    • status"active" | "hired" | "rejected" | "withdrawn"required

      active (in the process), hired, or rejected ("not this time", told or about to be).

    • sourcestring (enum)required

      One of: careers, share, referral, job_site, talent_pool, manual, internal.

    • referredbooleanrequired

      A colleague's referral (referrals on).

    • applied_atstringrequired
    • moved_atstringrequired
    • answer_due_onstring | nullrequired

      The answer promise: the date the company answers by (working days from the last move or message).

    • overduebooleanrequired

      Still open and the promised date has passed.

    • replyobject | nullrequired

      "Not this time": when the kind email goes out (cancellable until sent).

      3 fields
      • send_atstringrequired
      • emailbooleanrequired
      • sentbooleanrequired
    • has_cvbooleanrequired
    • cv_unread"no_credits"required

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

    • notesintegerrequired
    • feedbackobject | nullrequired

      Feedback in for the interviews held ("Feedback 1 of 2"); null before any interview was held.

      2 fields
      • submittedintegerrequired
      • expectedintegerrequired
    • internalobject | nullrequired

      W7: 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 | nullrequired
      • unitstring | nullrequired
      • locationstring | nullrequired
      • tenureobject | nullrequired
        2 fields
        • yearsintegerrequired
        • monthsintegerrequired
      • start_datestring | nullrequired
      • notestring | nullrequired

        "Why this job?" (the hiring team and HR).

      • person_idstring | nullrequired

        HR only: the person in People.

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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."
}'
Response
{
  "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_reject on HR Assistant, My Workplace
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • application_idsstring[]required

    1–100 characters. 1–100 items.

  • reasonstring

    Up to 500 characters.

  • emailboolean

    Default true.

  • delay_daysinteger

    From 0 to 14.

Returns

  • decidedintegerrequired
  • send_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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
}'
Response
{
  "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_reject on HR Assistant, My Workplace
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • application_idsstring[]required

    1–100 characters. 1–100 items.

Returns

  • reopenedintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"]}'
Response
{
  "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_note on HR Assistant, My Workplace
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • textstringrequired

    1–5000 characters.

  • privateboolean

    Default false.

Returns

  • idstringrequired
  • application_idstringrequired
  • privatebooleanrequired
  • atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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}'
Response
{
  "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_delete on HR Assistant, My Workplace
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • application_idstringrequired

    1–100 characters.

  • note_idstringrequired

    1–100 characters.

Returns

  • deletedtruerequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_interview on HR Assistant, My Workplace
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • datestringrequired

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • step_idstring

    1–40 characters.

  • notesstring

    Up to 5000 characters.

  • file_idstring

    1–100 characters.

Returns

  • idstringrequired
  • application_idstringrequired
  • datestringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
}'
Response
{
  "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_message on HR Assistant, My Workplace
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • subjectstringrequired

    1–150 characters.

  • textstringrequired

    1–5000 characters.

Returns

  • application_idstringrequired
  • sentbooleanrequired
  • reply_to"hiring_manager" | "none"required

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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?"
}'
Response
{
  "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_url on HR Assistant, My Workplace
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • namestringrequired

    1–200 characters.

  • sizeintegerrequired

    From 1 to 10000000.

  • content_type"application/pdf" | "application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "image/jpeg" | "image/png" | "image/heic"required
  • sha256stringrequired

    Pattern ^[0-9a-f]{64}$.

Returns

  • file_idstringrequired
  • uploadobject | nullrequired
    4 fields
    • urlstringrequired
    • method"PUT"required
    • headersobjectrequired
    • resumablefalserequired
  • expires_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
}'
Response
{
  "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_add on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • file_idstringrequired

    1–100 characters.

  • namestringrequired

    1–120 characters.

  • emailemailrequired

    Up to 254 characters.

  • phonestring

    Up to 40 characters. Pattern ^[+()\d\s./-]*$.

  • columnstring

    1–40 characters. Default "new".

  • notestring

    1–5000 characters.

Returns

16 fields
  • idstringrequired
  • candidateobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • columnstringrequired

    new, a step id, offer or hired.

  • status"active" | "hired" | "rejected" | "withdrawn"required

    active (in the process), hired, or rejected ("not this time", told or about to be).

  • sourcestring (enum)required

    One of: careers, share, referral, job_site, talent_pool, manual, internal.

  • referredbooleanrequired

    A colleague's referral (referrals on).

  • applied_atstringrequired
  • moved_atstringrequired
  • answer_due_onstring | nullrequired

    The answer promise: the date the company answers by (working days from the last move or message).

  • overduebooleanrequired

    Still open and the promised date has passed.

  • replyobject | nullrequired

    "Not this time": when the kind email goes out (cancellable until sent).

    3 fields
    • send_atstringrequired
    • emailbooleanrequired
    • sentbooleanrequired
  • has_cvbooleanrequired
  • cv_unread"no_credits"required

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

  • notesintegerrequired
  • feedbackobject | nullrequired

    Feedback in for the interviews held ("Feedback 1 of 2"); null before any interview was held.

    2 fields
    • submittedintegerrequired
    • expectedintegerrequired
  • internalobject | nullrequired

    W7: 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 | nullrequired
    • unitstring | nullrequired
    • locationstring | nullrequired
    • tenureobject | nullrequired
      2 fields
      • yearsintegerrequired
      • monthsintegerrequired
    • start_datestring | nullrequired
    • notestring | nullrequired

      "Why this job?" (the hiring team and HR).

    • person_idstring | nullrequired

      HR only: the person in People.

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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."
}'
Response
{
  "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_cv on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

Returns

  • namestring | nullrequired
  • emailstring | nullrequired
  • phonestring | nullrequired
  • foundbooleanrequired

    false: nothing could be read (or a dry run, which reads nothing).

  • ai_creditsobjectrequired
    3 fields
    • costintegerrequired

      AI credits this read used (0 when Bizisy read the text itself; on a dry run, what it would use).

    • leftinteger | nullrequired

      AI credits the company has left; null when unlimited.

    • notestringrequired

      The 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
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"}'
Response
{
  "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_draft on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • application_idstringrequired

    1–100 characters.

Returns

22 fields
  • application_idstringrequired
  • job_idstringrequired
  • position_idstring | nullrequired

    The job's position, while it is open or on hold: the hire fills it.

  • given_namestringrequired
  • family_namestringrequired
  • personal_emailstringrequired
  • personal_phonestring | nullrequired
  • titlestringrequired
  • unit_idstring | nullrequired
  • location_idstring | nullrequired
  • legal_entity_idstring | nullrequired
  • manager_idstring | nullrequired
  • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
  • weekly_hoursnumber | nullrequired
  • start_datestringrequired
  • start_date_source"position" | "suggested" | "offer"required

    position: its target start; suggested: about 30 days from today (a notice period), a Monday; offer: the offer's.

  • payobject | nullrequired

    A suggestion only (the middle of the job's range): change it to what was agreed.

    5 fields
    • amountnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
    • suggestionbooleanrequired

      true: the middle of the range, change it; false: from the offer.

    • rangeobject | nullrequired
      2 fields
      • minnumberrequired
      • maxnumberrequired
  • pay_hiddenbooleanrequired
  • inviteobjectrequired

    The sign-in invite on their first day (change it in the hire).

    1 field
    • when"start" | "none"required
  • sourceobjectrequired

    Pass it to org_people_hire: the candidate becomes hired, linked to the person.

    3 fields
    • kind"hiring"required
    • job_idstringrequired
    • application_idstringrequired
  • referrerobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • offerobject | nullrequired

    Phase 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
    • idstringrequired
    • statusstringrequired
    • work_emailstring | nullrequired
    • contract_end_datestring | nullrequired
    • probation_end_datestring | nullrequired
    • failedstring | nullrequired

      Why the hire could not run by itself after the acceptance.

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_me on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • referralsobjectrequired
    4 fields
    • enabledbooleanrequired
    • bonusbooleanrequired
    • earned"start" | "probation" | "months"required

      With the bonus on: when it is earned (the start date, the end of probation, or after months employed).

    • monthsinteger | nullrequired
  • jobsobject[]required
    20 fields
    • idstringrequired
    • slugstringrequired
    • titlestringrequired
    • language"en" | "pt" | "es" | "fr" | "de"required
    • urlstringrequired

      Its careers page (without your share code).

    • unitstring | nullrequired
    • locationobject | nullrequired
      3 fields
      • namestringrequired
      • citystring | nullrequired
      • countrystringrequired
    • workplace"on_site" | "hybrid" | "remote"required
    • employment_type"full_time" | "part_time" | "contract" | "temporary" | "internship"required
    • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
    • weekly_hoursnumber | nullrequired
    • salaryobject | nullrequired

      The range the post shows.

      4 fields
      • minnumberrequired
      • maxnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
    • posted_onstringrequired
    • bonusobject | nullrequired

      The 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
      • amountnumberrequired
      • currencystringrequired
      • applies_to_youbooleanrequired
    • my_applicantsintegerrequired

      People who applied with your link (a count only).

    • audience"public" | "internal_first" | "internal_only"required

      public: open to all (careers page too); internal_first: for people who work here first, public later; internal_only: only for people who work here.

    • shareablebooleanrequired

      On the careers page now, so it can be shared and referred (internal posts can't).

    • can_applybooleanrequired

      You can apply from My workspace (hiring_internal_apply): internal jobs on and nothing blocks it.

    • blockedobject | nullrequired

      Why 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"required
      • untilstring | nullrequired
      • monthsinteger
    • my_applicationobject | nullrequired

      Your live application to it, if any.

      1 field
      • idstringrequired
  • internalobjectrequired

    Internal jobs (Settings → Hiring): whether you can apply from My workspace, and the company's rules for applying.

    3 fields
    • enabledbooleanrequired
    • min_months_in_jobinteger | nullrequired
    • allow_in_probationbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/hiring/jobs.open_list_me \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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
    }
  }
}

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_link on My Workplace, HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • job_idstringrequired

    1–100 characters.

  • language"en" | "pt" | "es" | "fr" | "de"

Returns

  • job_idstringrequired
  • codestringrequired
  • urlstringrequired
  • image_urlstringrequired
  • messagestringrequired
  • linksobjectrequired
    5 fields
    • linkedinstringrequired
    • whatsappstringrequired
    • facebookstringrequired
    • xstringrequired
    • emailstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

Response
{
  "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_create on My Workplace, HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • namestringrequired

    1–120 characters.

  • emailemailrequired

    Up to 254 characters.

  • notestring

    Up to 300 characters.

  • consenttruerequired

    They agreed to be contacted about this job.

Returns

  • idstringrequired
  • job_idstringrequired
  • state"invited"required

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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
}'
Response
{
  "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_mine on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • enabledbooleanrequired
  • referralsobject[]required
    7 fields
    • idstringrequired
    • jobobjectrequired
      2 fields
      • idstringrequired
      • titlestringrequired
    • namestring | nullrequired

      The person you invited (null for someone who applied with your link: you never see who).

    • via"invite" | "link"required
    • state"invited" | "applied" | "in_process" | "hired" | "not_this_time" | "closed"required
    • bonusobject | nullrequired
      7 fields
      • amountnumberrequired
      • currencystringrequired
      • state"waiting" | "due" | "in_payroll" | "paid" | "not_due"required
      • due_onstring | nullrequired
      • earned"start" | "probation" | "months"required
      • monthsinteger | nullrequired
      • payrollobject | nullrequired

        in_payroll (and paid through payroll): the pay period it is in, as its first and last day.

        2 fields
        • startstringrequired
        • endstringrequired
    • created_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/hiring/referrals.mine \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • job_idstring

    1–100 characters.

  • bonus"waiting" | "due" | "in_payroll" | "paid" | "not_due"
  • limitinteger

    From 1 to 1000. Default 200.

Returns

  • referralsobject[]required
    11 fields
    • idstringrequired
    • jobobjectrequired
      2 fields
      • idstringrequired
      • titlestringrequired
    • referrerobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • candidateobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • application_idstringrequired
    • contact_namestring | nullrequired

      An invitation not answered yet: the name the referrer gave.

    • notestring | nullrequired
    • via"invite" | "link"required
    • state"invited" | "applied" | "in_process" | "hired" | "not_this_time" | "closed"required
    • bonusobject | nullrequired
      8 fields
      • amountnumberrequired
      • currencystringrequired
      • state"waiting" | "due" | "in_payroll" | "paid" | "not_due"required
      • due_onstring | nullrequired
      • earned"start" | "probation" | "months"required
      • monthsinteger | nullrequired
      • payrollobject | nullrequired

        in_payroll (and paid through payroll): the pay period it is in, as its first and last day.

        2 fields
        • startstringrequired
        • endstringrequired
      • paid_atstring | nullrequired
    • bonus_hiddenbooleanrequired
    • created_atstringrequired
  • totalintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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}'
Response
{
  "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_paid on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • referral_idstringrequired

    1–100 characters.

Returns

  • idstringrequired
  • state"paid"required
  • paid_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_you on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

9 fields
  • jobsobject[]required
    5 fields
    • idstringrequired
    • titlestringrequired
    • newintegerrequired

      Candidates in New (not answered yet).

    • overdueintegerrequired

      Candidates past the answer promise.

    • earliest_duestring | nullrequired

      The oldest promised date passed (YYYY-MM-DD).

  • overdueintegerrequired
  • newintegerrequired
  • bonuses_dueintegerrequired
  • interviews_to_rebookintegerrequired

    Interviews to arrange again: offers nobody picked in 48 hours, candidates who asked for other times or cancelled (hiring_interviews_list).

  • feedback_overdueintegerrequired

    Interview 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_approvalintegerrequired

    Job offers waiting for your approval (hiring_offers_list with waiting_for_me true).

  • offers_expiringintegerrequired

    Sent job offers ending within 2 days on your jobs.

  • finish_hireintegerrequired

    HR: 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
curl https://api.bizisy.com/v1/hiring/home.needs_you \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_erase on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

Returns

  • erasedtruerequired
  • applicationsintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_export on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • candidate_idstringrequired

    1–100 characters.

Returns

  • candidateobjectrequired
  • applicationsobject[]required
  • filesobject[]required
    4 fields
    • namestringrequired
    • sizenumberrequired
    • urlstring | nullrequired
    • expires_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/hiring/candidates.export \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"candidate_id":"c1"}'
Response
{
  "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_list on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • include_archivedboolean

    Default false.

Returns

  • poolsobject[]required
    8 fields
    • idstringrequired
    • namestringrequired
    • peopleobject[]required

      The people named in the group (erased people drop out).

      3 fields
      • idstringrequired
      • namestringrequired
      • activebooleanrequired

        Employed now (others are skipped when interviews are booked).

    • unitsobject[]required
      3 fields
      • idstringrequired
      • namestringrequired
      • membersintegerrequired

        People employed now whose team it is.

    • membersintegerrequired

      Everyone it resolves to today: its people and its teams' members, employed now.

    • archivedbooleanrequired
    • created_atstringrequired
    • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/hiring/pools.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"include_archived":true}'
Response
{
  "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_capacity on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • stepsobject[]required

    1–10 items.

    3 fields
    • keystringrequired

      Your 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[]required
    5 fields
    • keystringrequired
    • peopleintegerrequired

      People who can run it today.

    • hours_a_weeknumberrequired

      Their usual weeks together, each capped by their weekly hour cap.

    • without_weekintegerrequired

      In the group and employed, but without a usual week (nobody books them).

    • pausedintegerrequired

      In 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
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"
    }
  ]
}'
Response
{
  "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_create on HR Assistant
Preview
?dry_run=true runs 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

  • namestringrequired

    1–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
  • idstringrequired
  • namestringrequired
  • peopleobject[]required

    The people named in the group (erased people drop out).

    3 fields
    • idstringrequired
    • namestringrequired
    • activebooleanrequired

      Employed now (others are skipped when interviews are booked).

  • unitsobject[]required
    3 fields
    • idstringrequired
    • namestringrequired
    • membersintegerrequired

      People employed now whose team it is.

  • membersintegerrequired

    Everyone it resolves to today: its people and its teams' members, employed now.

  • archivedbooleanrequired
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"]}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • namestring

    1–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
  • idstringrequired
  • namestringrequired
  • peopleobject[]required

    The people named in the group (erased people drop out).

    3 fields
    • idstringrequired
    • namestringrequired
    • activebooleanrequired

      Employed now (others are skipped when interviews are booked).

  • unitsobject[]required
    3 fields
    • idstringrequired
    • namestringrequired
    • membersintegerrequired

      People employed now whose team it is.

  • membersintegerrequired

    Everyone it resolves to today: its people and its teams' members, employed now.

  • archivedbooleanrequired
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
  ]
}'
Response
{
  "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_archive on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • archivedboolean

    Default true.

Returns

8 fields
  • idstringrequired
  • namestringrequired
  • peopleobject[]required

    The people named in the group (erased people drop out).

    3 fields
    • idstringrequired
    • namestringrequired
    • activebooleanrequired

      Employed now (others are skipped when interviews are booked).

  • unitsobject[]required
    3 fields
    • idstringrequired
    • namestringrequired
    • membersintegerrequired

      People employed now whose team it is.

  • membersintegerrequired

    Everyone it resolves to today: its people and its teams' members, employed now.

  • archivedbooleanrequired
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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}'
Response
{
  "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_get on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • person_idstring

    1–100 characters.

Returns

9 fields
  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • setbooleanrequired

    They have said when they can usually interview (without it nobody books them).

  • time_zonestringrequired

    Their time zone: their location's, else the company's. Windows are in it.

  • windowsobject[]required
    3 fields
    • dayintegerrequired

      1 Monday … 7 Sunday.

      From 1 to 7.

    • fromstringrequired

      Pattern ^(?:[01]\d|2[0-3]):[03]0$|^24:00$.

    • tostringrequired

      Pattern ^(?:[01]\d|2[0-3]):[03]0$|^24:00$.

  • hours_a_weeknumberrequired

    Hours the windows cover in a week.

  • capobjectrequired
    2 fields
    • interviewsintegerrequired

      Interviews a week at most (0: none for now).

      From 0 to 10.

    • hoursnumber | nullrequired

      Hours of interviews a week at most; null: no hour limit.

      From 0 to 20.

  • paused_untilstring | nullrequired

    Not asked until this day (inclusive).

  • loadobjectrequired
    2 fields
    • weekobjectrequired

      This ISO week: interviews booked or held, and their hours.

      2 fields
      • interviewsintegerrequired
      • hoursnumberrequired
    • monthintegerrequired

      Interviews held and booked this calendar month.

  • updated_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/hiring/availability.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person_id":"p4"}'
Response
{
  "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_set on HR Assistant, My Workplace
Preview
?dry_run=true runs 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_idstring

    1–100 characters.

  • windowsobject[]

    Up to 336 items.

    3 fields
    • dayintegerrequired

      1 Monday … 7 Sunday.

      From 1 to 7.

    • fromstringrequired

      Pattern ^(?:[01]\d|2[0-3]):[03]0$|^24:00$.

    • tostringrequired

      Pattern ^(?:[01]\d|2[0-3]):[03]0$|^24:00$.

  • capobject
    2 fields
    • interviewsintegerrequired

      Interviews a week at most (0: none for now).

      From 0 to 10.

    • hoursnumber | nullrequired

      Hours of interviews a week at most; null: no hour limit.

      From 0 to 20.

  • paused_untilstring | null

    Pattern ^\d{4}-\d{2}-\d{2}$.

Returns

9 fields
  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • setbooleanrequired

    They have said when they can usually interview (without it nobody books them).

  • time_zonestringrequired

    Their time zone: their location's, else the company's. Windows are in it.

  • windowsobject[]required
    3 fields
    • dayintegerrequired

      1 Monday … 7 Sunday.

      From 1 to 7.

    • fromstringrequired

      Pattern ^(?:[01]\d|2[0-3]):[03]0$|^24:00$.

    • tostringrequired

      Pattern ^(?:[01]\d|2[0-3]):[03]0$|^24:00$.

  • hours_a_weeknumberrequired

    Hours the windows cover in a week.

  • capobjectrequired
    2 fields
    • interviewsintegerrequired

      Interviews a week at most (0: none for now).

      From 0 to 10.

    • hoursnumber | nullrequired

      Hours of interviews a week at most; null: no hour limit.

      From 0 to 20.

  • paused_untilstring | nullrequired

    Not asked until this day (inclusive).

  • loadobjectrequired
    2 fields
    • weekobjectrequired

      This ISO week: interviews booked or held, and their hours.

      2 fields
      • interviewsintegerrequired
      • hoursnumberrequired
    • monthintegerrequired

      Interviews held and booked this calendar month.

  • updated_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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
  }
}'
Response
{
  "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_slots on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • application_idstringrequired

    1–100 characters.

  • step_idstring

    1–40 characters.

Returns

8 fields
  • application_idstringrequired
  • stepobjectrequired
    5 fields
    • idstringrequired
    • namestringrequired
    • minutesintegerrequired
    • buffer_minutesintegerrequired
    • interviewers_neededintegerrequired
  • time_zonestringrequired

    The company's time zone: date and time of each start are in it.

  • daysintegerrequired

    Days looked ahead (14; 21 for interviews over 3 hours).

  • timesobject[]required
    6 fields
    • startstringrequired
    • endstringrequired
    • datestringrequired
    • timestringrequired
    • peoplestring[]required

      Everyone available then (person ids; names in people below).

    • suggestedstring[]required

      Who Bizisy suggests: the least loaded this month, then that week.

  • peopleobject[]required
    4 fields
    • idstringrequired
    • namestringrequired
    • time_zonestringrequired
    • loadobjectrequired

      Interviews held and booked this month and this week.

      2 fields
      • monthintegerrequired
      • weekintegerrequired
  • missing_availabilityobject[]required

    In the step's interview group but without a usual week set: nobody books them until they set one.

    2 fields
    • idstringrequired
    • namestringrequired
  • referrer_excludedbooleanrequired

    The colleague who referred this candidate is left out (conflict of interest).

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_list on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • application_idstring

    1–100 characters.

  • job_idstring

    1–100 characters.

  • upcomingboolean

    Default false.

Returns

  • interviewsobject[]required
    24 fields
    • idstringrequired
    • job_idstringrequired
    • application_idstring | nullrequired
    • candidateobject | nullrequired

      The candidate (their name as they applied).

      2 fields
      • idstringrequired
      • namestringrequired
    • stepobjectrequired
      2 fields
      • idstringrequired
      • namestring | nullrequired
    • status"offered" | "booked" | "requested" | "expired" | "cancelled" | "no_show"required

      offered (times held for the candidate), booked, requested (the candidate asked for other times), expired (the offer lapsed), cancelled, no_show.

    • heldbooleanrequired

      Booked and already over.

    • minutesintegerrequired
    • buffer_minutesintegerrequired
    • placeobjectrequired
      4 fields
      • kind"video" | "video_auto" | "phone" | "on_site" | "none"required

        video (a link HR pasted), video_auto (a Google Meet or Teams link the connected calendar makes), phone, on_site, none.

      • addressstring | nullrequired
      • linkstring | nullrequired

        The meeting link: pasted, or made by the calendar (video_auto; null until made).

      • link_source"google_meet" | "teams"required

        google_meet or teams: the calendar made the link; null: pasted, or none yet.

    • calendarobject | nullrequired

      Held 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"required
      • namestringrequired
      • state"pending" | "synced" | "fallback"required

        pending: 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_linkbooleanrequired

        The step asked for a video link and the calendar made none (a Microsoft account without Teams).

    • startstring | nullrequired
    • endstring | nullrequired
    • interviewersobject[]required
      2 fields
      • idstringrequired
      • namestringrequired
    • offersobject[]required

      The times offered (while offered).

      3 fields
      • startstringrequired
      • endstringrequired
      • interviewersobject[]required
        2 fields
        • idstringrequired
        • namestringrequired
    • hold_untilstring | nullrequired

      Offered times are held until then.

    • reschedulesintegerrequired
    • change_requestedobject | nullrequired

      The candidate asked for another time (status page).

      2 fields
      • atstringrequired
      • notestring | nullrequired
    • needs_hrbooleanrequired

      On Home: the offer expired, or the candidate asked for other times.

    • booked_by"team" | "candidate"required
    • cancelledobject | nullrequired
      2 fields
      • atstringrequired
      • by"team" | "candidate" | "system"required
    • erased_interviewersintegerrequired
    • created_atstringrequired
    • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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}'
Response
{
  "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_book on HR Assistant, My Workplace
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • step_idstring

    1–40 characters.

  • startdate-timerequired

    ISO 8601 date and time (UTC).

  • interviewer_idsstring[]required

    1–100 characters. 1–5 items.

  • messagestring | null

    A 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
  • idstringrequired
  • job_idstringrequired
  • application_idstring | nullrequired
  • candidateobject | nullrequired

    The candidate (their name as they applied).

    2 fields
    • idstringrequired
    • namestringrequired
  • stepobjectrequired
    2 fields
    • idstringrequired
    • namestring | nullrequired
  • status"offered" | "booked" | "requested" | "expired" | "cancelled" | "no_show"required

    offered (times held for the candidate), booked, requested (the candidate asked for other times), expired (the offer lapsed), cancelled, no_show.

  • heldbooleanrequired

    Booked and already over.

  • minutesintegerrequired
  • buffer_minutesintegerrequired
  • placeobjectrequired
    4 fields
    • kind"video" | "video_auto" | "phone" | "on_site" | "none"required

      video (a link HR pasted), video_auto (a Google Meet or Teams link the connected calendar makes), phone, on_site, none.

    • addressstring | nullrequired
    • linkstring | nullrequired

      The meeting link: pasted, or made by the calendar (video_auto; null until made).

    • link_source"google_meet" | "teams"required

      google_meet or teams: the calendar made the link; null: pasted, or none yet.

  • calendarobject | nullrequired

    Held 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"required
    • namestringrequired
    • state"pending" | "synced" | "fallback"required

      pending: 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_linkbooleanrequired

      The step asked for a video link and the calendar made none (a Microsoft account without Teams).

  • startstring | nullrequired
  • endstring | nullrequired
  • interviewersobject[]required
    2 fields
    • idstringrequired
    • namestringrequired
  • offersobject[]required

    The times offered (while offered).

    3 fields
    • startstringrequired
    • endstringrequired
    • interviewersobject[]required
      2 fields
      • idstringrequired
      • namestringrequired
  • hold_untilstring | nullrequired

    Offered times are held until then.

  • reschedulesintegerrequired
  • change_requestedobject | nullrequired

    The candidate asked for another time (status page).

    2 fields
    • atstringrequired
    • notestring | nullrequired
  • needs_hrbooleanrequired

    On Home: the offer expired, or the candidate asked for other times.

  • booked_by"team" | "candidate"required
  • cancelledobject | nullrequired
    2 fields
    • atstringrequired
    • by"team" | "candidate" | "system"required
  • erased_interviewersintegerrequired
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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."
}'
Response
{
  "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_offer on HR Assistant, My Workplace
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • step_idstring

    1–40 characters.

  • timesobject[]required

    1–8 items.

    2 fields
    • startdate-timerequired

      ISO 8601 date and time (UTC).

    • interviewer_idsstring[]

      1–100 characters. 1–5 items.

  • messagestring | null

    A 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
  • idstringrequired
  • job_idstringrequired
  • application_idstring | nullrequired
  • candidateobject | nullrequired

    The candidate (their name as they applied).

    2 fields
    • idstringrequired
    • namestringrequired
  • stepobjectrequired
    2 fields
    • idstringrequired
    • namestring | nullrequired
  • status"offered" | "booked" | "requested" | "expired" | "cancelled" | "no_show"required

    offered (times held for the candidate), booked, requested (the candidate asked for other times), expired (the offer lapsed), cancelled, no_show.

  • heldbooleanrequired

    Booked and already over.

  • minutesintegerrequired
  • buffer_minutesintegerrequired
  • placeobjectrequired
    4 fields
    • kind"video" | "video_auto" | "phone" | "on_site" | "none"required

      video (a link HR pasted), video_auto (a Google Meet or Teams link the connected calendar makes), phone, on_site, none.

    • addressstring | nullrequired
    • linkstring | nullrequired

      The meeting link: pasted, or made by the calendar (video_auto; null until made).

    • link_source"google_meet" | "teams"required

      google_meet or teams: the calendar made the link; null: pasted, or none yet.

  • calendarobject | nullrequired

    Held 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"required
    • namestringrequired
    • state"pending" | "synced" | "fallback"required

      pending: 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_linkbooleanrequired

      The step asked for a video link and the calendar made none (a Microsoft account without Teams).

  • startstring | nullrequired
  • endstring | nullrequired
  • interviewersobject[]required
    2 fields
    • idstringrequired
    • namestringrequired
  • offersobject[]required

    The times offered (while offered).

    3 fields
    • startstringrequired
    • endstringrequired
    • interviewersobject[]required
      2 fields
      • idstringrequired
      • namestringrequired
  • hold_untilstring | nullrequired

    Offered times are held until then.

  • reschedulesintegerrequired
  • change_requestedobject | nullrequired

    The candidate asked for another time (status page).

    2 fields
    • atstringrequired
    • notestring | nullrequired
  • needs_hrbooleanrequired

    On Home: the offer expired, or the candidate asked for other times.

  • booked_by"team" | "candidate"required
  • cancelledobject | nullrequired
    2 fields
    • atstringrequired
    • by"team" | "candidate" | "system"required
  • erased_interviewersintegerrequired
  • created_atstringrequired
  • updated_atstringrequired
  • emailedbooleanrequired

    The candidate was emailed the times.

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
      ]
    }
  ]
}'
Response
{
  "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_reschedule on HR Assistant, My Workplace
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • startdate-timerequired

    ISO 8601 date and time (UTC).

  • interviewer_idsstring[]

    1–100 characters. 1–5 items.

  • messagestring | null

    A 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
  • idstringrequired
  • job_idstringrequired
  • application_idstring | nullrequired
  • candidateobject | nullrequired

    The candidate (their name as they applied).

    2 fields
    • idstringrequired
    • namestringrequired
  • stepobjectrequired
    2 fields
    • idstringrequired
    • namestring | nullrequired
  • status"offered" | "booked" | "requested" | "expired" | "cancelled" | "no_show"required

    offered (times held for the candidate), booked, requested (the candidate asked for other times), expired (the offer lapsed), cancelled, no_show.

  • heldbooleanrequired

    Booked and already over.

  • minutesintegerrequired
  • buffer_minutesintegerrequired
  • placeobjectrequired
    4 fields
    • kind"video" | "video_auto" | "phone" | "on_site" | "none"required

      video (a link HR pasted), video_auto (a Google Meet or Teams link the connected calendar makes), phone, on_site, none.

    • addressstring | nullrequired
    • linkstring | nullrequired

      The meeting link: pasted, or made by the calendar (video_auto; null until made).

    • link_source"google_meet" | "teams"required

      google_meet or teams: the calendar made the link; null: pasted, or none yet.

  • calendarobject | nullrequired

    Held 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"required
    • namestringrequired
    • state"pending" | "synced" | "fallback"required

      pending: 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_linkbooleanrequired

      The step asked for a video link and the calendar made none (a Microsoft account without Teams).

  • startstring | nullrequired
  • endstring | nullrequired
  • interviewersobject[]required
    2 fields
    • idstringrequired
    • namestringrequired
  • offersobject[]required

    The times offered (while offered).

    3 fields
    • startstringrequired
    • endstringrequired
    • interviewersobject[]required
      2 fields
      • idstringrequired
      • namestringrequired
  • hold_untilstring | nullrequired

    Offered times are held until then.

  • reschedulesintegerrequired
  • change_requestedobject | nullrequired

    The candidate asked for another time (status page).

    2 fields
    • atstringrequired
    • notestring | nullrequired
  • needs_hrbooleanrequired

    On Home: the offer expired, or the candidate asked for other times.

  • booked_by"team" | "candidate"required
  • cancelledobject | nullrequired
    2 fields
    • atstringrequired
    • by"team" | "candidate" | "system"required
  • erased_interviewersintegerrequired
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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."
}'
Response
{
  "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_cancel on HR Assistant, My Workplace
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

Returns

24 fields
  • idstringrequired
  • job_idstringrequired
  • application_idstring | nullrequired
  • candidateobject | nullrequired

    The candidate (their name as they applied).

    2 fields
    • idstringrequired
    • namestringrequired
  • stepobjectrequired
    2 fields
    • idstringrequired
    • namestring | nullrequired
  • status"offered" | "booked" | "requested" | "expired" | "cancelled" | "no_show"required

    offered (times held for the candidate), booked, requested (the candidate asked for other times), expired (the offer lapsed), cancelled, no_show.

  • heldbooleanrequired

    Booked and already over.

  • minutesintegerrequired
  • buffer_minutesintegerrequired
  • placeobjectrequired
    4 fields
    • kind"video" | "video_auto" | "phone" | "on_site" | "none"required

      video (a link HR pasted), video_auto (a Google Meet or Teams link the connected calendar makes), phone, on_site, none.

    • addressstring | nullrequired
    • linkstring | nullrequired

      The meeting link: pasted, or made by the calendar (video_auto; null until made).

    • link_source"google_meet" | "teams"required

      google_meet or teams: the calendar made the link; null: pasted, or none yet.

  • calendarobject | nullrequired

    Held 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"required
    • namestringrequired
    • state"pending" | "synced" | "fallback"required

      pending: 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_linkbooleanrequired

      The step asked for a video link and the calendar made none (a Microsoft account without Teams).

  • startstring | nullrequired
  • endstring | nullrequired
  • interviewersobject[]required
    2 fields
    • idstringrequired
    • namestringrequired
  • offersobject[]required

    The times offered (while offered).

    3 fields
    • startstringrequired
    • endstringrequired
    • interviewersobject[]required
      2 fields
      • idstringrequired
      • namestringrequired
  • hold_untilstring | nullrequired

    Offered times are held until then.

  • reschedulesintegerrequired
  • change_requestedobject | nullrequired

    The candidate asked for another time (status page).

    2 fields
    • atstringrequired
    • notestring | nullrequired
  • needs_hrbooleanrequired

    On Home: the offer expired, or the candidate asked for other times.

  • booked_by"team" | "candidate"required
  • cancelledobject | nullrequired
    2 fields
    • atstringrequired
    • by"team" | "candidate" | "system"required
  • erased_interviewersintegerrequired
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_show on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

Returns

24 fields
  • idstringrequired
  • job_idstringrequired
  • application_idstring | nullrequired
  • candidateobject | nullrequired

    The candidate (their name as they applied).

    2 fields
    • idstringrequired
    • namestringrequired
  • stepobjectrequired
    2 fields
    • idstringrequired
    • namestring | nullrequired
  • status"offered" | "booked" | "requested" | "expired" | "cancelled" | "no_show"required

    offered (times held for the candidate), booked, requested (the candidate asked for other times), expired (the offer lapsed), cancelled, no_show.

  • heldbooleanrequired

    Booked and already over.

  • minutesintegerrequired
  • buffer_minutesintegerrequired
  • placeobjectrequired
    4 fields
    • kind"video" | "video_auto" | "phone" | "on_site" | "none"required

      video (a link HR pasted), video_auto (a Google Meet or Teams link the connected calendar makes), phone, on_site, none.

    • addressstring | nullrequired
    • linkstring | nullrequired

      The meeting link: pasted, or made by the calendar (video_auto; null until made).

    • link_source"google_meet" | "teams"required

      google_meet or teams: the calendar made the link; null: pasted, or none yet.

  • calendarobject | nullrequired

    Held 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"required
    • namestringrequired
    • state"pending" | "synced" | "fallback"required

      pending: 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_linkbooleanrequired

      The step asked for a video link and the calendar made none (a Microsoft account without Teams).

  • startstring | nullrequired
  • endstring | nullrequired
  • interviewersobject[]required
    2 fields
    • idstringrequired
    • namestringrequired
  • offersobject[]required

    The times offered (while offered).

    3 fields
    • startstringrequired
    • endstringrequired
    • interviewersobject[]required
      2 fields
      • idstringrequired
      • namestringrequired
  • hold_untilstring | nullrequired

    Offered times are held until then.

  • reschedulesintegerrequired
  • change_requestedobject | nullrequired

    The candidate asked for another time (status page).

    2 fields
    • atstringrequired
    • notestring | nullrequired
  • needs_hrbooleanrequired

    On Home: the offer expired, or the candidate asked for other times.

  • booked_by"team" | "candidate"required
  • cancelledobject | nullrequired
    2 fields
    • atstringrequired
    • by"team" | "candidate" | "system"required
  • erased_interviewersintegerrequired
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_calendar on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • connector"google_calendar" | "outlook_calendar"required
  • namestring | nullrequired
  • meeting"google_meet" | "teams"required

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/hiring/interviews.calendar \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_save on My Workplace, HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–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_idstringrequired

      1–40 characters.

    • ratingintegerrequired

      From 1 to 4.

  • textstring

    What you saw, in your words (≤ 5,000 characters). The candidate can ask to read it.

    Up to 5000 characters.

  • overallstring | null

    Your 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
  • idstringrequired
  • interview_idstringrequired
  • application_idstring | nullrequired
  • stepobjectrequired
    2 fields
    • idstringrequired
    • namestring | nullrequired
  • authorobject | nullrequired

    Who wrote it; null once they were erased (show "A former colleague").

    2 fields
    • idstringrequired
    • namestringrequired
  • author_erasedbooleanrequired
  • minebooleanrequired

    Yours.

  • status"draft" | "submitted"required

    draft: only its author sees it; submitted: final (correction notes may follow).

  • ratingsobject[]required

    1 (clear concerns) to 4 (excellent) per skill of the step's scorecard.

    3 fields
    • skill_idstringrequired
    • namestringrequired
    • ratingintegerrequired

      From 1 to 4.

  • textstringrequired
  • overallstring | nullrequired

    The answer to the scorecard's overall question.

  • recommendation"strong_no" | "no" | "yes" | "strong_yes"required
  • due_atstringrequired
  • submitted_atstring | nullrequired
  • on_timeboolean | nullrequired

    Sent by the time it was due.

  • notesobject[]required

    Corrections added after sending.

    2 fields
    • textstringrequired
    • atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
}'
Response
{
  "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_submit on My Workplace, HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–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_idstringrequired

      1–40 characters.

    • ratingintegerrequired

      From 1 to 4.

  • textstring

    What you saw, in your words (≤ 5,000 characters). The candidate can ask to read it.

    Up to 5000 characters.

  • overallstring | null

    Your 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
  • idstringrequired
  • interview_idstringrequired
  • application_idstring | nullrequired
  • stepobjectrequired
    2 fields
    • idstringrequired
    • namestring | nullrequired
  • authorobject | nullrequired

    Who wrote it; null once they were erased (show "A former colleague").

    2 fields
    • idstringrequired
    • namestringrequired
  • author_erasedbooleanrequired
  • minebooleanrequired

    Yours.

  • status"draft" | "submitted"required

    draft: only its author sees it; submitted: final (correction notes may follow).

  • ratingsobject[]required

    1 (clear concerns) to 4 (excellent) per skill of the step's scorecard.

    3 fields
    • skill_idstringrequired
    • namestringrequired
    • ratingintegerrequired

      From 1 to 4.

  • textstringrequired
  • overallstring | nullrequired

    The answer to the scorecard's overall question.

  • recommendation"strong_no" | "no" | "yes" | "strong_yes"required
  • due_atstringrequired
  • submitted_atstring | nullrequired
  • on_timeboolean | nullrequired

    Sent by the time it was due.

  • notesobject[]required

    Corrections added after sending.

    2 fields
    • textstringrequired
    • atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
}'
Response
{
  "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_note on My Workplace, HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • textstringrequired

    1–2000 characters.

Returns

17 fields
  • idstringrequired
  • interview_idstringrequired
  • application_idstring | nullrequired
  • stepobjectrequired
    2 fields
    • idstringrequired
    • namestring | nullrequired
  • authorobject | nullrequired

    Who wrote it; null once they were erased (show "A former colleague").

    2 fields
    • idstringrequired
    • namestringrequired
  • author_erasedbooleanrequired
  • minebooleanrequired

    Yours.

  • status"draft" | "submitted"required

    draft: only its author sees it; submitted: final (correction notes may follow).

  • ratingsobject[]required

    1 (clear concerns) to 4 (excellent) per skill of the step's scorecard.

    3 fields
    • skill_idstringrequired
    • namestringrequired
    • ratingintegerrequired

      From 1 to 4.

  • textstringrequired
  • overallstring | nullrequired

    The answer to the scorecard's overall question.

  • recommendation"strong_no" | "no" | "yes" | "strong_yes"required
  • due_atstringrequired
  • submitted_atstring | nullrequired
  • on_timeboolean | nullrequired

    Sent by the time it was due.

  • notesobject[]required

    Corrections added after sending.

    2 fields
    • textstringrequired
    • atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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."}'
Response
{
  "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_interviews on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • interviewerbooleanrequired

    You 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[]required
    13 fields
    • idstringrequired
    • status"booked" | "no_show"required

      booked (to come or held), or no_show (the candidate did not come: no feedback needed).

    • heldbooleanrequired

      It has ended.

    • jobobjectrequired
      2 fields
      • idstringrequired
      • titlestringrequired
    • stepobjectrequired
      3 fields
      • idstringrequired
      • namestring | nullrequired
      • kindstring (enum)required

        One of: call, interview, panel, task, trial, presentation, references, final.

    • candidateobjectrequired

      Only the name: the kit (hiring_me_interview) has the CV and answers.

      1 field
      • namestringrequired
    • startstringrequired
    • endstringrequired
    • minutesintegerrequired
    • placeobjectrequired
      4 fields
      • kind"video" | "video_auto" | "phone" | "on_site" | "none"required

        video (a link HR pasted), video_auto (a Google Meet or Teams link the connected calendar makes), phone, on_site, none.

      • addressstring | nullrequired
      • linkstring | nullrequired

        The meeting link: pasted, or made by the calendar (video_auto; null until made).

      • link_source"google_meet" | "teams"required

        google_meet or teams: the calendar made the link; null: pasted, or none yet.

    • withobject[]required

      The other interviewers.

      2 fields
      • idstringrequired
      • namestringrequired
    • feedbackobject | nullrequired

      Your feedback: null until the interview has ended (and for no-shows).

      4 fields
      • status"none" | "draft" | "submitted"required
      • due_atstringrequired
      • overduebooleanrequired

        Not sent and past its due time.

      • on_timeboolean | nullrequired
    • access_untilstringrequired

      You can open this candidate until then (30 days after the interview).

  • pastobject[]required
    13 fields
    • idstringrequired
    • status"booked" | "no_show"required

      booked (to come or held), or no_show (the candidate did not come: no feedback needed).

    • heldbooleanrequired

      It has ended.

    • jobobjectrequired
      2 fields
      • idstringrequired
      • titlestringrequired
    • stepobjectrequired
      3 fields
      • idstringrequired
      • namestring | nullrequired
      • kindstring (enum)required

        One of: call, interview, panel, task, trial, presentation, references, final.

    • candidateobjectrequired

      Only the name: the kit (hiring_me_interview) has the CV and answers.

      1 field
      • namestringrequired
    • startstringrequired
    • endstringrequired
    • minutesintegerrequired
    • placeobjectrequired
      4 fields
      • kind"video" | "video_auto" | "phone" | "on_site" | "none"required

        video (a link HR pasted), video_auto (a Google Meet or Teams link the connected calendar makes), phone, on_site, none.

      • addressstring | nullrequired
      • linkstring | nullrequired

        The meeting link: pasted, or made by the calendar (video_auto; null until made).

      • link_source"google_meet" | "teams"required

        google_meet or teams: the calendar made the link; null: pasted, or none yet.

    • withobject[]required

      The other interviewers.

      2 fields
      • idstringrequired
      • namestringrequired
    • feedbackobject | nullrequired

      Your feedback: null until the interview has ended (and for no-shows).

      4 fields
      • status"none" | "draft" | "submitted"required
      • due_atstringrequired
      • overduebooleanrequired

        Not sent and past its due time.

      • on_timeboolean | nullrequired
    • access_untilstringrequired

      You can open this candidate until then (30 days after the interview).

  • held_for_youobject[]required
    5 fields
    • startstringrequired
    • endstringrequired
    • jobobjectrequired
      2 fields
      • idstringrequired
      • titlestringrequired
    • stepobjectrequired
      2 fields
      • idstringrequired
      • namestring | nullrequired
    • untilstringrequired

      The hold ends then unless the candidate picks it.

  • countsobjectrequired
    3 fields
    • feedback_to_giveintegerrequired
    • feedback_overdueintegerrequired
    • todayintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/hiring/me.interviews \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_interview on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • interview_idstringrequired

    1–100 characters.

Returns

7 fields
  • interviewobjectrequired
    13 fields
    • idstringrequired
    • status"booked" | "no_show"required

      booked (to come or held), or no_show (the candidate did not come: no feedback needed).

    • heldbooleanrequired

      It has ended.

    • jobobjectrequired
      2 fields
      • idstringrequired
      • titlestringrequired
    • stepobjectrequired
      3 fields
      • idstringrequired
      • namestring | nullrequired
      • kindstring (enum)required

        One of: call, interview, panel, task, trial, presentation, references, final.

    • candidateobjectrequired

      Only the name: the kit (hiring_me_interview) has the CV and answers.

      1 field
      • namestringrequired
    • startstringrequired
    • endstringrequired
    • minutesintegerrequired
    • placeobjectrequired
      4 fields
      • kind"video" | "video_auto" | "phone" | "on_site" | "none"required

        video (a link HR pasted), video_auto (a Google Meet or Teams link the connected calendar makes), phone, on_site, none.

      • addressstring | nullrequired
      • linkstring | nullrequired

        The meeting link: pasted, or made by the calendar (video_auto; null until made).

      • link_source"google_meet" | "teams"required

        google_meet or teams: the calendar made the link; null: pasted, or none yet.

    • withobject[]required

      The other interviewers.

      2 fields
      • idstringrequired
      • namestringrequired
    • feedbackobject | nullrequired

      Your feedback: null until the interview has ended (and for no-shows).

      4 fields
      • status"none" | "draft" | "submitted"required
      • due_atstringrequired
      • overduebooleanrequired

        Not sent and past its due time.

      • on_timeboolean | nullrequired
    • access_untilstringrequired

      You can open this candidate until then (30 days after the interview).

  • candidateobjectrequired
    3 fields
    • namestringrequired
    • cvobject | nullrequired
      3 fields
      • namestringrequired
      • sizenumberrequired
      • urlstring | nullrequired
    • answersobject[]required
      2 fields
      • questionstringrequired
      • answerstringrequired
  • jobobjectrequired
    5 fields
    • idstringrequired
    • titlestringrequired
    • language"en" | "pt" | "es" | "fr" | "de"required
    • postobjectrequired
      4 fields
      • what_you_dostringrequired
      • what_you_needstringrequired
      • what_you_getstringrequired
      • how_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
      • promisestringrequired
      • stepsstring[]required
  • stepobjectrequired
    5 fields
    • idstringrequired
    • namestring | nullrequired
    • kindstring (enum)required

      One of: call, interview, panel, task, trial, presentation, references, final.

    • minutesintegerrequired
    • scorecardobject | nullrequired
      2 fields
      • skillsobject[]required
        4 fields
        • idstringrequired
        • namestringrequired
        • promptstring | nullrequired
        • levelsstring[]required

          4–4 items.

      • overall_questionstring | nullrequired
  • my_feedbackobject | nullrequired
    17 fields
    • idstringrequired
    • interview_idstringrequired
    • application_idstring | nullrequired
    • stepobjectrequired
      2 fields
      • idstringrequired
      • namestring | nullrequired
    • authorobject | nullrequired

      Who wrote it; null once they were erased (show "A former colleague").

      2 fields
      • idstringrequired
      • namestringrequired
    • author_erasedbooleanrequired
    • minebooleanrequired

      Yours.

    • status"draft" | "submitted"required

      draft: only its author sees it; submitted: final (correction notes may follow).

    • ratingsobject[]required

      1 (clear concerns) to 4 (excellent) per skill of the step's scorecard.

      3 fields
      • skill_idstringrequired
      • namestringrequired
      • ratingintegerrequired

        From 1 to 4.

    • textstringrequired
    • overallstring | nullrequired

      The answer to the scorecard's overall question.

    • recommendation"strong_no" | "no" | "yes" | "strong_yes"required
    • due_atstringrequired
    • submitted_atstring | nullrequired
    • on_timeboolean | nullrequired

      Sent by the time it was due.

    • notesobject[]required

      Corrections added after sending.

      2 fields
      • textstringrequired
      • atstringrequired
    • updated_atstringrequired
  • othersobject[]required

    The other interviewers' sent feedback on this candidate (empty while others_hidden).

    17 fields
    • idstringrequired
    • interview_idstringrequired
    • application_idstring | nullrequired
    • stepobjectrequired
      2 fields
      • idstringrequired
      • namestring | nullrequired
    • authorobject | nullrequired

      Who wrote it; null once they were erased (show "A former colleague").

      2 fields
      • idstringrequired
      • namestringrequired
    • author_erasedbooleanrequired
    • minebooleanrequired

      Yours.

    • status"draft" | "submitted"required

      draft: only its author sees it; submitted: final (correction notes may follow).

    • ratingsobject[]required

      1 (clear concerns) to 4 (excellent) per skill of the step's scorecard.

      3 fields
      • skill_idstringrequired
      • namestringrequired
      • ratingintegerrequired

        From 1 to 4.

    • textstringrequired
    • overallstring | nullrequired

      The answer to the scorecard's overall question.

    • recommendation"strong_no" | "no" | "yes" | "strong_yes"required
    • due_atstringrequired
    • submitted_atstring | nullrequired
    • on_timeboolean | nullrequired

      Sent by the time it was due.

    • notesobject[]required

      Corrections added after sending.

      2 fields
      • textstringrequired
      • atstringrequired
    • updated_atstringrequired
  • others_hiddenbooleanrequired

    Send your feedback first: then you see theirs (independent scoring).

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/hiring/me.interview \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"interview_id":"iv1"}'
Response
{
  "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_report on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with 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".

  • fromstring

    custom: the first day (YYYY-MM-DD).

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • tostring

    custom: the last day (YYYY-MM-DD).

    Pattern ^\d{4}-\d{2}-\d{2}$.

Returns

  • periodobjectrequired
    3 fields
    • kind"quarter" | "year" | "custom"required
    • fromstringrequired
    • tostringrequired
  • scope"everyone" | "reports" | "self"required

    everyone (owners, admins, HR), reports (a manager: the people below them) or self.

  • peopleobject[]required
    12 fields
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • interviews_heldintegerrequired

      Interviews they gave that ended in the period (no-shows included: they were there).

    • hoursnumberrequired

      Those interviews' length in hours (minutes / 60).

    • feedbackobjectrequired
      3 fields
      • dueintegerrequired

        Feedback due in the period on interviews they gave (no-shows excluded).

      • on_timeintegerrequired

        Sent by the time it was due.

      • on_time_pctnumber | nullrequired

        on_time / due as a percentage (whole number); null when nothing was due.

    • hires_interviewedintegerrequired

      People hired in the period whom they interviewed (at any step).

    • referralsintegerrequired

      People they referred in the period.

    • referral_hiresintegerrequired

      Of those referrals, how many were hired.

    • sharesintegerrequired

      Jobs they shared with their own link in the period.

    • applicants_from_sharesintegerrequired

      People who applied in the period through their share links.

    • thanksintegerrequired

      Thanks HR sent them in the period.

    • loadobjectrequired
      4 fields
      • monthintegerrequired

        Interviews booked or held this calendar month (their time zone).

      • weekintegerrequired

        Interviews booked or held this week.

      • capobject | nullrequired

        Their weekly cap; null without a usual week.

        2 fields
        • interviewsintegerrequired
        • hoursnumber | nullrequired
      • paused_untilstring | nullrequired
  • unitsobject[]required
    11 fields
    • unitobject | nullrequired

      null: people without a team.

      2 fields
      • idstringrequired
      • namestringrequired
    • peopleintegerrequired
    • interviews_heldintegerrequired

      Interviews they gave that ended in the period (no-shows included: they were there).

    • hoursnumberrequired

      Those interviews' length in hours (minutes / 60).

    • feedbackobjectrequired
      3 fields
      • dueintegerrequired

        Feedback due in the period on interviews they gave (no-shows excluded).

      • on_timeintegerrequired

        Sent by the time it was due.

      • on_time_pctnumber | nullrequired

        on_time / due as a percentage (whole number); null when nothing was due.

    • hires_interviewedintegerrequired

      People hired in the period whom they interviewed (at any step).

    • referralsintegerrequired

      People they referred in the period.

    • referral_hiresintegerrequired

      Of those referrals, how many were hired.

    • sharesintegerrequired

      Jobs they shared with their own link in the period.

    • applicants_from_sharesintegerrequired

      People who applied in the period through their share links.

    • thanksintegerrequired

      Thanks HR sent them in the period.

  • totalsobjectrequired
    9 fields
    • interviews_heldintegerrequired

      Interviews they gave that ended in the period (no-shows included: they were there).

    • hoursnumberrequired

      Those interviews' length in hours (minutes / 60).

    • feedbackobjectrequired
      3 fields
      • dueintegerrequired

        Feedback due in the period on interviews they gave (no-shows excluded).

      • on_timeintegerrequired

        Sent by the time it was due.

      • on_time_pctnumber | nullrequired

        on_time / due as a percentage (whole number); null when nothing was due.

    • hires_interviewedintegerrequired

      People hired in the period whom they interviewed (at any step).

    • referralsintegerrequired

      People they referred in the period.

    • referral_hiresintegerrequired

      Of those referrals, how many were hired.

    • sharesintegerrequired

      Jobs they shared with their own link in the period.

    • applicants_from_sharesintegerrequired

      People who applied in the period through their share links.

    • thanksintegerrequired

      Thanks HR sent them in the period.

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_contribution on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with 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".

  • fromstring

    custom: the first day (YYYY-MM-DD).

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • tostring

    custom: the last day (YYYY-MM-DD).

    Pattern ^\d{4}-\d{2}-\d{2}$.

Returns

  • periodobjectrequired
    3 fields
    • kind"quarter" | "year" | "custom"required
    • fromstringrequired
    • tostringrequired
  • meobjectrequired
    12 fields
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • interviews_heldintegerrequired

      Interviews they gave that ended in the period (no-shows included: they were there).

    • hoursnumberrequired

      Those interviews' length in hours (minutes / 60).

    • feedbackobjectrequired
      3 fields
      • dueintegerrequired

        Feedback due in the period on interviews they gave (no-shows excluded).

      • on_timeintegerrequired

        Sent by the time it was due.

      • on_time_pctnumber | nullrequired

        on_time / due as a percentage (whole number); null when nothing was due.

    • hires_interviewedintegerrequired

      People hired in the period whom they interviewed (at any step).

    • referralsintegerrequired

      People they referred in the period.

    • referral_hiresintegerrequired

      Of those referrals, how many were hired.

    • sharesintegerrequired

      Jobs they shared with their own link in the period.

    • applicants_from_sharesintegerrequired

      People who applied in the period through their share links.

    • thanksintegerrequired

      Thanks HR sent them in the period.

    • loadobjectrequired
      4 fields
      • monthintegerrequired

        Interviews booked or held this calendar month (their time zone).

      • weekintegerrequired

        Interviews booked or held this week.

      • capobject | nullrequired

        Their weekly cap; null without a usual week.

        2 fields
        • interviewsintegerrequired
        • hoursnumber | nullrequired
      • paused_untilstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/hiring/me.contribution \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"period":"quarter"}'
Response
{
  "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_export on HR Assistant
Method
POST with a JSON body, or GET with 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".

  • fromstring

    custom: the first day (YYYY-MM-DD).

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • tostring

    custom: the last day (YYYY-MM-DD).

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • lang"en" | "pt" | "es" | "fr" | "de"

Returns

  • fileobjectrequired
    6 fields
    • namestringrequired
    • content_typestringrequired
    • encoding"utf8" | "base64"required
    • contentstringrequired
    • bytesintegerrequired
    • sha256stringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_thank on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • job_idstringrequired

    1–100 characters.

  • copy_managerboolean

    Default false.

Returns

  • person_idstringrequired
  • job_idstringrequired
  • reason"interviewing" | "referring" | "sharing"required
  • emailedbooleanrequired
  • manager_copiedbooleanrequired
  • atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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}'
Response
{
  "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_draft on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • termsobject
    21 fields
    • titlestring

      1–120 characters.

    • start_datestring

      Pattern ^\d{4}-\d{2}-\d{2}$.

    • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"
    • end_datestring | null

      Pattern ^\d{4}-\d{2}-\d{2}$.

    • probationobject | null
      2 fields
      • valueintegerrequired

        From 1 to 366.

      • unit"days" | "months"required
    • weekly_hoursnumber | null

      From 1 to 60.

    • payobject
      4 fields
      • amountnumberrequired

        From 0 to 10000000.

      • currencyanyrequired
      • period"year" | "month" | "hour"required
      • payments_per_year12 | 13 | 14
    • benefitsstring | null

      Up 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 | null

      Up to 200 characters.

    • expires_onstring

      Pattern ^\d{4}-\d{2}-\d{2}$.

    • notestring | null

      Up to 1000 characters.

    • signer_person_idstring | null

      Who signs for the company (a person working there); null: the job's hiring manager.

      1–100 characters.

    • signer_titlestring | null

      Up to 120 characters.

    • work_emailemail | null

      Up to 254 characters.

    • invite"start" | "none"
    • unit_idstring | null

      1–100 characters.

    • location_idstring | null

      1–100 characters.

    • manager_idstring | null

      1–100 characters.

    • language"en" | "pt" | "es" | "fr" | "de"

      The letter's and the offer page's language (default the job's).

    • new_payboolean

      Transfers 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
  • idstringrequired
  • versionintegerrequired
  • supersedesstring | nullrequired
  • application_idstring | nullrequired
  • job_idstringrequired
  • candidateobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • statusstring (enum)required

    draft, 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"required
  • letter_kind"permanent" | "fixed_term"required
  • termsobjectrequired
    25 fields
    • titlestringrequired
    • legal_entity_idstring | nullrequired
    • employerstring | nullrequired
    • employer_countrystring | nullrequired
    • unit_idstring | nullrequired
    • location_idstring | nullrequired
    • manager_idstring | nullrequired
    • position_idstring | nullrequired
    • placestring | nullrequired
    • start_datestringrequired
    • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
    • end_datestring | nullrequired
    • probationobject | nullrequired
      2 fields
      • valueintegerrequired
      • unit"days" | "months"required
    • weekly_hoursnumber | nullrequired
    • payobject | nullrequired

      Pay tier: HR and the job's hiring manager; null over an API key or MCP.

      4 fields
      • amountnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
      • payments_per_yearinteger | nullrequired
    • benefitsstring | nullrequired

      HR's own words about benefits (appended after the catalogue's).

    • benefit_idsstring[]required

      Catalogue benefits named on the offer (benefits_offers_options).

    • benefit_linesstring[]required

      Those benefits as the letter writes them, in its language, frozen when the offer was saved.

    • expires_onstringrequired
    • notestring | nullrequired
    • signer_person_idstring | nullrequired
    • signer_namestring | nullrequired
    • signer_titlestring | nullrequired
    • work_emailstring | nullrequired

      The new work email the hire is made with (never on the letter).

    • invite"start" | "none"required

      The sign-in invite: on their first day (start) or none.

  • pay_hiddenbooleanrequired

    True over an API key or MCP: pay stays in the app.

  • rangeobject | nullrequired

    The job's published range the pay is checked against (pay tier).

    4 fields
    • minnumberrequired
    • maxnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
  • range_check"none" | "within" | "below" | "above"required

    below is refused on submit; above needs approval (unless approval is off).

  • approvalobject | nullrequired
    6 fields
    • reason"above_range" | "every_offer"required
    • approvers"hr" | "owner"required
    • state"pending" | "approved" | "rejected"required
    • asked_atstringrequired
    • decidedobject | nullrequired
      4 fields
      • atstringrequired
      • byobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • commentstring | nullrequired
      • automaticbooleanrequired
    • can_decidebooleanrequired

      You may approve or send it back (an approver, not its proposer, signed in to Bizisy).

  • approval_contextobject | nullrequired

    For an approver: the published range, the band of the position's level and how many hold the title.

    3 fields
    • rangeobject | nullrequired
      4 fields
      • minnumberrequired
      • maxnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
    • bandobject | nullrequired
      5 fields
      • minnumberrequired
      • maxnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
      • source"title" | "level"required
    • title_holdersinteger | nullrequired

      How many people hold the position's title today (never their names or pay).

  • proposed_byobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • sentobject | nullrequired
    3 fields
    • atstringrequired
    • expires_atstringrequired
    • remindedbooleanrequired
  • acceptanceobject | nullrequired
    3 fields
    • atstringrequired
    • typed_namestringrequired
    • sha256stringrequired
  • declinedobject | nullrequired
    3 fields
    • atstringrequired
    • reasonstring | nullrequired
    • kindstring (enum)required

      The 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 | nullrequired
    3 fields
    • atstringrequired
    • revisedbooleanrequired
    • toldbooleanrequired
  • expired_atstring | nullrequired
  • hireobjectrequired
    4 fields
    • person_idstring | nullrequired
    • failedobject | nullrequired
      2 fields
      • atstringrequired
      • reasonstringrequired
    • finishbooleanrequired

      The candidate accepted and HR must finish the hire (hiring_applications_hire_draft is filled in from the offer).

    • in_documentsbooleanrequired

      The signed offer is in the person's documents.

  • filesobjectrequired
    2 fields
    • letterobject | nullrequired

      The letter as sent (a 5-minute link, in the app only).

      1 field
      • urlstring | nullrequired
    • signedobject | nullrequired

      The signed copy with the acceptance record (a 5-minute link, in the app only, while it is kept in Hiring).

      1 field
      • urlstring | nullrequired
  • questionsintegerrequired
  • kind"hire" | "transfer"required

    transfer: to someone who works here (W7 D8): accepted in My workspace, then a job change under Settings → Approval rules.

  • transferobject | nullrequired
    5 fields
    • new_paybooleanrequired

      The offer changes their pay (else their pay stays).

    • state"none" | "waiting" | "approved" | "applied" | "rejected" | "cancelled"required

      none: not accepted yet; waiting: accepted, the job change waits for approval; approved/applied: done; rejected/cancelled: not approved (HR tells them).

    • approval_idstring | nullrequired
    • waiting_forstring | nullrequired

      waiting: the step it waits for (manager, hr).

    • approversstring[]required
  • created_atstringrequired
  • updated_atstringrequired
  • suggestionsobjectrequired
    4 fields
    • probationobject[]required

      Probation 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)required

        One of: general, complex, director, qualified, small_company, fixed_long, fixed_short, directive.

      • valueintegerrequired
      • unit"days" | "months"required
    • countrystring | nullrequired
    • pay_from_rangebooleanrequired

      The 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
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"
    }
  }
}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • termsobjectrequired
    21 fields
    • titlestring

      1–120 characters.

    • start_datestring

      Pattern ^\d{4}-\d{2}-\d{2}$.

    • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"
    • end_datestring | null

      Pattern ^\d{4}-\d{2}-\d{2}$.

    • probationobject | null
      2 fields
      • valueintegerrequired

        From 1 to 366.

      • unit"days" | "months"required
    • weekly_hoursnumber | null

      From 1 to 60.

    • payobject
      4 fields
      • amountnumberrequired

        From 0 to 10000000.

      • currencyanyrequired
      • period"year" | "month" | "hour"required
      • payments_per_year12 | 13 | 14
    • benefitsstring | null

      Up 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 | null

      Up to 200 characters.

    • expires_onstring

      Pattern ^\d{4}-\d{2}-\d{2}$.

    • notestring | null

      Up to 1000 characters.

    • signer_person_idstring | null

      Who signs for the company (a person working there); null: the job's hiring manager.

      1–100 characters.

    • signer_titlestring | null

      Up to 120 characters.

    • work_emailemail | null

      Up to 254 characters.

    • invite"start" | "none"
    • unit_idstring | null

      1–100 characters.

    • location_idstring | null

      1–100 characters.

    • manager_idstring | null

      1–100 characters.

    • language"en" | "pt" | "es" | "fr" | "de"

      The letter's and the offer page's language (default the job's).

    • new_payboolean

      Transfers 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
  • idstringrequired
  • versionintegerrequired
  • supersedesstring | nullrequired
  • application_idstring | nullrequired
  • job_idstringrequired
  • candidateobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • statusstring (enum)required

    draft, 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"required
  • letter_kind"permanent" | "fixed_term"required
  • termsobjectrequired
    25 fields
    • titlestringrequired
    • legal_entity_idstring | nullrequired
    • employerstring | nullrequired
    • employer_countrystring | nullrequired
    • unit_idstring | nullrequired
    • location_idstring | nullrequired
    • manager_idstring | nullrequired
    • position_idstring | nullrequired
    • placestring | nullrequired
    • start_datestringrequired
    • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
    • end_datestring | nullrequired
    • probationobject | nullrequired
      2 fields
      • valueintegerrequired
      • unit"days" | "months"required
    • weekly_hoursnumber | nullrequired
    • payobject | nullrequired

      Pay tier: HR and the job's hiring manager; null over an API key or MCP.

      4 fields
      • amountnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
      • payments_per_yearinteger | nullrequired
    • benefitsstring | nullrequired

      HR's own words about benefits (appended after the catalogue's).

    • benefit_idsstring[]required

      Catalogue benefits named on the offer (benefits_offers_options).

    • benefit_linesstring[]required

      Those benefits as the letter writes them, in its language, frozen when the offer was saved.

    • expires_onstringrequired
    • notestring | nullrequired
    • signer_person_idstring | nullrequired
    • signer_namestring | nullrequired
    • signer_titlestring | nullrequired
    • work_emailstring | nullrequired

      The new work email the hire is made with (never on the letter).

    • invite"start" | "none"required

      The sign-in invite: on their first day (start) or none.

  • pay_hiddenbooleanrequired

    True over an API key or MCP: pay stays in the app.

  • rangeobject | nullrequired

    The job's published range the pay is checked against (pay tier).

    4 fields
    • minnumberrequired
    • maxnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
  • range_check"none" | "within" | "below" | "above"required

    below is refused on submit; above needs approval (unless approval is off).

  • approvalobject | nullrequired
    6 fields
    • reason"above_range" | "every_offer"required
    • approvers"hr" | "owner"required
    • state"pending" | "approved" | "rejected"required
    • asked_atstringrequired
    • decidedobject | nullrequired
      4 fields
      • atstringrequired
      • byobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • commentstring | nullrequired
      • automaticbooleanrequired
    • can_decidebooleanrequired

      You may approve or send it back (an approver, not its proposer, signed in to Bizisy).

  • approval_contextobject | nullrequired

    For an approver: the published range, the band of the position's level and how many hold the title.

    3 fields
    • rangeobject | nullrequired
      4 fields
      • minnumberrequired
      • maxnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
    • bandobject | nullrequired
      5 fields
      • minnumberrequired
      • maxnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
      • source"title" | "level"required
    • title_holdersinteger | nullrequired

      How many people hold the position's title today (never their names or pay).

  • proposed_byobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • sentobject | nullrequired
    3 fields
    • atstringrequired
    • expires_atstringrequired
    • remindedbooleanrequired
  • acceptanceobject | nullrequired
    3 fields
    • atstringrequired
    • typed_namestringrequired
    • sha256stringrequired
  • declinedobject | nullrequired
    3 fields
    • atstringrequired
    • reasonstring | nullrequired
    • kindstring (enum)required

      The 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 | nullrequired
    3 fields
    • atstringrequired
    • revisedbooleanrequired
    • toldbooleanrequired
  • expired_atstring | nullrequired
  • hireobjectrequired
    4 fields
    • person_idstring | nullrequired
    • failedobject | nullrequired
      2 fields
      • atstringrequired
      • reasonstringrequired
    • finishbooleanrequired

      The candidate accepted and HR must finish the hire (hiring_applications_hire_draft is filled in from the offer).

    • in_documentsbooleanrequired

      The signed offer is in the person's documents.

  • filesobjectrequired
    2 fields
    • letterobject | nullrequired

      The letter as sent (a 5-minute link, in the app only).

      1 field
      • urlstring | nullrequired
    • signedobject | nullrequired

      The signed copy with the acceptance record (a 5-minute link, in the app only, while it is kept in Hiring).

      1 field
      • urlstring | nullrequired
  • questionsintegerrequired
  • kind"hire" | "transfer"required

    transfer: to someone who works here (W7 D8): accepted in My workspace, then a job change under Settings → Approval rules.

  • transferobject | nullrequired
    5 fields
    • new_paybooleanrequired

      The offer changes their pay (else their pay stays).

    • state"none" | "waiting" | "approved" | "applied" | "rejected" | "cancelled"required

      none: not accepted yet; waiting: accepted, the job change waits for approval; approved/applied: done; rejected/cancelled: not approved (HR tells them).

    • approval_idstring | nullrequired
    • waiting_forstring | nullrequired

      waiting: the step it waits for (manager, hr).

    • approversstring[]required
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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."
  }
}'
Response
{
  "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_submit on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

Returns

28 fields
  • idstringrequired
  • versionintegerrequired
  • supersedesstring | nullrequired
  • application_idstring | nullrequired
  • job_idstringrequired
  • candidateobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • statusstring (enum)required

    draft, 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"required
  • letter_kind"permanent" | "fixed_term"required
  • termsobjectrequired
    25 fields
    • titlestringrequired
    • legal_entity_idstring | nullrequired
    • employerstring | nullrequired
    • employer_countrystring | nullrequired
    • unit_idstring | nullrequired
    • location_idstring | nullrequired
    • manager_idstring | nullrequired
    • position_idstring | nullrequired
    • placestring | nullrequired
    • start_datestringrequired
    • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
    • end_datestring | nullrequired
    • probationobject | nullrequired
      2 fields
      • valueintegerrequired
      • unit"days" | "months"required
    • weekly_hoursnumber | nullrequired
    • payobject | nullrequired

      Pay tier: HR and the job's hiring manager; null over an API key or MCP.

      4 fields
      • amountnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
      • payments_per_yearinteger | nullrequired
    • benefitsstring | nullrequired

      HR's own words about benefits (appended after the catalogue's).

    • benefit_idsstring[]required

      Catalogue benefits named on the offer (benefits_offers_options).

    • benefit_linesstring[]required

      Those benefits as the letter writes them, in its language, frozen when the offer was saved.

    • expires_onstringrequired
    • notestring | nullrequired
    • signer_person_idstring | nullrequired
    • signer_namestring | nullrequired
    • signer_titlestring | nullrequired
    • work_emailstring | nullrequired

      The new work email the hire is made with (never on the letter).

    • invite"start" | "none"required

      The sign-in invite: on their first day (start) or none.

  • pay_hiddenbooleanrequired

    True over an API key or MCP: pay stays in the app.

  • rangeobject | nullrequired

    The job's published range the pay is checked against (pay tier).

    4 fields
    • minnumberrequired
    • maxnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
  • range_check"none" | "within" | "below" | "above"required

    below is refused on submit; above needs approval (unless approval is off).

  • approvalobject | nullrequired
    6 fields
    • reason"above_range" | "every_offer"required
    • approvers"hr" | "owner"required
    • state"pending" | "approved" | "rejected"required
    • asked_atstringrequired
    • decidedobject | nullrequired
      4 fields
      • atstringrequired
      • byobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • commentstring | nullrequired
      • automaticbooleanrequired
    • can_decidebooleanrequired

      You may approve or send it back (an approver, not its proposer, signed in to Bizisy).

  • approval_contextobject | nullrequired

    For an approver: the published range, the band of the position's level and how many hold the title.

    3 fields
    • rangeobject | nullrequired
      4 fields
      • minnumberrequired
      • maxnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
    • bandobject | nullrequired
      5 fields
      • minnumberrequired
      • maxnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
      • source"title" | "level"required
    • title_holdersinteger | nullrequired

      How many people hold the position's title today (never their names or pay).

  • proposed_byobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • sentobject | nullrequired
    3 fields
    • atstringrequired
    • expires_atstringrequired
    • remindedbooleanrequired
  • acceptanceobject | nullrequired
    3 fields
    • atstringrequired
    • typed_namestringrequired
    • sha256stringrequired
  • declinedobject | nullrequired
    3 fields
    • atstringrequired
    • reasonstring | nullrequired
    • kindstring (enum)required

      The 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 | nullrequired
    3 fields
    • atstringrequired
    • revisedbooleanrequired
    • toldbooleanrequired
  • expired_atstring | nullrequired
  • hireobjectrequired
    4 fields
    • person_idstring | nullrequired
    • failedobject | nullrequired
      2 fields
      • atstringrequired
      • reasonstringrequired
    • finishbooleanrequired

      The candidate accepted and HR must finish the hire (hiring_applications_hire_draft is filled in from the offer).

    • in_documentsbooleanrequired

      The signed offer is in the person's documents.

  • filesobjectrequired
    2 fields
    • letterobject | nullrequired

      The letter as sent (a 5-minute link, in the app only).

      1 field
      • urlstring | nullrequired
    • signedobject | nullrequired

      The signed copy with the acceptance record (a 5-minute link, in the app only, while it is kept in Hiring).

      1 field
      • urlstring | nullrequired
  • questionsintegerrequired
  • kind"hire" | "transfer"required

    transfer: to someone who works here (W7 D8): accepted in My workspace, then a job change under Settings → Approval rules.

  • transferobject | nullrequired
    5 fields
    • new_paybooleanrequired

      The offer changes their pay (else their pay stays).

    • state"none" | "waiting" | "approved" | "applied" | "rejected" | "cancelled"required

      none: not accepted yet; waiting: accepted, the job change waits for approval; approved/applied: done; rejected/cancelled: not approved (HR tells them).

    • approval_idstring | nullrequired
    • waiting_forstring | nullrequired

      waiting: the step it waits for (manager, hr).

    • approversstring[]required
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_decide on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • decision"approve" | "reject"required
  • commentstring

    Up to 500 characters.

Returns

28 fields
  • idstringrequired
  • versionintegerrequired
  • supersedesstring | nullrequired
  • application_idstring | nullrequired
  • job_idstringrequired
  • candidateobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • statusstring (enum)required

    draft, 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"required
  • letter_kind"permanent" | "fixed_term"required
  • termsobjectrequired
    25 fields
    • titlestringrequired
    • legal_entity_idstring | nullrequired
    • employerstring | nullrequired
    • employer_countrystring | nullrequired
    • unit_idstring | nullrequired
    • location_idstring | nullrequired
    • manager_idstring | nullrequired
    • position_idstring | nullrequired
    • placestring | nullrequired
    • start_datestringrequired
    • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
    • end_datestring | nullrequired
    • probationobject | nullrequired
      2 fields
      • valueintegerrequired
      • unit"days" | "months"required
    • weekly_hoursnumber | nullrequired
    • payobject | nullrequired

      Pay tier: HR and the job's hiring manager; null over an API key or MCP.

      4 fields
      • amountnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
      • payments_per_yearinteger | nullrequired
    • benefitsstring | nullrequired

      HR's own words about benefits (appended after the catalogue's).

    • benefit_idsstring[]required

      Catalogue benefits named on the offer (benefits_offers_options).

    • benefit_linesstring[]required

      Those benefits as the letter writes them, in its language, frozen when the offer was saved.

    • expires_onstringrequired
    • notestring | nullrequired
    • signer_person_idstring | nullrequired
    • signer_namestring | nullrequired
    • signer_titlestring | nullrequired
    • work_emailstring | nullrequired

      The new work email the hire is made with (never on the letter).

    • invite"start" | "none"required

      The sign-in invite: on their first day (start) or none.

  • pay_hiddenbooleanrequired

    True over an API key or MCP: pay stays in the app.

  • rangeobject | nullrequired

    The job's published range the pay is checked against (pay tier).

    4 fields
    • minnumberrequired
    • maxnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
  • range_check"none" | "within" | "below" | "above"required

    below is refused on submit; above needs approval (unless approval is off).

  • approvalobject | nullrequired
    6 fields
    • reason"above_range" | "every_offer"required
    • approvers"hr" | "owner"required
    • state"pending" | "approved" | "rejected"required
    • asked_atstringrequired
    • decidedobject | nullrequired
      4 fields
      • atstringrequired
      • byobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • commentstring | nullrequired
      • automaticbooleanrequired
    • can_decidebooleanrequired

      You may approve or send it back (an approver, not its proposer, signed in to Bizisy).

  • approval_contextobject | nullrequired

    For an approver: the published range, the band of the position's level and how many hold the title.

    3 fields
    • rangeobject | nullrequired
      4 fields
      • minnumberrequired
      • maxnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
    • bandobject | nullrequired
      5 fields
      • minnumberrequired
      • maxnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
      • source"title" | "level"required
    • title_holdersinteger | nullrequired

      How many people hold the position's title today (never their names or pay).

  • proposed_byobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • sentobject | nullrequired
    3 fields
    • atstringrequired
    • expires_atstringrequired
    • remindedbooleanrequired
  • acceptanceobject | nullrequired
    3 fields
    • atstringrequired
    • typed_namestringrequired
    • sha256stringrequired
  • declinedobject | nullrequired
    3 fields
    • atstringrequired
    • reasonstring | nullrequired
    • kindstring (enum)required

      The 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 | nullrequired
    3 fields
    • atstringrequired
    • revisedbooleanrequired
    • toldbooleanrequired
  • expired_atstring | nullrequired
  • hireobjectrequired
    4 fields
    • person_idstring | nullrequired
    • failedobject | nullrequired
      2 fields
      • atstringrequired
      • reasonstringrequired
    • finishbooleanrequired

      The candidate accepted and HR must finish the hire (hiring_applications_hire_draft is filled in from the offer).

    • in_documentsbooleanrequired

      The signed offer is in the person's documents.

  • filesobjectrequired
    2 fields
    • letterobject | nullrequired

      The letter as sent (a 5-minute link, in the app only).

      1 field
      • urlstring | nullrequired
    • signedobject | nullrequired

      The signed copy with the acceptance record (a 5-minute link, in the app only, while it is kept in Hiring).

      1 field
      • urlstring | nullrequired
  • questionsintegerrequired
  • kind"hire" | "transfer"required

    transfer: to someone who works here (W7 D8): accepted in My workspace, then a job change under Settings → Approval rules.

  • transferobject | nullrequired
    5 fields
    • new_paybooleanrequired

      The offer changes their pay (else their pay stays).

    • state"none" | "waiting" | "approved" | "applied" | "rejected" | "cancelled"required

      none: not accepted yet; waiting: accepted, the job change waits for approval; approved/applied: done; rejected/cancelled: not approved (HR tells them).

    • approval_idstring | nullrequired
    • waiting_forstring | nullrequired

      waiting: the step it waits for (manager, hr).

    • approversstring[]required
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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."
}'
Response
{
  "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_send on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

Returns

28 fields
  • idstringrequired
  • versionintegerrequired
  • supersedesstring | nullrequired
  • application_idstring | nullrequired
  • job_idstringrequired
  • candidateobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • statusstring (enum)required

    draft, 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"required
  • letter_kind"permanent" | "fixed_term"required
  • termsobjectrequired
    25 fields
    • titlestringrequired
    • legal_entity_idstring | nullrequired
    • employerstring | nullrequired
    • employer_countrystring | nullrequired
    • unit_idstring | nullrequired
    • location_idstring | nullrequired
    • manager_idstring | nullrequired
    • position_idstring | nullrequired
    • placestring | nullrequired
    • start_datestringrequired
    • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
    • end_datestring | nullrequired
    • probationobject | nullrequired
      2 fields
      • valueintegerrequired
      • unit"days" | "months"required
    • weekly_hoursnumber | nullrequired
    • payobject | nullrequired

      Pay tier: HR and the job's hiring manager; null over an API key or MCP.

      4 fields
      • amountnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
      • payments_per_yearinteger | nullrequired
    • benefitsstring | nullrequired

      HR's own words about benefits (appended after the catalogue's).

    • benefit_idsstring[]required

      Catalogue benefits named on the offer (benefits_offers_options).

    • benefit_linesstring[]required

      Those benefits as the letter writes them, in its language, frozen when the offer was saved.

    • expires_onstringrequired
    • notestring | nullrequired
    • signer_person_idstring | nullrequired
    • signer_namestring | nullrequired
    • signer_titlestring | nullrequired
    • work_emailstring | nullrequired

      The new work email the hire is made with (never on the letter).

    • invite"start" | "none"required

      The sign-in invite: on their first day (start) or none.

  • pay_hiddenbooleanrequired

    True over an API key or MCP: pay stays in the app.

  • rangeobject | nullrequired

    The job's published range the pay is checked against (pay tier).

    4 fields
    • minnumberrequired
    • maxnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
  • range_check"none" | "within" | "below" | "above"required

    below is refused on submit; above needs approval (unless approval is off).

  • approvalobject | nullrequired
    6 fields
    • reason"above_range" | "every_offer"required
    • approvers"hr" | "owner"required
    • state"pending" | "approved" | "rejected"required
    • asked_atstringrequired
    • decidedobject | nullrequired
      4 fields
      • atstringrequired
      • byobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • commentstring | nullrequired
      • automaticbooleanrequired
    • can_decidebooleanrequired

      You may approve or send it back (an approver, not its proposer, signed in to Bizisy).

  • approval_contextobject | nullrequired

    For an approver: the published range, the band of the position's level and how many hold the title.

    3 fields
    • rangeobject | nullrequired
      4 fields
      • minnumberrequired
      • maxnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
    • bandobject | nullrequired
      5 fields
      • minnumberrequired
      • maxnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
      • source"title" | "level"required
    • title_holdersinteger | nullrequired

      How many people hold the position's title today (never their names or pay).

  • proposed_byobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • sentobject | nullrequired
    3 fields
    • atstringrequired
    • expires_atstringrequired
    • remindedbooleanrequired
  • acceptanceobject | nullrequired
    3 fields
    • atstringrequired
    • typed_namestringrequired
    • sha256stringrequired
  • declinedobject | nullrequired
    3 fields
    • atstringrequired
    • reasonstring | nullrequired
    • kindstring (enum)required

      The 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 | nullrequired
    3 fields
    • atstringrequired
    • revisedbooleanrequired
    • toldbooleanrequired
  • expired_atstring | nullrequired
  • hireobjectrequired
    4 fields
    • person_idstring | nullrequired
    • failedobject | nullrequired
      2 fields
      • atstringrequired
      • reasonstringrequired
    • finishbooleanrequired

      The candidate accepted and HR must finish the hire (hiring_applications_hire_draft is filled in from the offer).

    • in_documentsbooleanrequired

      The signed offer is in the person's documents.

  • filesobjectrequired
    2 fields
    • letterobject | nullrequired

      The letter as sent (a 5-minute link, in the app only).

      1 field
      • urlstring | nullrequired
    • signedobject | nullrequired

      The signed copy with the acceptance record (a 5-minute link, in the app only, while it is kept in Hiring).

      1 field
      • urlstring | nullrequired
  • questionsintegerrequired
  • kind"hire" | "transfer"required

    transfer: to someone who works here (W7 D8): accepted in My workspace, then a job change under Settings → Approval rules.

  • transferobject | nullrequired
    5 fields
    • new_paybooleanrequired

      The offer changes their pay (else their pay stays).

    • state"none" | "waiting" | "approved" | "applied" | "rejected" | "cancelled"required

      none: not accepted yet; waiting: accepted, the job change waits for approval; approved/applied: done; rejected/cancelled: not approved (HR tells them).

    • approval_idstring | nullrequired
    • waiting_forstring | nullrequired

      waiting: the step it waits for (manager, hr).

    • approversstring[]required
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_withdraw on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • tellboolean

    Default true.

Returns

28 fields
  • idstringrequired
  • versionintegerrequired
  • supersedesstring | nullrequired
  • application_idstring | nullrequired
  • job_idstringrequired
  • candidateobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • statusstring (enum)required

    draft, 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"required
  • letter_kind"permanent" | "fixed_term"required
  • termsobjectrequired
    25 fields
    • titlestringrequired
    • legal_entity_idstring | nullrequired
    • employerstring | nullrequired
    • employer_countrystring | nullrequired
    • unit_idstring | nullrequired
    • location_idstring | nullrequired
    • manager_idstring | nullrequired
    • position_idstring | nullrequired
    • placestring | nullrequired
    • start_datestringrequired
    • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
    • end_datestring | nullrequired
    • probationobject | nullrequired
      2 fields
      • valueintegerrequired
      • unit"days" | "months"required
    • weekly_hoursnumber | nullrequired
    • payobject | nullrequired

      Pay tier: HR and the job's hiring manager; null over an API key or MCP.

      4 fields
      • amountnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
      • payments_per_yearinteger | nullrequired
    • benefitsstring | nullrequired

      HR's own words about benefits (appended after the catalogue's).

    • benefit_idsstring[]required

      Catalogue benefits named on the offer (benefits_offers_options).

    • benefit_linesstring[]required

      Those benefits as the letter writes them, in its language, frozen when the offer was saved.

    • expires_onstringrequired
    • notestring | nullrequired
    • signer_person_idstring | nullrequired
    • signer_namestring | nullrequired
    • signer_titlestring | nullrequired
    • work_emailstring | nullrequired

      The new work email the hire is made with (never on the letter).

    • invite"start" | "none"required

      The sign-in invite: on their first day (start) or none.

  • pay_hiddenbooleanrequired

    True over an API key or MCP: pay stays in the app.

  • rangeobject | nullrequired

    The job's published range the pay is checked against (pay tier).

    4 fields
    • minnumberrequired
    • maxnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
  • range_check"none" | "within" | "below" | "above"required

    below is refused on submit; above needs approval (unless approval is off).

  • approvalobject | nullrequired
    6 fields
    • reason"above_range" | "every_offer"required
    • approvers"hr" | "owner"required
    • state"pending" | "approved" | "rejected"required
    • asked_atstringrequired
    • decidedobject | nullrequired
      4 fields
      • atstringrequired
      • byobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • commentstring | nullrequired
      • automaticbooleanrequired
    • can_decidebooleanrequired

      You may approve or send it back (an approver, not its proposer, signed in to Bizisy).

  • approval_contextobject | nullrequired

    For an approver: the published range, the band of the position's level and how many hold the title.

    3 fields
    • rangeobject | nullrequired
      4 fields
      • minnumberrequired
      • maxnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
    • bandobject | nullrequired
      5 fields
      • minnumberrequired
      • maxnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
      • source"title" | "level"required
    • title_holdersinteger | nullrequired

      How many people hold the position's title today (never their names or pay).

  • proposed_byobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • sentobject | nullrequired
    3 fields
    • atstringrequired
    • expires_atstringrequired
    • remindedbooleanrequired
  • acceptanceobject | nullrequired
    3 fields
    • atstringrequired
    • typed_namestringrequired
    • sha256stringrequired
  • declinedobject | nullrequired
    3 fields
    • atstringrequired
    • reasonstring | nullrequired
    • kindstring (enum)required

      The 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 | nullrequired
    3 fields
    • atstringrequired
    • revisedbooleanrequired
    • toldbooleanrequired
  • expired_atstring | nullrequired
  • hireobjectrequired
    4 fields
    • person_idstring | nullrequired
    • failedobject | nullrequired
      2 fields
      • atstringrequired
      • reasonstringrequired
    • finishbooleanrequired

      The candidate accepted and HR must finish the hire (hiring_applications_hire_draft is filled in from the offer).

    • in_documentsbooleanrequired

      The signed offer is in the person's documents.

  • filesobjectrequired
    2 fields
    • letterobject | nullrequired

      The letter as sent (a 5-minute link, in the app only).

      1 field
      • urlstring | nullrequired
    • signedobject | nullrequired

      The signed copy with the acceptance record (a 5-minute link, in the app only, while it is kept in Hiring).

      1 field
      • urlstring | nullrequired
  • questionsintegerrequired
  • kind"hire" | "transfer"required

    transfer: to someone who works here (W7 D8): accepted in My workspace, then a job change under Settings → Approval rules.

  • transferobject | nullrequired
    5 fields
    • new_paybooleanrequired

      The offer changes their pay (else their pay stays).

    • state"none" | "waiting" | "approved" | "applied" | "rejected" | "cancelled"required

      none: not accepted yet; waiting: accepted, the job change waits for approval; approved/applied: done; rejected/cancelled: not approved (HR tells them).

    • approval_idstring | nullrequired
    • waiting_forstring | nullrequired

      waiting: the step it waits for (manager, hr).

    • approversstring[]required
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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}'
Response
{
  "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_revise on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

Returns

28 fields
  • idstringrequired
  • versionintegerrequired
  • supersedesstring | nullrequired
  • application_idstring | nullrequired
  • job_idstringrequired
  • candidateobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • statusstring (enum)required

    draft, 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"required
  • letter_kind"permanent" | "fixed_term"required
  • termsobjectrequired
    25 fields
    • titlestringrequired
    • legal_entity_idstring | nullrequired
    • employerstring | nullrequired
    • employer_countrystring | nullrequired
    • unit_idstring | nullrequired
    • location_idstring | nullrequired
    • manager_idstring | nullrequired
    • position_idstring | nullrequired
    • placestring | nullrequired
    • start_datestringrequired
    • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
    • end_datestring | nullrequired
    • probationobject | nullrequired
      2 fields
      • valueintegerrequired
      • unit"days" | "months"required
    • weekly_hoursnumber | nullrequired
    • payobject | nullrequired

      Pay tier: HR and the job's hiring manager; null over an API key or MCP.

      4 fields
      • amountnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
      • payments_per_yearinteger | nullrequired
    • benefitsstring | nullrequired

      HR's own words about benefits (appended after the catalogue's).

    • benefit_idsstring[]required

      Catalogue benefits named on the offer (benefits_offers_options).

    • benefit_linesstring[]required

      Those benefits as the letter writes them, in its language, frozen when the offer was saved.

    • expires_onstringrequired
    • notestring | nullrequired
    • signer_person_idstring | nullrequired
    • signer_namestring | nullrequired
    • signer_titlestring | nullrequired
    • work_emailstring | nullrequired

      The new work email the hire is made with (never on the letter).

    • invite"start" | "none"required

      The sign-in invite: on their first day (start) or none.

  • pay_hiddenbooleanrequired

    True over an API key or MCP: pay stays in the app.

  • rangeobject | nullrequired

    The job's published range the pay is checked against (pay tier).

    4 fields
    • minnumberrequired
    • maxnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
  • range_check"none" | "within" | "below" | "above"required

    below is refused on submit; above needs approval (unless approval is off).

  • approvalobject | nullrequired
    6 fields
    • reason"above_range" | "every_offer"required
    • approvers"hr" | "owner"required
    • state"pending" | "approved" | "rejected"required
    • asked_atstringrequired
    • decidedobject | nullrequired
      4 fields
      • atstringrequired
      • byobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • commentstring | nullrequired
      • automaticbooleanrequired
    • can_decidebooleanrequired

      You may approve or send it back (an approver, not its proposer, signed in to Bizisy).

  • approval_contextobject | nullrequired

    For an approver: the published range, the band of the position's level and how many hold the title.

    3 fields
    • rangeobject | nullrequired
      4 fields
      • minnumberrequired
      • maxnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
    • bandobject | nullrequired
      5 fields
      • minnumberrequired
      • maxnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
      • source"title" | "level"required
    • title_holdersinteger | nullrequired

      How many people hold the position's title today (never their names or pay).

  • proposed_byobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • sentobject | nullrequired
    3 fields
    • atstringrequired
    • expires_atstringrequired
    • remindedbooleanrequired
  • acceptanceobject | nullrequired
    3 fields
    • atstringrequired
    • typed_namestringrequired
    • sha256stringrequired
  • declinedobject | nullrequired
    3 fields
    • atstringrequired
    • reasonstring | nullrequired
    • kindstring (enum)required

      The 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 | nullrequired
    3 fields
    • atstringrequired
    • revisedbooleanrequired
    • toldbooleanrequired
  • expired_atstring | nullrequired
  • hireobjectrequired
    4 fields
    • person_idstring | nullrequired
    • failedobject | nullrequired
      2 fields
      • atstringrequired
      • reasonstringrequired
    • finishbooleanrequired

      The candidate accepted and HR must finish the hire (hiring_applications_hire_draft is filled in from the offer).

    • in_documentsbooleanrequired

      The signed offer is in the person's documents.

  • filesobjectrequired
    2 fields
    • letterobject | nullrequired

      The letter as sent (a 5-minute link, in the app only).

      1 field
      • urlstring | nullrequired
    • signedobject | nullrequired

      The signed copy with the acceptance record (a 5-minute link, in the app only, while it is kept in Hiring).

      1 field
      • urlstring | nullrequired
  • questionsintegerrequired
  • kind"hire" | "transfer"required

    transfer: to someone who works here (W7 D8): accepted in My workspace, then a job change under Settings → Approval rules.

  • transferobject | nullrequired
    5 fields
    • new_paybooleanrequired

      The offer changes their pay (else their pay stays).

    • state"none" | "waiting" | "approved" | "applied" | "rejected" | "cancelled"required

      none: not accepted yet; waiting: accepted, the job change waits for approval; approved/applied: done; rejected/cancelled: not approved (HR tells them).

    • approval_idstring | nullrequired
    • waiting_forstring | nullrequired

      waiting: the step it waits for (manager, hr).

    • approversstring[]required
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • offer_idstringrequired

    1–100 characters.

Returns

29 fields
  • idstringrequired
  • versionintegerrequired
  • supersedesstring | nullrequired
  • application_idstring | nullrequired
  • job_idstringrequired
  • candidateobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • statusstring (enum)required

    draft, 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"required
  • letter_kind"permanent" | "fixed_term"required
  • termsobjectrequired
    25 fields
    • titlestringrequired
    • legal_entity_idstring | nullrequired
    • employerstring | nullrequired
    • employer_countrystring | nullrequired
    • unit_idstring | nullrequired
    • location_idstring | nullrequired
    • manager_idstring | nullrequired
    • position_idstring | nullrequired
    • placestring | nullrequired
    • start_datestringrequired
    • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
    • end_datestring | nullrequired
    • probationobject | nullrequired
      2 fields
      • valueintegerrequired
      • unit"days" | "months"required
    • weekly_hoursnumber | nullrequired
    • payobject | nullrequired

      Pay tier: HR and the job's hiring manager; null over an API key or MCP.

      4 fields
      • amountnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
      • payments_per_yearinteger | nullrequired
    • benefitsstring | nullrequired

      HR's own words about benefits (appended after the catalogue's).

    • benefit_idsstring[]required

      Catalogue benefits named on the offer (benefits_offers_options).

    • benefit_linesstring[]required

      Those benefits as the letter writes them, in its language, frozen when the offer was saved.

    • expires_onstringrequired
    • notestring | nullrequired
    • signer_person_idstring | nullrequired
    • signer_namestring | nullrequired
    • signer_titlestring | nullrequired
    • work_emailstring | nullrequired

      The new work email the hire is made with (never on the letter).

    • invite"start" | "none"required

      The sign-in invite: on their first day (start) or none.

  • pay_hiddenbooleanrequired

    True over an API key or MCP: pay stays in the app.

  • rangeobject | nullrequired

    The job's published range the pay is checked against (pay tier).

    4 fields
    • minnumberrequired
    • maxnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
  • range_check"none" | "within" | "below" | "above"required

    below is refused on submit; above needs approval (unless approval is off).

  • approvalobject | nullrequired
    6 fields
    • reason"above_range" | "every_offer"required
    • approvers"hr" | "owner"required
    • state"pending" | "approved" | "rejected"required
    • asked_atstringrequired
    • decidedobject | nullrequired
      4 fields
      • atstringrequired
      • byobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • commentstring | nullrequired
      • automaticbooleanrequired
    • can_decidebooleanrequired

      You may approve or send it back (an approver, not its proposer, signed in to Bizisy).

  • approval_contextobject | nullrequired

    For an approver: the published range, the band of the position's level and how many hold the title.

    3 fields
    • rangeobject | nullrequired
      4 fields
      • minnumberrequired
      • maxnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
    • bandobject | nullrequired
      5 fields
      • minnumberrequired
      • maxnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
      • source"title" | "level"required
    • title_holdersinteger | nullrequired

      How many people hold the position's title today (never their names or pay).

  • proposed_byobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • sentobject | nullrequired
    3 fields
    • atstringrequired
    • expires_atstringrequired
    • remindedbooleanrequired
  • acceptanceobject | nullrequired
    3 fields
    • atstringrequired
    • typed_namestringrequired
    • sha256stringrequired
  • declinedobject | nullrequired
    3 fields
    • atstringrequired
    • reasonstring | nullrequired
    • kindstring (enum)required

      The 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 | nullrequired
    3 fields
    • atstringrequired
    • revisedbooleanrequired
    • toldbooleanrequired
  • expired_atstring | nullrequired
  • hireobjectrequired
    4 fields
    • person_idstring | nullrequired
    • failedobject | nullrequired
      2 fields
      • atstringrequired
      • reasonstringrequired
    • finishbooleanrequired

      The candidate accepted and HR must finish the hire (hiring_applications_hire_draft is filled in from the offer).

    • in_documentsbooleanrequired

      The signed offer is in the person's documents.

  • filesobjectrequired
    2 fields
    • letterobject | nullrequired

      The letter as sent (a 5-minute link, in the app only).

      1 field
      • urlstring | nullrequired
    • signedobject | nullrequired

      The signed copy with the acceptance record (a 5-minute link, in the app only, while it is kept in Hiring).

      1 field
      • urlstring | nullrequired
  • questionsintegerrequired
  • kind"hire" | "transfer"required

    transfer: to someone who works here (W7 D8): accepted in My workspace, then a job change under Settings → Approval rules.

  • transferobject | nullrequired
    5 fields
    • new_paybooleanrequired

      The offer changes their pay (else their pay stays).

    • state"none" | "waiting" | "approved" | "applied" | "rejected" | "cancelled"required

      none: not accepted yet; waiting: accepted, the job change waits for approval; approved/applied: done; rejected/cancelled: not approved (HR tells them).

    • approval_idstring | nullrequired
    • waiting_forstring | nullrequired

      waiting: the step it waits for (manager, hr).

    • approversstring[]required
  • created_atstringrequired
  • updated_atstringrequired
  • suggestionsobjectrequired
    4 fields
    • probationobject[]required

      Probation 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)required

        One of: general, complex, director, qualified, small_company, fixed_long, fixed_short, directive.

      • valueintegerrequired
      • unit"days" | "months"required
    • countrystring | nullrequired
    • pay_from_rangebooleanrequired

      The 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
curl https://api.bizisy.com/v1/hiring/offers.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"offer_id":"o1"}'
Response
{
  "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_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • application_idstring

    1–100 characters.

  • job_idstring

    1–100 characters.

  • statusstring (enum)

    One of: draft, awaiting_approval, ready, sent, accepted_pending_hire, accepted, declined, expired, withdrawn.

  • waiting_for_meboolean
  • limitinteger

    From 1 to 500. Default 100.

Returns

  • offersobject[]required
    28 fields
    • idstringrequired
    • versionintegerrequired
    • supersedesstring | nullrequired
    • application_idstring | nullrequired
    • job_idstringrequired
    • candidateobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • statusstring (enum)required

      draft, 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"required
    • letter_kind"permanent" | "fixed_term"required
    • termsobjectrequired
      25 fields
      • titlestringrequired
      • legal_entity_idstring | nullrequired
      • employerstring | nullrequired
      • employer_countrystring | nullrequired
      • unit_idstring | nullrequired
      • location_idstring | nullrequired
      • manager_idstring | nullrequired
      • position_idstring | nullrequired
      • placestring | nullrequired
      • start_datestringrequired
      • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
      • end_datestring | nullrequired
      • probationobject | nullrequired
        2 fields
        • valueintegerrequired
        • unit"days" | "months"required
      • weekly_hoursnumber | nullrequired
      • payobject | nullrequired

        Pay tier: HR and the job's hiring manager; null over an API key or MCP.

        4 fields
        • amountnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
        • payments_per_yearinteger | nullrequired
      • benefitsstring | nullrequired

        HR's own words about benefits (appended after the catalogue's).

      • benefit_idsstring[]required

        Catalogue benefits named on the offer (benefits_offers_options).

      • benefit_linesstring[]required

        Those benefits as the letter writes them, in its language, frozen when the offer was saved.

      • expires_onstringrequired
      • notestring | nullrequired
      • signer_person_idstring | nullrequired
      • signer_namestring | nullrequired
      • signer_titlestring | nullrequired
      • work_emailstring | nullrequired

        The new work email the hire is made with (never on the letter).

      • invite"start" | "none"required

        The sign-in invite: on their first day (start) or none.

    • pay_hiddenbooleanrequired

      True over an API key or MCP: pay stays in the app.

    • rangeobject | nullrequired

      The job's published range the pay is checked against (pay tier).

      4 fields
      • minnumberrequired
      • maxnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
    • range_check"none" | "within" | "below" | "above"required

      below is refused on submit; above needs approval (unless approval is off).

    • approvalobject | nullrequired
      6 fields
      • reason"above_range" | "every_offer"required
      • approvers"hr" | "owner"required
      • state"pending" | "approved" | "rejected"required
      • asked_atstringrequired
      • decidedobject | nullrequired
        4 fields
        • atstringrequired
        • byobject | nullrequired
          2 fields
          • idstringrequired
          • namestringrequired
        • commentstring | nullrequired
        • automaticbooleanrequired
      • can_decidebooleanrequired

        You may approve or send it back (an approver, not its proposer, signed in to Bizisy).

    • approval_contextobject | nullrequired

      For an approver: the published range, the band of the position's level and how many hold the title.

      3 fields
      • rangeobject | nullrequired
        4 fields
        • minnumberrequired
        • maxnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
      • bandobject | nullrequired
        5 fields
        • minnumberrequired
        • maxnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
        • source"title" | "level"required
      • title_holdersinteger | nullrequired

        How many people hold the position's title today (never their names or pay).

    • proposed_byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • sentobject | nullrequired
      3 fields
      • atstringrequired
      • expires_atstringrequired
      • remindedbooleanrequired
    • acceptanceobject | nullrequired
      3 fields
      • atstringrequired
      • typed_namestringrequired
      • sha256stringrequired
    • declinedobject | nullrequired
      3 fields
      • atstringrequired
      • reasonstring | nullrequired
      • kindstring (enum)required

        The 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 | nullrequired
      3 fields
      • atstringrequired
      • revisedbooleanrequired
      • toldbooleanrequired
    • expired_atstring | nullrequired
    • hireobjectrequired
      4 fields
      • person_idstring | nullrequired
      • failedobject | nullrequired
        2 fields
        • atstringrequired
        • reasonstringrequired
      • finishbooleanrequired

        The candidate accepted and HR must finish the hire (hiring_applications_hire_draft is filled in from the offer).

      • in_documentsbooleanrequired

        The signed offer is in the person's documents.

    • filesobjectrequired
      2 fields
      • letterobject | nullrequired

        The letter as sent (a 5-minute link, in the app only).

        1 field
        • urlstring | nullrequired
      • signedobject | nullrequired

        The signed copy with the acceptance record (a 5-minute link, in the app only, while it is kept in Hiring).

        1 field
        • urlstring | nullrequired
    • questionsintegerrequired
    • kind"hire" | "transfer"required

      transfer: to someone who works here (W7 D8): accepted in My workspace, then a job change under Settings → Approval rules.

    • transferobject | nullrequired
      5 fields
      • new_paybooleanrequired

        The offer changes their pay (else their pay stays).

      • state"none" | "waiting" | "approved" | "applied" | "rejected" | "cancelled"required

        none: not accepted yet; waiting: accepted, the job change waits for approval; approved/applied: done; rejected/cancelled: not approved (HR tells them).

      • approval_idstring | nullrequired
      • waiting_forstring | nullrequired

        waiting: the step it waits for (manager, hr).

      • approversstring[]required
    • created_atstringrequired
    • updated_atstringrequired
  • totalintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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}'
Response
{
  "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_benefits on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • offer_idstringrequired

    1–100 characters.

Returns

  • itemsobject[]required
    7 fields
    • idstringrequired
    • namestringrequired
    • funding"employer" | "flex" | "sacrifice" | "employee"required
    • amount_centsintegerrequired
    • unit"day" | "month" | "year"required
    • for_everyonebooleanrequired
    • wait_daysintegerrequired
  • flexible_budgetobject | nullrequired
    2 fields
    • budget_centsintegerrequired
    • period"month" | "year"required

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/hiring/offers.benefits \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"offer_id":"o1"}'
Response
{
  "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_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • lettersobject[]required
    7 fields
    • language"en" | "pt" | "es" | "fr" | "de"required
    • kind"permanent" | "fixed_term"required
    • titlestringrequired
    • bodystringrequired
    • custombooleanrequired

      The company's own letter (false: Bizisy's).

    • updated_atstring | nullrequired
    • pending_approvalboolean

      With Documents on and approval required to publish templates: the change waits for an approver (the letter in use stays the published one).

  • placeholdersstring[]required
  • templatesobject | null

    With 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
    • permanentobjectrequired
      2 fields
      • idstring | nullrequired
      • pending_approvalbooleanrequired
    • fixed_termobjectrequired
      2 fields
      • idstring | nullrequired
      • pending_approvalbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/hiring/letters.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • language"en" | "pt" | "es" | "fr" | "de"required
  • kind"permanent" | "fixed_term"required

    permanent (also freelance), or fixed_term (also temporary and internship contracts).

Returns

9 fields
  • language"en" | "pt" | "es" | "fr" | "de"required
  • kind"permanent" | "fixed_term"required
  • titlestringrequired
  • bodystringrequired
  • custombooleanrequired

    The company's own letter (false: Bizisy's).

  • updated_atstring | nullrequired
  • pending_approvalboolean

    With Documents on and approval required to publish templates: the change waits for an approver (the letter in use stays the published one).

  • defaultobjectrequired
    2 fields
    • titlestringrequired
    • bodystringrequired
  • placeholdersstring[]required

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • language"en" | "pt" | "es" | "fr" | "de"required
  • kind"permanent" | "fixed_term"required

    permanent (also freelance), or fixed_term (also temporary and internship contracts).

  • titlestringrequired

    1–120 characters.

  • bodystringrequired

    1–10000 characters.

Returns

7 fields
  • language"en" | "pt" | "es" | "fr" | "de"required
  • kind"permanent" | "fixed_term"required
  • titlestringrequired
  • bodystringrequired
  • custombooleanrequired

    The company's own letter (false: Bizisy's).

  • updated_atstring | nullrequired
  • pending_approvalboolean

    With 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
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}}"
}'
Response
{
  "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_reset on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • language"en" | "pt" | "es" | "fr" | "de"required
  • kind"permanent" | "fixed_term"required

    permanent (also freelance), or fixed_term (also temporary and internship contracts).

Returns

7 fields
  • language"en" | "pt" | "es" | "fr" | "de"required
  • kind"permanent" | "fixed_term"required
  • titlestringrequired
  • bodystringrequired
  • custombooleanrequired

    The company's own letter (false: Bizisy's).

  • updated_atstring | nullrequired
  • pending_approvalboolean

    With 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
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"}'
Response
{
  "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_preview on HR Assistant
Method
POST with a JSON body, or GET with 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).

  • titlestring

    1–120 characters.

  • bodystring

    1–10000 characters.

  • offer_idstring

    1–100 characters.

Returns

  • pdf_base64stringrequired
  • titlestringrequired
  • textstringrequired

    The letter's text as filled in.

  • language"en" | "pt" | "es" | "fr" | "de"required
  • kind"permanent" | "fixed_term"required

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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}}"
}'
Response
{
  "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_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • application_idstringrequired

    1–100 characters.

Returns

10 fields
  • application_idstringrequired
  • jobobjectrequired
    5 fields
    • idstringrequired
    • titlestringrequired
    • status"draft" | "open" | "paused" | "closed"required
    • open_applicationsintegerrequired

      Candidates still in the process for this job (they get "not this time" when the job closes with a reply).

    • replies_scheduledbooleanrequired

      Closed with a reply to everyone still open (it goes out after the reply days).

  • personobject | nullrequired

    null: the person was erased.

    5 fields
    • idstringrequired
    • namestringrequired
    • status"active" | "pre_hire" | "terminated" | "none"required
    • start_datestring | nullrequired
    • managerobject | nullrequired

      Their manager on their first day.

      2 fields
      • idstringrequired
      • namestringrequired
  • onboardingobject | nullrequired
    6 fields
    • checklistsintegerrequired
    • tasksintegerrequired
    • doneintegerrequired
    • openintegerrequired
    • overdueintegerrequired
    • nextobject[]required

      The next open tasks (up to 6); empty for a hiring manager who is not their manager.

      3 fields
      • titlestringrequired
      • due_datestringrequired
      • assignee"hr" | "manager" | "person" | "member"required
  • inviteobject | nullrequired

    Their 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"required
    • onstring | nullrequired
  • equipmentobjectrequired
    3 fields
    • onbooleanrequired

      The equipment register is on.

    • registeredbooleanrequired

      The company has registered equipment.

    • holdingintegerrequired

      Items registered to them.

  • probationobject | nullrequired

    The 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_datestringrequired
    • reminderobjectrequired
      3 fields
      • onbooleanrequired
      • lead_daysintegerrequired
      • datestring | nullrequired
  • one_on_oneobjectrequired
    4 fields
    • onbooleanrequired

      1:1s are on (Settings → Modules).

    • bookedbooleanrequired
    • series_idstring | nullrequired
    • first_datestring | nullrequired
  • buddyobjectrequired
    3 fields
    • fieldobject | nullrequired

      The welcome page's buddy field (Settings → Welcome page); null: none chosen.

      2 fields
      • keystringrequired
      • labelstringrequired
    • currentobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • can_setbooleanrequired
  • canobjectrequired
    4 fields
    • buddybooleanrequired
    • first_one_on_onebooleanrequired
    • close_jobbooleanrequired
    • why_notobjectrequired
      3 fields
      • buddystring | nullrequired
      • first_one_on_onestring | nullrequired
      • close_jobstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/hiring/handoff.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"application_id":"e1"}'
Response
{
  "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_apply on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • buddy_idstring | null

    1–100 characters.

  • first_one_on_oneboolean
  • close_jobboolean
  • reply_to_openboolean

    With close_job: send everyone still open the kind "not this time".

Returns

  • doneobjectrequired
    4 fields
    • buddybooleanrequired
    • first_one_on_oneobject | nullrequired
      4 fields
      • series_idstringrequired
      • first_datestringrequired
      • timestring | nullrequired
      • startedbooleanrequired
    • job_closedbooleanrequired
    • replies_tointegerrequired
  • handoffobjectrequired
    10 fields
    • application_idstringrequired
    • jobobjectrequired
      5 fields
      • idstringrequired
      • titlestringrequired
      • status"draft" | "open" | "paused" | "closed"required
      • open_applicationsintegerrequired

        Candidates still in the process for this job (they get "not this time" when the job closes with a reply).

      • replies_scheduledbooleanrequired

        Closed with a reply to everyone still open (it goes out after the reply days).

    • personobject | nullrequired

      null: the person was erased.

      5 fields
      • idstringrequired
      • namestringrequired
      • status"active" | "pre_hire" | "terminated" | "none"required
      • start_datestring | nullrequired
      • managerobject | nullrequired

        Their manager on their first day.

        2 fields
        • idstringrequired
        • namestringrequired
    • onboardingobject | nullrequired
      6 fields
      • checklistsintegerrequired
      • tasksintegerrequired
      • doneintegerrequired
      • openintegerrequired
      • overdueintegerrequired
      • nextobject[]required

        The next open tasks (up to 6); empty for a hiring manager who is not their manager.

        3 fields
        • titlestringrequired
        • due_datestringrequired
        • assignee"hr" | "manager" | "person" | "member"required
    • inviteobject | nullrequired

      Their 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"required
      • onstring | nullrequired
    • equipmentobjectrequired
      3 fields
      • onbooleanrequired

        The equipment register is on.

      • registeredbooleanrequired

        The company has registered equipment.

      • holdingintegerrequired

        Items registered to them.

    • probationobject | nullrequired

      The 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_datestringrequired
      • reminderobjectrequired
        3 fields
        • onbooleanrequired
        • lead_daysintegerrequired
        • datestring | nullrequired
    • one_on_oneobjectrequired
      4 fields
      • onbooleanrequired

        1:1s are on (Settings → Modules).

      • bookedbooleanrequired
      • series_idstring | nullrequired
      • first_datestring | nullrequired
    • buddyobjectrequired
      3 fields
      • fieldobject | nullrequired

        The welcome page's buddy field (Settings → Welcome page); null: none chosen.

        2 fields
        • keystringrequired
        • labelstringrequired
      • currentobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • can_setbooleanrequired
    • canobjectrequired
      4 fields
      • buddybooleanrequired
      • first_one_on_onebooleanrequired
      • close_jobbooleanrequired
      • why_notobjectrequired
        3 fields
        • buddystring | nullrequired
        • first_one_on_onestring | nullrequired
        • close_jobstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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
}'
Response
{
  "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_overview on HR Assistant
Method
POST with a JSON body, or GET with 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".

  • fromstring

    custom: the first day (YYYY-MM-DD).

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • tostring

    custom: the last day (YYYY-MM-DD).

    Pattern ^\d{4}-\d{2}-\d{2}$.

Returns

  • periodobjectrequired
    4 fields
    • kind"last_90_days" | "this_year" | "custom"required
    • fromstringrequired
    • tostringrequired
    • timezonestringrequired
  • scope"all_jobs" | "my_jobs"required

    all_jobs (owners, admins and HR) or my_jobs (a hiring manager: the jobs they hire for).

  • summaryobjectrequired
    8 fields
    • applicantsintegerrequired

      Applications received or added in the period (including those whose data retention has since deleted).

    • applicants_deletedintegerrequired

      Of those, how many retention deleted (counted here only; not in sources, times or steps).

    • hiresintegerrequired

      People hired in the period from Hiring (including deleted candidates' records).

    • time_to_hire_daysnumber | nullrequired

      Median days from applying to accepting the offer (or to the hire without an offer), one decimal.

    • time_to_hire_hiresintegerrequired

      Hires the median is over (those Bizisy still keeps).

    • answered_on_timeobjectrequired
      3 fields
      • dueintegerrequired

        Applicants of the period whose first answer was due (answered, or the date passed unanswered).

      • on_timeintegerrequired

        Answered (moved, written to, interviewed, told "not this time" or hired) by the date promised.

      • pctnumber | nullrequired

        on_time / due as a whole percentage; null when nothing was due.

    • offersobjectrequired
      6 fields
      • sentintegerrequired

        Offers sent in the period (a revised offer counts once).

      • acceptedintegerrequired
      • declinedintegerrequired
      • expiredintegerrequired
      • acceptance_pctnumber | nullrequired

        accepted / (accepted + declined + expired) as a whole percentage; null when none was answered or ended.

      • decline_reasonsobject[]required

        The reasons candidates picked when declining (never their words).

        2 fields
        • reasonstring (enum)required

          One of: pay, other_offer, role, location, start_date, personal, other, not_given.

        • countintegerrequired
    • open_jobsintegerrequired

      Jobs open today.

  • sourcesobject[]required
    4 fields
    • sourcestring (enum)required

      careers (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 | nullrequired
    • applicantsintegerrequired
    • hiresintegerrequired
  • stepsobject[]required

    Across the jobs: New, each kind of step (a job's steps grouped by kind), Offer.

    3 fields
    • keystring (enum)required

      new, 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 | nullrequired

      The median days candidates spent there (one decimal); null when nobody left it in the period.

    • staysintegerrequired

      How many times candidates left it in the period (the median is over these).

  • jobsobject[]required
    13 fields
    • idstringrequired
    • titlestringrequired
    • status"draft" | "open" | "paused" | "closed"required
    • opened_onstring | nullrequired
    • closed_onstring | nullrequired
    • days_openinteger | nullrequired

      Days from opening to closing (or today while open); null for a job never opened.

    • applicantsintegerrequired
    • interviewedintegerrequired

      Applicants of the period who moved past New (to a step, the offer or hired).

    • hiresintegerrequired
    • time_to_hire_daysnumber | nullrequired

      The median days to hire of its hires in the period; null without one.

    • answered_on_time_pctnumber | nullrequired
    • offersobjectrequired
      3 fields
      • sentintegerrequired
      • acceptedintegerrequired
      • declinedintegerrequired
    • stepsobject[]required
      5 fields
      • keystringrequired

        new, offer, or the step's id.

      • median_daysnumber | nullrequired

        The median days candidates spent there (one decimal); null when nobody left it in the period.

      • staysintegerrequired

        How many times candidates left it in the period (the median is over these).

      • namestring | nullrequired

        The step's name (null for New and Offer).

      • kindstring (enum)required

        One of: new, call, interview, panel, task, trial, presentation, references, final, offer.

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_export on HR Assistant
Method
POST with a JSON body, or GET with 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".

  • fromstring

    custom: the first day (YYYY-MM-DD).

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • tostring

    custom: the last day (YYYY-MM-DD).

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • lang"en" | "pt" | "es" | "fr" | "de"

Returns

  • fileobjectrequired
    6 fields
    • namestringrequired
    • content_typestringrequired
    • encoding"utf8" | "base64"required
    • contentstringrequired
    • bytesintegerrequired
    • sha256stringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_form on My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • job_idstringrequired

    1–100 characters.

Returns

7 fields
  • jobobjectrequired
    5 fields
    • idstringrequired
    • titlestringrequired
    • audience"public" | "internal_first" | "internal_only"required
    • answer_daysintegerrequired
    • questionsobject[]required
      5 fields
      • idstringrequired
      • textstringrequired
      • kind"text" | "yes_no" | "choice"required
      • optionsstring[]
      • requiredbooleanrequired
  • meobject | nullrequired
    4 fields
    • namestringrequired
    • work_emailstringrequired
    • titlestring | nullrequired
    • unitstring | nullrequired
  • blockedobject | nullrequired
    4 fields
    • rule"min_months" | "probation" | "hiring_manager" | "view_only" | "limit" | "off"required
    • untilstring | nullrequired
    • monthsinteger
    • maxinteger
  • noticeobjectrequired
    5 fields
    • rule"on_apply" | "on_interview" | "on_offer" | "at_transfer"required
    • managerobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • why"rule" | "hiring_team" | "approval"required
    • told_nowbooleanrequired
    • sentencestringrequired
  • nudge_manager_talkbooleanrequired
  • alreadystring | nullrequired

    Your 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
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"}'
Response
{
  "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_apply on My Workplace
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • answersobject[]

    Up to 5 items.

    2 fields
    • question_idstringrequired

      1–40 characters.

    • answerstringrequired

      Up to 500 characters.

  • notestring

    Up to 1000 characters.

  • cv_file_idstring

    An optional CV uploaded with hiring_internal_cv_upload_url.

    1–100 characters.

Returns

  • application_idstringrequired
  • answer_bystringrequired
  • noticeobjectrequired
    5 fields
    • rule"on_apply" | "on_interview" | "on_offer" | "at_transfer"required
    • managerobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • why"rule" | "hiring_team" | "approval"required
    • told_nowbooleanrequired
    • sentencestringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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."
}'
Response
{
  "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_mine on My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • applicationsobject[]required
    9 fields
    • idstringrequired
    • jobobjectrequired
      4 fields
      • idstringrequired
      • titlestringrequired
      • unitstring | nullrequired
      • locationstring | nullrequired
    • stagestring (enum)required

      One of: applied, interviewing, offer, moved, not_this_time, withdrawn, closed.

    • applied_atstringrequired
    • updated_atstringrequired
    • answer_bystring | nullrequired
    • notestring | nullrequired
    • can_withdrawbooleanrequired
    • offerobject | nullrequired
      11 fields
      • idstringrequired
      • status"sent" | "accepted_pending_hire" | "accepted" | "declined" | "expired" | "withdrawn"required
      • titlestringrequired
      • teamstring | nullrequired
      • placestring | nullrequired
      • start_datestringrequired
      • expires_onstringrequired
      • weekly_hoursnumber | nullrequired
      • payobject | nullrequired

        The new pay when the offer changes it (only you, HR and approvers see it).

        3 fields
        • amountnumberrequired
        • currencystringrequired
        • periodstringrequired
      • notestring | nullrequired
      • transfer"none" | "waiting" | "approved" | "applied" | "rejected" | "cancelled"required

        waiting: accepted, waiting for approval; applied/approved: agreed.

  • enabledbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/hiring/internal.mine \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_withdraw on My Workplace
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

Returns

  • application_idstringrequired
  • stage"withdrawn"required

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_view on My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • applicationsobject[]required
    5 fields
    • idstringrequired
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • job_titlestringrequired
    • stagestring (enum)required

      One 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
curl https://api.bizisy.com/v1/hiring/internal.manager_view \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_url on My Workplace
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • namestringrequired

    1–200 characters.

  • sizeintegerrequired

    From 1 to 10000000.

  • content_type"application/pdf" | "application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "image/jpeg" | "image/png" | "image/heic"required
  • sha256stringrequired

    Pattern ^[0-9a-f]{64}$.

Returns

  • file_idstringrequired
  • uploadobject | nullrequired
    4 fields
    • urlstringrequired
    • method"PUT"required
    • headersobjectrequired
    • resumablefalserequired
  • expires_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
}'
Response
{
  "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_internal on My Workplace
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • accepttruerequired

Returns

  • state"accepted"required
  • accepted_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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}'
Response
{
  "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_internal on My Workplace
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • kindstring (enum)

    One of: pay, other_offer, role, location, start_date, personal, other.

  • reasonstring

    Up to 500 characters.

Returns

  • state"declined"required

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_transfer on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

Returns

  • state"applied" | "waiting"required

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "data": {
    "state": "waiting"
  }
}

Something missing or wrong on this page? Write to hello@bizisy.com.

Developer docs