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.

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.
`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...",
    "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