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
Adata[] 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.{"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
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:
What the agent receives
gender_voiceandlanguagereach the agent as variables under their own names.phone_numberandtypedo 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_idreaches the agent only if the registry routes it into a variable. It is always stored alongside the adapter contact ID.rl_todayis added to every row — the campaign day inDD.MM.YYYYformat. It overrides a request field with the same name.
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 (ignoringuser 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
createcan take longer — so the client timeout must be at least 60 seconds.