Skip to content

Telesales Datasets ​

A Dataset is the schema unit for a Telesales campaign — it groups together:

  • Lead-phase custom fields (phase=lead) — data captured before the call (e.g. policy number, product, deal value)
  • Attempt-phase custom fields (phase=attempt) — outcome data the agent fills in during wrap-up (e.g. promise-to-pay date, payment method, notes)
  • Applicable disposition codes — the outcome catalogue this campaign uses
  • Conditional visibility — a field can be gated by disposition_in (e.g. "Commitment date" only shows when the disposition equals "Promise-to-Pay")

As of 2026-08-14, every new campaign must be linked to a Dataset. Legacy campaigns were auto-linked to each tenant's default dataset. The old /api/custom-fields endpoints for the two Telesales entities have been retired (HTTP 410 Gone) — see the Custom Fields page for details.

Access requirements ​

EndpointRequired scope
GET (read)telesales module — viewer or above
POST/PUT/DELETE (write)Permission manage_telesales_dataset (admin tier)
POST /api/v1/telesales/datasets/{code}/leads (push lead)Sanctum PAT with ability telesales:push

Dataset shape ​

Each dataset has the following top-level attributes:

FieldTypeDescription
idintegerAuto-increment
codestringUnique per tenant; used in the push-lead URL
namestringDisplay name (e.g. "FinanceCorp Life Insurance — Renewal")
descriptionstringShort summary
industry_tagstring | nullOptional enum: insurance, finance, tourism, healthcare, realestate, survey, other
is_defaultbooleanOne default dataset per tenant (auto-selected in the campaign wizard)
is_activebooleanfalse = hidden from list, cannot be used for new campaigns
fields[]arrayList of custom field definitions (details below)
dispositions[]arrayList of applicable disposition codes (N-N link to telesales_dispositions)
field_countintegerCached count
disposition_countintegerCached count

Each field object has:

FieldTypeDescription
idinteger
field_codestringUnique per dataset, snake_case (e.g. policy_number)
labelstringDisplay label
typestringEnum: text, textarea, number, date, datetime, select, multiselect, phone, email, boolean
requiredbooleanRequired on push-lead / disposition submit
optionsarray | nullFor select/multiselect types: [{value, label}, ...]
visible_whenobject | nullVisibility guard, e.g. {"disposition_in": ["RN-02", "RI-02"]}
phasestringlead or attempt
help_textstring | nullHint shown below the input
display_orderintegerPosition in the form

GET /api/telesales/datasets — List datasets ​

Returns every dataset owned by the tenant.

http
GET /api/telesales/datasets
Authorization: Bearer <api_token>
Accept: application/json

Query params:

ParamDescription
is_activetrue (default) returns only active datasets. Pass false to include archived ones.
industry_tagFilter by industry (e.g. insurance)

Response 200 — datasets are returned with a nested fields[] array:

json
{
  "data": [
    {
      "id": 5,
      "tenant_id": 1,
      "code": "sample_life_renewal",
      "name": "FinanceCorp Life Insurance — Renewal",
      "description": "Premium reminder + policy reinstatement campaign",
      "industry_tag": "insurance",
      "template_source_id": 2,
      "layout": null,
      "is_active": true,
      "is_default": true,
      "created_at": "2026-08-14T10:00:00+00:00",
      "updated_at": "2026-08-14T10:00:00+00:00",
      "fields": [
        {
          "id": 101,
          "dataset_id": 5,
          "field_code": "full_name",
          "label": "Full name",
          "type": "text",
          "required": true,
          "options": null,
          "help_text": null,
          "phase": "lead",
          "display_order": 10,
          "is_active": true,
          "visible_when": null
        }
      ]
    }
  ]
}

Note: dispositions[] are not embedded in the list — call GET /api/telesales/datasets/{id}/dispositions separately.

GET /api/telesales/datasets/{id} — Dataset detail ​

Returns full metadata plus fields and dispositions.

http
GET /api/telesales/datasets/5
Authorization: Bearer <api_token>

Response 200:

json
{
  "data": {
    "id": 5,
    "code": "sample_life_renewal",
    "name": "FinanceCorp Life Insurance — Renewal",
    "industry_tag": "insurance",
    "is_default": true,
    "is_active": true,
    "fields": [
      {
        "id": 101,
        "field_code": "full_name",
        "label": "Full name",
        "type": "text",
        "required": true,
        "phase": "lead",
        "display_order": 10
      },
      {
        "id": 102,
        "field_code": "policy_number",
        "label": "Policy number",
        "type": "text",
        "required": true,
        "phase": "lead",
        "help_text": "Format POL-YYYY-NNNN",
        "display_order": 20
      },
      {
        "id": 201,
        "field_code": "commitment_date",
        "label": "Commitment date",
        "type": "date",
        "required": true,
        "phase": "attempt",
        "visible_when": {
          "disposition_in": ["RN-02", "RI-02"]
        },
        "display_order": 10
      },
      {
        "id": 202,
        "field_code": "payment_method",
        "label": "Payment method",
        "type": "select",
        "options": [
          { "value": "cash",   "label": "Cash" },
          { "value": "bank",   "label": "Bank transfer" },
          { "value": "atm",    "label": "ATM card" },
          { "value": "wallet", "label": "e-Wallet" }
        ],
        "phase": "attempt",
        "visible_when": {
          "disposition_in": ["RN-01", "RI-01"]
        },
        "display_order": 20
      }
    ],
    "template": {
      "id": 2,
      "code": "insurance_life",
      "name": "Life Insurance",
      "industry_tag": "insurance",
      "description": "Premium reminder + policy renewal",
      "is_system": true,
      "tenant_id": null,
      "default_fields": [
        { "field_code": "policy_number", "label": "Policy number", "type": "text", "required": true, "phase": "lead", "display_order": 10 }
      ],
      "created_at": "2026-08-14 14:20:31"
    }
  }
}

Note: the response does not embed dispositions[] — use GET /api/telesales/datasets/{id}/dispositions for the applied disposition list.

The template block (when present) is the industry preset that seeded the dataset — kept as a reference; it does not stay in sync with the dataset's current fields.

POST /api/telesales/datasets/{id}/fields — Create field ​

http
POST /api/telesales/datasets/5/fields
Authorization: Bearer <api_token>
Content-Type: application/json

{
  "field_code": "policy_number",
  "label": "Policy number",
  "type": "text",
  "required": true,
  "phase": "lead",
  "display_order": 20,
  "help_text": "Format POL-YYYY-NNNN"
}

Response 201 returns the created field.

Validation:

  • field_code must match ^[a-z][a-z0-9_]{0,63}$ and be unique within the dataset
  • type must be one of the supported types listed above
  • For select/multiselect, options (array of {value, label}) is required
  • phase must be lead or attempt

Error 409 on duplicate code inside the dataset:

json
{ "error": "field_code_duplicate" }

PUT /api/telesales/datasets/{id}/fields/{fid} — Update field ​

field_code, type, and phase are immutable after creation (changing them could corrupt already-stored data). Mutable attributes: label, required, options, visible_when, help_text, display_order.

http
PUT /api/telesales/datasets/5/fields/102
Content-Type: application/json

{
  "label": "Policy No. (Contract ID)",
  "required": false,
  "help_text": "May be empty if not yet known"
}

Response 200:

json
{
  "data": {
    "id": 102,
    "dataset_id": 5,
    "field_code": "policy_number",
    "label": "Policy No. (Contract ID)",
    "type": "text",
    "required": false,
    "options": null,
    "help_text": "May be empty if not yet known",
    "phase": "lead",
    "display_order": 20,
    "is_active": true,
    "visible_when": null
  }
}

DELETE /api/telesales/datasets/{id}/fields/{fid} — Delete field ​

Soft delete: is_active=false. Data stored under the custom_fields JSON column on leads/attempts is preserved. You can restore with PUT ... {"is_active": true}.

POST /api/telesales/datasets/{id}/fields/reorder — Reorder fields ​

http
POST /api/telesales/datasets/5/fields/reorder
Content-Type: application/json

{
  "order": [
    { "id": 101, "display_order": 10 },
    { "id": 102, "display_order": 20 },
    { "id": 103, "display_order": 30 }
  ]
}

Validation: the order array is required; each item must include id (int) and display_order (int).

Response 200:

json
{ "ok": true, "count": 3 }

Error 422 if any id does not belong to the dataset (protects against typo IDs from another dataset):

json
{
  "error": "invalid_field_ids",
  "message": "One or more field IDs do not belong to this dataset",
  "invalid": [999999]
}

Tenant-wide disposition catalogue ​

In addition to the per-dataset applicable dispositions (endpoint below), each tenant maintains a catalogue of every disposition that may be used — managed via the /api/telesales/dispositions endpoint group.

GET /api/telesales/dispositions — Full catalogue ​

http
GET /api/telesales/dispositions
Authorization: Bearer <api_token>
Accept: application/json

Response 200 — every disposition available to the tenant, sorted by sort_order then code:

json
{
  "data": [
    {
      "id": 1,
      "code": "sale",
      "label": "Sale",
      "description": null,
      "category": "contact",
      "is_final": true,
      "is_conversion": true,
      "trigger_callback": false,
      "trigger_dnc": false,
      "trigger_ticket": false,
      "default_retry_delay_minutes": null,
      "color": "#10B981",
      "is_system": true,
      "sort_order": 10,
      "created_at": "2026-05-19T15:36:48+00:00"
    }
  ]
}
  • is_system=true → system code, cannot be deleted or have its code changed (label/color are editable).
  • category ∈ contact | callback | no_contact | remove.
  • is_final=true → once written, the lead is closed and will not auto-retry.
  • trigger_* → automatic hooks (open callback queue / add DNC / create CSKH ticket).

POST /api/telesales/dispositions — Create ​

http
POST /api/telesales/dispositions
Content-Type: application/json

{
  "code": "RN-06",
  "label": "Renewal · offer plan switch",
  "category": "contact",
  "is_final": false,
  "is_conversion": false,
  "trigger_callback": true,
  "default_retry_delay_minutes": 1440,
  "color": "#F59E0B",
  "sort_order": 15
}
  • code must be unique within the tenant, snake_case or XX-NN.
  • Cannot collide with an existing system code.

PUT /api/telesales/dispositions/{id} — Update ​

Every field is mutable except code and the is_system flag.

DELETE /api/telesales/dispositions/{id} — Delete ​

  • Only non-system codes that are not assigned to any dataset can be deleted.
  • If ≥1 dataset still uses it → HTTP 409 with the offending dataset IDs so the admin can unlink first.

GET /api/telesales/datasets/{id}/dispositions — Applicable dispositions ​

Returns the disposition codes assigned to the dataset (a subset of the tenant-wide telesales_dispositions catalogue).

Response 200:

json
{
  "data": [
    {
      "disposition_code": "CB-01",
      "display_order": 0,
      "label": "Callback",
      "category": "callback",
      "is_conversion": 0
    },
    {
      "disposition_code": "RN-01",
      "display_order": 1,
      "label": "Renewal — Paid",
      "category": "contact",
      "is_conversion": 1
    }
  ]
}

PUT /api/telesales/datasets/{id}/dispositions — Set applicable dispositions ​

Replaces the full list of applicable disposition codes for the dataset (idempotent).

http
PUT /api/telesales/datasets/5/dispositions
Content-Type: application/json

{
  "dispositions": [
    "RN-01", "RN-02", "RN-03", "RN-04",
    "RI-01", "RI-02", "RI-03",
    "CB-01", "DO-01", "OT-01"
  ]
}

Response 200:

json
{ "ok": true, "count": 10 }

Validation: every code in dispositions must exist in the tenant's telesales_dispositions catalogue (not necessarily already linked to the dataset). Unknown codes → HTTP 422:

json
{
  "error": "invalid_dispositions",
  "invalid": ["XX-99"]
}

Push leads from an external system ​

Two public endpoints for partners to push leads from external CRMs/systems into Zorio campaigns:

  • POST /api/v1/telesales/datasets/{dataset_code}/leads — bulk push (up to 500 leads per request)
  • POST /api/v1/telesales/datasets/{dataset_code}/leads/single — single push (one lead per request, REST-ful response, separate rate limit 300/min)

→ See full details + sample code + response examples in the Push leads from an external system (Ingest API) section on the Leads page.

Validation pipeline for attempt-phase custom_fields ​

When an agent submits a disposition through POST /api/telesales/calls/{uuid}/disposition, the custom_fields payload is validated against the campaign's dataset schema (fields where phase='attempt'). The 5-step pipeline:

  1. Reject unknown fields — keys not in the dataset return 422 unknown_field
  2. Coerce data types — "42" → int; "true" → bool
  3. Apply validation rules — required, min/max, options membership
  4. Filter by visible_when — fields that don't match the submitted disposition are silently dropped
  5. Persist into telesales_call_attempts.custom_fields JSON

Response 200 includes a custom_fields_report:

json
{
  "data": { "attempt_id": 999 },
  "custom_fields_report": {
    "summary": {
      "total_fields": 3,
      "accepted": 2,
      "rejected": 1,
      "filtered_by_visible_when": 0
    },
    "errors": [
      {
        "field": "commitment_date",
        "error": "missing_required",
        "message": "Field \"Commitment date\" is required when disposition = RN-02"
      }
    ]
  }
}

Migrating from the legacy Custom Fields API ​

If your integration used to call /api/custom-fields for the two Telesales entities, see the full migration guide on the Custom Fields page.

Quick steps:

  1. Call GET /api/telesales/datasets → cache the tenant's dataset list
  2. For each relevant dataset, call GET /api/telesales/datasets/{id} → cache its fields and dispositions
  3. Replace every GET /api/custom-fields?entity=TelesalesLead with reading fields[] from the dataset (filter phase='lead')
  4. Replace every POST/PUT/DELETE /api/custom-fields with the corresponding dataset endpoint
  5. When pushing leads through the new endpoint, use the dataset block in the response as confirmation

Sample code ​

Python (requests) ​

python
import requests

BASE = "https://api.zorio.vn"
TOKEN = "your_api_token"
headers = {"Authorization": f"Bearer {TOKEN}", "Accept": "application/json"}

# List datasets
datasets = requests.get(f"{BASE}/api/telesales/datasets", headers=headers).json()

# Get schema
dataset = requests.get(f"{BASE}/api/telesales/datasets/5", headers=headers).json()['data']
lead_fields = [f for f in dataset['fields'] if f['phase'] == 'lead']

# Push lead
result = requests.post(
    f"{BASE}/api/v1/telesales/datasets/sample_life_renewal/leads",
    headers=headers,
    json={
        "leads": [{"full_name": "Alice", "phone": "0900000001",
                   "lead_data": {"policy_number": "POL-2024-0001"}}],
        "campaign_code": "SAMPLE_RENEWAL_202608"
    }
).json()
print(f"Inserted {result['inserted']} into dataset {result['dataset']['name']}")

Node.js (axios) ​

javascript
const axios = require('axios');
const client = axios.create({
  baseURL: 'https://api.zorio.vn',
  headers: { Authorization: `Bearer ${process.env.ZORIO_TOKEN}` },
});

// Push a batch of leads
const { data } = await client.post('/api/v1/telesales/datasets/sample_life_renewal/leads', {
  leads: [
    { full_name: 'Alice', phone: '0900000001',
      lead_data: { policy_number: 'POL-2024-0001' } },
  ],
  campaign_code: 'SAMPLE_RENEWAL_202608',
});
console.log(`Inserted ${data.inserted} into dataset ${data.dataset.name}`);

cURL ​

bash
curl -X POST -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "leads": [
         { "full_name": "Alice", "phone": "0900000001",
           "lead_data": { "policy_number": "POL-2024-0001" } }
       ],
       "campaign_code": "SAMPLE_RENEWAL_202608"
     }' \
     https://api.zorio.vn/api/v1/telesales/datasets/sample_life_renewal/leads

FAQ ​

Q1. Do datasets support nesting (parent-child)?
A: Not yet. Each dataset is independent. Common fields must currently be duplicated across datasets.

Q2. Can I switch the dataset for a campaign that's already running?
A: Not recommended. Leads imported under the old schema will mismatch the new one. Create a new campaign with a different dataset instead.

Q3. Can I delete a dataset that a campaign uses?
A: No. The endpoint returns 422 dataset_in_use. Delete/archive the referring campaigns first.

Q4. Is bulk create/update supported for fields?
A: Not yet. Loop through individual calls. Batch support is planned for a future release.

Q5. Which webhook fires when a lead is pushed via the dataset endpoint?
A: telesales.lead.imported — one event per successful insert. Subscribe under Portal → Webhooks.

Cấp phép theo điều khoản sử dụng của Zorio.