--- title: "Update Pearl" method: PUT path: "/v2/Pearl/{pearlId}" tags: ["Pearl"] --- # Update Pearl `PUT /v2/Pearl/{pearlId}` Updates the configuration of a Simple Pearl (name, pearl settings and variables). The update applies to the published version of the Pearl: if several versions exist on the platform, only the currently published one is modified. For Pearls, use Update Voice Pearl or Update Text Pearl instead. ## Path parameters - `pearlId` string, required ## Request body - UpdateProjectApiRequest - `name` string, nullable — The updated 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). ## Response `200` The Pearl flow was updated successfully. - boolean ## 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)