Invite candidates

Once you have an interview (interview_def_set_id from Create an interview), there are two ways to get candidates in:

Goal	Use	MCP tool
Get interview URLs back, or send the email invite chain	`POST /job-interview-register-users`	`register_users_for_interview`
Invite people to the merchant (candidates, mentors, teammates)	`POST /invite-users`	`invite_users`

Interview role-plays — the interview-portal variant of a role-play persona — are invited exactly the same way. Pass their interview_def_set_id as the interview_id below; nothing else changes.

Generate links or send invitations

POST /job-interview-register-users handles both, switched by type:

type: "url" — generates a public interview URL (with an embedded JWT) per user. You redirect/send it yourself. No email is sent.
type: "invitation" — also subscribes the user to JobMojito’s email chain (invitation, reminders, and completion notifications).

Build the user list

Each user needs name and email. Optional: external_id (your own id, echoed back) and phone (international E.164 format, e.g. +421903123456) for SMS / WhatsApp notifications. A phone already stored on the candidate is never overwritten.

Call the endpoint

Required fields: interview_id, type, hide_menu, and users.

curl -X POST https://cool.jobmojito.com/functions/v1/job-interview-register-users \
  -H "Authorization: Bearer $SUPABASE_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "interview_id": "9c1b…e4f2",
    "type": "url",
    "hide_menu": false,
    "users": [
      { "name": "Peter Parker", "email": "peter@parker.com", "external_id": "abcd" },
      { "name": "MJ Watson", "email": "mj@example.com" }
    ]
  }'

curl -X POST https://cool.jobmojito.com/functions/v1/job-interview-register-users \
  -H "Authorization: Bearer $SUPABASE_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "interview_id": "9c1b…e4f2",
    "type": "invitation",
    "hide_menu": false,
    "users": [
      { "name": "Peter Parker", "email": "peter@parker.com" }
    ]
  }'

Read the per-user result

The response is an array mirroring your input, with an interview_url, profile_interview_id, and a result per user (ok or Error: …).

[
  {
    "name": "Peter Parker",
    "email": "peter@parker.com",
    "external_id": "abcd",
    "interview_url": "https://…",
    "profile_interview_id": "19bd…bae4",
    "result": "ok"
  }
]

Fields

is_test: true mints test links. They also work on a draft interview (the current questions are compiled first), and the result is flagged as a test. Use it with a uat interview and webhook. See Environments and testing.
SMS / WhatsApp. When the interview’s candidate_notification_channel is set (all, reminders or last_reminder, on job-interview-update), candidates with a phone also receive the invitation and/or reminders by WhatsApp, with SMS as the fallback. Messages are charged at the carrier price (1 credit per €1). This needs a paid plan.

Candidate invitations consume merchant interview credits. Each user is processed independently — one failing user returns an Error: … result for that row while the others still succeed.

Alternative: invite to the merchant

POST /invite-users invites people to the merchant and can attach candidates to an interview. It also supports mentor, merchant, and merchant_owner types.

curl -X POST https://cool.jobmojito.com/functions/v1/invite-users \
  -H "Authorization: Bearer $SUPABASE_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
      { "name": "Peter Parker", "email": "peter@parker.com",
        "type": "candidate", "interview_id": "9c1b…e4f2" }
    ],
    "message_from_recruiter": "We'd love you to complete this short interview."
  }'

For type: "candidate", interview_id is required. Optional: force_invite (resend pending invites), mojito_language_code (defaults en), and message_from_recruiter. Each user comes back with a result such as Invited, Activated, Skipped, or Error: ….

Portal branding

Generate links or send invitations

Fields

Alternative: invite to the merchant

Next steps

Review results

Pre-screen candidates

​Generate links or send invitations

​Fields

​Alternative: invite to the merchant

​Next steps

Review results

Pre-screen candidates

Generate links or send invitations

Fields

Alternative: invite to the merchant

Next steps