> ## 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. # Update Pearl > Updates the settings for the specified Pearl. ## OpenAPI ````yaml put /v2/Pearl/{pearlId} 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: [] paths: /v2/Pearl/{pearlId}: put: tags: - Pearl summary: Update Pearl description: Updates the settings for the specified Pearl. parameters: - name: pearlId in: path description: The unique identifier of the Pearl. required: true schema: type: string requestBody: description: The updated Pearl flow configuration. content: application/json: schema: allOf: - $ref: '#/components/schemas/UpdateProjectApiRequest' text/json: schema: allOf: - $ref: '#/components/schemas/UpdateProjectApiRequest' application/*+json: schema: allOf: - $ref: '#/components/schemas/UpdateProjectApiRequest' responses: '200': description: The Pearl flow was updated successfully. content: text/plain: schema: type: boolean application/json: schema: type: boolean text/json: schema: type: boolean '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: UpdateProjectApiRequest: type: object properties: name: type: string description: The updated name of the Pearl. nullable: true pearl: allOf: - $ref: '#/components/schemas/PearlSettingsApi' description: >- Updated conversation flow 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 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: {} PearlSettingsApi: type: object properties: agents: type: array items: $ref: '#/components/schemas/AgentConfigToAddApi' description: >- 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). nullable: true 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. - 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. `1 - Trident` `2 - Oyster` `3 - Arrow` `4 - Hydra` 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 name used by the agent during conversations.\r\n \r\nConstraints:\r\n- Max length: 500 characters." 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 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).\r\n \r\nConstraints:\r\n- Max entries: 10." nullable: true openingSentence: type: string description: "`🧩 may include variables`\r\n\r\nThe opening sentence spoken by the agent when a conversation starts.\r\n \r\nConstraints:\r\n-Max 500 characters only.\r\n-Supports pre-call variables only." nullable: true flowScript: type: string description: "`🧩 may include variables`\r\n\r\nThe flow script the agent follows to drive the conversation.\r\n \r\nConstraints:\r\n- Max 20,000 characters.\r\n- Supports pre-call variables and in-call variables." nullable: true transferCallSettings: type: array items: $ref: '#/components/schemas/TransferCallSettingsApi' description: "Call transfer rules configured for the Pearl (when and where calls should be transferred).\r\n \r\nConstraints:\r\n- Max rules: 10." nullable: true smsSettings: type: array items: $ref: '#/components/schemas/SMSTemplateApi' description: "SMS templates and triggers configured for the Pearl.\r\n \r\nDuring a call, the agent can send SMS messages based on these rules.\r\n \r\nConstraints:\r\n- Max templates: 10." nullable: true emailSettings: type: array items: $ref: '#/components/schemas/EmailTemplateApi' description: "Email templates and triggers configured for the Pearl.\r\n \r\nDuring a call, the agent can send emails based on these rules.\r\n \r\nConstraints:\r\n- Max templates: 10." nullable: true apiSettings: type: array items: $ref: '#/components/schemas/APISettingsApi' description: "API actions configured for the Pearl.\r\n \r\nConstraints:\r\n- Max actions: 10." nullable: true successDescription: type: string description: "Definition of what is considered a successful call for this Pearl.\r\nThis is used to classify call outcomes as successful or not successful.\r\n \r\nIf left empty, calls will only be marked as completed (no success classification).\r\n \r\nMax 200 characters only." nullable: true indicatorTags: type: array items: $ref: '#/components/schemas/CallLabelApi' description: "Indicator labels that can be applied to calls for classification and reporting.\r\n \r\nAt the end of the conversation, an AI analyzes the call and determines which of the configured labels should be applied.\r\n \r\nConstraints:\r\n- Max labels: 10." nullable: true notifications: type: array items: $ref: '#/components/schemas/CallEndNotificationApi' description: "Notifications configured to be triggered when a call ends.\r\n \r\nA notification can trigger an API call or send an email when specific indicator tags are detected.\r\n \r\nConstraints:\r\n- Max notifications: 30.\r\n- Each notification must reference indicator tag IDs (not tag names)." nullable: true additionalProperties: false 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 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 eBrainModelType: type: integer description: >+ Agent model type. - 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. `1 - Trident` `2 - Oyster` `3 - Arrow` `4 - Hydra` format: int32 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 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." 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 SMSTemplateApi: 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.\r\n- If sent at end of call, may also support post-call variables." nullable: true triggerDescription: type: string description: "Instructions describing when the SMS should be sent (trigger conditions).\r\n \r\nMax 500 characters only." nullable: true additionalProperties: false EmailTemplateApi: type: object properties: subject: type: string description: "`🧩 May support variables`\r\n\r\nEmail subject.\r\n \r\nMax 150 characters only." nullable: true body: type: string description: "`🧩 May support variables`\r\n \r\nEmail body content.\r\n \r\nMax 100,000 characters only." nullable: true triggerDescription: type: string description: "Instructions describing when the email should be sent (trigger conditions).\r\n \r\nMax 500 characters only." 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 APISettingsApi: 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 when this API action is executed:\r\n- Pre-call: pre-call variables only.\r\n- In-call: pre-call and in-call variables.\r\n- End-call: pre-call, in-call, and post-call variables." 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 triggerDescription: type: string description: "Describes when this API action should be triggered.\r\n \r\nMax 1,000 characters only." nullable: true description: type: string description: "A short description of what this API action does.\r\n \r\nMax 150 characters only." nullable: true additionalProperties: false 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 CallEndNotificationApi: type: object properties: apiSettings: allOf: - $ref: '#/components/schemas/APISettingsApi' description: API action to trigger when the notification conditions are met. nullable: true emailTemplate: allOf: - $ref: '#/components/schemas/EmailEndCallTemplateApi' description: Email template to send when the notification conditions are met. nullable: true indicatorTagsIds: type: array items: type: string description: "List of indicator tag IDs that must be detected to trigger this notification.\r\n \r\nImportant:\r\n- These must be tag IDs from IndicatorTags (IndicatorTag.Id), not tag names." 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 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 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 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 EmailEndCallTemplateApi: 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, in-call, and post-call variables." 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, in-call, and post-call variables." nullable: true triggerDescription: type: string description: "Instructions describing when the email should be sent (trigger conditions).\r\n \r\nMax 500 characters only." 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 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 ````