Scalysis API Field Reference: All Request & Response Fields

This page is your quick-lookup dictionary for every field you will encounter when working with the Scalysis API. Use the Request Fields table to know exactly what to send in your JSON body, and the Response Fields table to understand what comes back. Each entry notes the field’s data type, whether it is required or optional, and what it actually does.

Request Fields

These are the fields you can include in the JSON body of your API requests. Fields marked Required will produce a 400 error if omitted; fields marked Optional have sensible defaults or are only needed for specific script configurations.

Field	Type	Required?	Description
`scriptId`	number	Required	The integer ID of the AI agent script to run. Find this value on the Scripts page in the Scalysis dashboard.
`customerPhone`	string	Required	The phone number to dial, in E.164 format (e.g., `"+12025550147"`). Required for single-call triggers and for every contact in a campaign.
`customerName`	string	Optional	The customer’s full name. Not required, but passing it lets the AI agent address the person by name during the call.
`orderNumber`	string	Optional	Your internal order or ticket reference. Stored alongside the call record for your own tracking and lookup.
`orderNotes`	string	Optional	Free-text notes about the order or customer that the AI agent can reference during the call.
`brand_name`	string	Required if script uses it	The brand name the AI agent will speak aloud. Must be provided when your script contains a `brand_name` variable placeholder — omitting it returns a `400`.
`contacts[]`	array	Required if not using `csvText`	A JSON array of contact objects for campaign calls. Each object should include at minimum a phone number field. Use this or `csvText`, not both.
`csvText`	string	Required if not using `contacts[]`	Your contact list pasted as a raw CSV string. Use this or `contacts[]`, not both. The column identified by `phoneColumn` must be present in every row.
`phoneColumn`	string	Optional	The column name in `csvText` that contains phone numbers. Defaults to `"phone_number"` if not specified.
`name` / `campaignName`	string	Optional	A human-readable label for the campaign, visible in the Scalysis dashboard.
`kind`	string	Optional	The campaign type. Accepted values: `"cod"` (cash-on-delivery), `"list"` (general list dial), or `"ndr"` (non-delivery report).
`startImmediately`	boolean	Optional	When `true`, the campaign begins dialing as soon as it is created. When `false` or omitted, use the control endpoint with `"action": "start"` to begin manually.
`maxConcurrency`	number	Optional	The maximum number of simultaneous calls the campaign should place at once. The server may enforce a lower cap based on your plan’s channel pool.
`action`	string	Required for campaign control	Controls campaign state. Must be one of `"start"`, `"pause"`, or `"resume"`. Only used on the campaign control endpoint — not on trigger or create requests.

For campaign requests, you must supply either contacts[] or csvText — not both, and not neither. If you use csvText, make sure the column name for phone numbers matches your phoneColumn value (or the default "phone_number").

scriptId is required on every call trigger and campaign creation request. There is no account-level default script — you must always specify which AI agent script to use.

contacts[] object shape

Each object inside the contacts[] array should follow this structure:

{
  "phone_number": "+12025550147",
  "name": "Alex Johnson",
  "orderNumber": "ORD-9921"
}

Only phone_number (or whichever column phoneColumn points to) is strictly required per contact. All other fields are optional and will be passed through to the script as context.

csvText format example

If you prefer to upload contacts as CSV, paste the entire CSV content as a single string value:

{
  "scriptId": 42,
  "brand_name": "Acme Store",
  "csvText": "phone_number,name,orderNumber\n+12025550147,Alex Johnson,ORD-9921\n+13105550198,Sam Rivera,ORD-9922",
  "phoneColumn": "phone_number"
}

Response Fields

These fields appear in the JSON body of responses returned by the Scalysis API. Not every field appears in every response — the table notes which endpoint context each field is associated with.

Field	Type	Context	Description
`success`	boolean	All responses	`true` when the request was accepted and processed successfully; `false` when an error occurred. Always check this field first.
`order_id`	number	Call trigger	The unique identifier for the triggered call. Store this value to poll for the call outcome via `GET /api/order/{order_id}/call-outcome`.
`campaign_id`	number	Campaign create / control	The unique identifier for the campaign. Use this in subsequent start, pause, resume, and status requests.
`script_id`	number	Call outcome / campaign detail	Echoes back the `scriptId` that was used for the call or campaign.
`call_status`	string	Call outcome	The current status of the individual call (e.g., `"completed"`, `"failed"`, `"in_progress"`).
`state`	string	Campaign status	The current state of the campaign (e.g., `"running"`, `"paused"`, `"completed"`).
`callOutcome`	string	Call outcome	The AI agent’s classification of what happened on the call (e.g., `"confirmed"`, `"voicemail"`, `"no_answer"`, `"callback_requested"`).
`callDurationSec`	number	Call outcome	How long the call lasted, in seconds.
`totalCallCost`	number	Call outcome	The amount charged for the call, in your account’s billing currency.
`summary`	string	Call outcome	A short natural-language summary of the call generated by the AI agent.
`transcript`	array	Call outcome	A word-by-word log of the conversation. Each element is an object with `speaker`, `text`, and `timestamp` fields (see structure below).
`contact_count`	number	Campaign create / status	The total number of contacts in the campaign.
`started`	boolean	Campaign create	`true` if the campaign began dialing immediately (i.e., `startImmediately` was `true` in the request).
`message`	string	Error responses	A plain-English description of what went wrong. Always read this field when `success` is `false`.

transcript array object shape

Each element of the transcript array follows this structure:

{
  "speaker": "agent",
  "text": "Hi, this is Maya calling from Acme Store regarding your recent order.",
  "timestamp": 2.4
}

Sub-field	Type	Description
`speaker`	string	Who spoke — `"agent"` for the AI, `"customer"` for the person who answered.
`text`	string	The exact words spoken in this turn.
`timestamp`	number	Seconds from the start of the call when this turn began.

Use the transcript array together with callOutcome and summary to build a complete post-call audit log. The summary gives you a quick snapshot, callOutcome lets you filter and segment calls, and transcript provides the full detail if you ever need to review exactly what was said.

callDurationSec and totalCallCost are only populated once the call has fully completed. If you retrieve the outcome while the call is still running, you will receive a 404 Call is still in progress response — wait 10–30 seconds and try again.

Get Started

Core Concepts

Guides

Help

Scalysis API Field Reference: All Request & Response Fields

Request Fields

contacts[] object shape

csvText format example

Response Fields

transcript array object shape

​Request Fields

​contacts[] object shape

​csvText format example

​Response Fields

​transcript array object shape

Request Fields

contacts[] object shape

csvText format example

Response Fields

transcript array object shape