> ## Documentation Index > Fetch the complete documentation index at: https://developers.nlpearl.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Voice Pearl > Creates a new voice Pearl: the conversation is driven by a graph of nodes connected by transitions. The graph must contain one OpeningSentence node (or a PreCallAPI leading to one or two OpeningSentence nodes), one EndCall node, and every node must be reachable. Provide exactly one channel: inbound settings OR outbound settings. At least one agent voice is required; to retrieve available voices, use the Get Voices endpoint (GET /v2/Account/Voices). The Pearl is created already published: the configuration you send becomes its live (published) version. For more details, click [here](/api-reference/building_a_flow). ## OpenAPI ````yaml post /v2/Pearl/Voice openapi: 3.0.1 info: title: NLPearl Client API description: A sample API that demonstrates features in the OpenAPI specification version: v2 servers: - url: https://api.nlpearl.ai description: Production Environement security: - bearer_auth: [] tags: - name: Pearl description: >- Manage your Pearls, the AI agents that handle your inbound and outbound calls. Create and configure Pearls, retrieve their details and settings, run or pause them, list and bulk-export their calls, monitor calls in progress, get analytics, and reset a customer's conversation memory. paths: /v2/Pearl/Voice: post: tags: - Pearl summary: Create Voice Pearl description: >- Creates a new voice Pearl: the conversation is driven by a graph of nodes connected by transitions. The graph must contain one OpeningSentence node (or a PreCallAPI leading to one or two OpeningSentence nodes), one EndCall node, and every node must be reachable. Provide exactly one channel: inbound settings OR outbound settings. At least one agent voice is required; to retrieve available voices, use the Get Voices endpoint (GET /v2/Account/Voices). The Pearl is created already published: the configuration you send becomes its live (published) version. For more details, click [here](/api-reference/building_a_flow). requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/AddProjectVoiceApiRequest' text/json: schema: allOf: - $ref: '#/components/schemas/AddProjectVoiceApiRequest' application/*+json: schema: allOf: - $ref: '#/components/schemas/AddProjectVoiceApiRequest' responses: '200': description: The ID of the newly created Pearl. content: text/plain: schema: type: string application/json: schema: type: string text/json: schema: type: string '400': description: Error content: text/plain: schema: $ref: '#/components/schemas/ValidationProblemDetails' application/json: schema: $ref: '#/components/schemas/ValidationProblemDetails' text/json: schema: $ref: '#/components/schemas/ValidationProblemDetails' components: schemas: AddProjectVoiceApiRequest: type: object properties: name: type: string description: The name of the Pearl. nullable: true pearl: allOf: - $ref: '#/components/schemas/AdvancedVoicePearlApi' description: >- Conversation flow (node graph) and agent behavior configuration for the Pearl. nullable: true variables: type: array items: $ref: '#/components/schemas/DataSettingsApi' description: "Variables that can be defined, stored, and used by the agent during conversations.\r\nFor details on variable groups and how to use variables in supported fields, see: [Flow Variables](/api-reference/flow_variables)" nullable: true inbound: allOf: - $ref: '#/components/schemas/InboundVoiceSettingsApi' description: >- Inbound voice settings for the Pearl. Required when creating an inbound Pearl. Must not be provided together with Outbound. nullable: true outbound: allOf: - $ref: '#/components/schemas/OutboundVoiceSettingsApi' description: >- Outbound voice settings for the Pearl. Required when creating an outbound Pearl. Must not be provided together with Inbound. nullable: true additionalProperties: false ValidationProblemDetails: type: object properties: type: type: string nullable: true title: type: string nullable: true status: type: integer format: int32 nullable: true detail: type: string nullable: true instance: type: string nullable: true errors: type: object additionalProperties: type: array items: type: string nullable: true additionalProperties: {} AdvancedVoicePearlApi: type: object properties: agentPersonality: type: string description: >- Defines the agent's personality and tone (for example, more assertive or more calm). Constraints: - Max length: 35 characters. nullable: true timeZone: type: string description: "Time zone identifier used by the Pearl's agents.\r\n \r\nThe agent will operate according to this time zone, regardless of the lead/customer local time zone.\r\nFor accepted values, refer to the [Windows Time Zones list](https://learn.microsoft.com/en-us/windows-hardware/manufacture/desktop/default-time-zones?view=windows-11).\r\n \r\nExample: \"Pacific Standard Time\", \"Romance Standard Time\"." nullable: true modelType: allOf: - $ref: '#/components/schemas/eBrainModelType' description: >+ Agent model type. Voice Pearls use one of these models: - Trident: Default, highest-quality model with standard rate. Optimized for natural, human-like interactions. - Oyster: Most cost-effective model (2 credits cheaper per minute). Straightforward, prioritizes simplicity and efficiency. - Arrow: High-intelligence model with the same depth as Trident, built for ultra-low latency (fastest). Costs 2 credits more per minute. - Hydra: Smartest model, built for demanding tasks that need deeper reasoning. Costs 2 credits more per minute. Text Pearls use: - Swan: the model dedicated to text agents (chat and messaging conversations). It is the only model available for text Pearls. Swan is not available for voice Pearls, and the voice models are not available for text Pearls. `1 - Trident` `2 - Oyster` `3 - Arrow` `4 - Hydra` `11 - Swan` nullable: true companyName: type: string description: "The company name used by the agent during conversations.\r\n \r\nConstraints:\r\n- Max length: 100 characters." nullable: true companyDescription: type: string description: "The company description used by the agent during conversations.\r\n \r\nConstraints:\r\n- Max length: 500 characters." nullable: true generalInstructions: type: string description: "General behavior guidelines applied to the agent across the whole conversation, on top of the\r\nper-node scripts and instructions (for example a tone to keep or rules that always apply).\r\n \r\nConstraints:\r\n- Max length: 2,500 characters.\r\n- Cannot contain variables." nullable: true knowledgeBase: type: string description: "Knowledge base content provided to the agent, such as FAQs, internal context, and operational instructions.\r\n \r\nConstraints:\r\n- Max length: 20,000 characters." nullable: true memory: type: boolean description: >- Indicates whether memory is enabled. When enabled, the Pearl can remember previous conversations for a given phone number. nullable: true successDescription: type: string description: "Description of what makes a conversation successful. Used to evaluate and report the conversation outcome.\r\n \r\nConstraints:\r\n- Max length: 200 characters." nullable: true indicatorTags: type: array items: $ref: '#/components/schemas/CallLabelApi' description: "Indicator tags used to classify conversations (name, description and color).\r\n \r\nConstraints:\r\n- Max entries: 10.\r\n- Colors must be unique across tags." nullable: true nodes: type: array items: $ref: '#/components/schemas/NodeApi' description: "The nodes of the conversation graph. Each node has a unique NodeId and its transitions\r\nreference the NodeId of the target node.\r\n \r\nThe entry point is determined automatically: the PreCallAPI node if present, otherwise the OpeningSentence node.\r\n \r\nConstraints:\r\n- Exactly one OpeningSentence node (or one PreCallAPI leading to one or two OpeningSentence nodes).\r\n- Exactly one EndCall node, and every path must be able to reach it.\r\n- Every non-start node needs at least one incoming transition (except a TransferCall node, which may\r\n be left unwired and is then fired by the agent from its trigger description)." nullable: true agents: type: array items: $ref: '#/components/schemas/AgentConfigToAddApi' description: "Agents configured for the Pearl.\r\n \r\n- Each agent represents a language-specific entry point (based on the selected voice).\r\n- Configure multiple agents to support multilingual experiences and language-based transfers.\r\n \r\nConstraints:\r\n- Voice language must be unique across agents (no duplicates)." nullable: true speechRecognitionKeywords: type: array items: $ref: '#/components/schemas/VocabularyEntry' description: >- Keywords configured to improve speech recognition accuracy (for example product names, acronyms, or domain-specific terms). nullable: true additionalProperties: false description: "Configuration of a voice Pearl: a graph of nodes driven by voice agents (unlike a Simple Pearl, which is\r\ndriven by a single opening sentence and flow script)." DataSettingsApi: type: object properties: id: type: string description: "Variable identifier.\r\n \r\nThis is the ID you must reference when using the variable in scripts and templated fields.\r\nIt must not contain spaces.\r\n \r\nConstraints:\r\n- Max 40 characters.\r\n- Allowed characters: letters (A–Z, a–z), digits (0–9), underscore (_), hyphen (-)." nullable: true name: type: string description: "Friendly display name for the variable.\r\n \r\nMax 40 characters only." nullable: true group: allOf: - $ref: '#/components/schemas/eDataSettingsGroup' description: >+ Variable group. - PreCall: Variables available before the call (used in pre-call contexts such as opening sentence or pre-call API). - InCall: Variables collected or updated during the call. - PostCall: Variables generated after the call by the platform (cannot be created via the API). `1 - PreCall` `2 - InCall` `3 - PostCall` type: allOf: - $ref: '#/components/schemas/eStateDataType' description: |+ `1 - String` `2 - Long` `3 - Double` `4 - Boolean` `5 - DateOnly` `6 - TimeOnly` `7 - DateTime` isList: type: boolean description: >- Indicates whether the variable can contain multiple values (list) or a single value. description: type: string description: "Guidance for the agent on how to collect or infer this variable during the conversation.\r\n \r\nMax 300 characters only." nullable: true value: type: string nullable: true options: type: array items: $ref: '#/components/schemas/OptionChoice' description: "Optional predefined choices for this variable (allowed/preset values).\r\n \r\nNotes:\r\n- Use Value for the human-readable label.\r\n- Use Code for an optional internal/normalized value to store or send to integrations." nullable: true additionalProperties: false InboundVoiceSettingsApi: type: object properties: totalAgents: type: integer description: Total number of agents allocated to this inbound activity. format: int32 transcriptOptions: allOf: - $ref: '#/components/schemas/eTranscriptOptions' description: |+ `1 - FullTranscript` `2 - SensitiveInfoRemoved` `3 - NoTranscript` callWebhookUrl: type: string description: >- Optional webhook URL to receive call events (for example call started and call ended). nullable: true phoneNumberId: type: string description: "The phone number ID to use for this Pearl.\r\nTo retrieve available phone numbers, see: [Get Phone Numbers](/api-reference/v2/pearlSettings/get-phones)\r\n \r\nConstraints:\r\n- A phone number cannot be assigned to more than one active inbound Pearl at the same time." nullable: true recordingOptions: type: boolean description: Enables or disables call recording. isStopRecordingAfterTransferCall: type: boolean description: >- Indicates whether recording should continue after a call is transferred. nullable: true waitingSentence: type: string description: "Message played to the caller when no agent is available and the caller is waiting in the queue.\r\n \r\nMax 300 characters only." nullable: true isSayQueueDetails: type: boolean description: >- When enabled, the caller is informed about queue details (for example how many callers are ahead) while waiting. additionalProperties: false description: Inbound settings of a voice Pearl. OutboundVoiceSettingsApi: type: object properties: totalAgents: type: integer description: Total number of agents allocated to this outbound activity. format: int32 transcriptOptions: allOf: - $ref: '#/components/schemas/eTranscriptOptions' description: |+ `1 - FullTranscript` `2 - SensitiveInfoRemoved` `3 - NoTranscript` budgetTotal: type: integer description: "Total budget allocated for the outbound activity.\r\nIf null, the outbound activity runs without a budget limit." format: int32 nullable: true timeZone: type: string description: "Default time zone for the outbound activity.\r\n \r\nLeads are called according to this time zone unless a lead-specific time zone is provided when adding leads.\r\nFor accepted values, refer to the [Windows Time Zones list](https://learn.microsoft.com/en-us/windows-hardware/manufacture/desktop/default-time-zones?view=windows-11).\r\n \r\nExample: \"Pacific Standard Time\", \"Romance Standard Time\"." nullable: true callingHours: type: array items: $ref: '#/components/schemas/DayWorkingHours' description: Allowed calling hours for the outbound activity. nullable: true callWebhookUrl: type: string description: >- Optional webhook URL to receive call events (for example call started and call ended). nullable: true leadWebhookUrl: type: string description: >- Optional webhook URL to receive lead events (for example lead created/updated). nullable: true phoneNumberId: type: string description: "The phone number ID to use for this Pearl.\r\nTo retrieve available phone numbers, see: [Get Phone Numbers](/api-reference/v2/pearlSettings/get-phones)" nullable: true recordingTrack: allOf: - $ref: '#/components/schemas/eRecordingTrack' description: |+ `1 - Pearl` `2 - Inbound` `3 - Both` `4 - None` isStopRecordingAfterTransferCall: type: boolean description: >- Indicates whether recording should continue after a call is transferred. nullable: true maximumCallAttempts: type: integer description: "Maximum number of call attempts per lead.\r\n \r\nConstraints:\r\n- Max 5 attempts." format: int32 minimumRetryIntervalHours: allOf: - $ref: '#/components/schemas/eMinimumRetryIntervalHours' description: |+ `1 - Every6Hours` `2 - OnceADay` `3 - OnceEvery3Days` `4 - OnceAWeek` `5 - OnceAMonth` `6 - Every3Hours` voiceMail: type: string description: "`🧩 May support variables`\r\n \r\nVoicemail message left when a voicemail/answering machine is detected.\r\nIf empty, the agent will not leave voicemails." nullable: true bypassIVRInstruction: type: string description: "`🧩 May support variables`\r\n \r\nInstructions used to bypass IVR (Interactive Voice Response) systems." nullable: true ringDuration: type: integer description: "Ringing duration (in seconds) before considering the call unanswered.\r\n \r\nConstraints:\r\n- Min 10 seconds.\r\n- Max 50 seconds." format: int32 nullable: true callTimeout: type: integer description: "Maximum call duration (in minutes). The call is ended when this limit is reached.\r\n \r\nConstraints:\r\n- Min 1 minute.\r\n- Max 120 minutes." format: int32 nullable: true additionalProperties: false description: Outbound settings of a voice Pearl. eBrainModelType: type: integer description: >+ Agent model type. Voice Pearls use one of these models: - Trident: Default, highest-quality model with standard rate. Optimized for natural, human-like interactions. - Oyster: Most cost-effective model (2 credits cheaper per minute). Straightforward, prioritizes simplicity and efficiency. - Arrow: High-intelligence model with the same depth as Trident, built for ultra-low latency (fastest). Costs 2 credits more per minute. - Hydra: Smartest model, built for demanding tasks that need deeper reasoning. Costs 2 credits more per minute. Text Pearls use: - Swan: the model dedicated to text agents (chat and messaging conversations). It is the only model available for text Pearls. Swan is not available for voice Pearls, and the voice models are not available for text Pearls. `1 - Trident` `2 - Oyster` `3 - Arrow` `4 - Hydra` `11 - Swan` format: int32 CallLabelApi: type: object properties: id: type: string description: "Identifier of the label.\r\n \r\nIf not provided, it will be generated automatically.\r\n \r\nImportant:\r\n- The ID is the stable identifier of the label.\r\n- Changing the ID creates a new label.\r\n- Keeping the same ID while updating the name/description updates the existing label.\r\n \r\nConstraints:\r\n- Exactly 6 characters.\r\n- Letters only (A–Z, a–z)." nullable: true name: type: string description: "The label name.\r\n \r\nMax 25 characters only." nullable: true description: type: string description: "Describes when this label should be applied.\r\n \r\nMax 250 characters only." nullable: true color: allOf: - $ref: '#/components/schemas/ePredefinedCallLabelColors' description: |+ `1 - purple` `2 - red` `3 - yellow` `4 - green` `5 - blue` `6 - pink` `7 - teal` `8 - lime` `8 - gradient1` `9 - gradient2` additionalProperties: false NodeApi: type: object properties: nodeId: type: string description: "Unique identifier of the node within the flow. Transitions reference this value as their target.\r\nOptional: a node may be authored with only a name, in which case the id is derived from it server-side." nullable: true name: type: string description: Display name of the node. nullable: true nodeType: allOf: - $ref: '#/components/schemas/eNodeTypeApi' description: >+ The type of a node in a Pearl's conversation flow. It determines what the node does and which settings object it carries. - OpeningSentence: the first message the agent sends to start the conversation. - PreCallAPI: an API call executed before the conversation starts (for example a customer lookup). Its transitions use apiResult to branch on success or failure. - Dialogue: a scripted node where the agent converses with the customer. - HandoffChatToHuman: hands the conversation over to a human operator. Text Pearls only. - API: an API call executed during the conversation. - SMS: sends an SMS message. - Email: sends an email. - TransferCall: transfers the call to another phone number. Voice Pearls only. - StartCallRecording: starts recording the call from this point. Voice Pearls only. This node carries no settings. - SearchKnowledgeBase: searches the agent's knowledge base and returns the answer. - EndCall: terminates the conversation. Exactly one per flow, and every path must lead to it. - PostCallActions: a container whose nested actions run after the conversation ends. `2 - OpeningSentence` `3 - PreCallAPI` `10 - Dialogue` `31 - HandoffChatToHuman` `40 - API` `50 - SMS` `51 - Email` `60 - TransferCall` `65 - StartCallRecording` `80 - SearchKnowledgeBase` `100 - EndCall` `200 - PostCallActions` transitions: type: array items: $ref: '#/components/schemas/TransitionApi' description: "Outgoing transitions of the node. Each transition has a name describing the condition that triggers\r\nit and the NodeId of the target node (the transition id is generated server-side from the name).\r\n \r\nOn a PreCallAPI node, every transition must set apiResult (Success or Failure) and must lead to an\r\nOpeningSentence node." nullable: true script: type: string description: "`🧩 May support variables`\r\n \r\nThe script the agent follows while in this node (for OpeningSentence and Dialogue nodes)." nullable: true instructions: type: string description: "`🧩 May support variables`\r\n \r\nFree-form instructions that guide the agent's behavior in this node." nullable: true apiSettings: allOf: - $ref: '#/components/schemas/NodeAPISettingsApi' description: >- API call configuration. Required when the node type is API or PreCallAPI. nullable: true smsSettings: allOf: - $ref: '#/components/schemas/NodeSMSTemplateApi' description: SMS configuration. Required when the node type is SMS. nullable: true emailSettings: allOf: - $ref: '#/components/schemas/NodeEmailTemplateApi' description: Email configuration. Required when the node type is Email. nullable: true transferCallSettings: allOf: - $ref: '#/components/schemas/TransferCallSettingsApi' description: >- Call transfer configuration. Required when the node type is TransferCall (voice Pearls only). nullable: true handOffAction: type: array items: $ref: '#/components/schemas/NodeApi' description: "Notification actions fired when the conversation is handed off to a human. Allowed only on a\r\nHandoffChatToHuman node (text Pearls only).\r\n \r\nEach entry is a node object, with the same fields as the items of `nodes`, whose type is an action:\r\nSMS, Email, or API (with the matching settings object). These nested nodes are fire-and-forget\r\nactions: they cannot have transitions, nor nested lists of their own." nullable: true postCallActions: type: array items: $ref: '#/components/schemas/NodeApi' description: "Actions executed after the conversation ends. Allowed only on a PostCallActions node, which acts as\r\nthe container of these actions and is not connected to the rest of the graph.\r\n \r\nEach entry is a node object, with the same fields as the items of `nodes`, whose type is an action:\r\nSMS, Email, or API (with the matching settings object). These nested nodes are fire-and-forget\r\nactions: they cannot have transitions, nor nested lists of their own." nullable: true additionalProperties: false description: "A node of the Pearl's conversation graph.\r\nThe settings object matching the node type must be provided (for example ApiSettings for an API node).\r\nA StartCallRecording node is the exception: it carries no settings, its presence alone starts the recording." AgentConfigToAddApi: type: object properties: name: type: string description: |- The display name of the agent. Constraints: - Max length: 50 characters. nullable: true voiceId: type: string description: "The ID of the voice to use for this agent.\r\nTo retrieve available voices, see: [Get Voices](/api-reference/v2/pearlSettings/get-voices)\r\n \r\nConstraints:\r\n- The voice language must be unique across agents in the same Pearl (no two agents can use voices from the same language)." nullable: true additionalProperties: false VocabularyEntry: type: object properties: word: type: string description: "The keyword to recognize in speech recognition.\r\n \r\n- Max length: 50 characters." nullable: true pronunciations: type: array items: type: string description: "Alternative pronunciations for the keyword.\r\n \r\nConstraints:\r\n- Max elements: 3.\r\n- Each pronunciation max length: 50 characters." nullable: true additionalProperties: false eDataSettingsGroup: type: integer description: >+ Variable group. - PreCall: Variables available before the call (used in pre-call contexts such as opening sentence or pre-call API). - InCall: Variables collected or updated during the call. - PostCall: Variables generated after the call by the platform (cannot be created via the API). `1 - PreCall` `2 - InCall` `3 - PostCall` format: int32 eStateDataType: type: integer description: |+ `1 - String` `2 - Long` `3 - Double` `4 - Boolean` `5 - DateOnly` `6 - TimeOnly` `7 - DateTime` format: int32 OptionChoice: type: object properties: value: type: string description: "The option value (human-readable label).\r\nIf Code is empty, this value is also used for display." nullable: true code: type: string description: "Optional display/encoded value for the option.\r\nUse this to store a mapped value (for example a normalized code, an internal identifier, or a hex color)." nullable: true additionalProperties: false eTranscriptOptions: type: integer description: |+ `1 - FullTranscript` `2 - SensitiveInfoRemoved` `3 - NoTranscript` format: int32 DayWorkingHours: type: object properties: day: allOf: - $ref: '#/components/schemas/DayOfWeek' description: |+ `0 - Sunday` `1 - Monday` `2 - Tuesday` `3 - Wednesday` `4 - Thursday` `5 - Friday` `6 - Saturday` start: type: string description: "Start time of the allowed calling window (based on the campaign time zone).\r\n \r\nConstraints:\r\n- Must be before End." format: date-span end: type: string description: "End time of the allowed calling window (based on the campaign time zone).\r\n \r\nConstraints:\r\n- Must be after Start." format: date-span additionalProperties: false eRecordingTrack: type: integer description: |+ `1 - Pearl` `2 - Inbound` `3 - Both` `4 - None` format: int32 eMinimumRetryIntervalHours: type: integer description: |+ `1 - Every6Hours` `2 - OnceADay` `3 - OnceEvery3Days` `4 - OnceAWeek` `5 - OnceAMonth` `6 - Every3Hours` format: int32 ePredefinedCallLabelColors: type: integer description: |+ `1 - purple` `2 - red` `3 - yellow` `4 - green` `5 - blue` `6 - pink` `7 - teal` `8 - lime` `8 - gradient1` `9 - gradient2` format: int32 eNodeTypeApi: type: integer description: >+ The type of a node in a Pearl's conversation flow. It determines what the node does and which settings object it carries. - OpeningSentence: the first message the agent sends to start the conversation. - PreCallAPI: an API call executed before the conversation starts (for example a customer lookup). Its transitions use apiResult to branch on success or failure. - Dialogue: a scripted node where the agent converses with the customer. - HandoffChatToHuman: hands the conversation over to a human operator. Text Pearls only. - API: an API call executed during the conversation. - SMS: sends an SMS message. - Email: sends an email. - TransferCall: transfers the call to another phone number. Voice Pearls only. - StartCallRecording: starts recording the call from this point. Voice Pearls only. This node carries no settings. - SearchKnowledgeBase: searches the agent's knowledge base and returns the answer. - EndCall: terminates the conversation. Exactly one per flow, and every path must lead to it. - PostCallActions: a container whose nested actions run after the conversation ends. `2 - OpeningSentence` `3 - PreCallAPI` `10 - Dialogue` `31 - HandoffChatToHuman` `40 - API` `50 - SMS` `51 - Email` `60 - TransferCall` `65 - StartCallRecording` `80 - SearchKnowledgeBase` `100 - EndCall` `200 - PostCallActions` format: int32 TransitionApi: type: object properties: name: type: string description: "`🧩 May support variables`\r\n \r\nThe condition that triggers this transition (for example \"the customer asks for a human agent\").\r\nMust be unique within the node: the transition id is generated from it server-side.\r\nPost-call variables are not allowed here." nullable: true toNodeId: type: string description: The NodeId of the target node. nullable: true apiResult: allOf: - $ref: '#/components/schemas/eTransitionApiResult' description: >+ The outcome of the pre-call API request that fires this transition. Allowed only on the transitions of a PreCallAPI node, where every transition must set it: Success leads to the opening sentence used when the pre-call API succeeds, Failure to the one used when it fails. `1 - Success` `2 - Failure` nullable: true additionalProperties: false description: A transition between two nodes of the conversation graph. NodeAPISettingsApi: type: object properties: name: type: string description: "A friendly name for this API action.\r\n \r\nMax 50 characters only." nullable: true method: allOf: - $ref: '#/components/schemas/APIMethod' description: |+ `1 - GET` `2 - POST` `3 - PUT` `4 - DELETE` `5 - PATCH` endpointUrl: type: string description: "`🧩 May support variables`\r\n \r\nThe endpoint URL to call.\r\n \r\nMax 4,000 characters only.\r\n \r\nVariables support depends on the node: on a PreCallAPI node only pre-call variables are available,\r\nwhile on an API node pre-call and in-call variables are available." nullable: true body: type: array items: $ref: '#/components/schemas/APIDataSchemaPropertyApi' description: "Request body definition (key/value pairs) for this API call.\r\n \r\nConstraints:\r\n- Only applicable for POST, PUT, or PATCH.\r\n- Must be empty for GET, DELETE (and any method that does not send a body)." nullable: true headers: type: object additionalProperties: type: string description: Optional HTTP headers to include in the API request. nullable: true description: type: string description: "A short description of what this API action does.\r\n \r\nMax 150 characters only." nullable: true outputBody: type: array items: $ref: '#/components/schemas/APIDataSchemaPropertyApi' description: "Maps fields of the API response onto flow variables, so the values returned by the API can be used\r\nlater in the conversation." nullable: true credentialId: type: string description: "Optional ID of a credential used to authenticate the API call.\r\nTo retrieve the credentials available to a Pearl, use the Get Pearl Credentials endpoint (GET /v2/Pearl/Credential/{pearlId})." nullable: true additionalProperties: false description: "API call configuration of an API or PreCallAPI node.\r\nThere is no trigger description here: the node runs when a transition leads to it." NodeSMSTemplateApi: type: object properties: body: type: string description: "`🧩 May support variables`\r\n \r\nThe SMS message content.\r\n \r\nConstraints:\r\n- Max 2,000 characters.\r\n- Supports pre-call and in-call variables. Inside a PostCallActions container, post-call variables are also supported." nullable: true additionalProperties: false description: "SMS configuration of an SMS node.\r\nThere is no trigger description here: the node runs when a transition leads to it." NodeEmailTemplateApi: type: object properties: to: type: array items: type: string description: "List of primary recipients.\r\n \r\nConstraints:\r\n- Max 10 recipients.\r\n- Max 255 characters per email address." nullable: true cc: type: array items: type: string description: "List of CC recipients.\r\n \r\nConstraints:\r\n- Max 10 recipients.\r\n- Max 255 characters per email address." nullable: true subject: type: string description: "`🧩 May support variables`\r\n \r\nEmail subject.\r\n \r\nConstraints:\r\n- Max 150 characters.\r\n- Supports pre-call and in-call variables. Inside a PostCallActions container, post-call variables are also supported." nullable: true body: type: string description: "`🧩 May support variables`\r\n \r\nEmail body content.\r\n \r\nConstraints:\r\n- Max 100,000 characters.\r\n- Supports pre-call and in-call variables. Inside a PostCallActions container, post-call variables are also supported." nullable: true smtpSettings: allOf: - $ref: '#/components/schemas/SmtpSettings' description: "Optional SMTP configuration used to send the email.\r\nIf not provided, the email is sent using the default platform email sender." nullable: true additionalProperties: false description: "Email configuration of an Email node.\r\nThere is no trigger description here: the node runs when a transition leads to it." TransferCallSettingsApi: type: object properties: transferCallPhoneNumber: type: string description: "`🧩 May support variables`\r\n \r\nThe destination phone number to transfer the call to.\r\nIf a variable is used, it must resolve to a valid phone number, otherwise the transfer will fail.\r\n \r\nMax 25 characters only." nullable: true triggerDescription: type: string description: "Instructions describing when the agent should transfer the call (for example, when the caller asks to speak with a human).\r\n \r\nMax 500 characters only.\r\n \r\nIn a Simple Pearl, this field is required.\r\nIn a Pearl (node graph), it depends on how the TransferCall node is reached: required when the node\r\nhas no inbound transition (the agent fires the transfer based on this description), and not allowed when\r\nthe node is reached by transitions (the flow decides when the transfer happens)." nullable: true warmTransferMessage: type: string description: "`🧩 May support variables`\r\n \r\nOptional warm transfer message spoken by the agent when the transfer starts.\r\nIf empty, warm transfer is disabled.\r\n \r\nMax 2,000 characters only." nullable: true additionalProperties: false DayOfWeek: type: integer description: |+ `0 - Sunday` `1 - Monday` `2 - Tuesday` `3 - Wednesday` `4 - Thursday` `5 - Friday` `6 - Saturday` format: int32 eTransitionApiResult: type: integer description: >+ The outcome of the pre-call API request that fires this transition. Allowed only on the transitions of a PreCallAPI node, where every transition must set it: Success leads to the opening sentence used when the pre-call API succeeds, Failure to the one used when it fails. `1 - Success` `2 - Failure` format: int32 APIMethod: type: integer description: |+ `1 - GET` `2 - POST` `3 - PUT` `4 - DELETE` `5 - PATCH` format: int32 APIDataSchemaPropertyApi: type: object properties: key: type: string description: "The request body field name (JSON key).\r\n \r\nMax 255 characters only." nullable: true variableId: type: string description: "The variable ID to send as the value for this field (without curly braces).\r\n \r\nConstraints:\r\n- If VariableId is provided, Type and Value must be null/empty." nullable: true type: allOf: - $ref: '#/components/schemas/eStateDataType' description: |+ `1 - String` `2 - Long` `3 - Double` `4 - Boolean` `5 - DateOnly` `6 - TimeOnly` `7 - DateTime` nullable: true value: type: string description: "`🧩 May support variables`\r\n \r\nThe static value to send for this field.\r\n \r\nConstraints:\r\n- Max 255 characters.\r\n- Must be provided together with Type when VariableId is not provided.\r\n- Must not be provided when VariableId is provided.\r\n- When Type is String, the value may include variables using curly braces." nullable: true required: type: boolean description: Indicates whether this request body field is required. additionalProperties: false SmtpSettings: type: object properties: id: type: string description: Optional SMTP configuration identifier. nullable: true provider: allOf: - $ref: '#/components/schemas/EmailProvider' description: |+ `1 - Gmail` `2 - Office365` `10 - Custom` nullable: true smtpServer: type: string description: SMTP server hostname. nullable: true port: type: integer description: SMTP server port. format: int32 nullable: true enableSsl: type: boolean description: Indicates whether SSL/TLS is enabled for the SMTP connection. nullable: true senderEmail: type: string description: >- Sender email address used for SMTP authentication and as the "From" address. nullable: true senderPassword: type: string description: Sender password or SMTP credential used for authentication. nullable: true displayName: type: string description: Display name shown in the recipient inbox (the "From" name). nullable: true additionalProperties: false EmailProvider: type: integer description: |+ `1 - Gmail` `2 - Office365` `10 - Custom` format: int32 securitySchemes: bearer_auth: type: http description: >- Specify the authorization token. For more information, check out the [Authorization Guide](/api-reference/authorization). scheme: bearer ````