Skip to main content

Personas

A persona is a reusable interviewer configuration. It captures who the AI is interviewing for — a role name and an interview language. By default ZenHire generates the interviewer system prompt from a templated v1 prompt, but you may supply your own. You create a persona once and reuse it across every candidate session for that role.

Prompt authoring. Omit system_prompt and ZenHire generates one server-side from the role + language. Supply your own system_prompt to store it verbatim, and optionally a base_prompt_override to customize the behavioral base layer (turn-taking / pacing). Job-description-to-prompt generation is not exposed in v1.

Create a persona​

POST https://platform.zenhire.ai/api/v1/interview/personas

FieldTypeRequiredNotes
role_namestringyesThe role being interviewed for. Max 200 chars. Injected into the generated prompt.
languagestringyesInterview language (engines are multilingual). Max 64 chars. One language per persona.
system_promptstringnoSupply your own interviewer prompt to store verbatim (max 20 000 chars). Omit it to have ZenHire generate one from the v1 template.
base_prompt_overridestringnoOverride the global behavioral base prompt (turn-taking / pacing). Omit or send null to inherit the ZenHire default.
curl -X POST "https://platform.zenhire.ai/api/v1/interview/personas" \
  -H "X-API-Key: zh_api_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "role_name": "Customer Success Manager", "language": "de" }'

Response (HTTP 201):

{
  "id": "0f2c9e2a-7b1d-4a8e-9b3c-1f2a3b4c5d6e",
  "client_id": "9a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "role_name": "Customer Success Manager",
  "language": "de",
  "status": "active",
  "created_at": "2026-05-29T10:00:00.000Z"
}

List personas​

GET https://platform.zenhire.ai/api/v1/interview/personas

Returns the personas owned by your client.

curl "https://platform.zenhire.ai/api/v1/interview/personas" \
  -H "X-API-Key: zh_api_YOUR_KEY"
{
  "data": [
    {
      "id": "0f2c9e2a-7b1d-4a8e-9b3c-1f2a3b4c5d6e",
      "client_id": "9a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
      "role_name": "Customer Success Manager",
      "language": "de",
      "status": "active",
      "created_at": "2026-05-29T10:00:00.000Z"
    }
  ]
}

Get one persona​

GET https://platform.zenhire.ai/api/v1/interview/personas/{personaId}

Returns a single persona including the generated system_prompt. You can only read personas owned by your own client.

{
  "id": "0f2c9e2a-7b1d-4a8e-9b3c-1f2a3b4c5d6e",
  "client_id": "9a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "role_name": "Customer Success Manager",
  "language": "de",
  "system_prompt": "You are an AI interviewer for the role of …",
  "status": "active",
  "created_at": "2026-05-29T10:00:00.000Z",
  "updated_at": null
}

Next​

Start an interview against a persona — see Sessions.