Skip to main content
API variables are placeholders you can embed in specific Pearl Flow fields to make your configuration dynamic (scripts, endpoints, messages, and notifications). Whenever a field is labeled: 🧩 May support variables you can insert variables using this syntax: 
{variableId}
Example: 
Hello {firstName}, this is {agentName}.

​
Variable Groups

Variables belong to one of three groups.

​
Pre-call variables (Group = PreCall)

Pre-call variables are expected to be available before the call starts (for example from your lead import, CSV mapping, or an API integration). If a pre-call value is missing, it’s not always blocking — depending on your flow, the agent may still collect it during the call. Common usage:
  • Opening sentence
  • Pre-call API actions
  • Endpoint URLs and message templates (when supported)
Opening sentence example (pre-call only): 
Hello, I’m {agentName}. Am I speaking with {firstName}?

​
In-call variables (Group = InCall)

In-call variables are collected or updated during the call. Common usage:
  • In-call API actions
  • Email/SMS templates (when supported)
  • Flow scripts (when supported)
Script example (collecting an in-call variable): 
Please tell me your address. I will store it as {customerAddress}.

​
Post-call variables (Group = PostCall)

Post-call variables are generated after the call ends (transcript, summary, duration, etc.). You cannot create post-call variables manually — they are pre-defined by the platform. Common usage:
  • End-call notifications (Email / API)

​
Built-in Variables (Reserved IDs)

Some variables are built into the platform and already exist by default. Because they are reserved, **you cannot create a new variable using the same id** as a built-in variable. If you try, the API will reject it as a duplicate ID.

​
Built-in Pre-call Variables

IDNameDescription
agentNameAgent NameThe name of the agent.
firstNameFirst NameThe customer’s first name formatted as a proper first name.
lastNameLast NameThe customer’s last name formatted as a proper last name.
emailAddressEmail AddressThe customer’s email address in a standard format (RFC 5321 / RFC 5322).
phoneNumberPhone NumberThe customer’s phone number with country code (digits + optional +).
callIdCall IDThe identifier of the call.

​
Built-in In-call Variables

There are currently no built-in in-call variables. In-call variables are typically created per Pearl to match what you want to collect during the conversation.

​
Built-in Post-call Variables

IDNameDescription
post_call_durationCall DurationDuration of the call.
post_call_summaryCall SummarySummary generated after the call concludes.
post_call_transcriptCall TranscriptTranscript of the call for reference.
post_call_call_timeCall TimeTimestamp indicating when the call occurred.
post_call_recordingRecording LinkLink to the call recording.

​
Where Variables Are Supported

Only fields explicitly marked with: 🧩 May support variables support the {variableId} syntax. Typical examples include:
  • Flow scripts (when enabled)
  • API endpoint URLs
  • API body values (when the body field is a string)
  • SMS / Email templates (depending on the action timing)
  • End-call notifications (supports post-call variables)
Only fields that support variables will be labeled with 🧩 May support variables. If the field is not labeled, assume it is static-only.

​
Using Variables in API Requests

​
1) Use variables inside scripts

Example script snippet: 
Ask the caller for their address and store it in {customerAddress}.
If {customerAddress} is empty, ask again politely.

​
2) Use variables in API action endpoint URLs

Example: 
https://example-crm.com/leads?phone={phoneNumber}&name={firstName}

​
3) Use variables in API action body values (string)

If a body field is a string value, it can include variables: 
{
  "key": "message",
  "type": "String",
  "value": "New call completed for {firstName} {lastName}."
}
API Body Exception (VariableId field)When configuring an API action body, the VariableId property must contain the raw variable ID without brackets. Example: use firstName (not {firstName}).This is a special case for the API body schema only — everywhere else, variables are inserted using {variableId}.

​
4) Use post-call variables in End-call notifications

Example email body: 
Call ended for {firstName} {lastName}.
Summary: {post_call_summary}
Transcript: {post_call_transcript}
Recording: {post_call_recording}
Duration: {post_call_duration}

​
Best Practices

  • Use short, stable variable IDs (e.g., customerAddress, membershipStatus).
  • Treat built-in variable IDs as reserved keywords.
  • Use post-call variables only in end-call notifications.
  • Avoid defining variables you never reference in your flow.

​
Quick Reference

  • Syntax: {variableId}
  • Groups: PreCall / InCall / PostCall
  • Built-in InCall variables: none
  • Post-call variables: available inside end-call notifications only