Developer docs

API for HR teams

Send simulation interview invitations by email and pull the score, behavioral assessment, and panel feedback into your existing HR portal. Built for ATS / HRIS integrations — REST over HTTPS, JSON in and out, signed webhooks for completion events.

Quickstart API reference Get API access

Quickstart

Get your API key

Once your team is provisioned, generate a live key from your account settings. Treat it like a password — keep it server-side.

Send an invitation

Call POST /invitations with the candidate’s email and the role context. We send the email; the candidate clicks through and takes the simulation.

Pull the result

When the interview completes, fetch the score and structured assessment via GET /invitations/{id}/result, or subscribe to the webhook to get notified.

Authentication

The API uses bearer-token auth. Pass your API key in the Authorization header on every request:

Authorization: Bearer mga_live_xxxxxxxxxxxxxxxxxxxxxxxx

Test keys (mga_test_*) hit a sandbox that returns deterministic results without sending real emails. Live keys (mga_live_*) consume your interview-minute balance and send real candidate emails.

Base URLhttps://api.meetandgreet.ai/v1

Endpoints

POST/v1/invitations

Send an interview invitation

Creates an invitation and emails the candidate a unique link. The candidate clicks the link, lands on a hosted simulation page, and takes the interview. The invitation moves through pending → started → completed. Your recruiting team can optionally supply its own interview questions via the questions field — the panel works them into the conversation.

Request body

Field	Type	Description
`candidateEmail`required	string	Email address that receives the invitation.
`candidateName`required	string	Used in the email greeting and during the interview.
`role`required	string	Target role the candidate is interviewing for. Max 200 chars.
`jobPosting`required	string	Full job description. Used to generate the panelist mix. Max 2000 chars.
`questions`	string[]	Interview questions your recruiting team wants the panel to ask this candidate. Up to 10 questions, each max 300 chars. The panel weaves them naturally into the conversation alongside its own follow-ups — they are not read out as a fixed script. Omit to let the panel derive all questions from the role and job posting.
`toughness`	integer (1–5)	Difficulty of the panel. Defaults to 3 if omitted.
`durationMinutes`	integer	Interview length. Allowed values: 10, 15, 20, 30, 45, 60. Defaults to 30.
`language`	"en" \| "de"	Locale for both the email and the interview. Defaults to "en".
`expiresAt`	ISO 8601 timestamp	When the invitation link stops working. Defaults to 14 days from creation.
`metadata`	object	Free-form key–value pairs (e.g. ATS req ID). Returned verbatim on result lookups.

Example request

curl -X POST https://api.meetandgreet.ai/v1/invitations \
  -H "Authorization: Bearer mga_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "candidateEmail": "alex@example.com",
    "candidateName": "Alex Chen",
    "role": "Senior Product Manager",
    "jobPosting": "We are hiring a Senior PM to lead our checkout team...",
    "questions": [
      "Walk me through a product launch you led end to end.",
      "How do you prioritize when engineering capacity is cut in half?"
    ],
    "toughness": 3,
    "durationMinutes": 30,
    "language": "en",
    "expiresAt": "2026-06-01T00:00:00Z"
  }'

Response (201 Created)

{
  "id": "inv_01HX2BT8A3JXG5Z3F4WV7QY3K9",
  "status": "pending",
  "candidateEmail": "alex@example.com",
  "candidateName": "Alex Chen",
  "role": "Senior Product Manager",
  "invitationUrl": "https://meetandgreet.ai/invite/abc123XYZ",
  "expiresAt": "2026-06-01T00:00:00Z",
  "createdAt": "2026-05-02T12:00:00Z",
  "metadata": {}
}

GET/v1/invitations/{id}

Get invitation status

Lightweight status lookup — returns the invitation envelope and a one-line summary if the interview has completed. For the full transcript and skill breakdown, use the result endpoint below.

curl https://api.meetandgreet.ai/v1/invitations/inv_01HX2B... \
  -H "Authorization: Bearer mga_live_xxx"

Response (200 OK)

{
  "id": "inv_01HX2BT8A3JXG5Z3F4WV7QY3K9",
  "status": "completed",
  "candidateEmail": "alex@example.com",
  "candidateName": "Alex Chen",
  "role": "Senior Product Manager",
  "createdAt": "2026-05-02T12:00:00Z",
  "startedAt": "2026-05-15T14:00:00Z",
  "completedAt": "2026-05-15T14:30:00Z",
  "summary": "Alex showed strong product judgment and clear communication."
}

GET/v1/invitations/{id}/result

Get full result

Returns the overall score (0–100), the per-skill behavioral breakdown, named strengths and improvement areas, and the full interview transcript. Available only after the invitation reaches completed.

curl https://api.meetandgreet.ai/v1/invitations/inv_01HX2B.../result \
  -H "Authorization: Bearer mga_live_xxx"

Response (200 OK)

{
  "id": "inv_01HX2BT8A3JXG5Z3F4WV7QY3K9",
  "candidateName": "Alex Chen",
  "role": "Senior Product Manager",
  "completedAt": "2026-05-15T14:30:00Z",
  "overallScore": 78,
  "summary": "Strong product judgment and clear narrative under pressure...",
  "skills": {
    "communication":        { "score": 8, "evidence": "..." },
    "structuredThinking":   { "score": 7, "evidence": "..." },
    "problemSolving":       { "score": 7, "evidence": "..." },
    "leadership":           { "score": 6, "evidence": "..." },
    "domainDepth":          { "score": 8, "evidence": "..." },
    "compositeAndPressure": { "score": 7, "evidence": "..." }
  },
  "strengths":    ["Concise framing under tough probing", "..."],
  "improvements": ["Quantify trade-offs more explicitly", "..."],
  "panel": [
    { "name": "Sarah Patel",  "role": "VP Product",  "remark": "..." },
    { "name": "Marcus Hall",  "role": "Eng Lead",    "remark": "..." },
    { "name": "Lena Krause",  "role": "Design Lead", "remark": "..." }
  ],
  "transcript": [
    { "speaker": "interviewer", "name": "Sarah Patel", "text": "..." },
    { "speaker": "candidate",                          "text": "..." }
  ]
}

GET/v1/invitations

List invitations

Paginated list of invitations ordered by createdAt descending. Cursor-based — pass the nextCursor from a previous response to continue.

Query parameters

Field	Type	Description
`status`	"pending" \| "started" \| "completed" \| "expired"	Filter by status.
`limit`	integer (1–100)	Page size. Defaults to 20.
`cursor`	string	Pagination cursor from a previous response.

curl "https://api.meetandgreet.ai/v1/invitations?status=completed&limit=20" \
  -H "Authorization: Bearer mga_live_xxx"

Webhooks

Register an HTTPS endpoint and we’ll POST a JSON event whenever something happens to one of your invitations. Events are signed with HMAC-SHA256; verify the X-MGA-Signature header before trusting the payload.

Event types

Field	Type	Description
`invitation.opened`	event	Candidate clicked the email link and landed on the simulation page.
`interview.started`	event	Candidate began the interview. Minute reservation is now active.
`interview.completed`	event	Interview finished and the result is ready. Payload includes the same shape as /result.
`invitation.expired`	event	Invitation link expired without being used.

Example payload

POST https://your-app.example.com/webhooks/mga
X-MGA-Signature: t=1714659600,v1=ad12c3f7...
Content-Type: application/json

{
  "id": "evt_01HX5RBN...",
  "type": "interview.completed",
  "createdAt": "2026-05-15T14:30:01Z",
  "data": {
    "invitationId": "inv_01HX2BT8A3JXG5Z3F4WV7QY3K9",
    "overallScore": 78,
    "summary": "Strong product judgment ..."
  }
}

Verifying the signature

# Webhook signatures are verified server-side, not over cURL.
# Inspect headers on a webhook delivery:
#   X-MGA-Signature: t=1714659600,v1=abcdef0123...
# and recompute HMAC-SHA256(body, your_webhook_secret).

Errors

Errors return standard HTTP status codes plus a JSON body with a stable code field. Programmatic callers should branch on code; the human message may evolve.

{
  "error": {
    "code": "insufficient_balance",
    "message": "Account does not have enough interview minutes to send this invitation.",
    "param": null,
    "requestId": "req_01HX5S..."
  }
}

Field	Type	Description
`400 invalid_request`	error	Body failed schema validation. Inspect "param" for the offending field.
`401 unauthenticated`	error	Missing or malformed Authorization header.
`403 forbidden`	error	API key is valid but lacks scope (e.g. test key calling a live-only endpoint).
`404 not_found`	error	Resource does not exist or does not belong to your account.
`409 already_completed`	error	Tried to mutate an invitation that has already finished.
`422 insufficient_balance`	error	Account does not have enough interview minutes for the requested duration.
`429 rate_limited`	error	Per-key rate limit hit. Inspect Retry-After header.
`503 generation_failed`	error	Internal LLM call failed or timed out. Safe to retry with idempotency key.

Get API access

The API is currently invite-only. Tell us about your hiring volume and ATS, and we’ll provision a sandbox key, a live key, and a webhook secret so you can wire it into your existing flow.

Request access About MeetandGreet