API Integration Guide

Flowmingo has a REST API for your own systems. With an API key you can create hiring projects and assessments, read a project and edit its name and the words of its job post, publish and boost a job post, invite candidates (now or at a time you choose) and pause and resume an invitation's automatic reminders, hand over recordings of interviews you ran yourself to be scored, read scores and AI evaluations, read the transcript and the recording links of a finished interview, read counts of what was recorded during a finished Skill Test or Technical Test, ask a question about your hiring data in plain words, make and manage tracking links (the custom share links of Settings), read your email sequences and how they are doing, update your hiring pipeline, and poll the same events that webhooks deliver. This guide covers all 77 operations of the public API. If you would rather be told when something happens than ask, use webhooks.

• Base URL: https://apis.flowmingo.ai/company/integration. A path such as GET /me/v1 in this guide means GET https://apis.flowmingo.ai/company/integration/me/v1.
• One environment: the public API has one environment, production. Every call acts on your real data, and every key starts with fl_live_. To try a call safely, invite yourself first (see section 1.4). There is no sandbox or test mode: section 1.5 says what that means and how to test without reaching real candidates.
• Machine-readable description: the OpenAPI document (version 3.0) is at https://flowmingo.ai/openapi.json. It is a static file that lists the 77 operations of this guide, each with its summary, the scope it needs, its parameters, its request body and its response shape, and the x-api-key header. Import it into Postman, Insomnia or any API client or no-code tool that reads OpenAPI. Its server is https://apis.flowmingo.ai/company, so its paths start with /integration/. We refresh the file when the API changes; if it and this guide ever differ, this guide is right.

1. Quick start: your first invitation in 5 minutes

You need an Owner or Admin account (only they can create API keys) and one AI interview or role-play in your workspace (make one in the dashboard, or through the API: section 3.6). The samples use curl; any HTTP client works the same way.

1.1 Create a key with the scopes you need

1. Sign in at https://team.flowmingo.ai, click your email at the bottom-left of the sidebar, then Settings.
2. Open Integrations -> API Keys and click Create New Key.
3. Type a Name. The name is required.
4. Tick the permissions (scopes) the key needs. For this quick start tick Read hiring data (read_hiring) and Invite candidates (invite_candidates). Tick Read candidates (read_candidates) as well if you want candidate names and email addresses in results. A key with no scope ticked can do almost nothing, so always tick at least one.
5. Click Create secret key.
6. Copy the secret from the API Key Created! window now. It is shown once and looks like fl_live_abcd12345.n8G3zPNw9gWkK1Kj.

Keep it in an environment variable for the next steps:

export BASE='https://apis.flowmingo.ai/company/integration'
export FLOWMINGO_API_KEY='fl_live_abcd12345.n8G3zPNw9gWkK1Kj'

1.2 Check the key

curl -s -H "X-API-Key: $FLOWMINGO_API_KEY" "$BASE/me/v1"

{
  "api_key_id": "0b0a9f3e-6c2d-4c1a-9a47-5d3e8b7f2a10",
  "organization_id": 4217,
  "scopes": ["read_hiring", "invite_candidates"],
  "expires_at": null
}

A 200 with your scopes means the key works. A 401 means the key was not accepted (section 11 explains each message).

1.3 Find an assessment and look at results

curl -s -H "X-API-Key: $FLOWMINGO_API_KEY" "$BASE/hiring/interview-sets/v1?limit=5"

{
  "data": [
    {
      "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
      "title": "Senior Backend Engineer - Async Interview",
      "position": "Senior Backend Engineer",
      "status": 1,
      "assessment_type": "ai_interview",
      "set_type": 1,
      "interview_duration": 20,
      "cfg_lingual_ids": [290],
      "project_ids": ["a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"],
      "created_at": "2026-10-01T09:30:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 5
}

Copy the id of an assessment whose assessment_type is ai_interview or role_play and whose status is 1 (published): the simplest kinds to send through the invite route. An invitation to a draft, inactive or archived assessment is created but not emailed (section 4.5). Section 4.1 says what a key whose creator is limited to some projects can send to. A Skill Test, a Technical Test or a Showcase can be sent through it too, with a few extra rules (sections 4.2, 4.6 and 4.8). Then list its results:

export SET_ID='3f2504e0-4f89-41d3-9a0c-0305e82c3301'   # replace with your own id
curl -s -H "X-API-Key: $FLOWMINGO_API_KEY" "$BASE/hiring/submissions/v1?com_interview_set_id=$SET_ID&limit=5"

The answer is { "data": [...], "total": n, "page": 1, "limit": 5 }. A candidate you have invited but who has not started yet is listed too, with status 5 and submission_at null (section 5.2 describes every field).

1.4 Send one invitation, to yourself first

curl -X POST "$BASE/interview/candidate/invite/v1" \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $FLOWMINGO_API_KEY" \
  --data @- <<EOF
{
  "com_interview_set_ids": ["$SET_ID"],
  "candidates": [{ "name": "Your Name", "email": "you@example.com" }],
  "invitation_message": "Testing the Flowmingo API: please ignore this invitation."
}
EOF

Replace you@example.com with your own address. This creates a real invitation and, for a published assessment, makes it eligible for an email to be queued. That is not a promise: the sender can still skip an invitation (for example when the candidate already has a result on that assessment, or the address failed our address check). Queued means handed over for sending, not delivered: the email can leave before or after the answer, and it can be delayed. For a draft, an inactive or an archived assessment nothing is emailed and the result carries warnings (section 4.5); a result without warnings still does not prove that the email was delivered. The answer is 201 with a results array that holds the invitation that was created (section 4.5 shows the full response). Once that works, read section 2.3 to give a production key only the scopes it needs, and section 8 for how errors, limits and retries behave. If you use Zapier, Make or n8n instead of code, section 10 has two step-by-step recipes.

1.5 Trying the API safely

The API has no sandbox, no test mode and no test keys. Every key starts with fl_live_, every call acts on your real account, and nothing is simulated: an invitation to a published assessment can send a real email, a project made through the API creates a real job post that can become public after review, and whatever costs something in production costs the same when you are only testing. These habits keep a test away from real candidates and real data:

1. Test in a separate company account. A key reaches only the organization that owns it (section 2.9), and the limits of section 8.5 are counted for each organization and each key. A second company account that you make for testing therefore keeps its candidates, projects, keys and counts apart from your production account. Create the key for it in that account (section 2.2).
2. Invite only addresses you control, such as your own (section 1.4). An invitation to a published assessment can send a real email to the address (sending and delivery are not guaranteed: section 1.4).
3. To watch an invitation without an email going out, schedule it far ahead and cancel it. For an AI interview or a role-play, send_at accepts a time from 2 minutes to 90 days from now (section 4.9). An invitation scheduled 60 days ahead and cancelled (section 4.9.1) before it is due is not emailed. The scheduled invite itself creates or uses a candidate record and, when a project is named, can add the candidate to its board: check the entry of each candidate in results (section 4.5). Creating a real invitation (not a practice invitation) can also produce an invitation.lifecycle.update event with the status invitation_created (see the webhook guide), and, for a candidate who already has a Flowmingo account, Flowmingo also attempts an in-app notice at once (section 4.9.2). Neither effect waits for send_at. Use addresses you control here too.
4. Pause the reminders of a test invitation that you do send (section 4.10), so that the candidate is not chased: Reminder 1 would be due 2 days after the invitation email went out and Reminder 2 two days after that. The pause never holds the invitation email back, so you can call it right after the invite call. Leave it paused: if you or a teammate resumes it after a reminder's due day, that reminder is skipped, and if before, it goes (section 4.10.1). It works for an AI interview or a role-play invitation; an invitation to another kind of assessment is refused with 409 (section 4.10).
5. Clean up what a test makes. A project made through the API creates a real job post that can become publicly available after the automatic content check (section 3.5.2). If you do not want it public, unpublish it (section 3.7.3) or archive the project (section 3.7.5) promptly. Deleting a project through the API needs a person to approve it (section 9.7.2). Assessments made with the AI use your generation budget (section 3.6.11), and a Skill Test, a Technical Test or a Showcase that your organization has set up as sponsored can use your organization's wallet when a candidate takes it (sections 4.6.7 and 4.8.3).

2. Request an API key

2.1 Open the API Keys panel

1. Sign in at https://team.flowmingo.ai.
2. Click your email at the bottom-left of the sidebar, then Settings.
3. In the Settings window open Integrations -> API Keys.

Only Owners and Admins can create, edit or delete API keys. A Member cannot.

2.2 Create a key

1. Click Create New Key.
2. In the Create New API Key window, type a Name. The name is required. The Description is optional.
3. Tick the permissions (scopes) the key needs. Tick at least one: see section 2.3.
4. Click Create secret key.

You will receive a one-time secret with the format fl_live_<prefix>.<secret>, for example fl_live_abcd12345.n8G3zPNw9gWkK1Kj. Copy and store it immediately: Flowmingo keeps only a hash, and cannot show it again. After creation the key is masked in the list (for example fl_live_abcd12345.****).

A key acts with the permissions of the person who creates it, not with a company-wide login. Read section 2.9 before you create a key for a shared integration.

An organization can hold at most 50 active keys. Turned-off and deleted keys do not count. Creating a 51st, or turning a turned-off key back on when 50 are active, answers 409 with the code api_key_limit_reached: turn off or delete a key you no longer use, or write to contact@flowmingo.ai (section 8.5).

2.3 Choose scopes

A scope is a permission. A route that needs a scope answers 403 (API key missing required scope: <scope>) when the key does not carry it. There are eleven:

GET /me/v1 needs no scope. A key with no scope can call GET /me/v1 and is refused (403) by every route that reads or changes your data, except that it can still read and withdraw the approval requests it made earlier (section 9.7). A key made with nothing ticked looks valid and does nothing new. The dashboard lets you create one, so tick at least one scope.

Combinations that people use:

• Reporting into a spreadsheet or BI tool: read_hiring, plus read_candidates if the report needs names. Reading the transcript or the recording links of an interview needs both (section 5.10).
• Starting assessments from a form or an ATS: invite_candidates alone.
• Syncing stages with an ATS: read_hiring and write_pipeline.
• Opening a role from your own system: create_project to create the hiring project (the same call can make its assessments, section 3.5.5), to edit it and the words of its job post (section 3.5.14) and to publish or boost its job post (section 3.7), create_assessment to make further assessments with the AI (section 3.6) or create_set to build one from your own questions (section 3.1), and invite_candidates to invite into it.
• Handing over recordings of interviews you ran yourself: submit_recordings for the two recording routes, create_set to make the recording evaluation they are scored against (section 4.7.1), and read_hiring to read the scores.
• Managing tracking links from your own system: manage_tracking_links to make, change, switch off and delete links (making one needs the Growth plan), read_hiring and read_candidates to list them, and read_candidates to list the sources (section 3.8).
• Reading how your email sequences are doing: read_sequences alone (section 5.12).
• Reading what was recorded during a Skill Test or a Technical Test: read_integrity with read_hiring and read_candidates (section 5.13).
• An AI assistant (MCP): read_hiring and read_candidates, plus write_pipeline and invite_candidates if it may act. Add create_project and create_assessment only if you want it to create projects and assessments and to publish, close or boost a job post: they are opt-in at the MCP sign-in (a client must ask for them by name), the tools act at once (except delete_project, which only asks a person to approve deleting a project, section 9.7.2), and the key's creator must be an Owner or an Admin. The assistant does not use create_set or submit_recordings.

Candidate names and email addresses require read_candidates. read_hiring alone returns ids, scores and evaluations. Without read_candidates, candidate_name, firstname, lastname and email are left out of the applications, results and result-detail responses, and candidate_email and source_detail are removed from events. GET /me/v1 shows what your key holds.

2.4 Edit, rotate or revoke

Use Edit on a key to change its name, description, scopes and status (Active or Disabled). The secret itself cannot be changed. A change to scopes or status applies from the next request made with the key.

Taking access away is always allowed: remove a scope, turn the key off, rename it. Giving a key more access (adding a scope, or turning a disabled key back on) is allowed only to the person who created it or to an Owner, and only while that creator is still in the company and is an Owner or an Admin. If the creator has left, take the key over first (section 2.10).

There is no rotate action. To rotate a key, create a new one, switch your integration to it, then delete the old one. An organization that already has 50 active keys cannot create the new key first (section 2.2): turn off or delete a key you no longer use to make room. Deleting a key revokes it from the next request made with it. A deleted key answers 401 Invalid API key, and so does a disabled one, except a key turned off because its creator left, which answers 403 with the code key_creator_left (section 2.10).

Keys created in the dashboard do not expire (expires_at is null). Revoke a key you no longer need by deleting it.

If the person who created a key leaves the company, the key normally stops after seven days unless an Owner or an Admin takes it over (at once, if no other Owner is left in the company). See section 2.10.

2.5 Security notes

Store API keys in a secret manager (AWS Secrets Manager, GCP Secret Manager, 1Password, etc.). Never embed keys in frontend code, logs, or version control. Always send the key in a header, never in a URL or in the request body: URLs end up in logs and browser history.

A key acts with the permissions of the person who created it (section 2.9). If that person is limited to some projects, the key has the same limit: the projects they can open and the interview sets they created. A key made by an Owner, or by someone with access to all hiring projects, reaches all of your organization's hiring data, so create it only for an integration you trust with that. Notes, ratings, shortlists and stage moves made with a key are recorded under the name of the person who created it. Sending a Skill Test, a Technical Test or a Showcase goes out on behalf of that person too and uses the hiring projects they can open (section 4.6.2). Publishing and boosting a job post act as that person too (section 3.7).

2.6 Authenticate your requests

Send the key in the X-API-Key header:

X-API-Key: fl_live_abcd12345.n8G3zPNw9gWkK1Kj

The Authorization header carries the same key too, in these forms, for tools that cannot set a custom header:

• Authorization: ApiKey fl_live_abcd12345.n8G3zPNw9gWkK1Kj
• Authorization: Bearer fl_live_abcd12345.n8G3zPNw9gWkK1Kj. This is accepted when the value starts with fl_, which every Flowmingo key does. Any other bearer value, such as a session token, is not an API key and answers 401 API key is required.
• Authorization: Basic <base64>, with the key as the user name and an empty password. Some applicant-tracking tools can send a key only this way. It is read as a key only when the user name starts with fl_.

A tool that only offers "Bearer token" authentication therefore works without a custom header.

2.7 Check a key

To check a key without side effects, call the introspection endpoint. It needs no scope, so any valid key can verify itself:

curl -s -H 'X-API-Key: fl_live_abcd12345.n8G3zPNw9gWkK1Kj' \
  https://apis.flowmingo.ai/company/integration/me/v1

{
  "api_key_id": "0b0a9f3e-6c2d-4c1a-9a47-5d3e8b7f2a10",
  "organization_id": 4217,
  "scopes": ["read_hiring", "read_candidates", "write_pipeline", "invite_candidates", "create_set", "create_project", "create_assessment", "submit_recordings"],
  "expires_at": null,
  "features": { "ask_data": true }
}

A 200 proves the key is accepted and shows which organization and scopes it carries. features says which optional abilities the key has right now: ask_data is true only when your company has asking questions of your hiring data switched on and the key carries read_hiring (section 5.11). It is a hint for your client, not a permission: each route checks the key again on every call. It does not list the projects the key can open: that is its creator's list (see section 2.9). A key whose creator left and whose grace period is over (section 2.10), whose creator can open no hiring project, or that has no creator on record answers 403 with the reason instead of 200. A 503 means the permissions of the key could not be checked just now: send the request again. Anything else: see section 11, Troubleshooting.

2.8 When a key was last used

The Last used column in the key list shows when the key last made a request. Every request that presents a valid key counts, whatever it does: reads, writes, the events feed, and calls made through an AI assistant connected with that key. A request refused because the key is unknown, disabled, deleted or expired does not count. The time is brought up to date about once an hour, so a key you used a minute ago can still read "Never" for a while.

2.9 Whose permissions a key carries

A key does what the person who created it can do, and no more.

• Reach. If the creator has access to all hiring projects (an Owner always does), so has the key, and it reaches the whole organization. If the creator is limited to some projects, the key has that limit: the projects they can open and the interview sets they created. An Admin who was given projects one by one is limited to that list, even if it names every project today. Lists, counts and averages leave out what the key cannot reach.
• Their own interview sets. For an interview set the creator made, the key can read its results and its candidates, add notes, ratings and shortlist marks to those results, add those candidates to the talent collection, and file recordings into a recording evaluation they made. Ownership alone does not authorise an invite: a limited key can invite only into a set that has a live, switched-on link to one of the creator's projects.
• Their role, for creating things. In the dashboard only an Owner or an Admin can create an interview set, a hiring project or an assessment, and a key follows that rule on the three scopes that do these: create_set, create_project and create_assessment. If its creator has been made a Member, a request that needs one of them is refused with a 403 before anything is created (section 11). For create_set the role they left with normally counts during the grace period after they leave (section 2.10). Nothing else about the key changes: its other scopes still work, inside the creator's projects. The other five scopes (read_hiring, read_candidates, write_pipeline, invite_candidates and submit_recordings) have no rule of this kind, because a Member can do the same things in the dashboard. The three opt-in scopes for tracking links, email sequences and integrity signals differ: manage_tracking_links has a rule of its own, that its creator must be an Owner or an Admin (section 3.8), read_sequences has none, except that its activation preview is answered only for an Owner or an Admin (section 5.12.4), and read_integrity needs a key whose creator is currently an Owner or an Admin (section 5.13).
• It follows its creator. If the creator's access changes later, the key's reach changes with it. You do not need to issue a new key.
• The key's own settings only narrow. A scope you leave off a key (for example read_candidates, so no candidate names) takes something away. No setting gives a key more than its creator has.

The response code tells you what was refused: 403 with the code key_out_of_reach for something the key cannot reach, or 404 where the record is not visible to the key. Each route's section states the errors it can answer; branch on the code, not on the status alone. The events feed (section 7) needs a key whose creator has access to all hiring projects.

2.10 When the person who created a key leaves

A key carries its creator's permissions and nothing of its own, so it cannot outlive its creator's access. After the creator leaves, the key keeps working for a grace period: seven days, or until the date chosen when the member was removed with a delayed deletion (see below). So that your integration does not stop without warning:

1. Unless item 6 applies, every Owner and every Admin of the company gets an email that names the keys, who created them and the date they stop. The person who removed the member, when someone did, is not emailed.
2. During the grace period the key normally keeps working with the access the creator had on the day they left. Several things differ. Creating a hiring project or an assessment stops at once, because those routes ask for the person's role again and a person who has left holds none (sections 3.5 and 3.6.1); creating an interview set carries on with the role they left with (section 3.1). Sending a Skill Test or a Technical Test (section 4.6) also stops at once and answers 404 Project ... not found, because those two go out as the person and read their access today. Editing the words of a job post (section 3.5.14) and pausing or resuming an invitation's reminders (section 4.10) read the person's access today too: a body with a job_post part, even an empty {}, answers 403 with the code key_out_of_reach before anything is written, whatever role the creator left with (the same key can still edit the project's own fields in a body without one), and the stop-reminders and resume-reminders calls answer 404 with the code invitation_not_found for every invitation. The tracking-link routes (section 3.8), the email-sequence routes (section 5.12) and the integrity route (section 5.13) refuse such a key during the grace period too, normally with a 403, and the code is normally key_creator_left on the tracking-link routes and key_creator_in_grace on the email-sequence routes. And a key whose creator could open no hiring project when they left has nothing to carry on with, so it stops at once, and the email lists it as already stopped.
3. An Owner or an Admin can take the key over in Settings -> Integrations -> API Keys: the key shows a "Take over" button. From then on the key belongs to that person and works with their access (an Admin's access is the Admin's own projects, so the key can become narrower). Its scopes stay as they are.
4. When you take a key over you can ask for a new secret. The person who left may still hold the old one, so a new secret is the safer choice. If you ask for one, the old secret stops working when the take-over is saved, and you see the new one once. Anything that used the old secret, including an AI assistant connected through MCP, must be given the new one or connected again. If you do not ask for one, the old secret keeps working, now with your access.
5. If nobody takes the key over, it normally stops when the grace period ends (a creator who is re-invited is the exception). Every request then answers 403 with the code key_creator_left, except for a key whose delayed deletion has run: that key is deleted and answers 401 like any deleted key, and cannot be taken over.
6. If no other Owner is left in the company when the creator leaves (Admins do not count for this), the key gets no grace period: it is turned off at once, and nobody is emailed, even if Admins remain. Requests answer 403 with the code key_creator_left and a message that says the key was turned off, as long as the secret is right (a wrong secret still gets 401 Invalid API key). An Owner or an Admin can take the key over and turn it back on in Settings, or you can create a new key.

Only an Owner or an Admin can take a key over. Taking over a key whose creator is still in the company is normally refused with 409: ask them to hand it over, or create a new key. A key that has already stopped can always be taken over. A creator who is still in the company but can open no hiring project (for example an Admin whose project access was taken away) has a key that has stopped working (the 403 about hiring projects in section 11). Settings shows that key as stopped, and an Owner or an Admin can take it over to bring it back.

Removing someone in the dashboard. When an Owner or an Admin removes a team member who has keys, the Remove screen asks what to do with them: hand them to an Owner or an Admin and keep the secrets, hand them to the person who is removing the member and issue new secrets, or delete them (at once, or after 7, 14 or 30 days). The keys keep working until the chosen date. They are then deleted unless someone takes them over, the person has come back, or a key was turned off in the meantime (delete such a key in Settings); where no other Owner is left, a delayed deletion becomes an immediate stop and the keys are not deleted (deleting at once is not affected). Settings -> Integrations -> API Keys shows what became of each key, and you can delete a key there. With no choice, the keys follow the normal grace period above. This is a screen of the dashboard, not a route of this API.

A key you gave to an applicant-tracking tool. A key you paste into a tool such as Recruitee or Zoho Recruit follows the same rules, so create it as an Owner. The tool's list of tests and its sends follow the creator's permissions (section 2.9). When the creator leaves and the grace period runs out, the tool's calls to Flowmingo start failing with the 403 in section 11, until an Owner or an Admin takes the key over or you give the tool a new key. A key that was deleted answers 401 and cannot be taken over: create a new key and update the tool.

3. Create assessments and hiring projects through the API

There are three ways to create things with the API:

Sections 3.1 to 3.4 describe the third: use POST /interview/set/v1 to programmatically provision an interview set (interview or CV set) along with its questions, requirements, and access list. To put the set in a new hiring project, create the project first (section 3.5).

Creating is not the same as opening the role to candidates. Once a project and its job post exist, section 3.7 shows how to publish and unpublish the job post, boost it, and open or close the project. Section 3.8 shows how to make tracking links for a job post, a set of job posts or your careers page, to see where applications come from.

3.1 Endpoint & environments

Method: POST. Required API key scope: create_set.

The key acts with its creator's permissions (section 2.9). It can create interview sets only while its creator is an Owner or an Admin, the same people who can create a set in the dashboard. During the grace period after the creator left (section 2.10), the role they left with normally counts. If the creator has since become a Member, the request is refused with a 403 and nothing is created (see section 11).

3.2 Request payload

Choose how an AI interview gets its questions. POST /interview/set/v1 creates the assessment already live, so an AI interview (set_type 1, the default) must say who decides what the AI interviewer asks. Send question_mode:

• realtime, the product's "Let AI decide during interview": the AI chooses the interview questions for you. Send no interview question and Flowmingo prepares them from the role, the description and the criteria (iai_requirements, the first 20 are used) you send, and saves them with the assessment. The request then takes longer, typically 10 to 30 seconds, so give it a generous timeout. If you do send interview questions of your own they are kept, and no more are prepared. Your pre_screening questions are kept (Flowmingo only numbers them, in the order you send them).
• predefined, the product's "I'll set the questions": the AI interviewer asks the interview questions you send in iai_questions, in your order, as many as the interview length allows. Send at least one entry whose question_mode is interview (the default).

question_mode is required whenever the request holds no interview question. A request that names no question_mode but does hold an interview question is predefined, so a request that already works keeps working. A request with neither is refused:

{ "code": "question_mode_required", "message": "Choose how this AI interview gets its questions. Send \"question_mode\": \"realtime\" (Let AI decide during interview: Flowmingo prepares the interview questions from the role and the criteria) or \"question_mode\": \"predefined\" (I'll set the questions: send at least one interview question in \"iai_questions\", whose \"question_mode\" is \"interview\")." }

A predefined request with no interview question is refused with the code interview_questions_required:

{ "code": "interview_questions_required", "message": "An AI interview needs at least one interview question, and this request has none, so there would be nothing for the AI interviewer to ask. Add at least one interview question (an iai_questions entry whose question_mode is interview) and send the request again." }

Both are a 400 and nothing is created. If Flowmingo cannot prepare the questions for a realtime request just now, the answer is a 503 with the code question_generation_failed, nothing is created, and you can send the same request again (or switch to predefined and send your own interview questions). Pre-screening questions (question_mode pre_screening inside iai_questions) are asked on the candidate's form, not by the interviewer, so they never count as interview questions. The rule applies only to AI interviews: a CV evaluation (set_type 2) and the other kinds need no question_mode and ignore the field whatever it holds. For an AI interview, any value other than realtime or predefined is a 400 that lists the two that are allowed (null counts as not sent). AI interviews you created earlier are not affected.

Numbers must be JSON numbers. set_type, interview_duration, number_of_retakes and priority are refused with a 400 when they arrive as text, even numeric text: "interview_duration": "30" answers interview_duration must be a whole number (a JSON number, not text). Send 30, not "30".

3.2.1 iai_questions[] item

3.2.2 iai_requirements[] item

cfg_importance_id values. These are configured IDs, not a 1-4 scale, and the lowest ID is the weakest importance. Importance sets how heavily the requirement counts toward the candidate's evaluation score. The ID selects the importance, and the importance carries the weight:

If omitted, or if the value is not one of the four above, the requirement is stored as 244 (Good To Have).

3.2.3 com_accesses[] item

A new assessment is open to anyone who has its link, so this list only matters once the assessment is restricted to listed candidates. It is a list of candidates, not of your teammates, and it does not change which teammates can see the assessment. Duplicate addresses are stored once.

3.2.4 cfg_lingual_ids values

Like cfg_importance_id, these are configured IDs rather than a sequence, so the two you are most likely to need are listed here:

Send them as an array of integers, e.g. [290] or [290, 204]. The array is the set of languages a candidate is allowed to conduct the interview in.

If you omit the field, English is applied for you. That default is best-effort, so send [290] explicitly if your integration depends on the language being set deterministically. CV sets (set_type: 2) have no interview, so the field is ignored for them.

Need an ID for a language that is not listed? Ask us rather than guessing — a value that is not a real configuration ID is stored as-is and then resolves to nothing.

Evaluation report language is a separate setting that this endpoint's documented contract does not cover, so do not rely on setting it here. If none is ever stored, reports come out in English. Once a language has been stored for a set it is fixed — a later attempt to change it is ignored rather than rejected, because reports already written are never regenerated.

3.2.5 Your own ids on the assessment, its questions and its criteria

external_id can be sent on the body (the assessment), on each entry of iai_questions and on each entry of iai_requirements. The rules are those of section 8.8: optional, plain text of 1 to 128 characters, stored exactly as you send it, scoped to your company, not unique, and fixed when the assessment is created. A value that breaks them is a 400 with no code and the message "external_id must be plain text of 1 to 128 characters with no control characters. It is stored exactly as sent." Nothing is created.

The answer returns them (section 3.4): results.external_id for the assessment, and results.iai_questions and results.iai_requirements for the questions and criteria. GET /hiring/interview-sets/v1 returns the assessment's external_id on every row, and GET /hiring/interview-sets/v1?external_id= finds it. No other route reads a question or a criterion back. A copy of the assessment made in the dashboard starts without ids. Never pair the returned rows with your input by their position in the list: on the call that makes the assessment they come in the order you sent, but the repeat of a keyed request lists the questions and criteria as they are now (section 3.2.6). Matching by external_id works only for the entries whose ids you supplied and that are distinct in the list. An entry you gave no id, an entry whose id is also on another entry (ids are not unique) and a question Flowmingo prepared for a realtime interview (it was never in your input) cannot be matched that way. If you need to match them, give every question and criterion its own distinct external_id.

When you send an idempotency_key (section 3.2.6), the external_id is part of the request: the same key with a different external_id is a 409.

3.2.6 Retrying safely: idempotency_key

Without a key this route has no protection against a duplicate: sending the same request twice makes two assessments. Send an idempotency_key to make a retry safe. Here it is optional (the project route and the six assessment routes require one). It is a token you choose, 8 to 128 characters from A-Z a-z 0-9 . _ : -, for example the id of the requisition in your own system plus a suffix; anything else is a 400 with the message "idempotency_key must be 8 to 128 characters from A-Z a-z 0-9 . _ : -". It belongs to your organization, whichever of your API keys sends it, and it is remembered for good.

• "The same request" is the body exactly as you sent it, less the key. The order of the keys does not matter; any other difference counts (the external_id, the project_id, one word of a question). A repeat is compared with the body of the first call, not with the assessment as it looks now.
• Who can get the assessment back. A repeat is answered only if the key's creator has the same reach over the assessment as GET /hiring/interview-sets/v1 gives: they can open every project (an Owner, or an Admin with access to all), or the assessment is linked to a project they can open, or they made it themselves. An assessment made by a request that carries an idempotency_key counts as made by the person who created the API key, so a repeat from the same API key is not refused for this reason. An assessment made without project_id is visible to the keys of its maker and to no one else who is limited to some projects.
• A request that fails before the assessment is saved (a 400, a plan limit, a 503 question_generation_failed, an unexpected error) does not use its key up: send it again at once. One that is refused before the key is reserved (a 403 for a project outside the creator's reach, a 404 for a project that does not exist) never touches the key.
• A call that is cut off (a restart, for example) keeps its key busy: identical repeats get 409 idempotency_request_in_progress until the reservation is ten minutes old, and then the next identical request takes it over and makes the assessment. A different body under that key is 409 idempotency_key_reused for good.
• A repeat returns the assessment as it is now, with any edit made in the dashboard, not as it was first made. It does not repeat the steps after the save, which is why addons is refused with a key. The answer has the shape of section 3.4. That includes the lists results.iai_questions and results.iai_requirements: on the call that makes the assessment they come in the order you sent them, and on a repeat they are the questions and criteria the assessment holds now, in their current order, so someone who has added, removed or reordered some in the dashboard changes what the repeat lists. Never pair a returned row with your input by its position. Matching by external_id works only for the entries whose ids you supplied and that are distinct in the list: an entry with no external_id, an entry whose external_id is also on another entry, and a question Flowmingo prepared for a realtime interview cannot be matched that way. Give every question and criterion its own distinct external_id if you need to match them.
• The key lives in a list of its own. The same token can also be used on the six assessment routes, and GET /assessments/requests/{idempotency_key}/v1 does not see a key made here: it answers 404 assessment_request_not_found.
• The key is not the external_id. The key protects a retry and is remembered for good; the id tags the record and can repeat (section 8.8).

3.3 Sample request

curl -X POST https://apis.flowmingo.ai/company/integration/interview/set/v1 \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: fl_live_abcd12345.n8G3zPNw9gWkK1Kj' \
  -d '{
    "title": "Senior Backend Engineer - Async Interview",
    "set_type": 1,
    "question_mode": "predefined",
    "description": "Async interview for senior backend candidates.",
    "interview_duration": 20,
    "number_of_retakes": 1,
    "project_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "iai_questions": [
      {
        "title": "System design",
        "content": "Walk us through how you would design a rate limiter.",
        "question_mode": "interview",
        "question_type": "text",
        "priority": 1
      }
    ],
    "iai_requirements": [
      {
        "title": "5+ years backend experience",
        "cfg_importance_id": 273,
        "priority": 1
      }
    ],
    "com_accesses": [
      { "email": "candidate@example.com", "fullname": "Jane Doe" }
    ]
  }'

import fetch from 'node-fetch'

const response = await fetch('https://apis.flowmingo.ai/company/integration/interview/set/v1', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'fl_live_abcd12345.n8G3zPNw9gWkK1Kj'
  },
  body: JSON.stringify({
    title: 'Senior Backend Engineer - Async Interview',
    set_type: 1,
    question_mode: 'predefined',
    interview_duration: 20,
    number_of_retakes: 1,
    project_id: 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d',
    iai_questions: [
      {
        title: 'System design',
        content: 'Walk us through how you would design a rate limiter.',
        question_mode: 'interview',
        question_type: 'text',
        priority: 1
      }
    ],
    iai_requirements: [{ title: '5+ years backend experience', cfg_importance_id: 273, priority: 1 }],
    com_accesses: [{ email: 'candidate@example.com', fullname: 'Jane Doe' }]
  })
})

const data = await response.json()
console.log(data)

import requests

response = requests.post(
    "https://apis.flowmingo.ai/company/integration/interview/set/v1",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": "fl_live_abcd12345.n8G3zPNw9gWkK1Kj",
    },
    json={
        "title": "Senior Backend Engineer - Async Interview",
        "set_type": 1,
        "question_mode": "predefined",
        "interview_duration": 20,
        "number_of_retakes": 1,
        "project_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "iai_questions": [
            {
                "title": "System design",
                "content": "Walk us through how you would design a rate limiter.",
                "question_mode": "interview",
                "question_type": "text",
                "priority": 1,
            }
        ],
        "iai_requirements": [
            {"title": "5+ years backend experience", "cfg_importance_id": 273, "priority": 1}
        ],
        "com_accesses": [{"email": "candidate@example.com", "fullname": "Jane Doe"}],
    },
)

print(response.json())

<?php
$payload = [
    'title' => 'Senior Backend Engineer - Async Interview',
    'set_type' => 1,
    'question_mode' => 'predefined',
    'interview_duration' => 20,
    'number_of_retakes' => 1,
    'project_id' => 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d',
    'iai_questions' => [
        [
            'title' => 'System design',
            'content' => 'Walk us through how you would design a rate limiter.',
            'question_mode' => 'interview',
            'question_type' => 'text',
            'priority' => 1,
        ],
    ],
    'iai_requirements' => [
        ['title' => '5+ years backend experience', 'cfg_importance_id' => 273, 'priority' => 1],
    ],
    'com_accesses' => [
        ['email' => 'candidate@example.com', 'fullname' => 'Jane Doe'],
    ],
];

$ch = curl_init('https://apis.flowmingo.ai/company/integration/interview/set/v1');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: fl_live_abcd12345.n8G3zPNw9gWkK1Kj',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    payload := map[string]any{
        "title":              "Senior Backend Engineer - Async Interview",
        "set_type":           1,
        "question_mode":      "predefined",
        "interview_duration": 20,
        "number_of_retakes":  1,
        "project_id":         "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "iai_questions": []map[string]any{
            {
                "title":         "System design",
                "content":       "Walk us through how you would design a rate limiter.",
                "question_mode": "interview",
                "question_type": "text",
                "priority":      1,
            },
        },
        "iai_requirements": []map[string]any{
            {"title": "5+ years backend experience", "cfg_importance_id": 273, "priority": 1},
        },
        "com_accesses": []map[string]any{
            {"email": "candidate@example.com", "fullname": "Jane Doe"},
        },
    }

    body, _ := json.Marshal(payload)
    req, _ := http.NewRequest(
        "POST",
        "https://apis.flowmingo.ai/company/integration/interview/set/v1",
        bytes.NewReader(body),
    )
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", "fl_live_abcd12345.n8G3zPNw9gWkK1Kj")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    out, _ := io.ReadAll(resp.Body)
    fmt.Println(string(out))
}

require 'net/http'
require 'json'
require 'uri'

uri = URI('https://apis.flowmingo.ai/company/integration/interview/set/v1')

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Content-Type'] = 'application/json'
request['X-API-Key'] = 'fl_live_abcd12345.n8G3zPNw9gWkK1Kj'
request.body = {
  title: 'Senior Backend Engineer - Async Interview',
  set_type: 1,
  question_mode: 'predefined',
  interview_duration: 20,
  number_of_retakes: 1,
  project_id: 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d',
  iai_questions: [
    {
      title: 'System design',
      content: 'Walk us through how you would design a rate limiter.',
      question_mode: 'interview',
      question_type: 'text',
      priority: 1
    }
  ],
  iai_requirements: [
    { title: '5+ years backend experience', cfg_importance_id: 273, priority: 1 }
  ],
  com_accesses: [
    { email: 'candidate@example.com', fullname: 'Jane Doe' }
  ]
}.to_json

response = http.request(request)
puts response.body

3.3.1 Sample request: let the AI decide

The same endpoint with question_mode realtime and no interview question of your own. Flowmingo prepares the interview questions from the description and the criteria you send, so the more precise they are, the better the questions. The pre_screening question is kept as you send it.

curl -X POST https://apis.flowmingo.ai/company/integration/interview/set/v1 \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: fl_live_abcd12345.n8G3zPNw9gWkK1Kj' \
  -d '{
    "title": "Senior Backend Engineer - AI screening",
    "position": "Senior Backend Engineer",
    "question_mode": "realtime",
    "description": "We are hiring a senior backend engineer to own our payments services.",
    "interview_duration": 20,
    "iai_questions": [
      {
        "title": "Location",
        "content": "Are you based in or willing to relocate to Bengaluru?",
        "question_mode": "pre_screening",
        "question_type": "text"
      }
    ],
    "iai_requirements": [
      { "title": "5+ years backend experience", "content": "Has run production services.", "cfg_importance_id": 273 }
    ]
  }'

3.4 Sample response

The endpoint returns a results envelope, with status 201. A request that carries an idempotency_key also gets idempotent_replay, and the repeat of one is answered 200 (section 3.2.6).

Treat the response as an acknowledgement, not a confirmation. results describes the set itself and lists the ids of what was saved: iai_questions and iai_requirements hold one { "id", "external_id" } for each question and each criterion. It does not return the other fields you sent (their text, their options, the access entries), and it does not repeat project_id. It also does not show when a value was stored differently from how you sent it: a cfg_importance_id outside the four valid IDs, for example, is stored as 244, and a project_id that could not be attached leaves no trace in the answer. To confirm that the set was linked to your project, find it in GET /hiring/interview-sets/v1 and read its project_ids. To check its questions and criteria, open the assessment in the dashboard.

{
  "results": {
    "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
    "title": "Senior Backend Engineer - Async Interview",
    "set_type": 1,
    "status": 1,
    "interview_duration": 20,
    "number_of_retakes": 1,
    "external_id": "REQ-48213",
    "iai_questions": [
      { "id": "a7b8c9d0-1234-4abc-8def-1234567890ab", "external_id": "Q-SYSTEM-DESIGN" }
    ],
    "iai_requirements": [
      { "id": "b8c9d0e1-2345-4bcd-9ef0-234567890abc", "external_id": null }
    ]
  }
}

The fields shown are the ones to rely on; more may be present. Put id in com_interview_set_ids when you invite candidates (section 4).

• external_id is your id for the assessment, exactly as you sent it, or null.
• iai_questions and iai_requirements list the questions and the criteria that were saved, in the order of your arrays (they are numbered 1, 2, 3). On the repeat of a keyed request they are the ones the assessment holds now, in their current order (section 3.2.6): never pair them with your input by position. An external_id matches a row only where you sent one that no other entry in the list carries; an entry with no id, an entry with a repeated id and a question Flowmingo prepared cannot be matched. An entry you sent with neither a title nor a content was skipped and has no item. For a realtime interview the questions Flowmingo prepared are listed too, with external_id null. Each external_id is the one you sent for that entry, or null.
• idempotent_replay, beside results, is there only when you sent an idempotency_key: false for the call that made the assessment, true for a repeat (section 3.2.6).

3.5 Create a hiring project

A hiring project is where an assessment, its candidates and the job post come together. Create one through the API when your own system opens a role. The same call can make the project's assessments (section 3.5.5), set the job post's details yourself (section 3.5.6) and store your own ids on the project, its job post and its stages (section 3.5.11); you can also attach assessments later with project_id (sections 3.2 and 3.6) and invite candidates into it (section 4). To find the id of a project that already exists, see section 5.7; if the answer to a create call never reached you, read the call back by its idempotency_key (section 3.5.12). Once a project exists, you can read it by its id (section 3.5.13) and change its name, its role, its description and the words of its job post (section 3.5.14).

Method: POST. Required API key scope: create_project.

It acts as the person who created the key, and that person must be an Owner or Admin of your organization at the moment of each call. The role is read again on every call, so a key whose creator was demoted stops working here at once, and so does a key whose creator has left the organization, during the grace period that follows (section 2.10): each answers 403 with the code project_create_requires_admin. After the grace period the key is refused before it reaches this route (section 2.10). If the role cannot be confirmed just now the answer is 503 with project_create_role_unconfirmed, and nothing is created. A key with no creator on record is refused with a 403 before anything runs (section 11). If the creator is an Admin who is limited to some projects, Flowmingo then tries to add the new project to that person's access, as the dashboard does, so the key can use it (section 2.9). If that step fails the project still exists; give the person access to it in the dashboard.

3.5.1 Request payload

Text is trimmed before it is checked, except an external_id, which is kept exactly as you send it. Only these eight fields are used. The settings the dashboard offers when it creates a project (file_link, attributes, filters, priority, cv_score, status, source, location, locations) are refused with 400 and the code project_field_not_supported when they carry a value, so you never believe one was applied; a null in one of them is ignored. Any other top-level property that is not in the table is ignored without an error (a misspelt setting is not reported, and the camelCase externalId is not read), but a key inside job_post, or inside an entry of stages, that the route does not take is refused (sections 3.5.6 and 3.5.11), and constructor, __proto__ and prototype count as keys there. At the top level of the body those three names are still ignored. A number, a boolean or a list where the text belongs is refused, not turned into text.

3.5.2 What is created

• An active hiring project with the source api, owned by your organization and created by the person who created the key. It appears in the dashboard like any other project. It carries your external_id when you sent one (section 3.5.11).
• Its four default stages, in order: Unassigned, Shortlisted, In Progress, Rejected. Each carries the id you gave it in stages, or none (section 3.5.11).
• A job post drafted by the same AI that drafts one in the dashboard: from your description when you send one (it also reads the location, level and employment type out of the text), or from the position alone when you do not, which gives a weaker post. The post is saved active with a public link, titled with the position, with no screening and no automatic invitation. It is not boosted to job boards. The post goes live within about a minute. The AI content check reviews the posts that are switched on and not yet checked once a minute, so the post is normally approved soon after the call (review_status approved, public_state live), its public address opens, and after the next job board sync, a few minutes later, it shows next to your company's other jobs. Read the publication to see where it stands (section 3.7.1). To close the page, unpublish the post (section 3.7.3). No location is guessed from where your server is. Details you send in job_post replace what the AI read (section 3.5.6), and the AI's own age, gender, marital status and nationality filters are always cleared. It carries the job_post.external_id you sent, never the project's.
• A CV Evaluation and an AI Interview, unless you name other assessments or send assessments: [] (section 3.5.5). They are made after the project exists, from the position and the description, and attached to the project.

All or nothing. The call drafts the job post first, before anything is saved, and then saves the project, its four stages, the job post and the record of your call together: either all of them exist or none does. A project without its job post is never left behind. The assessments are made after that and are not part of it: a project is never lost to an assessment that fails (section 3.5.5).

A call that omits assessments now also makes a CV Evaluation and an AI Interview. It waits up to about 45 seconds for them, where a call that makes none answers in a few seconds, and the assessments use the generation budget of section 3.6.11. Send assessments: [] to create the project alone. To attach other assessments, name them in assessments or create them later with project_id (sections 3.2 and 3.6), then invite candidates (section 4).

When the AI cannot draft the job post, nothing is created. A model call sometimes fails or takes too long. The call then answers 503 with the code job_post_generation_failed and a Retry-After header (in seconds), creates no project, and does not count against the project limits (it is still a request against the per-key limit of section 8.5). Send the same request again with the same idempotency_key. If it keeps failing, shorten or simplify the description.

The answer still carries job_post_error, and it is always null now. It only reads a reason (job_post_generation_failed, job_post_save_failed or job_post_interrupted) for a project that was created before 22 October 2026, when the post was drafted after the project was saved; when you read such a project again with its old key, the reason is still shown.

3.5.3 Sending the same request twice

idempotency_key is required, and it belongs to your organization, whichever of your API keys sends it.

• Same key, same title, position, description, assessments, job_post and ids (external_id, job_post.external_id and stages): you get the project the first call created, with idempotent_replay true. The status is 201 when the call made no assessments and 200 when it made some (202 while one is still being made: section 3.5.5). No second project is created, and the repeat does not count against the project limits below. A repeat can start or resume the project's assessments (section 3.5.5), and that takes units from the generation budget (section 3.6.11). The answer is read fresh, so it shows the project as it is now, including any edit made in the dashboard, and its missing_details (section 3.5.7) reflect those edits. The ids are read from the saved rows, so a repeat returns exactly the ids the first call stored. This is how you get the id back when the answer to the first call was lost; it is not a way to look projects up (section 5.7).
• Same key, a different title, position, description, set of assessments, job_post block or id: 409 with the code idempotency_key_reused, and the message "This idempotency_key was already used with a different title, position, description or set of assessments, or with different job post details (the job_post block), or with different external ids (external_id, job_post.external_id or stages). Use a new key for a different project, or send the original body to get the original project back. Nothing was created." Use a new key for a different project. The order of the assessments, and the order and letter case of the names in the lists job_functions, seniority_levels, employment_types and workplace_types, do not make a different request. Leaving assessments out (or sending null), sending [] and sending a list are three different requests.
• The ids are part of the request. An id counts exactly as you sent it (REQ-1 and req-1 are two ids), the order of the entries of stages does not matter, and null is the same as leaving an id out. An id added to a repeat, an id dropped from it, another id, and an id moved between the project, the job post and a stage are each a different request, so a 409. A request that carries no id is compared exactly as before, so a call you made earlier still repeats. A project made before ids existed can be repeated only without any: the same key with a body that now carries an id is a 409.
• A key is remembered for good. It is never expired, so the same key with the same body returns the same project (reported as deleted if someone has since deleted it) and with an edited body is always a 409. If your own id is the key (for example the id of a job) and the job can be reopened with changes, add a revision to it, such as ats-job-48213-r2.
• A call that fails with a 5xx or times out: send it again with the same key. The project may already exist, and then you get it back; if it does not, the repeat simply creates it. After a 503 job_post_generation_failed nothing was created: send the same request again after the Retry-After wait (about 30 seconds; about 90 seconds when the AI took too long to answer, because that attempt is still running on our side and a repeat before it ends is answered 409 idempotency_request_in_progress).
• Two calls with the same key at the same moment: one project is created. The other call is answered 409 idempotency_request_in_progress while the first is still working (a job post takes a few seconds to draft). Wait a few seconds and send the same request again to get the project. If your organization is at its limit (section 3.5.4), the second call can instead be answered 429: send it again with the same key.

3.5.4 Limits

Each organization can create 10 projects per minute and 300 per UTC day, counted across all its keys. A call past a limit answers 429 with the code project_create_limit_reached, and nothing is created. The message says whether to try again in a minute (the per-minute limit) or after 00:00 UTC (the daily one). A call that creates nothing (a 503 for the job post, a refusal) gives its place back. If the limit cannot be checked just now the call answers 503 project_create_limit_unavailable and creates nothing: it never creates a project it could not count.

These limits count projects. The assessments a call makes also take units from the generation budget of section 3.6.11, which the standalone assessment routes share: when that budget is spent the project is still created and the assessment is reported as failed (section 3.5.5).

3.5.5 Make the assessments in the same call

assessments says which assessments the call makes for the project. Each one is published, attached to the project and ready to send to candidates, the way the matching route of section 3.6 leaves it. The call needs only the create_project scope, not create_assessment.

• They are made in parallel, with the project's position as the job title and its description as the job description, and with the dashboard's defaults. For options such as your own criteria, languages or durations, create the assessment with its own route and the project's id as project_id (section 3.6). The call normally writes one list of criteria and shares it among the CV Evaluation, the AI Interview and the Role-play you named; if that attempt fails, each of them writes its own.
• A project holds one CV Evaluation. A request is refused with 409 project_already_has_cv_evaluation when the project already has one, so if you name cv_evaluation here (or leave assessments out), do not create another one for the project later. The check is not atomic: do not create two CV Evaluations for the same project at the same moment. Requests that follow one another are refused.
• The position must fit every kind you name. Every assessment takes a job title of at least 2 characters, and a Skill Test, a Showcase and a Technical Test take at most 200 (a project's position can be longer). One that does not fit fails that assessment only, with the code assessment_compose_invalid_input.
• The call waits up to about 45 seconds for the assessments, and the status says how far they got:

• A Technical Test is not waited for. It takes 3 to 9 minutes, so a Technical Test that starts is pending in the first answer. One that cannot start (for example because the generation budget is spent) is reported failed at once. The call answers 202 only while some entry is pending.
• To read the result, send the same request again with the same idempotency_key, until no entry is pending. A repeat returns the project, reports every assessment as it stands, and never makes an assessment twice. An entry that failed with retryable true is tried again by the repeat (unless the repeat sent a Prefer that shortens the wait: see the next bullet).
• To wait less, send a Prefer header. It is the header of the assessment routes (section 3.6.2) and it shortens the wait for the assessments only. Prefer: respond-async answers as soon as every assessment can be reported, or after about two seconds if any is still being made (a 202 with Retry-After, as above; one that is already finished is reported as it stands), and Prefer: wait=20 answers when they are all final or after about 20 seconds (up to two seconds more; a longer wait is cut to the usual wait of about 45 seconds). It does not shorten the job post's draft, which comes first and usually takes 2 to 4 seconds (up to 45), nor sign-in and validation, so give a caller that times out early a few seconds more than its own network needs. The answer carries Preference-Applied (respond-async or wait=<seconds>) when the call made assessments and the header was applied; without the header, or with one that cannot be read, nothing changes. It is not part of the request, so the same idempotency_key can be sent again with a different preference (or none). What it leaves unfinished carries on: send the same request again, with or without Prefer, to read where it has got to. A call whose Prefer shortens the wait does not start a failed assessment again: it reports the entry failed, with its code, so that a caller who polls does not spend generation budget on a restart it cannot see (in a rare race, or if the record cannot be read, it can still be started again). To try a failure with retryable true again, send the same request without Prefer.
• A project made before 22 October 2026 keeps replaying as it was made. A repeat of its call makes no assessment and answers with the fields it always had (none of assessments, partial_failure and missing_details), and the same key with a non-empty assessments list or a job_post block is a 409 (a different request). A project made from that date on gets the behavior described in this section.
• A project is never lost to an assessment. The assessments are made after the project exists. One that fails is reported in its entry with a code and partial_failure is true, and the call is still a success.

The answer gains these fields:

The codes in failure are those of section 3.6.12, and assessment_compose_invalid_input (the project's position or description does not fit that kind; make it with its own route and a job title that fits). The generation budget of section 3.6.11 applies: when it is spent, or generation is busy, an entry fails with assessment_create_limit_reached or assessment_capacity_busy and retryable true, and the project is created all the same. An assessment that someone deletes in the dashboard is reported as failed with assessment_was_deleted by a later repeat, and is not made again.

3.5.6 Set the job post's details yourself

By default the AI that drafts the job post reads the location, level, employment type and the rest out of your description. job_post lets you set those details yourself, so a value that matters to matching and filtering is the one you meant. Every value is given by name, in the English words the dashboard shows (there is no route that lists Flowmingo's internal ids). Every key is optional: what you send wins over what the AI read, and what you leave out keeps the AI's value. These keys set the job post's details, not its words: to put your own title and description on the job post, create the project and then edit it (section 3.5.14).

job_post also takes external_id, your own id for the job post (section 3.5.11). It is not a detail: a block that holds only external_id leaves every detail to the AI and looks no name up.

How names are matched. Use the names the dashboard shows. Letter case does not matter, nor does the difference between a space, -, _ and / (Full-Time, full_time and FULL TIME are one name), nor the kind of apostrophe (Côte d'Ivoire and Côte d’Ivoire are one name). Accents do matter (Zurich is not Zürich). Matching never guesses a near miss (no plural, synonym or spelling correction), but it accepts more than the displayed name: a country by its full name, a stored alias or its two-letter code, and a state or city by its full name. A name listed twice (Sales, SALES) counts once. A name that matches nothing is refused with 400 job_post_name_unknown, and its message lists the accepted names (the closest ones, with a count of the rest, when the list is too long to print), so you can correct the name and send the request again. Nothing is created.

Places. Each place is looked up exactly, a country, then its state, then its city.

• A place is saved once. The same place named twice with the same address is one place; with two different addresses it is refused with 400 job_post_value_invalid, so put both addresses in one address, or leave one entry out.
• A name that matches two places under the same parent is refused with 400 job_post_location_ambiguous. Leave that level out and put the rest in address.
• When every workplace type of the post is Remote, the places are saved at country level and the addresses are dropped (the dashboard then reads "Hiring In" with the countries). This applies to the places you send, and to the workplace types you send or, if you send none, the AI's.

Salary. min and max are JSON numbers (not text) from 0 up to, but not including, 10,000,000,000,000, with at most two decimals; send at least one of them, and max must not be below min. When you send an amount you must also send currency and period, and nothing is assumed:

What can never be set. A job post made through the API cannot filter on age, gender, marital status, nationality or religion, in any spelling: a key of that kind inside job_post is refused, and the AI's own age, gender, marital status and nationality filters are always cleared, with a job_post block or without one. Any other key that is not in the table above (or external_id), at any level of the block, is refused too, and constructor, __proto__ and prototype are refused like any other key.

On every row nothing is created, and the call does not count against the project limits (the coded ones say "Nothing was created." in the message). The block is read only when the project is created: the same idempotency_key with a different job_post is a 409 (section 3.5.3), and to change a job post afterwards you edit it in the dashboard. The one exception is the job post's own title and description, which the edit route of section 3.5.14 changes, while the job post is switched on; the details of this section are changed only in the dashboard.

For example, a project alone, with its job post set by name:

curl -X POST https://apis.flowmingo.ai/company/integration/hiring/projects/v1 \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: fl_live_abcd12345.n8G3zPNw9gWkK1Kj' \
  -d '{
    "title": "Customer Success Manager - Singapore",
    "position": "Customer Success Manager",
    "description": "We are hiring a customer success manager to look after our largest accounts and keep them renewing...",
    "idempotency_key": "ats-job-48214",
    "assessments": [],
    "job_post": {
      "job_functions": ["Customer Service"],
      "seniority_levels": ["Mid-Senior level"],
      "employment_types": ["Full-time"],
      "workplace_types": ["Hybrid"],
      "locations": [{ "country": "Singapore" }],
      "salary": { "min": 6000, "max": 9000, "currency": "SGD", "period": "monthly" }
    }
  }'

The answer is 201:

{
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "title": "Customer Success Manager - Singapore",
  "position": "Customer Success Manager",
  "status": "active",
  "source": "api",
  "created_at": "2026-10-22T04:30:00.000Z",
  "external_id": null,
  "stages": [
    { "id": "b0b0b0b0-abcd-4ef0-8123-456789abcdef", "name": "Unassigned", "external_id": null },
    { "id": "1d2c3b4a-5f6e-4d7c-9b8a-0a1b2c3d4e5f", "name": "Shortlisted", "external_id": null },
    { "id": "2e3d4c5b-6a7f-4e8d-8c9b-1b2c3d4e5f60", "name": "In Progress", "external_id": null },
    { "id": "3f4e5d6c-7b8a-4f9e-a0dc-2c3d4e5f6071", "name": "Rejected", "external_id": null }
  ],
  "job_post": { "id": "c0ffee00-dead-4bee-8f00-0123456789ab", "status": "active", "external_id": null },
  "job_post_error": null,
  "idempotent_replay": false,
  "missing_details": [],
  "assessments": [],
  "partial_failure": false
}

A name that matches nothing answers 400 before anything is created:

{
  "statusCode": 400,
  "code": "job_post_name_unknown",
  "message": "job_post.workplace_types[0]: `Teleport` is not a workplace type we know. Accepted: On-site, Remote, Hybrid. Use a name the dashboard shows; case and the separators - _ / are not significant. Nothing was created.",
  "timestamp": "2026-10-22T04:30:00.000Z",
  "path": "/integration/hiring/projects/v1"
}

3.5.7 What the job post still lacks: missing_details

Every answer to a project made from 22 October 2026 on carries missing_details, a list of the details the saved job post still lacks, so your system can see at once whether the AI found everything it needs in your description (and whether the job_post you sent covered the rest).

• The entries come in this order, and only the ones that are missing are listed. [] means nothing is missing. null means it cannot be told: the project has no job post, or the check could not be completed just now.
• The salary is never listed: a post with no pay reads as Negotiable.
• It is read from the job post as it is now, on every call. A repeat of the call after someone completed the post in the dashboard shows the shorter list.
• job_post is read only when the project is created, so you cannot add a missing detail by sending the same request again with a different block (that is a 409). Complete the post in the dashboard, or create the next project with the details in job_post. A missing description can also be filled with the edit route (section 3.5.14), which sets the words of the job post.

For example, a description that names no place gives "missing_details": ["locations"].

3.5.8 Sample request

This call names no assessments, so it also makes a CV Evaluation and an AI Interview. Add "assessments": [] to create the project alone; section 3.5.6 has a sample that sets the job post by name.

curl -X POST https://apis.flowmingo.ai/company/integration/hiring/projects/v1 \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: fl_live_abcd12345.n8G3zPNw9gWkK1Kj' \
  -d '{
    "title": "Support Engineer - Q4 hiring",
    "position": "Support Engineer",
    "description": "We are hiring a support engineer for our payments platform. You will review, prioritise and answer customer tickets.",
    "idempotency_key": "ats-job-48213"
  }'

const res = await fetch('https://apis.flowmingo.ai/company/integration/hiring/projects/v1', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'fl_live_abcd12345.n8G3zPNw9gWkK1Kj'
  },
  body: JSON.stringify({
    title: 'Support Engineer - Q4 hiring',
    position: 'Support Engineer',
    description: 'We are hiring a support engineer for our payments platform...',
    idempotency_key: 'ats-job-48213'
  })
})
const project = await res.json() // 201; 202 while an assessment is still being made: send the same request again
// project.id is the project_id for the assessment routes (section 3.6) and for POST /interview/set/v1

3.5.9 Sample response

The answer is 201: both assessments were ready within the wait (criteria is cut to two of its seven entries here).

{
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "title": "Support Engineer - Q4 hiring",
  "position": "Support Engineer",
  "status": "active",
  "source": "api",
  "created_at": "2026-10-22T04:18:44.051Z",
  "external_id": null,
  "stages": [
    { "id": "b0b0b0b0-abcd-4ef0-8123-456789abcdef", "name": "Unassigned", "external_id": null },
    { "id": "1d2c3b4a-5f6e-4d7c-9b8a-0a1b2c3d4e5f", "name": "Shortlisted", "external_id": null },
    { "id": "2e3d4c5b-6a7f-4e8d-8c9b-1b2c3d4e5f60", "name": "In Progress", "external_id": null },
    { "id": "3f4e5d6c-7b8a-4f9e-a0dc-2c3d4e5f6071", "name": "Rejected", "external_id": null }
  ],
  "job_post": { "id": "c0ffee00-dead-4bee-8f00-0123456789ab", "status": "active", "external_id": null },
  "job_post_error": null,
  "idempotent_replay": false,
  "missing_details": ["locations"],
  "assessments": [
    {
      "kind": "cv_evaluation",
      "status": "ready",
      "assessment": {
        "id": "7d2c1c3e-5b1f-4f55-9a3b-0c9a2f7e8d11",
        "type": "cv_evaluation",
        "name": "Support Engineer – CV Evaluation, 22 Oct '26",
        "job_title": "Support Engineer",
        "external_id": null,
        "status": "active",
        "ready": true,
        "report_language": "en",
        "criteria": [
          {
            "id": "1f0e0f0a-6b6c-4c1c-9a3a-0a0a0a0a0a0a",
            "title": "Customer support and ticket triage",
            "details": "Help payments-platform customers by reviewing, prioritizing, and responding to support tickets.",
            "importance": "must_have"
          },
          {
            "id": "2a1f1a1b-7c7d-4d2d-8b4b-1b1b1b1b1b1b",
            "title": "Clear written communication",
            "details": "Write understandable, helpful answers to customers about their issues.",
            "importance": "must_have"
          }
        ],
        "criteria_count": 7,
        "project_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "linked": true,
        "complimentary_cv_evaluation": { "enabled": true, "notice_acknowledged": true }
      }
    },
    {
      "kind": "ai_interview",
      "status": "ready",
      "assessment": {
        "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
        "type": "ai_interview",
        "name": "Support Engineer — AI Interview, 22 Oct '26",
        "job_title": "Support Engineer",
        "external_id": null,
        "status": "active",
        "ready": true,
        "duration_minutes": 20,
        "interview_languages": ["English"],
        "report_language": "en",
        "criteria": [
          {
            "id": "4d3e5f6a-8b9c-4d1e-a2f3-4b5c6d7e8f90",
            "title": "Customer support and ticket triage",
            "details": "Help payments-platform customers by reviewing, prioritizing, and responding to support tickets.",
            "importance": "must_have"
          },
          {
            "id": "5e4f6a7b-9c0d-4e2f-b3a4-5c6d7e8f9a01",
            "title": "Clear written communication",
            "details": "Write understandable, helpful answers to customers about their issues.",
            "importance": "must_have"
          }
        ],
        "criteria_count": 7,
        "questions": { "interview": 13, "pre_screening": 2 },
        "project_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "linked": true
      }
    }
  ],
  "partial_failure": false
}

The fields shown are the ones to rely on; more may be added (section 8.7). status is a word on this route (a project reads active, draft, inactive, archived or deleted; a job post reads active, pending, inactive, archived, approved, rejected or expired), while the read routes return the same states as numbers. The answer to a repeated key shows the project as it is now: a renamed stage, a job post deleted in the dashboard (job_post null; job_post_error stays null when the post was created, and shows the original reason when its creation had failed), or status deleted for a project someone has since deleted. missing_details here says the AI found no place in the description (section 3.5.7). The job post is active in this answer. Its AI content check runs about a minute later, and its page is then live (section 3.5.2).

3.5.10 Errors on this route

An assessment that cannot be made is not an error of this route: the project is created and the entry says why (section 3.5.5).

3.5.11 Your own ids on the project, its job post and its stages

The call can store ids of your own on three things it creates, so you can find them again by the number your own system uses. The rules are those of section 8.8: optional, plain text of 1 to 128 characters, stored exactly as you send them, scoped to your company, not unique, and fixed when the project is created.

stages. A list of at most four entries, each exactly { "name": ..., "external_id": ... }, with both keys in every entry (an entry whose external_id is null is refused). [], null and leaving stages out mean no stage ids. The name is one of Unassigned, Shortlisted, In Progress and Rejected, spelled as stages[].name spells them in the answer: case matters, nothing is trimmed, and the stage's machine type is not accepted. Name each stage once. A stage you do not list gets null. Any other key in an entry, such as color or the camelCase externalId, is refused, not ignored.

The answer. external_id on the project, on every entry of stages and on job_post is always there: your id, or null when you gave none. The ids are written together with the rows and read back from them, so a repeat (section 3.5.3) returns exactly what the first call stored. The assessments the call makes get no id (section 3.5.5). A project you duplicate in the dashboard starts without ids, and so does its job post.

A job_post block that holds only external_id sets no detail: the AI's values stay (section 3.5.6). The camelCase job_post.externalId is refused as a key the block does not take.

The ids are part of the request. The same idempotency_key with another id, an id added or an id dropped is a 409 (section 3.5.3).

On every row nothing is created and nothing is reserved, no AI is asked and the call does not count against the project limits (section 3.5.4). The check for a key that is not allowed inside stages or job_post runs first, right after the key itself is accepted, so a body with several faults answers stage_field_not_supported or job_post_field_not_supported before any other 400. A body that carried such a key used to be accepted, with the key dropped; a repeat of such an earlier call is now this 400, not a replay. For example:

{
  "statusCode": 400,
  "code": "stage_name_unknown",
  "message": "stages[0].name `Hired` is not a default stage of a new project. The stages are: Unassigned, Shortlisted, In Progress, Rejected (spelled exactly like this, case matters). Nothing was created.",
  "timestamp": "2026-11-02T04:30:00.000Z",
  "path": "/integration/hiring/projects/v1"
}

A project with ids, made alone (assessments: []):

curl -X POST https://apis.flowmingo.ai/company/integration/hiring/projects/v1 \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: fl_live_abcd12345.n8G3zPNw9gWkK1Kj' \
  -d '{
    "title": "Support Engineer - Q4 hiring",
    "position": "Support Engineer",
    "description": "We are hiring a support engineer for our payments platform. You will review, prioritise and answer customer tickets.",
    "idempotency_key": "ats-job-48213",
    "assessments": [],
    "external_id": "REQ-48213",
    "job_post": { "external_id": "POST-48213" },
    "stages": [
      { "name": "Unassigned", "external_id": "STAGE-NEW" },
      { "name": "Rejected", "external_id": "STAGE-REJECTED" }
    ]
  }'

The answer is 201:

{
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "title": "Support Engineer - Q4 hiring",
  "position": "Support Engineer",
  "status": "active",
  "source": "api",
  "created_at": "2026-11-02T04:18:44.051Z",
  "external_id": "REQ-48213",
  "stages": [
    { "id": "b0b0b0b0-abcd-4ef0-8123-456789abcdef", "name": "Unassigned", "external_id": "STAGE-NEW" },
    { "id": "1d2c3b4a-5f6e-4d7c-9b8a-0a1b2c3d4e5f", "name": "Shortlisted", "external_id": null },
    { "id": "2e3d4c5b-6a7f-4e8d-8c9b-1b2c3d4e5f60", "name": "In Progress", "external_id": null },
    { "id": "3f4e5d6c-7b8a-4f9e-a0dc-2c3d4e5f6071", "name": "Rejected", "external_id": "STAGE-REJECTED" }
  ],
  "job_post": { "id": "c0ffee00-dead-4bee-8f00-0123456789ab", "status": "active", "external_id": "POST-48213" },
  "job_post_error": null,
  "idempotent_replay": false,
  "missing_details": [],
  "assessments": [],
  "partial_failure": false
}

Later, find the project by your own number with GET /hiring/projects/v1?external_id=REQ-48213 (section 8.8).

3.5.12 Read a create call back by its key

GET /hiring/projects/requests/{idempotency_key}/v1 says what became of a create call, from the idempotency_key you sent with it. Use it when the answer never reached you (a timeout, a dropped connection) and you want the project's id without sending the body again. It only reads: it creates nothing, starts nothing, and does not count against the project limits (section 3.5.4).

Required API key scope: create_project, the scope of the create call. The route acts as the same person: the person who created the key must still be an Owner or Admin of the organization on every read. The {idempotency_key} is the key of the create call, 8 to 128 characters from A-Z a-z 0-9 . _ : -. Spaces at either end of it are ignored, the same way the create call ignores them: a call sent with " ats-job-48213 " is found by reading ats-job-48213, or the same text with its spaces (written %20 in a URL). A space inside the key is never valid. Any key of your organization can read a call that another key made, as long as the project is one this key can open (section 2.9).

curl -s -H "X-API-Key: $FLOWMINGO_API_KEY" "$BASE/hiring/projects/requests/ats-job-48213/v1"

{
  "idempotency_key": "ats-job-48213",
  "status": "created",
  "project_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "project": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "title": "Support Engineer - Q4 hiring",
    "external_id": "REQ-48213",
    "deleted": false,
    "archived": false
  },
  "job_post": { "state": "created", "failure_code": null },
  "created_at": "2026-11-02T04:18:44.051Z"
}

A record that is still pending after 5 minutes reads as created when its job post was saved (a post, or a project, deleted since still counts as saved), and otherwise as job_post_failed with job_post_interrupted. The read does not write that down; the next repeat of the create call does. The read does not report the project's assessments: for where each one has got to, send the create request again (section 3.5.5).

What an unknown key can mean. The record of a call is written in the same step as the project. A call that is still running (it drafts the job post before it saves anything), or that ended before its project was saved (a 503 for a job post that could not be drafted, a 429, a 409, a crash), has no record yet. A 404 for a key you did send therefore does not prove that no call was made, and it can also mean the project was not saved (yet). If you are not sure, send the same create request again with the same idempotency_key: you get the project the first call made, or the project is made now (section 3.5.3).

Deleted projects and reach. project.deleted is true once the project has been deleted, and the record of the call stays, with the project's title and external_id. Only a key whose creator can open every project (an Owner, or an Admin with access to all projects) reads it that way. For a creator who is limited to some projects, a deleted project is no longer one of theirs, so the same request reads as the 404 below, not as deleted true. An archived project reads archived true.

How it fits sections 5.7 and 8.6. Section 5.7 lists where a project's id comes from. This read is one more source, for one case: you hold the idempotency_key of the create call and need the id. It is not a way to search projects: there is no project-list filter by idempotency_key. If you also sent an external_id, GET /hiring/projects/v1?external_id= finds the project (section 8.8), but that list is read from a replica and a project made a moment ago can take a few seconds to appear; this read does not wait for a replica. When a create call times out (section 8.6), read this route first: with status created you have the id and need send nothing; with a 404, send the create request again with the same key and the same body.

3.5.13 Read one hiring project

GET /hiring/projects/{id}/v1 returns one hiring project by its Flowmingo id: its name, role and status, its job post (the words it displays, the words as they are stored before the content check could reword them, and whether its public page is open), and the assessments linked to it. It only reads. Required API key scope: read_hiring. Section 5.7 shows how to find a project's id. The id may be written in capital or small letters; the answer gives it in small letters. The read comes from the primary database, so an edit you have just made (section 3.5.14) shows at once, which the project list of section 5.7, read from a replica, does not promise. After a timeout or a 503 on an edit, this read is how you find out whether your words landed: compare job_post.sent_title and job_post.sent_description (of the project's newest job post) with what you sent, after removing leading and trailing blanks from it (see the table below). The answer to an edit carries this same view of the project only for a key that also holds read_hiring (section 3.5.14).

curl -s -H "X-API-Key: $FLOWMINGO_API_KEY" \
  "$BASE/hiring/projects/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/v1"

{
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "title": "Support Engineer - Q4 hiring",
  "position": "Support Engineer",
  "status": "active",
  "description": "We are hiring a support engineer for our payments platform. You will review, prioritise and answer customer tickets.",
  "external_id": "REQ-48213",
  "created_at": "2026-11-02T04:18:44.051Z",
  "updated_at": "2026-11-02T04:18:44.051Z",
  "job_post": {
    "id": "c0ffee00-dead-4bee-8f00-0123456789ab",
    "status": "active",
    "public_state": "live",
    "external_id": "POST-48213",
    "title": "Support Engineer",
    "description": "We are hiring a support engineer for our payments platform. You will review, prioritise and answer customer tickets.",
    "sent_title": "Support Engineer",
    "sent_description": "We are hiring a support engineer for our payments platform. You will review, prioritise and answer customer tickets.",
    "review": "approved",
    "differs_from_sent": false
  },
  "assessments": [
    {
      "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
      "assessment_type": "ai_interview",
      "status": 1,
      "status_label": "active",
      "external_id": null
    }
  ]
}

3.5.14 Edit a hiring project and its job post

POST /hiring/projects/{id}/update/v1 sets a project's title, position and description, and the words of its job post (job_post.title and job_post.description), to the values you send. Use it to keep a project in step with the job on your own platform, and to put your own wording on a job post: creating a project always has the AI draft the job post (section 3.5.2), so a job whose exact text matters is created first and then edited. Required API key scope: create_project. The answer shows the project only to a key that also holds read_hiring: with create_project alone, project is null and the answer is { id, changed, updated_at, project: null, warnings }, so a key that may not read a project does not learn its words through an edit (read it with a key that holds read_hiring, section 3.5.13). The answer is 200, also when nothing changed. The project id in the path may be written in capital or small letters; the id in the answer is in small letters.

It acts as the person who created the key, and that person must be an Owner or Admin of your organization. The role is read again on every call; during the grace period after a creator has left, the role they left with is used (section 2.10). The hiring project must be one that person can open (section 2.9). A key whose creator has left can still change the project's own fields while its grace period runs (section 2.10), but not the job post: a body that carries a job_post object, even an empty {} and even when it is the only thing in the body, is refused with 403 key_out_of_reach before anything is written, whatever role the creator left with, because the job post's words are saved with the person's access as it is today. The refusal depends on the key alone (its creator has left), not on what the job_post object holds, so an empty {} that would otherwise be 400 nothing_to_update is this 403 instead. An unknown project id still answers 404 first. A body without a job_post object still works until the grace period ends; after that the key stops working.

The job post's words are checked, and the check can reword them. The words you send in job_post.title and job_post.description are stored after leading and trailing blanks are removed from them, so compare the stored words with what you sent after trimming it. They then go through the same automatic content check that runs when a recruiter edits the same words in the dashboard. The check can reword the text or flag it, and the job post shows the checked wording, which is not always yours. After every edit of the job post's words, read job_post.differs_from_sent, job_post.review and the warnings of the answer (the first two are in the answer's project), or read the project again (section 3.5.13): differs_from_sent true means that a displayed field differs from the words stored, so the job post shows a checked copy that is not yours. It does not say whether the check of your new words has finished: read review too. When the call changed the job post's words, job_post.review in the answer is pending for the job post the call edited, when it is the job post the answer shows, until a check of those words has been seen to finish, also when the check cannot run at all (for example because the checking service is busy), and the warning job_post_awaiting_review is then made as well. The answer shows the project's newest job post, and differs_from_sent, public_state and review in its project.job_post describe that job post: the one the call edited in the normal case, another job post when a newer one exists (with its own values), and another job post or none when the edited one was deleted. The warnings are about the job post the call edited (when it was deleted, no warning about the check or the page is made). The warning job_post_rewritten_by_review is about the fields this call changed (the title and/or the description): a rewrite of a field it did not change, an older one for example, is not reported by it, and shows in the differs_from_sent of the job post the answer shows, which describes the whole job post. A later read reports the last check instead of the progress of this one: a job post that was already flagged or rejected before your edit can keep showing that earlier result for a while. review is a best-effort reading of the last check. A check of older words that was still running when you edited can finish afterwards, and the job post can then keep older checked wording while review reads approved. To know what the job post shows, compare title and description (what it displays) with sent_title and sent_description (what you sent, trimmed). If they are not what you expect, change the words (even by one character; you can change them back afterwards) or change them in the dashboard: sending or saving the same words again starts no check, here or in the dashboard, and a call whose words equal the stored ones writes nothing. Each such change made through this route to the words of a switched-on job post uses one unit of the daily allowance below, and changing them back is a second change that uses a second unit. This route cannot promise that a job post shows your exact wording.

Request payload.

Every field is optional, but send at least one: a body with none of the five answers 400 with the code nothing_to_update. Text is trimmed before it is checked. null and blank text are refused, because clearing a field is not supported, and so are a number or a list where text belongs, and an unpaired UTF-16 surrogate (half of an emoji, for example). A null for job_post itself is accepted and treated as if it were left out.

Fields this route does not take. external_id (fixed when the project and its job post are created: sending one is a 400, section 8.8), status (its own route: section 3.7.5), stages, assessments, idempotency_key, and the dashboard-only settings file_link, attributes, filters, priority, cv_score, source, location and locations are refused with 400 and the code project_field_not_supported when they carry a value, so that you never believe one was applied; a null in one of them is ignored. expected_updated_at is refused in the same way: this route has no version check, see below. A key inside job_post other than title and description is refused with 400 and the code job_post_field_not_supported. Any other top-level property is ignored without an error, so a misspelt field name is not reported.

What the call changes, and what it leaves alone.

• The request accepts only the text fields above, and the call does not intentionally change anything else: not the job post's switch or boost (use the publish, unpublish and boost routes: section 3.7), the project's status (section 3.7.5), your own ids, the project's stages or assessments, the job post's details (job functions, seniority levels, employment and workplace types, places, pay) or its screening questions. Those details are changed in the dashboard.
• Do not edit other settings of the same job post at the same moment. The job post's words are saved through the dashboard's own save, which writes back the other values it read a moment earlier. A change made to one of those other settings between that read and the save can therefore be overwritten. The condition behind job_post_changed (below) protects the job post's title, description and switch only.
• Editing the job post's title does not change the address of its public page.
• Nothing is sent to candidates and no webhook fires.

Sending the same body again. The call sets the fields you send to the values you send, as the dashboard's own save does. A value that already equals what is stored, once leading and trailing blanks are removed from what you sent, is not a change in itself. When no text differs, the answer says changed false, nothing is written, no new check is started and nothing is counted against the daily allowance below. When at least one project field you sent does differ, the call writes every project field you sent, also one that already equals what is stored, so that a value a colleague changed while the call was running becomes yours too. The last write wins: the call does not look at who changed the project last, and there is no version token (expected_updated_at is refused by name). updated_at in the answers is the project's ordinary timestamp; it is informational, so do not send it back and do not use it to tell whether the job post changed. Your own platform stays the source of truth: send one edit per job at a time. The one protection against overwriting a colleague is on the job post: if its words or its switch were changed between the moment the call read the job post and the moment it wrote, its words are not changed, and the call answers 409 with the code job_post_changed.

The title-only-draft marker. A job post made from a project's title alone can carry an internal note that its first description was drafted from the title. The call removes that note only when it changes the job post's description, as the dashboard does when a recruiter replaces the draft. If the removal fails, the words are saved and the warning job_post_draft_stamp_not_cleared says so. Sending the same description again does not remove the note and does not retry the removal, because nothing differs and so nothing is written: change the description again, or edit it in the dashboard. A read does not show the marker, so that warning and the messages of the two 503 answers named in the table below are the only places that tell you it may still be set.

Two writes, not one. The project fields (title, position, description) are written first, in one write, and the words of the job post second, through the dashboard's own save. They are not one transaction. Everything that can be checked without writing is checked before the first write, the job post's switch and the daily allowance below included, so a 400, a 403, a 404, a 409 project_has_no_job_post or job_post_is_off, a 429 job_post_edit_budget_reached or a 503 job_post_edit_budget_unavailable means that nothing was changed. If the job post step then fails, the project fields stay saved. The errors of that step (job_post_changed, job_post_not_saved and job_post_outcome_unknown) say which project fields were saved (every project field you sent, once any of them differed) and whether the job post's words were. If the project write itself ends in an error that does not say whether it went through, the call answers 503 with the code project_outcome_unknown: the project fields may or may not have been saved, and the job post was not attempted. If the edit was saved but its answer could not be built, the call answers 503 with the code edit_saved_answer_unavailable, and its message names the writes that were recorded. The answer is built after the writes and is about the job post that was edited: its review state and its warnings come from that job post, read again by its own id. If that job post is deleted between the save and the answer (an older project can hold several), no review state is compared and no warning about the check or the page is made, and for a key that can read the project, project.job_post is whatever a read of the project shows at that moment (the project's other job post, with its own differs_from_sent, public_state and review, or null). After either 503, after any other error and when the call times out, read the project (section 3.5.13) before you decide what to send again, and compare job_post.sent_title and job_post.sent_description (of the project's newest job post) with what you sent, after removing leading and trailing blanks from it: they are the stored words, never the checked copy, so they show whether your job post words landed. Reading needs the read_hiring scope, and a message that tells you to read the project says so when the key does not have it. When you were changing the job post's description, the message of job_post_outcome_unknown also says that, if the description was saved and the job post was drafted from its title only, the title-only-draft marker may still be set, and that sending the same description again will not clear it: change the description once more, or clear the marker in the dashboard. The message of edit_saved_answer_unavailable says the same when the marker could not be cleared. If no one else changed the same fields in between, sending the same body again leaves the values that were already saved as they are and tries the rest again. If someone else may be editing the same project, read it first: a repeat writes your values over theirs.

What the job post displays while the check runs.

• A job post that is switched on is checked at once, and the call waits for the check for up to about a minute. Give your client a timeout above 60 seconds when the body carries job post words (the call waits only when the words differ from the stored ones). A call that changes only project fields does not wait. Until the check is done, a job post that was approved before shows your new words unchecked, exactly as it does in the dashboard (one that has never been approved does not open until a check approves it: section 3.7.1). If the check cannot run (for example because the checking service is busy), the new words stay shown unchecked and review in the answer says pending for the job post the call edited, when it is the one the answer shows, until a check is seen to finish. A job post that has been live for a long time is not checked again by itself, exactly as in the dashboard: if review is still not what you expect after a few minutes, change the words (even by one character; you can change them back afterwards) or change them in the dashboard, because saving the same words again starts no check. If the check approves them, its checked copy is what the page shows from then on (it may differ from your words: differs_from_sent). If the check refuses them, what happens depends on whether the job post has been posted before. A live job post that has been posted before is not taken down: it keeps serving, leaves job boards and search, and review reads flagged. A live job post that has never been posted (it has no posting date, as with some job posts made in the dashboard and switched on later) is taken offline instead, and review reads rejected; when you change the words of such a job post that was approved, the answer carries the warning job_post_may_go_offline_if_rejected, on the conditions given below. A job post that had not been approved before reads rejected instead, and its page does not open (public_state, section 3.7.1). The two warnings that speak of a page being served, job_post_flagged_still_live and job_post_may_go_offline_if_rejected, are made only while the page of the job post this call edited is open when the answer is built (public_state live or flagged): never for a project that is a draft or archived, where nothing is being served, and not for a job post that was switched off after the save. job_post_may_go_offline_if_rejected also needs three things to have been true before the edit: the job post was switched on, had never been posted, and was approved. It is not made when a refusal came back within the wait: the job post's review is then rejected and its page is not open (its public_state is rejected, or project_not_open when the project is not open, or off when the job post was switched off meanwhile: section 3.7.1 gives the order), and the warning job_post_review_rejected carries the verdict. public_state in the project view is the page of the job post the view shows: the job post the call edited in the normal case, another job post when a newer one exists, and another job post or none when the edited one was deleted. Such an edit uses a daily allowance, described next.
• The words of a job post that is switched off or has expired are not edited by this call. A call that would change them answers 409 with the code job_post_is_off before anything is written, and the project fields of the same body are not written either. It applies to a job post whose status is not active (section 3.5.13): inactive, which is switched off, and other, which includes an expired one. A call that changes only project fields, and a call whose job post words equal the stored ones, still work on such a job post. The reason: an edit clears the job post's checked copy of its words, nothing reliably checks the new words of a job post that is not switched on, and the publish route refuses to switch on an approved job post whose words were changed while it was off (409 job_post_edited_while_off, section 3.7.2), so an edit of a switched-off job post could leave it stuck. To change the words, switch the job post on first (POST /hiring/job-posts/{id}/publish/v1, section 3.7.2) and then edit it, or edit it in the dashboard.

A daily allowance for edits that are checked by AI. An edit that changes the words of a job post is checked by AI at once (only a job post that is switched on can have its words edited here), and an organization may make 50 such edits per UTC day, counted across all its keys. The allowance has a counter of its own: the publish checks of section 3.7.2 have the same number but are counted separately. A call refused with job_post_is_off, an edit of project fields only and a call that changes no word do not use it. The allowance is taken after every check that needs no write and before anything is written, so a refused call changed nothing. A unit that was taken is not given back: an edit that then fails (for example with 409 job_post_changed, or with an unknown outcome) has used it. When the 50 are used, the call answers 429 with the code job_post_edit_budget_reached and a Retry-After header that holds the seconds until 00:00 UTC, when the count restarts (the message says the same in words). When the allowance cannot be read just now, the call answers 503 with the code job_post_edit_budget_unavailable, fails closed and changes nothing: try again in a moment. For a higher limit, write to contact@flowmingo.ai (section 8.5).

Sample request. This call renames the project and sets the words of its job post:

curl -s -X POST "$BASE/hiring/projects/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/update/v1" \
  -H "X-API-Key: $FLOWMINGO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Support Engineer - Q1 hiring",
    "job_post": {
      "description": "We are hiring a support engineer for our payments platform. You will review, prioritise and answer customer tickets, and you will work with our engineers to fix what you find."
    }
  }'

With a key that holds read_hiring as well as create_project, the answer is 200:

{
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "changed": true,
  "updated_at": "2026-11-06T04:12:44.208Z",
  "project": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "title": "Support Engineer - Q1 hiring",
    "position": "Support Engineer",
    "status": "active",
    "description": "We are hiring a support engineer for our payments platform. You will review, prioritise and answer customer tickets.",
    "external_id": "REQ-48213",
    "created_at": "2026-11-02T04:18:44.051Z",
    "updated_at": "2026-11-06T04:12:44.208Z",
    "job_post": {
      "id": "c0ffee00-dead-4bee-8f00-0123456789ab",
      "status": "active",
      "public_state": "live",
      "external_id": "POST-48213",
      "title": "Support Engineer",
      "description": "We are hiring a support engineer for our payments platform. You will review, prioritise and answer customer tickets, and work with our engineers to fix the problems you find.",
      "sent_title": "Support Engineer",
      "sent_description": "We are hiring a support engineer for our payments platform. You will review, prioritise and answer customer tickets, and you will work with our engineers to fix what you find.",
      "review": "approved",
      "differs_from_sent": true
    },
    "assessments": [
      {
        "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
        "assessment_type": "ai_interview",
        "status": 1,
        "status_label": "active",
        "external_id": null
      }
    ]
  },
  "warnings": ["job_post_text_may_be_rewritten", "job_post_rewritten_by_review"]
}

The project's title was saved as sent. The check reworded the job post's description, so differs_from_sent is true, job_post.description is the checked wording, and job_post.sent_description is the sentence that was sent. project.description is the project's own copy and was not part of this call. The job post's page stayed open (public_state live) while its new words were checked, as that of a live job post that has been posted before does. The answer has the fields of section 3.5.13 inside project, plus id, changed (false when nothing differed), updated_at (the same as project.updated_at) and warnings.

With a key that holds create_project but not read_hiring, the edit is made in the same way and the warnings follow the same rules, but project is null. This example is of an edit after which the check had approved the words as sent, so only the first warning is made:

{
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "changed": true,
  "updated_at": "2026-11-06T04:12:44.208Z",
  "project": null,
  "warnings": ["job_post_text_may_be_rewritten"]
}

Such a key cannot see whether the check reworded the words, except through the warnings that name it; read the project with a key that holds read_hiring (section 3.5.13). job_post_rewritten_by_review speaks only of the title and the description that this call changed, so it tells such a key nothing about a field it did not send. The warnings are made from the job post that was edited, not from the project view, so this key is given them too, the two that speak of a page being served included, while the page of that job post is open when the answer is built; it cannot read public_state from the project or from the publication read (section 3.7.1) to check, because those need read_hiring.

Warnings. warnings lists things worth knowing that did not stop the call. More codes may be added: ignore one you do not know.

The page warnings follow the page. job_post_flagged_still_live and job_post_may_go_offline_if_rejected are made only while the page of the job post this call edited is open when the answer is built. For example, when you change the words of a switched-on job post in an archived project and the check flags them, review reads flagged and public_state reads project_not_open, and job_post_flagged_still_live is not among the warnings, because nothing is being served. job_post_review_rejected and job_post_awaiting_review are different: they state the verdict or the progress of the check, so they are made whatever the page does. A job post switched off right after the save can therefore still carry job_post_awaiting_review while its check is pending.

A caution that has no warning of its own. review is a best-effort reading of the last check. A check of older words that was still running when you edited can finish afterwards, and the job post can then keep older checked wording while review reads approved and no warning appears. The same older check can be the one that flagged or refused the job post. To know what the job post shows, compare title and description (what it displays) with sent_title and sent_description (what you sent, trimmed). If they are not what you expect, change the words (even by one character; you can change them back afterwards) or change them in the dashboard: sending or saving the same words again starts no check, and a call whose words equal the stored ones writes nothing. A blank at the beginning or the end is not a change, because blanks there are removed first. Each change made through this route to the words of a switched-on job post uses one unit of the daily allowance below, and changing them back is a second change that uses a second unit.

Errors on this route. Every error has the shape of section 8.4. Branch on code. A message that tells you to read the project says that reading needs the read_hiring scope when the key does not have it.

The limits on requests per key of section 8.5 apply to this route like any other, and so does the daily allowance above.

3.6 Create an assessment with the AI

Six routes each make one assessment from a job title, the way the dashboard's own wizard does: the AI writes the content, the assessment is published, and it is ready to send to candidates. Use them when your system knows the job and not the questions. To write the questions yourself, use POST /interview/set/v1 (sections 3.1 to 3.4). To open a role with its assessments in one call, use the project route (section 3.5.5). Required API key scope for all of them: create_assessment. Each takes an optional external_id, your own id for the assessment (section 3.6.4).

Every path is relative to https://apis.flowmingo.ai/company/integration. The AI Interview, the Role-play and the Showcase usually take about half a minute, a Skill Test about a minute and a Technical Test 3 to 9 minutes (the figures of the OpenAPI document); a CV Evaluation is one AI call.

3.6.1 What you need

• The create_assessment scope (section 2.3). A key does not gain it automatically: tick Create assessments on the key.
• Two people are checked, and each must be an Owner or Admin of your organization at the moment of each call. One is the person who created the key. The other is the person the assessment is made as: the user the key is bound to, when it has one, otherwise the person who created the key (the two can be different people). The project route (section 3.5.5) makes its assessments as the person it makes the project as, the creator of the key. The roles are read again on every call, so a key whose creator was demoted stops working here at once, and so does a key whose creator has left, during the grace period that follows (section 2.10). A failed check of either person answers 403 with the code assessment_create_requires_admin, so the code alone does not say which of the two failed; after the grace period the key is refused before it reaches these routes (section 2.10). If the role cannot be confirmed just now the answer is 503 assessment_create_role_unconfirmed; a key with no creator on record is refused with a 403 before anything runs (section 11). Nothing is created in any of these.
• Each assessment costs AI generation, so your organization has a per-minute and a per-day budget, counted across all its keys (section 3.6.11).
• The assessment is ready to use. It is published, attached to the project if you named one, and made with the dashboard's own defaults. The dashboard-only settings named in section 3.6.4 are refused; other properties that are not listed are ignored.

3.6.2 How a call works: keys, replays and waiting

All six routes work the same way.

• idempotency_key is required. It is a token you choose, 8 to 128 characters from A-Z a-z 0-9 . _ : -, for example the id of the job in your own system plus the kind (ats-job-48213-cv). It belongs to your organization, whichever of your API keys sends it, and it is remembered for good. Use one key for each assessment you want.
• The same body means the same request once the defaults are filled in: a field you send with the value its default has (such as language en, or duration_minutes 20) is the same request as leaving it out (name and interview_languages are the exceptions: sending the name the dashboard would have given, or ["English"], is a different request from leaving them out), text is trimmed, and a job_description shorter than 50 characters counts as none. An external_id is part of the body: another one, one added or one dropped is a different request, and sending null is the same request as leaving it out. A request you stored before this field existed and send again unchanged is still a replay, never a 409. The answer to a repeat is read fresh, so it shows the assessment as it is now (one deleted in the dashboard reads status deleted, ready false and external_id null).
• Two calls with the same key at the same moment make one assessment. The second waits for the first one's result and answers it.
• Resuming can cost again. Repeating a request that is still pending or has failed resumes it and can take units again (section 3.6.11); it can then answer 201, 202 or an error instead of 200.
• After a 202, ask again with the same key, never with a new one (a new key makes a second assessment). Wait the seconds the Retry-After header says, then either send the same request again (each repeat waits up to about 45 seconds itself) or read the status route (section 3.6.3), until the status is ready.
• To wait less, send a Prefer header. Prefer: respond-async makes the call answer at once with where the assessment has got to (a 202 like the one above, with a Retry-After; an assessment that is already finished is answered as usual, 200 or 201), and Prefer: wait=20 waits at most 20 seconds (a longer wait is cut to the usual wait of about 45 seconds). Use it when your caller gives up early, for example a no-code step that times out at 30 seconds. The answer carries Preference-Applied (respond-async or wait=<seconds>) when it was applied; without the header, or with one that cannot be read, nothing changes. It is not part of the request, so the same idempotency_key can be sent again with a different preference (or none). After a 202 that came from a Prefer, follow the assessment with the status read (section 3.6.3), not by sending the request again: a repeated request with a short wait restarts a failed attempt each time, which can cost again, and it answers 202 before it can say why the attempt failed, while the status read reports the failure. A wait of 0 still includes sign-in, validation and the budget check, so give your caller a few seconds more than your own network needs. It applies to the six assessment routes of this section. POST /hiring/projects/v1 takes it too, for the assessments it makes (section 3.5.5); it drafts the job post before it answers, and the header does not shorten that.

The 202 body:

{
  "status": "pending",
  "kind": "technical_test",
  "idempotency_key": "ats-job-48213-tt",
  "message": "The assessment is still being made. Nothing is lost: ask again with the same idempotency_key (send the same request, or read GET /integration/assessments/requests/{idempotency_key}/v1) until its status is ready.",
  "retry_after_seconds": 10
}

A loop that sends the request until it stops answering 202:

const BASE = 'https://apis.flowmingo.ai/company/integration'
const HEADERS = { 'Content-Type': 'application/json', 'X-API-Key': process.env.FLOWMINGO_API_KEY }

// Every repeat has the same body and the same idempotency_key, so it never makes a second assessment.
async function createAssessment(route, body, giveUpAfterMs = 15 * 60 * 1000) {
  const startedAt = Date.now()
  for (;;) {
    const res = await fetch(`${BASE}/assessments/${route}/v1`, { method: 'POST', headers: HEADERS, body: JSON.stringify(body) })
    if (res.status !== 202) return { status: res.status, body: await res.json() } // 201, 200, or an error with a code
    if (Date.now() - startedAt > giveUpAfterMs) throw new Error('still being made: read it later with the status route')
    const seconds = Number(res.headers.get('Retry-After')) || 10
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000))
  }
}

3.6.3 Read where a request has got to

GET /assessments/requests/{idempotency_key}/v1 answers where a create call has got to. Use it to follow a call that answered 202. It only reads: it never starts or restarts any work. Any key of your organization can read a request that another key made, and, like the create routes, it needs a key whose creator is an Owner or Admin (section 3.6.1).

A key that no request of your organization used answers 404 with the code assessment_request_not_found (a key that could never have been accepted, such as one with the wrong characters, answers the same). A request that was made for a project that the key's creator can no longer open (the project was archived or deleted, or taken out of their access) answers 404 project_not_found. Here that does not mean nothing was made: the request exists, and an assessment may have been made for it. The message says so: "This request was made for a project that this API key can no longer open (it may have been archived or deleted, or taken out of the key's access), so its status is not shown. The request exists and an assessment may have been made for it. This API key may not be able to read the assessments list, so ask a colleague who can open it (an Owner, for example) to check it there." Reading the assessments list needs the read_hiring scope, and a key whose creator is limited to some projects sees only the assessments of those projects, so a colleague who can open every project is the one who can look; if you sent an external_id, GET /hiring/interview-sets/v1?external_id= finds the assessment there. The six create routes answer the same code and status for a project_id they cannot use, and there it is true that nothing was created.

{
  "idempotency_key": "ats-job-48213-tt",
  "kind": "technical_test",
  "status": "pending",
  "project_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "assessment": null,
  "failure": null,
  "retry_after_seconds": 10
}

3.6.4 Fields every route takes

Names are snake_case. Text is trimmed before it is checked.

external_id. It follows the rules of section 8.8: not trimmed, scoped to your company, not unique, and fixed when the assessment is made. The camelCase externalId is not read. A value that breaks the rules is a 400 with no code and the message "external_id must be plain text of 1 to 128 characters with no control characters. It is stored exactly as sent."; nothing is created. Every answer of the route carries external_id (your id exactly as stored, or null when you sent none, and null once the assessment has been deleted), and so do the status read (section 3.6.3) and the assessments list, which ?external_id= filters. The id is written a moment after the assessment exists, inside the call, so no answer of the call shows the assessment without it. It is part of the request (section 3.6.2) and it is not the idempotency_key. An assessment that a create-project call makes (section 3.5.5) gets no id.

project_id. It must be an active hiring project of your organization that the key's creator can use (a project-limited Admin can use only the projects they were given), and that the person the assessment is made as (section 3.6.1) can use too; a project that person cannot use answers the same 404 as a project that is not active. The answer then says linked true. If the creator is limited to some projects, any project outside theirs, another organization's and a deleted project included, answers 403 with the code key_out_of_reach ("The person who created this API key does not have access to that hiring project ...", section 11) before anything is made or any AI is called. A project the creator may name but that is not an active project of your organization (archived, or, for a creator with access to all hiring projects, deleted or another organization's) answers 404 with the code project_not_found. Either way nothing is created; a value that is not a UUID answers 400 with no code. A creator limited to some projects can still make an assessment that names no project. If the assessment was made but could not be attached, the call fails with 502 assessment_project_link_failed, which sending the same request again repairs.

Send project_id when you make a Skill Test or a Technical Test. The invite route sends these two only through a hiring project the test is attached to (section 4.6.1). A test made without project_id is not attached to one, so inviting a candidate to it answers 400 with the code project_required (or 404 if you name a project it is not attached to). No route of the API attaches an existing test to a project afterwards: attach it in the Flowmingo dashboard, or make a new one with project_id (or with the project route, section 3.5.5, which attaches the tests it makes).

Three kinds are scored on criteria that you can supply: a CV Evaluation, an AI Interview and a Role-play. A criterion has this shape:

Report language. Where a route takes language, it is a language tag the dashboard lists (en, vi-VN, th-TH, ja-JP and so on) or the bare language (vi finds vi-VN), with the default en. A language that is not supported answers 400 with the code language_not_supported, and its message lists the accepted tags.

Options these routes refuse. The routes read only the fields documented here. A value in any of features, addons, attributes, com_accesses, pdf_url, file_link, status, set_type, id, priority or interview_duration is refused with 400 and the code assessment_field_not_supported, so you are never left believing it was applied (a null is ignored). The Technical Test refuses more, listed in section 3.6.10. Any other property is ignored without an error.

3.6.5 CV Evaluation

POST /assessments/cv-evaluation/v1 makes a CV Evaluation: a set of criteria that candidates' CVs are scored against, published and ready to use. It takes the fields of section 3.6.4 and:

• A project can have only one CV Evaluation. With a project_id that already has one, the call answers 409 with the code project_already_has_cv_evaluation and nothing is made.
• The free CV report that candidates may get after applying follows your organization's own setting. It is on for a new CV Evaluation, but the email goes out only when someone in your organization has accepted the notice in the dashboard (the answer says whether they have: notice_acknowledged). This route never accepts it for you.
• The answer adds report_language, criteria (each with id, title, details and importance), criteria_count and complimentary_cv_evaluation (enabled and notice_acknowledged). A full sample is in section 3.6.13.

3.6.6 AI Interview

POST /assessments/ai-interview/v1 makes an AI Interview the way the dashboard's wizard does: the AI writes the criteria and the interview questions from the job title (and the description), and the interview is published, ready to send to candidates. Everything else takes the dashboard's defaults: 20 minutes, English, the candidate uploads a CV first, a public link, the free tier with no paid options. It takes the fields of section 3.6.4 and:

• If the project's job post already has auto-invite switched on, the interview becomes the one it invites with, as in the dashboard.
• The answer adds duration_minutes, interview_languages, report_language, criteria, criteria_count and questions (interview, the questions the AI interviewer asks, and pre_screening, the ones the candidate answers first, such as the CV upload). A sample is in section 3.5.9.

3.6.7 Role-play

POST /assessments/role-play/v1 makes a Role-play: the candidate plays themselves in a situation, an AI plays a character, and the conversation is scored. The AI writes the criteria and one 15-minute scenario with its character from the job title (and the description). It is published and ready to send to candidates, with the dashboard's defaults: English, the free tier, a public link. It takes the fields of section 3.6.4 and:

• Sending only one of scenario and character answers 400 with the code role_play_scene_invalid; a text over 4,000 characters is a 400 with no code.
• The character is the answer key. Candidates never see it and the API never returns it.
• The answer adds duration_minutes (15), report_language, interview_languages, scenario, scenes_count, criteria and criteria_count:

{
  "id": "4c9d1e2f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "type": "role_play",
  "name": "Data Analyst — Role-play, 22 Oct '26",
  "job_title": "Data Analyst",
  "external_id": null,
  "status": "active",
  "ready": true,
  "duration_minutes": 15,
  "report_language": "en",
  "interview_languages": ["English"],
  "scenario": "You are a Data Analyst at Northstar Metrics, a company that provides analytics services to subscription businesses. You are meeting Daniel Reed, Growth Director…",
  "scenes_count": 1,
  "criteria": [ ... ],
  "criteria_count": 5,
  "project_id": null,
  "linked": false,
  "idempotent_replay": false
}

Here scenario and criteria are cut; the criteria have the shape of section 3.6.5.

3.6.8 Skill Test

POST /assessments/skill-test/v1 makes a Skill Test the way the dashboard's automatic path does: the AI writes one fixed multiple-choice paper from the job title (and the description), it is approved and published, and it is ready to invite candidates to. Every candidate gets the same questions, in a shuffled order. The defaults are 30 questions, 20 minutes, medium difficulty and strict exam security. It takes the fields of section 3.6.4 and:

• There is no language field: the questions follow the job title and description. Whatever name you give, the questions are still written for job_title.
• Send project_id if you mean to invite candidates to this test through the API: a Skill Test is sent only through a hiring project it is attached to (section 3.6.4).
• The answer adds question_count, duration_minutes, difficulty, exam_security and config_revision (the test's stored configuration revision; it is not a counter of every edit). Its status is published when the paper is published and usable, draft while it is being made, archived or deleted after the dashboard changed it:

{
  "id": "8e7a1c52-3d4b-4f90-a6e1-2b9c5d7f0a13",
  "type": "skill_test",
  "name": "Data Analyst – Test",
  "job_title": "Data Analyst",
  "external_id": null,
  "status": "published",
  "ready": true,
  "question_count": 30,
  "duration_minutes": 20,
  "difficulty": "medium",
  "exam_security": "strict",
  "config_revision": 4,
  "project_id": null,
  "linked": false,
  "idempotent_replay": false
}

3.6.9 Showcase

POST /assessments/showcase/v1 makes a Showcase: candidates record themselves (screen, camera and microphone) doing a few tasks, each with a time limit, and nobody scores it with criteria. By default the AI is asked for two tasks of ten minutes each from the job title (or from the description when you send one); the result can have fewer, so read tasks_count. The Showcase is published, ready to invite candidates to. It takes the fields of section 3.6.4 and:

A task has:

• The tasks together may record at most 3,600 seconds, and no more than your plan allows. A repeated title or too much recording time answers 400 with the code showcase_tasks_invalid; a total over your plan's limit answers 400 assessment.length_exceeds_plan. Nothing is created.
• A Showcase can be sent through the invite route, by email address (section 4.8).
• It starts with the dashboard wizard's defaults. A Showcase made through the API has an intro message for the candidate and the CV upload question, like one made in the dashboard wizard.
• The answer adds tasks (each with id, title, content, max_seconds and priority, the order candidates do them in), tasks_count and total_seconds. Its status is active when it is published and usable, draft while it is being made, inactive or deleted:

{
  "id": "6b3a9f10-2c4d-4e5f-9a7b-8c1d2e3f4a5b",
  "type": "showcase",
  "name": "Data Analyst – Showcase, 22 Oct '26",
  "job_title": "Data Analyst",
  "external_id": null,
  "status": "active",
  "ready": true,
  "tasks": [
    {
      "id": "3b8e2a64-7c1d-4f0e-9a52-1d6f0c9b7e21",
      "title": "Open a growth dashboard you built and walk through its weekly reporting.",
      "content": "Open a dashboard you created for growth reporting, …",
      "max_seconds": 600,
      "priority": 1
    }
  ],
  "tasks_count": 2,
  "total_seconds": 1200,
  "project_id": null,
  "linked": false,
  "idempotent_replay": false
}

Here tasks is cut to its first entry of two (tasks_count), and the text of the task is cut.

3.6.10 Technical Test

POST /assessments/technical-test/v1 makes a Technical Test: a few coding problems that the AI writes and then proves, by running its own reference solution against its own test cases in a code sandbox (a problem that fails the check is thrown away). The test is then published, and attached to the hiring project you name in project_id, which is what lets you invite candidates to it (see "Create it inside a hiring project" below). The defaults are two medium problems, one of them a debugging problem, in Python 3, JavaScript and Java, with AI assistance not allowed, and a time derived from the problems. It takes the fields of section 3.6.4 and:

• Create it inside a hiring project. Send project_id (section 3.6.4) when you make the test. Candidates can be invited to a Technical Test only through a hiring project it is attached to, and the API has no route that attaches an existing one afterwards: without project_id the invitation fails with 400 project_required until a person attaches the test to a project in the Flowmingo dashboard (section 4.6.1). The test is attached once it is published, and the answer then says linked true.
• It takes minutes. The call waits about 45 seconds and then answers 202, so plan to ask again with the same key, or read the status route, until it is ready. The first answer is normally 202 and pending.
• Capacity. A Technical Test creation can be refused with 429 assessment_capacity_busy when generation capacity is not available. Nothing is started: send the same request again later.
• Your plan's length limit (assessment.length_exceeds_plan) is known only once the AI has written the problems, so for this kind it can arrive after the wait, as a failed status with that code. Ask for fewer or easier problems with a new idempotency_key. By then an unpublished draft of the test may already exist and generation units may have been spent.
• Refused options. On top of section 3.6.4, a value in any of these answers 400 assessment_field_not_supported: sponsorship and white-label, who may take the test (access, access_type, recipients), the intro, outro and background media, result_visibility, max_attempts, exam_security, strictness, durations (duration, duration_minutes, duration_seconds), time_limit_ms, memory_mb, your own test_cases, starter_code, harness, reference_solution or questions, settings, and pre-screening questions. The problems, their cases and the time are all produced by the generation.
• The answer adds languages (those a candidate can actually use), skills, difficulty, duration_minutes (the problems' times added up), problem_count, problems and generation. Each problem has id, title, difficulty, duration_minutes, languages, is_debugging, verified (the AI's own solution passed the problem's own cases in the sandbox), sample_case_count (cases the candidate can see) and hidden_case_count (cases that grade the answer). The answer shows only these counts: it never returns a hidden case, the harness or any solution. generation says how many problems were requested, kept and discarded. The status is published, draft, archived or deleted. A full sample is in section 3.6.14.

3.6.11 Budget and capacity

Every assessment costs AI generation. Your organization therefore has two budgets, counted in units (a Skill Test costs more than a CV Evaluation), shared by all its API keys and by the assessments that project calls make (section 3.5.5):

• When units are taken. A request takes its units when its work starts. A repeat of a request that already finished costs nothing. A request that is refused before any AI work gives its units back; once the AI has been called the units stay taken even if the attempt then fails, and a new attempt takes its own.
• When the budget is spent the call answers 429 with the code assessment_create_limit_reached and starts nothing. The message says whether to try again in a minute or after 00:00 UTC (when both are spent it names the day), and what the kind costs.
• If the budget cannot be checked just now the call answers 503 assessment_create_limit_unavailable and starts nothing: it never starts work it could not count.
• Capacity is separate from the budget. When capacity is not available the call answers 429 assessment_capacity_busy at once and starts nothing. Send the same request again a little later.

3.6.12 When a request fails

A request can fail in two ways.

• Refused at the door. A rule, a missing scope or role, a project_id that cannot be used, a spent budget: the answer is an error status with a code, and nothing is recorded under the idempotency_key. Correct the request and send it again with the same key.
• Failed after it was accepted. The work started and could not finish. The call that is waiting answers with the error status and the code below. A call that already answered 202 finds the same thing later as status failed with a failure object on the status route (section 3.6.3). The failure stays under the key: when retryable is true, send the same request again with the same key and the work takes up again; when it is false, an unchanged repeat is not expected to resolve it without a corrective step, which the last column of the table names. A key stays bound to the body it was first used with, so if the fix changes the body, use a new key.

Two statuses here are not general server errors: 502 and 500 come with a code from the table, and every row says whether sending the same request again can finish the assessment.

A problem with the key itself (401, or a 403 for a missing scope, an expired key, a creator who has left, can open no hiring project or is not on record) is described in section 11.

3.6.13 Sample: create a CV Evaluation

The ids in these samples are placeholders.

curl -X POST https://apis.flowmingo.ai/company/integration/assessments/cv-evaluation/v1 \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: fl_live_abcd12345.n8G3zPNw9gWkK1Kj' \
  -d '{
    "idempotency_key": "ats-job-48213-cv",
    "external_id": "REQ-48213",
    "job_title": "Support Engineer",
    "job_description": "We are hiring a support engineer for our payments platform. You will review, prioritise and answer customer tickets."
  }'

The answer is 201 (criteria is cut to two of its seven entries here):

{
  "id": "7d2c1c3e-5b1f-4f55-9a3b-0c9a2f7e8d11",
  "type": "cv_evaluation",
  "name": "Support Engineer – CV Evaluation, 22 Oct '26",
  "job_title": "Support Engineer",
  "external_id": "REQ-48213",
  "status": "active",
  "ready": true,
  "report_language": "en",
  "criteria": [
    {
      "id": "1f0e0f0a-6b6c-4c1c-9a3a-0a0a0a0a0a0a",
      "title": "Customer support and ticket triage",
      "details": "Help payments-platform customers by reviewing, prioritizing, and responding to support tickets.",
      "importance": "must_have"
    },
    {
      "id": "2a1f1a1b-7c7d-4d2d-8b4b-1b1b1b1b1b1b",
      "title": "Clear written communication",
      "details": "Write understandable, helpful answers to customers about their issues.",
      "importance": "must_have"
    }
  ],
  "criteria_count": 7,
  "project_id": null,
  "linked": false,
  "complimentary_cv_evaluation": { "enabled": true, "notice_acknowledged": true },
  "idempotent_replay": false
}

Sending the same request again returns this assessment with 200 and idempotent_replay true; sending it with another external_id is a 409. Find the assessment later with GET /hiring/interview-sets/v1?external_id=REQ-48213 (section 8.8). The id is the assessment's id: use it as com_interview_set_ids on the invite route (section 4) for the kinds that route can send (section 4.2).

3.6.14 Sample: a Technical Test

A Technical Test takes minutes, so the first answer is normally 202. The request names the hiring project (here a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d, a placeholder: use the id of one of your own projects from GET /hiring/projects/v1) so that the test is attached to it and candidates can be invited to it through the API (section 3.6.10):

curl -i -X POST https://apis.flowmingo.ai/company/integration/assessments/technical-test/v1 \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: fl_live_abcd12345.n8G3zPNw9gWkK1Kj' \
  -d '{
    "idempotency_key": "ats-job-48213-tt",
    "job_title": "Data Analyst",
    "job_description": "We are hiring a data analyst to report on growth and campaign spend.",
    "project_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  }'

HTTP/1.1 202 Accepted
Retry-After: 10

The body is the 202 body of section 3.6.2. Read where it has got to, until status is ready:

curl -H 'X-API-Key: fl_live_abcd12345.n8G3zPNw9gWkK1Kj' \
  https://apis.flowmingo.ai/company/integration/assessments/requests/ats-job-48213-tt/v1

{
  "idempotency_key": "ats-job-48213-tt",
  "kind": "technical_test",
  "status": "ready",
  "project_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "assessment": {
    "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "type": "technical_test",
    "name": "Data Analyst – Technical Test",
    "job_title": "Data Analyst",
    "external_id": null,
    "status": "published",
    "ready": true,
    "project_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "linked": true,
    "languages": ["python3", "javascript", "java"],
    "skills": [],
    "difficulty": "medium",
    "duration_minutes": 60,
    "problem_count": 2,
    "problems": [
      {
        "id": "5d0f6a9e-2c1b-4e7a-8f3d-9b1c2a3d4e5f",
        "title": "Rank Campaign Conversion Rates",
        "difficulty": "medium",
        "duration_minutes": 30,
        "languages": ["python3", "javascript", "java"],
        "is_debugging": false,
        "verified": true,
        "sample_case_count": 2,
        "hidden_case_count": 4
      },
      {
        "id": "2e6f8a1c-4b3d-4c5e-9f7a-0b1c2d3e4f5a",
        "title": "Debug the Campaign Budget Ledger",
        "difficulty": "medium",
        "duration_minutes": 30,
        "languages": ["python3", "javascript", "java"],
        "is_debugging": true,
        "verified": true,
        "sample_case_count": 2,
        "hidden_case_count": 5
      }
    ],
    "generation": { "requested": 2, "kept": 2, "discarded": 0 }
  },
  "failure": null
}

linked true says the test is attached to the project, so candidates can now be invited to it (section 4.6). Without project_id in the request, project_id here is null and linked is false, and an invitation would fail with project_required. While it is being made the same read shows status pending (section 3.6.3). The same request sent again once it is ready answers 200 with this assessment and idempotent_replay true.

3.7 Publish, unpublish and boost a job post

A job post is the public page where candidates read about a role and apply. Four routes switch it on or off, promote it, and open or close the hiring project it belongs to, the way the Live switch and the status control do in the dashboard. A fifth route says whether the page is open. None of them changes the words of the job post: for its title and description, use the edit route of section 3.5.14 (while the job post is switched on) or the dashboard. Every path is relative to https://apis.flowmingo.ai/company/integration.

The id of a job post is the job_post.id of the create-project answer (section 3.5.9) or the id of a row of GET /hiring/job-posts/v1 (section 5.6). The id of a project is the one section 5.7 explains how to find. The read answers 200. The four POST routes answer 201 when they work, also when nothing changed (changed false), and so does the cancel route of section 4.9.1.

The four POST routes act as the person who created the key, and that person must be an Owner or Admin of your organization. The role is read again on every call. During the grace period after a creator has left (section 2.10), the role they left with is used. If the role is not enough, the answer is 403 with the code project_create_requires_admin. The hiring project of the job post must also be one that person can open, or the answer is 403 with the code key_out_of_reach (section 2.9). A job post or a project that is not in your organization answers 404. The read route needs only read_hiring.

3.7.1 Is the job post open to the public?

A job post whose status is active is not necessarily open: status is only the post's own switch. A job post is open to the public only when all three of these hold:

1. it is switched on,
2. the AI content check approved it, and
3. its hiring project is active.

So the publication read, and the publish, unpublish and boost answers, all carry the same block, and the field to read is public_state. (The project status answer has its own shape: section 3.7.5.) This request changes nothing:

curl -s -H "X-API-Key: $FLOWMINGO_API_KEY" \
  "$BASE/hiring/job-posts/c0ffee00-dead-4bee-8f00-0123456789ab/publication/v1"

{
  "job_post_id": "c0ffee00-dead-4bee-8f00-0123456789ab",
  "com_project_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "active",
  "review_status": "approved",
  "review_rejection_reason": null,
  "public_state": "live",
  "public_url": "https://talent.flowmingo.ai/jobs/ZW5naW5lZXI",
  "tier": "off",
  "reasons": [],
  "warnings": []
}

off comes before project_not_open. A post that is switched off reads off, even when its hiring project is a draft or archived: reasons then holds both post_off and project_not_open. The state project_not_open itself appears only when a post is still switched on while its project is not active. After you move a project to draft or archived, the job post can already read off, so read reasons, not the state alone, to see every cause. project_not_open in turn comes before rejected, awaiting_review and flagged: a post that the check refused reads rejected only while it is switched on and its project is open. If its project is not open it reads project_not_open, and if it has been switched off it reads off.

Errors: 404 with the code job_post_not_found for a job post that is not in your organization, and 403 with the code key_out_of_reach for one inside a project the key's creator cannot open.

3.7.2 Publish a job post

POST /hiring/job-posts/{id}/publish/v1 switches the job post on, like the Live switch on the project's job post page. It takes no body. Nothing is emailed and no webhook fires.

curl -s -X POST -H "X-API-Key: $FLOWMINGO_API_KEY" \
  "$BASE/hiring/job-posts/c0ffee00-dead-4bee-8f00-0123456789ab/publish/v1"

{
  "job_post_id": "c0ffee00-dead-4bee-8f00-0123456789ab",
  "com_project_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "active",
  "review_status": "approved",
  "review_rejection_reason": null,
  "public_state": "live",
  "public_url": "https://talent.flowmingo.ai/jobs/ZW5naW5lZXI",
  "tier": "off",
  "reasons": [],
  "warnings": ["company_profile_incomplete"],
  "changed": true
}

The answer is the block of section 3.7.1 plus changed, which is false when the post was already on. Read public_state, not status: live means the page opens now. The warning company_profile_incomplete says the company logo or description is missing. Only a publish call adds it: the read of section 3.7.1 for the same post answers []. The post is published anyway, as in the dashboard, but boosting needs both.

• The hiring project must be active. If it is a draft, archived or deleted, the call answers 409 with the code project_not_open and changes nothing. Open the project first (section 3.7.5).
• The text is checked before it goes public. A post whose wording has no checked copy yet (it was never checked, it was refused, it was flagged while it was live, or it was edited since its last check) goes through the same AI check as the dashboard first, and is switched on only if it passes (the one exception is in the next point). If the check refuses it, the call answers 422 with the code publish_review_rejected and a rejection_reason, and nothing is changed. A post whose approved wording already has a checked copy needs no check.
• A post that was approved, then edited while it was off, cannot be switched on from here. (An edit in the dashboard counts. The edit route of section 3.5.14 does not change the words of a job post that is switched off, so an edit made while it is off cannot cause this: it answers 409 job_post_is_off. An edit of a post that is switched on can leave it in the same state, for example if its check does not finish. Once you have this 409, switch the post on in the dashboard.) Its new wording has no check yet (the same is true if an earlier check flagged it). The call answers 409 with the code job_post_edited_while_off and changes nothing. Switch it on once in the dashboard, which checks it.
• A check can be slow, and a failed check is rolled back. After the switch, the call waits up to 60 seconds for the checked copy. If the check cannot finish, or refuses the post after all, Flowmingo tries to switch the post back off, and the call answers 503 with the code job_post_review_unavailable or 422 with the code publish_review_rejected. If switching it back off fails too, the message says the post may still be live: open it in the dashboard and switch it off. After any of these answers, read public_state (section 3.7.1) before you tell anyone the post is live or off. Try again in a moment after a 503.
• The post must stay as it was. If it is edited, switched on or off, or deleted while the check runs, the call answers 409 with the code job_post_changed. If that happens before the switch, nothing is switched on. If the post was edited and checked again after this call switched it on, it is left exactly as it now is. Read the post again and retry.
• There are 50 checks per organization per UTC day, counted across all your keys. At the limit the call answers 429 with the code publish_review_limit_reached. If the counter cannot be read, it answers 503 with the code publish_review_limit_unavailable and changes nothing.
• Publishing again is safe. A post that is already on stays on, and the answer says changed false. If that post was never checked, the call can still run its content check.

An example of a refused post:

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "code": "publish_review_rejected",
  "message": "The AI check of this job post did not pass, so it was switched back off. Reason: The post asks applicants to pay a fee. Change the text in the dashboard and publish again.",
  "rejection_reason": "The post asks applicants to pay a fee.",
  "timestamp": "2026-11-05T08:15:00.000Z",
  "path": "/integration/hiring/job-posts/c0ffee00-dead-4bee-8f00-0123456789ab/publish/v1"
}

Branch on code, never on the wording of message.

3.7.3 Unpublish a job post

POST /hiring/job-posts/{id}/unpublish/v1 switches the job post off. Its public link stops opening, and it leaves the job boards and search at the next sync, which takes a few minutes. The hiring project stays as it is.

curl -s -X POST "$BASE/hiring/job-posts/c0ffee00-dead-4bee-8f00-0123456789ab/unpublish/v1" \
  -H "X-API-Key: $FLOWMINGO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "withdraw_boost": true }'

{
  "job_post_id": "c0ffee00-dead-4bee-8f00-0123456789ab",
  "com_project_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "inactive",
  "review_status": "approved",
  "review_rejection_reason": null,
  "public_state": "off",
  "public_url": null,
  "tier": "off",
  "reasons": ["post_off"],
  "warnings": [],
  "changed": true,
  "boost_withdrawn": true
}

The answer is the block of section 3.7.1 plus changed (false when the post was already off) and boost_withdrawn (true when this call also switched the boost off). An unpublish of a post that is already off can still withdraw the boost, so changed can be false while boost_withdrawn is true.

• Switching off a job post or moving its project to draft or archived does not reliably stop invitations or reminders. An automatic invitation triggered by an application may still be sent; reminders may still go out, although some invitations and reminders may be held.
• The warning linkedin_posted says the job was marked as posted on LinkedIn. Close it there too.
• To undo it, publish the post again (section 3.7.2).

3.7.4 Boost a job post

POST /hiring/job-posts/{id}/boost/v1 sets how widely the job post is promoted. Boosting is free: no wallet, credit or plan is involved.

curl -s -X POST "$BASE/hiring/job-posts/c0ffee00-dead-4bee-8f00-0123456789ab/boost/v1" \
  -H "X-API-Key: $FLOWMINGO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "tier": "flowmingo" }'

{
  "job_post_id": "c0ffee00-dead-4bee-8f00-0123456789ab",
  "com_project_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "active",
  "review_status": "approved",
  "review_rejection_reason": null,
  "public_state": "live",
  "public_url": "https://talent.flowmingo.ai/jobs/ZW5naW5lZXI",
  "tier": "flowmingo",
  "reasons": [],
  "warnings": [],
  "changed": true
}

The answer is the block of section 3.7.1 plus changed, which is false when the post already had that tier.

• Raising the tier needs three things: the post is switched on (otherwise 409 with the code job_post_not_active), its hiring project is active (otherwise 409 with the code project_not_open), and the company profile has a logo and a description (otherwise 409 with the code company_profile_required, and 503 with the code company_profile_unavailable when the profile cannot be read). The post also needs a description to be checked (otherwise 400 with the code job_post_description_empty).
• A raise runs the dashboard's AI check. If the check refuses the post, the call answers 422 with the code boost_review_rejected and a rejection_reason. The boost is not applied, and the post stays exactly as it was, live or not.
• There are 50 raises per organization per UTC day, counted across all your keys. At the limit the call answers 429 with the code boost_limit_reached. If the counter cannot be read, it answers 503 with the code boost_limit_unavailable and changes nothing.
• If the post changes while it is being checked, the call answers 409 with the code job_post_changed and no boost is applied.
• Lowering the tier, or switching it off, needs no check and uses none of the 50.
• The warning boost_not_public_yet says the boost was set before the post is approved, so it does nothing until the post is. The call never rewrites the post's text.
• To undo it, set the previous tier.

3.7.5 Open, draft or archive a hiring project

POST /hiring/projects/{id}/status/v1 moves a hiring project between three states, like the status control in the dashboard (which is for Owners and Admins, and so is this call). The answer is 201, also when the project was already in that state. It changes only the status. To change the project's name, role or description, use section 3.5.14, and to read the project's status back, section 3.5.13.

Switching off a job post or moving its project to draft or archived does not reliably stop invitations or reminders. An automatic invitation triggered by an application may still be sent; reminders may still go out, although some invitations and reminders may be held. Candidate data, interviews and reports are kept in every case, and invitations already sent and referral links keep working. Google is not asked to drop an archived job. You can move the project back at any time.

curl -s -X POST "$BASE/hiring/projects/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/status/v1" \
  -H "X-API-Key: $FLOWMINGO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "status": "archived" }'

{
  "com_project_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "archived",
  "changed": true,
  "job_post_ids": ["c0ffee00-dead-4bee-8f00-0123456789ab"],
  "notes": [
    "The project is hidden from the active board and its job link is closed. Switching off a job post or moving its project to draft or archived does not reliably stop invitations or reminders. An automatic invitation triggered by an application may still be sent; reminders may still go out, although some invitations and reminders may be held. Candidate data stays. Google is not asked to drop an archived job."
  ]
}

A project that is not in your organization answers 404 with the code project_not_found. A project the key's creator cannot open answers 403 with the code key_out_of_reach.

3.7.6 Errors on these routes

Every error has the shape of section 8.4. Branch on code.

Repeating a call is safe. changed false means the switch of the post, the boost tier or the status of the project was already as you asked. The call can still do one small extra: an unpublish can withdraw the boost, and a publish can run the content check of a post that was never checked. After a timeout, read the job post's publication (section 3.7.1) before you repeat a publish.

3.8 Tracking links

A tracking link is one of the custom share links of Settings: the address of a job post, of your careers page or of a set of your job posts, with ?tl=<token> on the end. A candidate who applies through a link is credited the link's source, its name and its person. These five routes make, change, switch off, delete and list tracking links. They are not the candidate profile share link, which is a different feature and is not available through the API.

manage_tracking_links is opt-in: a key does not have it unless it is chosen when the key is created or edited (section 2.3). A link holds no candidate record, but the text people type into one (its label, its details, the name of the person it credits and the name of its source) can name an applicant or a referrer. That is why both lists need read_candidates, and why the answer to a make or a change leaves that text out for a key without it (below). The MCP server has no tool for these routes.

Who can use them. The key acts as the person who created it. To make, change or delete a link, or to list the sources, that person must be an Owner or an Admin: an Owner reaches every hiring project, an Admin the projects they hold. A Member is refused with 403, whatever custom role they have, normally with the code tracking_link_requires_admin. A link for your careers page needs access to all hiring projects (an Owner has it; an Admin who was given projects one by one does not, even if the list names every project today), and a link for a set of job posts needs every project of its posts. A call from a key whose creator has left the company is refused, normally with 403 and the code key_creator_left, including during the grace period that other routes normally allow (section 2.10). Making a link, listing links and listing sources also need Custom share links to be switched on for your company (403 with the code custom_share_links_off). Changing and deleting a link are not stopped by that switch or by your plan, so you can still tidy up what you made.

3.8.1 Make a link

POST /tracking-links/v1 takes this JSON body.

A link needs a person, a source or both (400, code tracking_link_needs_person_or_source). A person cannot be made through the API from a name and an email: attributed_person.outside is a 400 with the code tracking_link_field_not_supported, and a person given by a numeric user id is a 400 with the code tracking_link_colleague_not_supported. token, id and enabled cannot be sent on a make (400, tracking_link_field_not_supported). Text that starts with =, +, -, @, a tab or a carriage return is refused (400, tracking_link_text_not_allowed). A text field that is not a JSON string is a 400 too. A source_type of any other shape, or one that names none of your sources or an archived one, is a 400.

curl -s -X POST -H "X-API-Key: $FLOWMINGO_API_KEY" -H "Content-Type: application/json" \
  "$BASE/tracking-links/v1" \
  -d '{"target_kind": "job_post", "project_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "target_id": "c0ffee00-dead-4bee-8f00-0123456789ab", "source_type": "linkedin", "label": "Careers fair, Lagos"}'

The answer is 201. This one is for a key that holds read_candidates:

{
  "id": "2b6f1d8c-4e3a-4c9b-8a7d-5e0f9c1b3a64",
  "target_kind": "job_post",
  "target_id": "c0ffee00-dead-4bee-8f00-0123456789ab",
  "com_project_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "source_type": "linkedin",
  "source_label": "LinkedIn",
  "source_detail": null,
  "label": "Careers fair, Lagos",
  "attributed_person": null,
  "token": "k3JwX9aQ2mTn7vYbL0sDhA",
  "enabled": true,
  "created_at": "2026-11-11T08:30:00.000Z",
  "address": "https://talent.flowmingo.ai/jobs/c2VuaW9yLW51cnNlLTJmOWE?tl=k3JwX9aQ2mTn7vYbL0sDhA",
  "address_host_note": "Built on Flowmingo’s default candidate address. This route does not apply a company’s own candidate domain."
}

• token is 22 case-sensitive characters made by the server. It is a public label, not a credential: it sits in the address a candidate opens and grants nothing alone. It never changes and is never reused, even after the link is deleted.
• address says where the link points. It does not say that the link credits anyone: a link credits an application only while it is switched on (enabled) and its target is open. A switched-off link and a link to a closed job post keep their address. address is built on Flowmingo's default candidate address and does not apply a company's own candidate domain (address_host_note says so). It is null when the API cannot build one: for a link to an AI interview or a bundle (made in the dashboard), for a job post whose address cannot be read, and for a job post link whose job post has moved to another hiring project since the link was made. That job post's page still opens, but the link no longer credits applications: make a new link for the post.
• applications_count can appear on the items of the list (section 3.8.3). It is not in the answer to a make or a change, and it is left out unless your company's source and attribution screens are switched on.
• Without read_candidates, the answer to a make and to a change leaves out label, source_detail, source_label and the person's name: the fields are absent, and null means the link has none. The person is then { "id": "...", "kind": "..." } (kind is colleague or outside), and that id is what you send as person_id. source_type is left out as well when it is the code of a source your company made itself (a code is the source's name in lower-case letters: a source named Jane Doe has the code jane_doe). The codes of the ten default sources (linkedin, facebook, instagram, whatsapp, telegram, email, career_fair, agency, company_website, other) and null are always present. The write is made as you sent it, whatever the answer leaves out.
• No target. The answer to a make or a change does not say whether the link's job post is open: that is in the list (section 3.8.3). A key that holds only manage_tracking_links can therefore be handed the address of a link to a closed job post and cannot see through this API that the post is closed. Make that check with a key that also holds read_hiring and read_candidates.

The plan. Making a link needs the Growth plan or above. Below Growth the answer is 403 with the code growth_required and required_tier set to growth. When the plan cannot be confirmed just now the answer is 503 with the code plan_unconfirmed: try again. It is not a statement about your plan. Changing a link, deleting a link and the two lists never need the plan.

Projects and job posts you cannot reach. A project_id that the key's creator cannot open is a 404 with the message Project not found., the same answer as a project that does not exist, belongs to another company or was deleted. A job post that cannot be linked is a job post that is not there: a job_post link whose job post is not in project_id, and a job_post_set with a job post in a project the creator does not hold, answer 404 with Job post not found., the same answer as an id that does not exist. A link for your careers page, when the creator holds only some projects, is a 403.

The key is checked again. The key and the person who created it are checked again shortly before a link is read, written, changed or deleted. A call that no longer qualifies by then (a key that was revoked, expired or lost a scope, a creator who was demoted or lost the project and, for a make, a company that was downgraded) is refused and nothing is saved. A change made after that check applies from your next request. When the check cannot be made the answer is 503 with the code key_reach_unavailable and a Retry-After header, and nothing was read or changed.

3.8.2 List the sources a link can credit

GET /tracking-links/sources/v1 needs manage_tracking_links and read_candidates. It lists your company's own sources that are not archived or deleted, in your order, as { "items": [...], "total": n }. Each item has source_type (the code to send when you make or change a link), label (the name), short_tag and colour (a colour or null).

{
  "items": [
    { "source_type": "linkedin", "label": "LinkedIn", "short_tag": "LinkedIn", "colour": null },
    { "source_type": "career_fair", "label": "Career fair", "short_tag": "Career fair", "colour": null }
  ],
  "total": 2
}

This read can write: it can create default sources. That is why it needs the managing scope and not a reading one. A source's name is text people typed, so a key that holds only manage_tracking_links is refused with 403 and is not handed the names. The key is checked again before the default sources are written and again before they are read, and a call that is refused at either check has created nothing.

3.8.3 List your links

GET /tracking-links/v1 needs read_hiring and read_candidates. It answers { "items": [...], "total": n } with the links of the hiring projects the key's creator can open, newest first, at most 2,000. A link for a set of job posts is listed only when that person can open every project of its posts, and the links made in the dashboard for an AI interview or a bundle can be listed too, with address null. Switched-off links are left out unless you send include_disabled=true.

Send each filter once, in its plain spelling (?project_id=<uuid>&include_disabled=true). A bracketed spelling (project_id[]=..., project_id[0]=..., include_disabled[]=..., also percent-encoded) is a 400, never "no filter", and so is a filter sent twice and a query with more than 1,000 parameters.

Each item has the fields of a link (section 3.8.1) and a target: { "title": "...", "available": true }, with job_post_count and job_post_live_count for a set. available is false when what the link opens is gone or its public page would not open (a closed or deleted job post, a switched-off interview), for a job post link whose job post has moved to another hiring project (such a link credits nothing), and when the API could not confirm the job post's project just now (the list is still served). The list does not say who applied; applications_count can say how many.

3.8.4 Change and delete a link

PATCH /tracking-links/{id}/v1 takes label, source_type, source_detail, attributed_person ({ "person_id": "<uuid>" } or null) and enabled (a JSON boolean). Only the fields you send change. null clears label, source_type, source_detail and attributed_person, but a link keeps a person or a source, and source_detail needs a source. "enabled": false stops the link crediting applications at once. Its address is not changed, and the applications it already credited keep their credit. The target, the project and the token never change (a body that names them is a 400). The answer is 200 with the link, and it leaves text out for a key without read_candidates in the same way as a make.

DELETE /tracking-links/{id}/v1 deletes the link and answers 200 with { "id": "...", "deleted": true }. It stops crediting at once, the applications it already credited keep their source, and its token is never reused. To stop a link without losing it, switch it off instead. If two deletes of the same link arrive together, the link is deleted once: one answers 200 and the other 404.

A link that the key's creator cannot reach (a link of a hiring project they do not hold, a set of job posts or the careers page that needs projects they do not hold, an AI interview link they cannot open) answers 404 to a change and to a delete, the same answer as an id nobody has.

3.8.5 Limits, repeats and failures

• Links. A hiring project can hold at most 200 links and your company 2,000 (409). A switched-off link counts; a deleted link frees its place.
• Changes. Making, changing and deleting links together are limited to 30 a UTC minute and 300 a UTC day for your company, across all its keys. Past that the answer is 429 with the code tracking_link_write_limit_reached and a Retry-After header. When this limit cannot be checked just now the answer is 503 with the code tracking_link_write_limit_unavailable, and nothing was changed.
• Reads. The list and the source list together are limited to 30 a UTC minute for your company, across all its keys. Past that the answer is 429 with the code tracking_link_read_limit_reached and a Retry-After header. When the server is already serving as many of these reads as it allows at once, the answer is 429 with the code tracking_link_reads_busy, and nothing is counted against your limit. When the limit cannot be checked just now the answer is 503 with the code tracking_link_read_limit_unavailable and a Retry-After header, and nothing was read.
• The key limit. The limit of 600 requests a minute for each key (section 8.5) applies to these routes too.
• A ban. A key whose holder has been banned is refused with 403 and the code user_banned. When that cannot be checked just now the answer is 503 (no code), and nothing was read or changed.
• No idempotency key. Making a link twice makes two links, and a duplicate can be deleted by its id.
• The 500 codes. internal_error means nothing was made or changed, so send the request again. tracking_link_saved_not_read_back means the link is saved and only the read after it failed: for a change, send the same change again (it answers the link); for a make, do not send it again, because the id is in the message. tracking_link_may_be_saved means the database did not confirm the save, so nobody can say whether it happened. For a change or a delete, send it again: that is safe. For a make, the message carries the id the link would have, and you must look before you make it again. A key that holds read_hiring and read_candidates lists the links with include_disabled=true and looks for the id. Any other key sends PATCH /tracking-links/{id}/v1 with {"enabled": true}, which answers the link, or 404 when the key cannot reach a link with that id (that call counts as one of the 30 changes a UTC minute and switches the link on if somebody had switched it off). If you find the link, it exists. Not finding it proves nothing: the list leaves out, and a change answers 404 for, every link the creator can no longer reach, so making the link again can leave two links.

3.8.6 Errors on these routes

Branch on statusCode and code, never on the wording of message.