> ## Documentation Index
> Fetch the complete documentation index at: https://api.scalysis.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Scalysis API Field Reference: All Request & Response Fields
> A complete quick-lookup dictionary for every request and response field in the Scalysis API, including types, requirements, and usage notes.
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:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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.