---
title: "Create Pearl"
method: POST
path: "/v2/Pearl"
tags: ["Pearl"]
---

# Create Pearl

`POST /v2/Pearl`

Creates a new Simple Pearl, driven by an opening sentence and a flow script. Provide exactly one channel: inbound settings OR outbound settings. The Pearl is created already published: the configuration you send becomes its live (published) version. To create a Pearl (node graph), use Create Voice Pearl or Create Text Pearl instead.

## Request body

- AddProjectApiRequest — Create Pearl request (simple mode): a voice Pearl driven by an opening sentence and a flow script.
  - `name` string, nullable — The name of the Pearl.
  - `pearl` PearlSettingsApi
    - `agents` AgentConfigToAddApi[], nullable — Agents configured for the Pearl. - Each agent represents a language-specific entry point (based on the selected voice). - Configure multiple agents to support multilingual experiences and language-based transfers. Constraints: - Voice language must be unique across agents (no duplicates).
      - `name` string, nullable — The display name of the agent. Constraints: - Max length: 50 characters.
      - `voiceId` string, nullable — The ID of the voice to use for this agent. To retrieve available voices, see: [Get Voices](/api-reference/v2/pearlSettings/get-voices) Constraints: - The voice language must be unique across agents in the same Pearl (no two agents can use voices from the same language).
    - `agentPersonality` string, nullable — Defines the agent's personality and tone (for example, more assertive or more calm). Constraints: - Max length: 35 characters.
    - `timeZone` string, nullable — Time zone identifier used by the Pearl's agents. The agent will operate according to this time zone, regardless of the lead/customer local time zone. For 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). Example: "Pacific Standard Time", "Romance Standard Time".
    - `modelType` integer — 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`
    - `companyName` string, nullable — The company name used by the agent during conversations. Constraints: - Max length: 100 characters.
    - `companyDescription` string, nullable — The company name used by the agent during conversations. Constraints: - Max length: 500 characters.
    - `knowledgeBase` string, nullable — Knowledge base content provided to the agent, such as FAQs, internal context, and operational instructions. Constraints: - Max length: 20,000 characters.
    - `memory` boolean, nullable — Indicates whether memory is enabled. When enabled, the Pearl can remember previous conversations for a given phone number.
    - `speechRecognitionKeywords` VocabularyEntry[], nullable — Keywords configured to improve speech recognition accuracy (for example product names, acronyms, or domain-specific terms). Constraints: - Max entries: 10.
      - `word` string, nullable — The keyword to recognize in speech recognition. - Max length: 50 characters.
      - `pronunciations` string[], nullable — Alternative pronunciations for the keyword. Constraints: - Max elements: 3. - Each pronunciation max length: 50 characters.
    - `openingSentence` string, nullable — `🧩 May support variables` The opening sentence spoken by the agent when a conversation starts. Constraints: -Max 500 characters only. -Supports pre-call variables only.
    - `flowScript` string, nullable — `🧩 May support variables` The flow script the agent follows to drive the conversation. Constraints: - Max 20,000 characters. - Supports pre-call variables and in-call variables.
    - `transferCallSettings` TransferCallSettingsApi[], nullable — Call transfer rules configured for the Pearl (when and where calls should be transferred). Constraints: - Max rules: 10.
      - `transferCallPhoneNumber` string, nullable — `🧩 May support variables` The destination phone number to transfer the call to. If a variable is used, it must resolve to a valid phone number, otherwise the transfer will fail. Max 25 characters only.
      - `triggerDescription` string, nullable — Instructions describing when the agent should transfer the call (for example, when the caller asks to speak with a human). Max 500 characters only. In a Simple Pearl, this field is required. In a Pearl (node graph), it depends on how the TransferCall node is reached: required when the node has no inbound transition (the agent fires the transfer based on this description), and not allowed when the node is reached by transitions (the flow decides when the transfer happens).
      - `warmTransferMessage` string, nullable — `🧩 May support variables` Optional warm transfer message spoken by the agent when the transfer starts. If empty, warm transfer is disabled. Max 2,000 characters only.
    - `smsSettings` SMSTemplateApi[], nullable — SMS templates and triggers configured for the Pearl. During a call, the agent can send SMS messages based on these rules. Constraints: - Max templates: 10.
      - `body` string, nullable — `🧩 May support variables` The SMS message content. Constraints: - Max 2,000 characters. - Supports pre-call and in-call variables. - If sent at end of call, may also support post-call variables.
      - `triggerDescription` string, nullable — Instructions describing when the SMS should be sent (trigger conditions). Max 500 characters only.
    - `emailSettings` EmailTemplateApi[], nullable — Email templates and triggers configured for the Pearl. During a call, the agent can send emails based on these rules. Constraints: - Max templates: 10.
      - `subject` string, nullable — `🧩 May support variables` Email subject. Max 150 characters only.
      - `body` string, nullable — `🧩 May support variables` Email body content. Max 100,000 characters only.
      - `triggerDescription` string, nullable — Instructions describing when the email should be sent (trigger conditions). Max 500 characters only.
      - `smtpSettings` SmtpSettings
        - `id` string, nullable — Optional SMTP configuration identifier.
        - `provider` integer — `1 - Gmail` `2 - Office365` `10 - Custom`
        - `smtpServer` string, nullable — SMTP server hostname.
        - `port` integer, nullable — SMTP server port.
        - `enableSsl` boolean, nullable — Indicates whether SSL/TLS is enabled for the SMTP connection.
        - `senderEmail` string, nullable — Sender email address used for SMTP authentication and as the "From" address.
        - `senderPassword` string, nullable — Sender password or SMTP credential used for authentication.
        - `displayName` string, nullable — Display name shown in the recipient inbox (the "From" name).
    - `apiSettings` APISettingsApi[], nullable — API actions configured for the Pearl. Constraints: - Max actions: 10.
      - `name` string, nullable — A friendly name for this API action. Max 50 characters only.
      - `method` integer — `1 - GET` `2 - POST` `3 - PUT` `4 - DELETE` `5 - PATCH`
      - `endpointUrl` string, nullable — `🧩 May support variables` The endpoint URL to call. Max 4,000 characters only. Variables support depends on when this API action is executed: - Pre-call: pre-call variables only. - In-call: pre-call and in-call variables. - End-call: pre-call, in-call, and post-call variables.
      - `body` APIDataSchemaPropertyApi[], nullable — Request body definition (key/value pairs) for this API call. Constraints: - Only applicable for POST, PUT, or PATCH. - Must be empty for GET, DELETE (and any method that does not send a body).
        - `key` string, nullable — The request body field name (JSON key). Max 255 characters only.
        - `variableId` string, nullable — The variable ID to send as the value for this field (without curly braces). Constraints: - If VariableId is provided, Type and Value must be null/empty.
        - `type` integer — `1 - String` `2 - Long` `3 - Double` `4 - Boolean` `5 - DateOnly` `6 - TimeOnly` `7 - DateTime`
        - `value` string, nullable — `🧩 May support variables` The static value to send for this field. Constraints: - Max 255 characters. - Must be provided together with Type when VariableId is not provided. - Must not be provided when VariableId is provided. - When Type is String, the value may include variables using curly braces.
        - `required` boolean — Indicates whether this request body field is required.
      - `headers` object, nullable — Optional HTTP headers to include in the API request.
      - `triggerDescription` string, nullable — Describes when this API action should be triggered. Max 1,000 characters only.
      - `description` string, nullable — A short description of what this API action does. Max 150 characters only.
      - `outputBody` APIDataSchemaPropertyApi[], nullable — Maps fields of the API response onto flow variables, so the values returned by the API can be used later in the conversation.
        - `key` string, nullable — The request body field name (JSON key). Max 255 characters only.
        - `variableId` string, nullable — The variable ID to send as the value for this field (without curly braces). Constraints: - If VariableId is provided, Type and Value must be null/empty.
        - `type` integer — `1 - String` `2 - Long` `3 - Double` `4 - Boolean` `5 - DateOnly` `6 - TimeOnly` `7 - DateTime`
        - `value` string, nullable — `🧩 May support variables` The static value to send for this field. Constraints: - Max 255 characters. - Must be provided together with Type when VariableId is not provided. - Must not be provided when VariableId is provided. - When Type is String, the value may include variables using curly braces.
        - `required` boolean — Indicates whether this request body field is required.
      - `credentialId` string, nullable — Optional ID of a credential used to authenticate the API call. To retrieve the credentials available to a Pearl, use the Get Pearl Credentials endpoint (GET /v2/Pearl/Credential/{pearlId}).
    - `successDescription` string, nullable — Definition of what is considered a successful call for this Pearl. This is used to classify call outcomes as successful or not successful. If left empty, calls will only be marked as completed (no success classification). Max 200 characters only.
    - `indicatorTags` CallLabelApi[], nullable — Indicator labels that can be applied to calls for classification and reporting. At the end of the conversation, an AI analyzes the call and determines which of the configured labels should be applied. Constraints: - Max labels: 10.
      - `id` string, nullable — Identifier of the label. If not provided, it will be generated automatically. Important: - The ID is the stable identifier of the label. - Changing the ID creates a new label. - Keeping the same ID while updating the name/description updates the existing label. Constraints: - Exactly 6 characters. - Letters only (A–Z, a–z).
      - `name` string, nullable — The label name. Max 25 characters only.
      - `description` string, nullable — Describes when this label should be applied. Max 250 characters only.
      - `color` integer — `1 - purple` `2 - red` `3 - yellow` `4 - green` `5 - blue` `6 - pink` `7 - teal` `8 - lime` `8 - gradient1` `9 - gradient2`
    - `notifications` CallEndNotificationApi[], nullable — Notifications configured to be triggered when a call ends. A notification can trigger an API call or send an email when specific indicator tags are detected. Constraints: - Max notifications: 30. - Each notification must reference indicator tag IDs (not tag names).
      - `apiSettings` APISettingsApi
        - `name` string, nullable — A friendly name for this API action. Max 50 characters only.
        - `method` integer — `1 - GET` `2 - POST` `3 - PUT` `4 - DELETE` `5 - PATCH`
        - `endpointUrl` string, nullable — `🧩 May support variables` The endpoint URL to call. Max 4,000 characters only. Variables support depends on when this API action is executed: - Pre-call: pre-call variables only. - In-call: pre-call and in-call variables. - End-call: pre-call, in-call, and post-call variables.
        - `body` APIDataSchemaPropertyApi[], nullable — Request body definition (key/value pairs) for this API call. Constraints: - Only applicable for POST, PUT, or PATCH. - Must be empty for GET, DELETE (and any method that does not send a body).
          - `key` string, nullable — The request body field name (JSON key). Max 255 characters only.
          - `variableId` string, nullable — The variable ID to send as the value for this field (without curly braces). Constraints: - If VariableId is provided, Type and Value must be null/empty.
          - `type` integer — `1 - String` `2 - Long` `3 - Double` `4 - Boolean` `5 - DateOnly` `6 - TimeOnly` `7 - DateTime`
          - `value` string, nullable — `🧩 May support variables` The static value to send for this field. Constraints: - Max 255 characters. - Must be provided together with Type when VariableId is not provided. - Must not be provided when VariableId is provided. - When Type is String, the value may include variables using curly braces.
          - `required` boolean — Indicates whether this request body field is required.
        - `headers` object, nullable — Optional HTTP headers to include in the API request.
        - `triggerDescription` string, nullable — Describes when this API action should be triggered. Max 1,000 characters only.
        - `description` string, nullable — A short description of what this API action does. Max 150 characters only.
        - `outputBody` APIDataSchemaPropertyApi[], nullable — Maps fields of the API response onto flow variables, so the values returned by the API can be used later in the conversation.
          - `key` string, nullable — The request body field name (JSON key). Max 255 characters only.
          - `variableId` string, nullable — The variable ID to send as the value for this field (without curly braces). Constraints: - If VariableId is provided, Type and Value must be null/empty.
          - `type` integer — `1 - String` `2 - Long` `3 - Double` `4 - Boolean` `5 - DateOnly` `6 - TimeOnly` `7 - DateTime`
          - `value` string, nullable — `🧩 May support variables` The static value to send for this field. Constraints: - Max 255 characters. - Must be provided together with Type when VariableId is not provided. - Must not be provided when VariableId is provided. - When Type is String, the value may include variables using curly braces.
          - `required` boolean — Indicates whether this request body field is required.
        - `credentialId` string, nullable — Optional ID of a credential used to authenticate the API call. To retrieve the credentials available to a Pearl, use the Get Pearl Credentials endpoint (GET /v2/Pearl/Credential/{pearlId}).
      - `emailTemplate` EmailEndCallTemplateApi
        - `to` string[], nullable — List of primary recipients. Constraints: - Max 10 recipients. - Max 255 characters per email address.
        - `cc` string[], nullable — List of CC recipients. Constraints: - Max 10 recipients. - Max 255 characters per email address.
        - `subject` string, nullable — `🧩 May support variables` Email subject. Constraints: - Max 150 characters. - Supports pre-call, in-call, and post-call variables.
        - `body` string, nullable — `🧩 May support variables` Email body content. Constraints: - Max 100,000 characters. - Supports pre-call, in-call, and post-call variables.
        - `triggerDescription` string, nullable — Instructions describing when the email should be sent (trigger conditions). Max 500 characters only.
        - `smtpSettings` SmtpSettings
          - `id` string, nullable — Optional SMTP configuration identifier.
          - `provider` integer — `1 - Gmail` `2 - Office365` `10 - Custom`
          - `smtpServer` string, nullable — SMTP server hostname.
          - `port` integer, nullable — SMTP server port.
          - `enableSsl` boolean, nullable — Indicates whether SSL/TLS is enabled for the SMTP connection.
          - `senderEmail` string, nullable — Sender email address used for SMTP authentication and as the "From" address.
          - `senderPassword` string, nullable — Sender password or SMTP credential used for authentication.
          - `displayName` string, nullable — Display name shown in the recipient inbox (the "From" name).
      - `indicatorTagsIds` string[], nullable — List of indicator tag IDs that must be detected to trigger this notification. Important: - These must be tag IDs from IndicatorTags (IndicatorTag.Id), not tag names.
  - `variables` DataSettingsApi[], nullable — Variables that can be defined, stored, and used by the agent during conversations. For details on variable groups and how to use variables in supported fields, see: [Flow Variables](/api-reference/flow_variables)
    - `id` string, nullable — Variable identifier. This is the ID you must reference when using the variable in scripts and templated fields. It must not contain spaces. Constraints: - Max 40 characters. - Allowed characters: letters (A–Z, a–z), digits (0–9), underscore (_), hyphen (-).
    - `name` string, nullable — Friendly display name for the variable. Max 40 characters only.
    - `group` integer — 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` integer — `1 - String` `2 - Long` `3 - Double` `4 - Boolean` `5 - DateOnly` `6 - TimeOnly` `7 - DateTime`
    - `isList` boolean — Indicates whether the variable can contain multiple values (list) or a single value.
    - `description` string, nullable — Guidance for the agent on how to collect or infer this variable during the conversation. Max 300 characters only.
    - `value` string, nullable
    - `options` OptionChoice[], nullable — Optional predefined choices for this variable (allowed/preset values). Notes: - Use Value for the human-readable label. - Use Code for an optional internal/normalized value to store or send to integrations.
      - `value` string, nullable — The option value (human-readable label). If Code is empty, this value is also used for display.
      - `code` string, nullable — Optional display/encoded value for the option. Use this to store a mapped value (for example a normalized code, an internal identifier, or a hex color).
  - `inbound` InboundVoiceSettingsApi — Inbound settings of a voice Pearl.
    - `totalAgents` integer — Total number of agents allocated to this inbound activity.
    - `transcriptOptions` integer — `1 - FullTranscript` `2 - SensitiveInfoRemoved` `3 - NoTranscript`
    - `callWebhookUrl` string, nullable — Optional webhook URL to receive call events (for example call started and call ended).
    - `phoneNumberId` string, nullable — The phone number ID to use for this Pearl. To retrieve available phone numbers, see: [Get Phone Numbers](/api-reference/v2/pearlSettings/get-phones) Constraints: - A phone number cannot be assigned to more than one active inbound Pearl at the same time.
    - `recordingOptions` boolean — Enables or disables call recording.
    - `isStopRecordingAfterTransferCall` boolean, nullable — Indicates whether recording should continue after a call is transferred.
    - `waitingSentence` string, nullable — Message played to the caller when no agent is available and the caller is waiting in the queue. Max 300 characters only.
    - `isSayQueueDetails` boolean — When enabled, the caller is informed about queue details (for example how many callers are ahead) while waiting.
  - `outbound` OutboundVoiceSettingsApi — Outbound settings of a voice Pearl.
    - `totalAgents` integer — Total number of agents allocated to this outbound activity.
    - `transcriptOptions` integer — `1 - FullTranscript` `2 - SensitiveInfoRemoved` `3 - NoTranscript`
    - `budgetTotal` integer, nullable — Total budget allocated for the outbound activity. If null, the outbound activity runs without a budget limit.
    - `timeZone` string, nullable — Default time zone for the outbound activity. Leads are called according to this time zone unless a lead-specific time zone is provided when adding leads. For 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). Example: "Pacific Standard Time", "Romance Standard Time".
    - `callingHours` DayWorkingHours[], nullable — Allowed calling hours for the outbound activity.
      - `day` integer — `0 - Sunday` `1 - Monday` `2 - Tuesday` `3 - Wednesday` `4 - Thursday` `5 - Friday` `6 - Saturday`
      - `start` string, date-span — Start time of the allowed calling window (based on the campaign time zone). Constraints: - Must be before End.
      - `end` string, date-span — End time of the allowed calling window (based on the campaign time zone). Constraints: - Must be after Start.
    - `callWebhookUrl` string, nullable — Optional webhook URL to receive call events (for example call started and call ended).
    - `leadWebhookUrl` string, nullable — Optional webhook URL to receive lead events (for example lead created/updated).
    - `phoneNumberId` string, nullable — The phone number ID to use for this Pearl. To retrieve available phone numbers, see: [Get Phone Numbers](/api-reference/v2/pearlSettings/get-phones)
    - `recordingTrack` integer — `1 - Pearl` `2 - Inbound` `3 - Both` `4 - None`
    - `isStopRecordingAfterTransferCall` boolean, nullable — Indicates whether recording should continue after a call is transferred.
    - `maximumCallAttempts` integer — Maximum number of call attempts per lead. Constraints: - Max 5 attempts.
    - `minimumRetryIntervalHours` integer — `1 - Every6Hours` `2 - OnceADay` `3 - OnceEvery3Days` `4 - OnceAWeek` `5 - OnceAMonth` `6 - Every3Hours`
    - `voiceMail` string, nullable — `🧩 May support variables` Voicemail message left when a voicemail/answering machine is detected. If empty, the agent will not leave voicemails.
    - `bypassIVRInstruction` string, nullable — `🧩 May support variables` Instructions used to bypass IVR (Interactive Voice Response) systems.
    - `ringDuration` integer, nullable — Ringing duration (in seconds) before considering the call unanswered. Constraints: - Min 10 seconds. - Max 50 seconds.
    - `callTimeout` integer, nullable — Maximum call duration (in minutes). The call is ended when this limit is reached. Constraints: - Min 1 minute. - Max 120 minutes.

## Response `200`

The ID of the newly created Pearl.

- string

## Other responses

- `400` — Error

---

[API](https://skmtc.net/nlpearl/apis/nlpearl-client-api.md) · [All operations](https://skmtc.net/nlpearl/apis/nlpearl-client-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nlpearl/nlpearl-client-api/versions/52d64fc5d6e9/schema)