> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hubtalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# create: uploading contacts

> Request rows, checks, the response with IDs, hours, the campaign day, agent variables, repeats, and failures.

# 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.

| Common field (`v2-mx`) | Rule |
| - | - |
| `phone_number` | 11–13 digits |
| `type` | The script name exactly as in the registry. Case matters. |
| `gender_voice` | `male` or `female` |
| `language` | `en`, `ru`, or `es` |

Every script field is required in every row. Field rules are on the [Account and field rules](https://docs.hubtalk.ai/v4/compat-adapter/account-settings.md#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:

```json List of ids theme={null}
{"type":"success", "data":[100000001,100000002]}
```

```json Pairs of batch_id and foreign_id theme={null}
{"type":"success", "data":[{"batch_id":100000001,"foreign_id":"MX-77120"},{"batch_id":100000002,"foreign_id":null}]}
```

Keep the IDs: [`delete`](https://docs.hubtalk.ai/v4/compat-adapter/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:

| # | Condition | Response text |
| - | - | - |
| 1 | `ending_hour` outside the window (`create` only) | `End time is out of eligible range from 10 to 21` (added by the platform; the numbers come from V2, not your window) |
| 2 | The current hour is not earlier than `ending_hour`, and the window is still open (`create` only) | `The end time is set incorrectly, the current time is greater than the end time` |
| 3 | `start_hour` is not earlier than `ending_hour` (`create` only) | `The end time is set incorrectly, the end time is less than or equal to the start time` |
| 4 | `start_hour` outside the window (any operation that passes it) | `The time is set incorrectly, restrictions from 8 to 19` |

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:

  ```json theme={null}
  {"type":"success", "data":[…], "notice":"End time 21:30 is out of eligible range, cut to 21:00"}
  ```

* **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.

> [!NOTE]
>
> 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:

```
<cname> <YYYY-MM-DD> <HH:MM> (<script>)
```

— up to 80 characters. The campaign closes at the end of its day or when canceled; an empty queue does not close it.

> [!WARNING]
>
> 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](https://docs.hubtalk.ai/v4/compat-adapter/registry-fields.md).

## 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](https://docs.hubtalk.ai/v4/platform/campaigns/frequency.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.