Most mistakes when driving JobMojito come from using the wrong id in the wrong field. This page is the reference: what each id means, which tool/endpoint returns it, and which field expects it. When you’re unsure which id to pass, come back here rather than guessing.
The same interview lives under three different field names depending on the endpoint (interview_def_set_id, position_id, interview_id), and result endpoints need interview_result_id — not the result row’s id. See The interview id has three names and Result ids below. The key ids
| Id | What it is | Where to get it |
|---|
merchant_id | Which account you’re acting for. | Omit it to act as yourself (taken from your token). To act for a managed account, pick one with jobmojito_configuration / list_my_merchants. Only admins & sub-merchants may override it. |
interview_template_id | The avatar template an interview is based on (voice, look, style). Required to create an interview. | list_avatars (GET /merchant-avatar-list) → each item’s id. |
| interview definition id | The interview / position itself (its questions & config). | Returned as interview_def_set_id when you create one; listed as id by list_interviews (GET /merchant-interview-list). See the three names below. |
| candidate id | A candidate’s enrolment (a “profile interview”). | list_candidates (GET /merchant-candidate-list) → id. (profile_id is the underlying person, rarely needed.) |
interview_result_id | One completed interview attempt / result. | list_interview_results (GET /merchant-result-list) → interview_result_id. |
knowledge_base_store_id | A knowledge base store used to ground question generation. | See Manage a knowledge base. |
The interview id has three names
When you create an interview you get back an interview_def_set_id. That same value is what every “which interview?” field wants — but the field is named differently per endpoint. Don’t be thrown by the different names:
| To do this | Tool | Field to put the interview id in |
|---|
| Read its definition | get_interview_definition (GET /job-interview-get) | position_id |
| Change its state | set_interview_state (POST /job-interview-set-state) | position_id |
| Register / invite candidates | register_users_for_interview (POST /job-interview-register-users) | interview_id |
| Generate a public URL | generate_interview_url (POST /job-interview-token) | interview_id |
| List its results | list_interview_results (GET /merchant-result-list) | interview_id (as a filter) |
position_id and interview_id both accept either an interview-definition id or a position id — for the common case they’re the same value you got back as interview_def_set_id.
Result ids
list_interview_results returns rows with several ids. Use the right one:
interview_result_id — the id you pass to get_interview_result_details (GET /job-interview-details, as the query param interview_result_id) and to generate_interview_report (POST /job-interview-pdf). This is the one you almost always want.id — the position result row id. Not accepted by the detail/report endpoints; don’t use it there.profile_interview_id — the candidate id (same family as list_candidates.id).interview_result_pre_screening_id — the pre-screening result, when present.
Admin app links (build them yourself)
There is no link-building tool. To let a user open something in the JobMojito admin app, construct the URL from the right id and present it as a clickable Markdown link. Base: https://app.jobmojito.com.
| To open | URL | Id to use |
|---|
| A candidate | https://app.jobmojito.com/candidates/{id} | candidate id (list_candidates.id) |
| An interview | https://app.jobmojito.com/interview_creator/{id} | interview definition id |
| A result | https://app.jobmojito.com/interview_results/result/{id} | interview_result_id |
Finding an id when you only have a name
You have two options:
- Ask the API. The list tools accept a
filter_text query parameter — e.g. list_interviews(filter_text="Backend Engineer"), list_candidates(filter_text="peter@…"), list_interview_results(filter_text="…") — then read the id from the matching row (mind which id for results).
- Use the admin UI. In app.jobmojito.com: interviews live under Interview Creator, candidates under Candidates, and completed interviews under Interview Results. Each list has a search box; open the item and its id is the last segment of the page URL (matching the link patterns above).
