Skip to main content

create: uploading contacts

create uploads rows with phone numbers into a V4 campaign: the first request of the day creates it, and the following ones add to it.

Rows

A data[] row starts with the common fields, followed by the fields of its script in the order agreed with the administrator. The host key is accepted and ignored. Every script field is required in every row. Field rules are on the Account and field rules page.

Row checks

Checks run in V2 order. If the request is rejected, nothing is created.
1

Unsupported parameters

A non-empty batch_status responds with {"type":"error", "data":"The parameter batch_status is not supported"}, a non-empty uniqueID — with {"type":"error", "data":"The parameter uniqueID is not supported"} (both added by the platform).
2

Keys

An unknown key responds with {"type":"error", "data":"#<key># does not exist in the format of the request"} (two spaces — as in V2), a missing one — with {"type":"error", "data":"The required field is missing #<key>#"}. The first such error stops the request.
3

Script

A row whose script is not in your account’s registry or cannot be used right now (the agent is archived, not published, or not set) gets a row error on the type field.
4

Values

Errors respond with {"type":"error", "data":[{"line":"1", "fields":["amount_due"]}]} — one entry for each row with an error. With flag_ignore_errors: "skip" such rows are dropped and the rest are accepted.
5

Do not call registry

For a number on your organization’s Do not call registry, the account either skips the row (the row gets an ID, but nobody calls — the V2 behavior) or rejects the request with a row error on phone_number. With flag_ignore_errors: "skip" such a row is simply dropped.
6

Repeated upload

If the check is enabled in the account: a number already uploaded today, or the same number with the same foreign_id, is dropped.
If all rows are dropped, the response is {"type":"success", "data":[]}, and no campaign is created.

Response

Each accepted row gets an adapter contact ID — a nine-digit number starting from 100 000 000. IDs are issued in row order, including rows skipped because of the Do not call registry. The response form is set in the account:
List of ids
Pairs of batch_id and foreign_id
Keep the IDs: delete accepts them.

Hours

Hours are read in your organization’s time zone and checked against the account’s dialing window. First come four V2 checks — they compare only hours; minutes are ignored: Without ending_hour, the end is the end of the account’s window; 24 means 23:59. Then minutes are taken into account:
  • The end is cut to the earlier of the end of the account’s window and the end of the organization’s calling window. A cut request is still accepted, and the response contains one key beyond the V2 templates:
  • The start — passed in the request or the account’s start hour — must fall before the end after the cut. Otherwise the response is the text of check 3.
The notice key is not an error: the request is accepted, only the end is shortened. Code that parses the JSON by keys will skip it. If your code compares the whole response body, send an end within the window.

Campaign day and campaign

The campaign day is today in your organization’s time zone. If 5 minutes or less remain until the end of the day (the earliest of the window ends and the requested end), or the end has already passed, the request moves to tomorrow with the same hours. The V2 rule “after 19:56 — to tomorrow” is not used. All requests of one day with the same script, cname, start hour and minute, and number of attempts go into one campaign. The first one creates and starts it; the following ones add their rows to it. Campaign name:
— up to 80 characters. The campaign closes at the end of its day or when canceled; an empty queue does not close it.
A completed or canceled campaign stays closed. Until the end of the day, requests with the same attributes get the internal error Internal error, try again later. To start a new campaign, change cname or the start hour.

What the agent receives

  • gender_voice and language reach the agent as variables under their own names. phone_number and type do not become variables.
  • Each script field reaches the agent under its own name, under the name of another variable, or not at all — as configured in the registry.
  • An empty value is replaced with the fallback value from the registry; if there is none, the variable’s default in the agent itself applies.
  • foreign_id reaches the agent only if the registry routes it into a variable. It is always stored alongside the adapter contact ID.
  • rl_today is added to every row — the campaign day in DD.MM.YYYY format. It overrides a request field with the same name.
For details on how a request field becomes a variable, see Fields and variables.

Dialing

Attempts, speed, and interval come from the request or from the account defaults. The interval is counted from each contact’s previous attempt. Calls go out only during the campaign hours and within the organization’s calling window; the organization’s Do not call registry and frequency rules apply.

Repeated requests

The same body (ignoring user and pass) sent again within 10 minutes gets the stored response with the same IDs, and no rows are added. To add rows to a campaign, send a different body — different numbers or field values.

Failures and timing

  • If the platform cannot complete a request after the checks, nothing of it remains: the campaign it created is canceled, rows it added to an existing campaign are withdrawn, and the response is an internal error. Retry the request later.
  • All waits of a request before writing starts fit within 50 seconds. After that, a large create can take longer — so the client timeout must be at least 60 seconds.