Skip to main content
POST
Create agent
Creates an agent — the AI that runs a call — scoped to the API key’s company. An agent holds the voice, the conversation it will have, and what it should extract from it.

​
Overview

An agent conducts the conversation with your contact. Give it a voice, a focus (or a custom flow of your own), the questions it should ask and how to judge the answers. One agent can run any number of conversations.

​
Use Cases

  • Technical Screening: Create agents for technical skill assessments
  • Behavioural screens: Configure agents for soft skills evaluation
  • Culture Fit Assessment: Set up agents to evaluate cultural alignment
  • Initial Screening: Create quick screening agents for high-volume applications

​
Basic Agent Creation

​
Comprehensive Agent Configuration

Note: The duration field is specified in minutes (maximum 180 minutes).

​
Phone Agents

When creating an agent with type: "PHONE", you must provide a valid companyPhoneNumberId. This ID corresponds to a phone number assigned to your company that the agent will use for calls.

​
Background Sound

Use backgroundSound to control the ambient noise played to the contact during calls.

​
Voice Options

  • ALEX (Male)
  • PETER (Male)
  • MIRIAM (Female)
  • SUE (Female)
  • VIERA (Female)
  • CASANDRA (Female)
  • SILVIA (Female)
  • MICHAEL (Male)
  • LUKE (Male)
  • EMMA (Female)
  • SARAH (Female)
  • EVA (Female)

​
Agent Focus

focus sets what kind of call the agent runs. Four are supported, all of them hiring-shaped; for anything else send a flow instead and the agent becomes a custom one with no focus at all:
  • GENERIC: job-optional. The conversation is not about a particular job, so no job assignment is needed — talent-pool building, general outreach, a first call before anyone is matched to a role.
  • SCREENING: a hiring screen, evaluating the contact against a job’s requirements.
  • OUTREACH: a first call to gauge interest and re-engage people already in your database.
  • LANGUAGE_TEST: language proficiency, scored against CEFR.

​
Example with Focus

GENERIC is job-optional: a conversation using focus: "GENERIC" does not need a job, and the contact may hold any number of job assignments — they are simply not used. You may still attach a job explicitly if you want the conversation recorded against one. Custom agents (created with a flow) are jobless rather than job-optional and reject an attached job outright. See the Create Conversation documentation for more details.

​
Speaking for Another Company

By default an agent introduces itself as the company your API key belongs to. If you call on behalf of your own customers, overrides lets each agent speak as one of them instead:
Both fields are optional and each falls back to your own company profile. It works on any agent — template or custom — and is picked up on the next call, with nothing to recompile.
Send both fields together. They fall back independently, so companyName on its own leaves your own company’s description in place — the agent introduces itself as Acme and then describes you. If your company profile has a description, override both.
Only what the agent says changes. The agent still belongs to your company, and billing, analytics and phone-number routing all keep it — as does the address an invitation to a web conversation is sent from. The company named inside that invitation follows the override, so the email and the call that follows it agree. You are responsible for having the right to speak in the name you send.

​
Creating from a Composer Session

If you would rather describe the agent than write a flow, design it first and create it from the session you get back:
That builds exactly the agent the preview showed. Send fields alongside it to override parts of it — { "composerSessionId": "…", "name": "Backend Screen v2" } — or post the preview’s agent object yourself, with the session id attached, if you edited it locally first. Anything you send wins over the preview. While composerSessionId is present, name, type, language and duration are optional: the session already has them.
The design conversation comes with it. The messages that produced the agent are attached to it, so opening that agent in InstaView shows how it was built and lets someone keep editing it by hand.

​
Custom Agents

Instead of picking a focus and a list of questions, you can design the whole conversation yourself by sending a flow. An agent created with a flow is a custom agent: it runs the conversation you designed rather than one of the built-in templates, which is what makes it usable outside hiring — sales outreach, support callbacks, operations checks. A flow is a firstMessage, one or more sections, and a lastMessage. sections is the body of the conversation: every step you can add on the builder canvas is one entry in that array, and its type decides the rest of its shape. Each shape is written out in Section types below.
Do not send focus with a flow. An agent that carries a flow is custom by definition, so its focus is derived — sending both is rejected.
Ids and schemaVersion are assigned by InstaView. Do not send id, defaultBranchId or schemaVersion anywhere in the flow; a request that does is rejected. To give a conditional a fallthrough route, set defaultBranch to the label of the branch it should fall through to. A flow read back from the API contains the assigned ids and version, so strip all three before sending it again — everything you authored, defaultBranch included, comes back as you wrote it, so a stripped flow re-creates the same conversation.
Three optional objects configure a custom agent, and are accepted only together with a flow:
  • guardrails — { "rules": [...] }, things the agent must always or never do (max 50).
  • contextConfig — who the agent is (role, communicationStyle), what the call is for (callToAction), and whether the agent is told what you know about the person it is calling (useContactContext).
  • callConfig — how persistently the agent calls, and when. See Retries and calling hours.
communicationStyle is one of a fixed set — professional, friendly, warm and empathetic, assertive, concise and direct, enthusiastic, casual — the same list the visual builder offers, so an agent created over the API stays editable there.
You do not describe your company here. The description on your company profile is given to every custom agent automatically, and resolved at the moment of each call — so editing the profile reaches the next call without touching a single agent. It also means one agent can call on behalf of several companies and introduce each correctly. To have an agent speak as a different company, use overrides.

​
Telling the agent about the person it is calling

contextConfig.useContactContext gives the agent a short summary of what you hold about each contact, built per call — so one agent serves a whole list and each call is told about the person actually on the line.
It comes in two halves, and the difference is worth knowing when you decide what to store. A short platform-decided set of fields goes into the agent’s prompt, so it is always known. Everything else the contact has a value for is generated into a document the agent can query mid-call, alongside any files on the contact. A prompt line is spent on every call; a document entry costs nothing until the agent looks it up — but it is only used if the agent thinks to look. There is nothing per-field to curate. Define fields, store values, turn the switch on.
The agent is told it may refer to the summary and must not volunteer it unprompted, list what it holds, or explain how it knows. It is also told the summary is data rather than instructions, so a value that reads like a command is ignored.
Fields marked isPii reach neither half. They are excluded from the prompt and from the document, which is what keeps email and phone off every call without anyone deciding. To let one through, set allowPiiInContext on that field and the value joins both. There are cases where that is the point — an amount owed on a collections call — and cases where it is a liability. Nothing turns it on for you.
A contact’s document is generated the first time a context-enabled agent is scheduled to call them, and refreshed before a later call when a value or the catalog has changed. An immediate ad-hoc call for a contact nobody has called before runs prompt-only rather than waiting on it, and the document is ready for the next one.
Off unless set. See List Contact Fields for the catalog, and Update Contact for the values.

​
Section types

Everything the visual builder can put in a conversation is expressed inside sections — the API is not a reduced version of the builder. A section is an object with a type, and type selects which other fields it carries. In the schema reference on the right this is a oneOf on the sections items, which renders collapsed, so the four shapes are written out here in full. label is optional on every section and is only a name for the step; it is what the builder shows on the canvas. id is assigned by InstaView — never send one.

​
sequential — a topic to cover

A step written as a free-text instruction, for when you want the agent to cover something in its own words rather than ask a fixed question. Supports {{contact.*}} variables.

​
looping — a set of questions

A list of questions the agent works through. One block can hold several questions; use separate blocks when you want them in different places in the conversation. question is the only required field. idealAnswer is what a good answer looks like, and it is optional: a question without one is still asked, just never scored. That is how you write a question set with no right answers, such as an internal survey or a satisfaction check. importance and weight are how a question joins the agent’s match score: set either one to score it (REQUIRED gates the score, PREFERRED contributes by weight), and a question with neither is asked but not scored. They sit on the question itself rather than in analyticsConfig because a question is addressed by an id InstaView assigns, which you cannot know while writing the flow.

​
conditional — take a different route

Splits the conversation. The agent evaluates the branches in order and follows exactly one; blocks is the route it then works through. blocks holds sections of any type, including another conditional, which is how you build a decision tree. condition is usually { "type": "intent", "description": "..." } — a plain-language intent the agent reads off the conversation — and may instead be an expression for a deterministic test on an extracted field. defaultBranch is the fallthrough taken when no condition matches, and it addresses the branch by its label, because branch ids are assigned by InstaView. The condition is what the agent routes on, so it has to be one it can read. Every entry in branches must be an object to begin with (CONDITIONAL_BRANCH_NOT_AN_OBJECT), and every branch needs a condition of one of those two shapes: a missing or non-object condition is a 422 (CONDITIONAL_CONDITION_MISSING), a type that is neither intent nor expression is CONDITIONAL_CONDITION_TYPE_UNKNOWN, and a condition of a known type missing what that type needs — an intent without a description, an expression without a field, with an operator outside the documented set, or with no value for an operator other than EXISTS — is CONDITIONAL_CONDITION_INVALID. The path names the branch, e.g. sections[0].branches[1].condition. The condition on the branch you nominate as defaultBranch is checked like any other: it is not read while that branch is the fallthrough, but moving defaultBranch elsewhere later would put it back in charge of a route.

​
human_handoff — hand the call to a person

Ends the agent’s part of the call and transfers it to a phone number. phoneNumber is required and must be E.164 (+, country code, no spaces or dashes) and a real number for that country: the right length and leading digits for its numbering plan, so +42190012345, a Slovak mobile one digit short, is rejected even though it has the E.164 shape. Either problem is a 422 with HUMAN_HANDOFF_INVALID_NUMBER on the block. A number the dialler could not use is rejected at design time rather than at the moment of transfer. message is the line the caller hears as the call is transferred to this number, and it is optional — omit it and InstaView supplies a neutral line in the call’s language. That default says only that a transfer is happening: the block knows a number and nothing else, so it cannot claim who picks up. Send a message when you do know. It supports {{contact.*}} and {{system.*}} variables like any other text in a flow. A message that resolves to nothing on a call, because it held only variables and none had a value, falls back to the neutral line, so the transfer is never silent. Sending message as an empty string is rejected rather than treated as absent, so clearing the field cannot silently give you the default back. Write message so it is true on every transfer to this number. A caller who asks for a person before the flow reaches this step can be transferred here too, and hear this line. Describe the transfer (“I’ll put you through to our sales team now”) rather than what came before it (“Your card is blocked now, I’ll put you through”). Anything the agent should say only at this point of the flow belongs in the step before the handoff. The agent says that step in a turn of its own and transfers once the caller has responded, so a spoken step before a handoff adds one exchange to the call. The transfer itself carries no words but message. Blocks that share a phoneNumber share one line. A number has a single line, taken from the first handoff block that names it, reading the flow top to bottom with each branch in order. It is heard on every transfer to that number, including one made at a later block. A later block’s message is never heard. If the first block has no message, the neutral line is used even when a later block has one. To give a number a line of your own, put it on the first block that names the number.
A handoff block also changes what happens when somebody asks for a person away from that step. Every agent carries a standing rule for “can I speak to a human?”; on a flow with no handoff it says a colleague will be in touch and ends the call, and on a flow that has one it transfers instead, wherever in the conversation the request comes. Where it can, the agent chooses the destination by label, and the caller can then hear that number’s line: the message of the first block that names it, or the neutral line if that block has none. That is why a message has to make sense away from its step.
The transfer is final, and it is the end of the conversation. InstaView hands the call to the carrier and leaves it (a cold transfer), so the agent does not come back: nothing after a human_handoff ever runs, including your lastMessage. The conversation settles as completed with the call recorded as forwarded, and the transcript covers your agent’s part of the call only — what the two people then say to each other is not ours to record.Because such a step could never run, a handoff must be the last block in its own list, and a sibling after it is rejected with HUMAN_HANDOFF_NOT_LAST. That is scoped to immediate siblings: a handoff ending one branch of a conditional says nothing about the sections after that conditional, which the other branches still reach.
PHONE agents only. An ONLINE agent has no call to transfer, so a flow carrying a handoff is rejected with a 422 (HUMAN_HANDOFF_NOT_PHONE) rather than creating an agent with a step that could never fire.
A handoff may sit inside a conditional branch, which is the useful shape: route on intent, then transfer to the number that fits. Two branches transferring to the same number are one destination, not two — handoffs are deduplicated by number.
A flow that can reach two numbers needs a label on every handoff, and they must differ. The agent is offered all reachable destinations at once and chooses between them by label — the number is deliberately never in its prompt — so two destinations described alike would make the choice a coin flip that lands a caller on the wrong team. Missing labels are HUMAN_HANDOFF_LABEL_REQUIRED and a collision is HUMAN_HANDOFF_LABEL_DUPLICATE. A single-destination flow needs no label: there is nothing to tell apart. Two blocks pointing at the same number are one destination, so they may share a label, or go without one.
There is no fallback number. Once the carrier has the call InstaView is no longer on it, so nothing can notice that the destination was busy and try a second one. “Try sales, otherwise support” is a conditional the agent routes on while it still has the call, not a property of the handoff.

​
Limits

Exceeding any of these is rejected with 422.
These four types are the whole set. The schema reserves nothing beyond them, so any other value in type is simply an unknown block: it comes back as UNKNOWN_BLOCK_TYPE in the errors array, alongside every other fault in the document.A type may still be added to the schema before it works, and while it is in that state sending one is rejected with a 422 naming the block and the types you may use instead. That list is generated from what is actually built, so it is the authoritative answer to what a section may be at any given moment.

​
Flow Validation Errors

The flow is validated when you create the agent, using the same rules as the visual builder — an invalid flow is rejected with 422, rather than failing later when a call is placed. The rejection carries an errors array with every problem found in the document, so fixing a flow does not take one request per fault. Each entry has a machine-readable code and the path of the offending node in the flow you sent, which is what to anchor an editor or an error list to.
Match on the codes you handle, and fall back on message for the rest. The set of codes grows as the flow schema does, and a new one is added without a major version.
path is the anchor, and the only one. Block ids are assigned by InstaView when a flow is stored, so a flow that was just rejected has none to report — errors address the document you sent, by position.
Not every 422 on this route is a flow-validation failure — one of the size limits above, a block type that is not available yet, or a companyPhoneNumberId that is not yours, is also a 422. Those carry a message and no errors array, so treat errors as optional:
The same 422 shape is returned by Update Agent and by an inline agent on Create Conversation.

​
Analytics

analyticsConfig says what should come back after every call. Without it a custom agent places a call and returns a transcript; with it you get structured data your own systems can act on. Like guardrails and contextConfig, it is accepted only alongside a flow.

​
Keys are yours

Every item has a key — the name its results come back under. Set it if your integration reads results by name. A key you choose is stable; a derived one is not:
  • Omit key and InstaView derives a slug of label (Budget confirmed → budget_confirmed). Convenient, but renaming the label later silently moves the results to a new key, and your consumer breaks with a 200. Two labels that slug to the same thing get a numeric suffix — Budget and Budget? become budget and budget_2, in the order you listed them.
  • Send key and it is used verbatim, whatever you do to the label afterwards. Letters, digits and underscores, up to 64 characters, unique within its list — a duplicate you sent is rejected with 400 rather than quietly renamed, and __proto__, constructor and prototype are refused because they cannot be used as field names in the results.
Editing the agent in the visual builder re-derives each key from its label, so a key you chose over the API can be replaced by someone editing that agent in the UI.

​
Scoring a flow question

Questions join the match score inline, on the question itself — not through analyticsConfig:
Only the first question is scored. The second carries an idealAnswer but no importance or weight, so it stays out of the score — nothing is scored that you did not ask for. The third has no idealAnswer at all, so it cannot be scored even if you set importance on it.
This is inline for the same reason ids are assigned by us: a question is addressed by an id InstaView mints, which you cannot know while writing the flow. Reading the agent back returns the same inline form, so a round-trip works.
Weights are relative, not a budget — 50 / 30 / 20 and 5 / 3 / 2 score identically. Results report each item’s share as a percentage. The results arrive as analytics on the conversation (Get Conversation) and on the analysis.completed webhook.

​
Retries and calling hours

callConfig answers two questions: how many times a contact who does not answer is called, and when the agent is allowed to dial. Omit callConfig and a new agent calls Mon–Fri, 09:00–18:00, in each contact’s own timezone, three attempts each.

​
Whose 09:00?

timezoneAnchor.mode is either contact or fixed. With contact, the contact’s timezone is detected from their phone number, down to the area code — not from their country. On one list, a +1 212 number is called at 09:00 in New York, a +1 310 number at 09:00 in Los Angeles, and a +1 602 number at 09:00 in Phoenix, which does not observe daylight saving at all. The same holds inside any country that spans zones: +7 4212 is Vladivostok rather than Moscow, +55 92 is Manaus rather than São Paulo, +52 664 is Tijuana rather than Mexico City.
With fixed, every contact is called on one named IANA zone, wherever they are — the right choice when the hours belong to your own operation rather than to the person being called.
A timezone is validated against the runtime’s own timezone database, so a plausible-looking but nonexistent zone is a 422 on this request rather than a schedule that quietly never fires.
Some prefixes cover more than one timezone. An Australian +61 8 number could be in Adelaide or Perth, up to two hours apart, and a phone number cannot tell you which. In that case the agent waits until the hours you set are correct in every contact’s zone rather than picking one — so an uncertain contact is called a little later, never two hours too early. timezoneAnchor.fallbackTimezone (default Europe/Bratislava) covers the rarer case where a number resolves to no timezone at all.
A narrow window over a wide prefix can leave no valid moment at all. Requiring the hours to be correct in every contact’s zone means a short window over zones far enough apart never lines up: 09:00–10:00 cannot be true in both Adelaide and Perth at once. When that happens the contact is called anyway rather than left uncalled indefinitely, and the call is recorded as having gone out outside the window. Widening the window, or pinning the anchor to fixed, is how you avoid it.
Retries land inside the same window, so a contact is never called back outside the hours you set.
A time you name yourself is not moved. The window bounds the times we choose: when a conversation created with no scheduleTime goes out, and every retry after a call that did not connect. Pass a scheduleTime on POST /conversations, or a time on either call-attempt route, and the call is placed then even if the window is shut, because you have told us something the window cannot know. If you would rather your window always won, keep sending times inside it: an appointment your contact agreed to is usually the case where you want the override, and a bulk import is usually the case where you want to omit scheduleTime and let the window place the call.

​
Agents created before calling windows existed

An agent from before this was configurable reports a callWindow.mode of business_hours and no other window fields:
That is a legacy preset meaning Mon–Fri, 08:00–20:00, in the contact’s own timezone — the hours those agents were already being called within, so nothing about their dialling changed when calling windows shipped. You cannot select it; sending a callWindow is how such an agent is moved onto a real one.
Those hours are not a new restriction and not a widening. Before agents carried a window, the hours were attached to the phone number instead, and every number was created with exactly this schedule. The preset reproduces it so that migrating changes nothing you can observe. The practical difference between it and a window you set yourself is that you cannot edit it, and that its timezone anchor is fixed to the contact.

​
Contact Variables

Any text in a flow — messages, prompts, questions — may contain {{contact.<key>}} placeholders. They are not filled in when you create the agent: the agent is compiled once and the placeholders are resolved per call, so one agent serves every person you call. Seven keys are always available. The first four come from the contact on the conversation; the rest come from your company profile and the agent itself:
{{contact.company_name}} is your company, not theirs. It resolves from the company placing the call, so "I see you work at {{contact.company_name}}" is a fluent sentence that is wrong on every single call, and nothing rejects it. The contact’s own employer is an ordinary catalogued field — organization in the default catalog — set per contact like any other.
You can add your own. Send them as fields when you create the contact, then reference them by key:
Keys are a-z, 0-9 and _, and each one has to be a field in your company’s catalog — read GET /contact-fields for the ones you have, or pass ?createMissingFields=true on the contact write to have a new key defined for you. A key with no value resolves to an empty string rather than being spoken aloud, so a missing variable degrades quietly — but write prompts that still read correctly without it. The seven system keys above are reserved: sending one in fields is a 422 naming the key, not a write that quietly does nothing. first_name, last_name, email and phone are set through their own properties on the contact; the other three are resolved by the platform and cannot hold a per-contact value at all.

​
{{contact.profile}}

An eighth reserved key exists and is deliberately not in the table above. {{contact.profile}} is the whole rendered summary of what we know about the contact — the block contextConfig.useContactContext puts in the agent’s prompt, a paragraph rather than a value. The agent is given it on its own when that switch is on, so there is nothing to gain by writing the token, and putting it in a message or a prompt makes the agent read that paragraph out loud. Like the other reserved keys it cannot hold a per-contact value: sending profile in fields is a 422.

​
System Variables

A second namespace, {{system.<key>}}, is filled from the platform’s clock rather than from the contact. It works anywhere {{contact.*}} does and needs no setup:
The timezone is derived from the contact’s phone number, falling back to UTC when the number resolves to none. Every agent is separately told the current date and time whether or not it uses these, so reach for them only when a line has to state a date or a day.
A key with no value resolves to nothing, in both namespaces. The placeholder disappears from the line — it is never read out as a token, and the agent is never told a value was missing. So "Am I through to {{contact.organization}}?" is spoken as "Am I through to?" for a contact with no organisation. The agent is instructed to reword around the hole, but the reliable fix is to write the sentence so it survives losing the value: put the token where it can be dropped, or ask instead of asserting.

​
Company Scoping

Agents are automatically scoped to your API key’s company. You can only access and use agents that belong to your company. ATS keys can access agents from companies they manage by specifying the companyId query parameter.

Agents Resource Guide

Learn about agent configuration and best practices

Conversations Resource Guide

See how a conversation uses an agent

API Reference

List and manage your agents

Authorizations

​
Authorization
string
header
required

API key for authentication using Bearer scheme

Query Parameters

​
companyId
string

Required for ATS API keys to specify which company to access. Ignored for standard company API keys.

Body

application/json
​
composerSessionId
string<uuid>
required

Create this agent from a composer session (POST /agents/composer). Send it alone to build exactly what the preview showed, or alongside your own fields to override parts of it — anything you send wins. The session's conversation is attached to the new agent. While it is present, name, type, language and duration are optional: the session already has them.

Example:

"9f8c1d2e-4b7a-4c3d-9e1f-2a5b6c7d8e90"

​
name
string

Agent name

Required string length: 2 - 100
Example:

"Senior Developer Phone Screen"

​
type
enum<string>

Type of the agent

Available options:
UNDEFINED,
ONLINE,
PHONE
Example:

"ONLINE"

​
focus
enum<string>

Focus of the agent. GENERIC: job-optional, for a conversation that is not about a particular job. SCREENING: a hiring screen against a job's requirements. OUTREACH: a first call to gauge interest. LANGUAGE_TEST: language proficiency. Required unless a conversation flow is provided: an agent with a flow is a custom agent, whose focus is derived rather than selected. Sending both is rejected.

Available options:
GENERIC,
SCREENING,
OUTREACH,
LANGUAGE_TEST
Example:

"SCREENING"

​
language
enum<string>

Language of the conversation

Available options:
UNDEFINED,
EN,
JA,
ZH,
DE,
HI,
FR,
KO,
PT,
IT,
ES,
ID,
NL,
TR,
FIL,
PL,
SV,
BG,
RO,
AR,
CS,
EL,
FI,
HR,
MS,
SK,
DA,
TA,
UK,
RU,
HU,
NO,
VI
Example:

"EN"

​
duration
number

Duration of the conversation in minutes

Required range: 1 <= x <= 180
Example:

30

​
questions
string[]

List of questions for the conversation

Example:
​
instructions
string

Additional instructions for the conversation. Compiled into the agent's prompt as its own reference section, for a CUSTOM (flow) agent as well as a template one, so this is where reference material the agent must state accurately belongs: prices, stock, lead times, opening hours, policy.

Example:

"Focus on communication skills and team fit"

​
voiceId
enum<string>

Voice ID the agent speaks with

Available options:
ALEX,
PETER,
MIRIAM,
SUE,
VIERA,
CASANDRA,
SILVIA,
MICHAEL,
LUKE,
EMMA,
SARAH,
EVA
​
companyPhoneNumberId
string<uuid>

ID of the company phone number assignment to use for calls from this agent (CompanyPhoneNumber.id)

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
metadata
object

Custom metadata for the agent (max 10KB, 5 levels deep, 50 keys)

Example:
​
cefrLevel
enum<string>

CEFR level for language test agents

Available options:
A1,
A2,
B1,
B2,
C1,
C2
Example:

"B1"

​
backgroundSound
enum<string>

Ambient background sound during calls (OFFICE or OFF). Defaults to OFFICE when omitted.

Available options:
OFF,
OFFICE
Example:

"OFFICE"

​
flow
object

Conversation flow graph. Providing it makes this a custom agent, so focus must be omitted. guardrails and contextConfig are accepted only alongside a flow. Validated on write: an invalid flow is rejected with 422 rather than failing when a call is placed.

​
guardrails
object

Rules the agent must obey during the call. Accepted only alongside a flow — sending it for an agent that will not be custom is rejected.

​
contextConfig
object

Who the agent is and what the call is about. Accepted only alongside a flow — sending it for an agent that will not be custom is rejected.

​
analyticsConfig
object

What to extract, score, decide and label after every call. Accepted only alongside a flow — sending it for an agent that will not be custom is rejected. Per-question scoring is set inline on the flow's looping questions, not here.

​
callConfig
object

How persistently and when the agent calls: how many attempts a contact who does not answer gets, and the days, local hours and timezone the agent may dial in. Accepted only alongside a flow. Omitted, a new agent calls Mon–Fri 09:00–18:00 in each contact's own timezone.

​
overrides
object

Who this agent says it is on a call. By default it introduces itself as the company your API key belongs to; send this to have it speak for one of your own customers instead. Unlike guardrails and contextConfig, this is accepted with or without a flow.

Response

​
id
string<uuid>
required

Agent ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
name
string
required

Agent name

Example:

"Frontend Developer Interview"

​
type
enum<string>
required

Type of the agent

Available options:
UNDEFINED,
ONLINE,
PHONE
Example:

"ONLINE"

​
focus
enum<string>
required

Focus of the agent. GENERIC: job-optional, for a conversation that is not about a particular job. SCREENING: a hiring screen against a job's requirements. OUTREACH: a first call to gauge interest. LANGUAGE_TEST: language proficiency.

Available options:
GENERIC,
SCREENING,
OUTREACH,
LANGUAGE_TEST
Example:

"SCREENING"

​
language
enum<string>
required

Language of the conversation

Available options:
UNDEFINED,
EN,
JA,
ZH,
DE,
HI,
FR,
KO,
PT,
IT,
ES,
ID,
NL,
TR,
FIL,
PL,
SV,
BG,
RO,
AR,
CS,
EL,
FI,
HR,
MS,
SK,
DA,
TA,
UK,
RU,
HU,
NO,
VI
Example:

"EN"

​
duration
number
required

Duration of the conversation in minutes

Example:

30

​
createdAt
string<date-time>
required

Agent creation timestamp (UTC)

Example:

"2025-11-20T10:30:00Z"

​
updatedAt
string<date-time>
required

Agent last update timestamp (UTC)

Example:

"2025-11-20T10:30:00Z"

​
questions
string[]

List of questions for the conversation

Example:
​
instructions
string

Additional instructions for the conversation. Compiled into the agent's prompt as its own reference section, for a CUSTOM (flow) agent as well as a template one, so this is where reference material the agent must state accurately belongs: prices, stock, lead times, opening hours, policy.

Example:

"Focus on technical skills and previous project experience"

​
voiceId
enum<string>

Voice ID the agent speaks with

Available options:
ALEX,
PETER,
MIRIAM,
SUE,
VIERA,
CASANDRA,
SILVIA,
MICHAEL,
LUKE,
EMMA,
SARAH,
EVA
​
companyId
string<uuid>

Company ID that owns the agent

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
metadata
object

Custom metadata

Example:
​
cefrLevel
enum<string>

CEFR level for language test agents

Available options:
A1,
A2,
B1,
B2,
C1,
C2
Example:

"B1"

​
backgroundSound
enum<string> | null

Ambient background sound during calls (OFFICE or OFF). Null means no override is set and the default applies.

Available options:
OFF,
OFFICE
Example:

"OFFICE"

​
flow
object | null

Conversation flow graph, as designed. Null on a template agent.

​
guardrails
object | null

Rules the agent must obey during the call. Custom agents only; null on a template agent.

​
contextConfig
object | null

Who the agent is and what the call is about. Custom agents only; null on a template agent.

​
analyticsConfig
object | null

What the agent extracts, scores, decides and labels after every call. Custom agents only — null on a template agent. Per-question scoring is folded back onto the flow's looping questions rather than returned as an id-keyed map — the same form the write accepts.

​
callConfig
object

How persistently and when the agent calls. Custom agents only. An agent created before calling windows were configurable reports a callWindow.mode of business_hours.

​
overrides
object | null

Who this agent says it is on a call, when that is not the company your API key belongs to. Null when it speaks as your own company.