Import a contact list in the background
import { createClient, createResources } from "@morevoice/sdk";
const mv = createResources({ client: createClient({ baseUrl: "https://api.morevoice.ai/v1", auth: process.env.MOREVOICE_API_KEY }),});
const contactImport = await mv.campaigns.contacts.import("cmp_ojFwMD7YNTROjaTP0i3ZFb", { csv: "Mobile,Name,Plan\n0501234567,Dana Levi,Gold\n0527654321,Yossi Cohen,Silver\n", default_country: "IL", mapping: { name: "Name", phone: "Mobile", variables: { plan: "Plan", }, },});console.log(contactImport);import osimport uuid
import requests
response = requests.post( "https://api.morevoice.ai/v1/campaigns/cmp_ojFwMD7YNTROjaTP0i3ZFb/contacts/import", headers={"Authorization": f"Bearer {os.environ['MOREVOICE_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())}, json={ "csv": "Mobile,Name,Plan\n0501234567,Dana Levi,Gold\n0527654321,Yossi Cohen,Silver\n", "default_country": "IL", "mapping": { "name": "Name", "phone": "Mobile", "variables": { "plan": "Plan", }, }, },)response.raise_for_status()print(response.json())curl -X POST https://api.morevoice.ai/v1/campaigns/cmp_ojFwMD7YNTROjaTP0i3ZFb/contacts/import \ -H "Authorization: Bearer $MOREVOICE_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "csv": "Mobile,Name,Plan\n0501234567,Dana Levi,Gold\n0527654321,Yossi Cohen,Silver\n", "default_country": "IL", "mapping": { "name": "Name", "phone": "Mobile", "variables": { "plan": "Plan" } }}'Imports a CSV or XLSX list in the background through the dashboard’s import path and answers 202 with the import; poll GET /v1/imports/{id} until it succeeds or fails. Send the file as multipart/form-data (a file part plus the options as text fields, mapping as a JSON string), or as JSON: CSV text, a base64 file, or an https URL to download. An Idempotency-Key is required, so a retried upload never imports twice.
Try it in the API playground with a test-mode key.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”A campaign ID (cmp_…).
Header Parameters
Section titled “Header Parameters”The API version to use for this request. Defaults to the version the API key is pinned to.
Example
2026-11-01A unique key (for example a UUID) that makes this request safe to retry: for 24 hours, a retry with the same key and parameters returns the first response instead of acting twice.
Example
5f0c1e8a-7b2d-4c3e-9f1a-2b6d8e4c0a17Request Bodyrequired
Section titled “Request Bodyrequired”A contact list to import in the background (up to 50,000 rows). Send exactly one of csv, file and url.
object
How every consenting row consented, when the file has no channel column.
Where every consenting row consented, when the file has no source column.
The list as CSV text (UTF-8; comma, semicolon, tab or pipe separated).
Country of numbers written without a country code (ISO 3166-1 alpha-2, default IL).
Leave do-not-call numbers out entirely (default false: kept with status dnc, never dialled).
A CSV or XLSX file.
object
The file, base64-encoded (≤ 10 MB decoded).
Its name; .xlsx is read as a spreadsheet, anything else as CSV.
The first row holds column names (default: detected).
Which column holds what: contact field → header name (or 0-based index). Any other key names a {{variable}}. Omit the mapping to detect the columns like the dashboard does.
object
An https URL to download the CSV / XLSX from (public addresses only, ≤ 10 MB).
The import as multipart/form-data: the file part plus the same options as text fields.
object
How every consenting row consented, when the file has no channel column.
Where every consenting row consented, when the file has no source column.
ISO 3166-1 alpha-2 country of numbers without a country code (default IL).
Leave do-not-call numbers out entirely.
The CSV or XLSX file (up to 10 MB).
The file’s name, when the file part carries none; .xlsx is read as a spreadsheet.
The first row holds column names (default: detected).
A JSON object: contact field → column header, e.g. {“phone”:“Mobile”,“name”:“Name”,“plan”:“Plan”}.
Responses
Section titled “Responses”Accepted: the import runs in the background.
A background contact-list import and its result. Poll it until status is succeeded or failed.
object
A campaign ID (prefix cmp_).
Consent records created from the evidence sent.
An ISO-8601 timestamp in UTC.
Rejected rows (the first 100).
object
The number as sent.
Row in the file (1-based, the header is row 1).
A import ID (prefix imp_).
Contacts added to the campaign for dialling.
true in live mode, false in test mode.
Non-empty contacts / rows received.
Contacts not added for dialling (invalid, duplicate, do-not-call).
Rejected contacts per reason.
object
On the organisation’s do-not-call list.
Repeated in the request, or already in the campaign.
Not a valid phone number.
Pending → processing → succeeded | failed. Poll GET /v1/imports/{id}.
Rows added with a problem (the first 100).
object
The number as sent.
Row in the file (1-based, the header is row 1).
Marketing: contacts added without a consent record. The dialer skips them (§30A) unless consent is recorded first.
Example
{ "campaign_id": "cmp_2Yb7mCq9aPLk", "completed_at": "2026-11-02T07:00:03.870Z", "consent_recorded": 0, "created_at": "2026-11-02T07:00:00.000Z", "error": null, "errors": [ { "message": "too-short", "phone": "05012", "reason": "invalid", "row": 17 } ], "filename": "contacts.csv", "id": "imp_7RkXq2Lm9PvTz4nB1c8Ya", "imported": 4890, "livemode": true, "object": "import", "received": 5000, "rejected": 110, "rejected_reasons": { "dnc": 20, "duplicate": 40, "invalid": 50 }, "source": "csv", "started_at": "2026-11-02T07:00:00.120Z", "status": "succeeded", "warnings": [], "without_consent": 0}The request is invalid: a parameter is missing, malformed or unknown, or the version header is unknown.
Every /v1 error.
object
object
A stable, machine-readable code from the error-code catalogue.
Structured context, e.g. required_scope or the compliance verdict.
object
A link to the documentation of this code.
A human-readable explanation. Do not parse it.
The request parameter the error relates to, e.g. to or metadata[order_id].
The X-Request-Id of this request. Quote it when you contact support.
The category of the error.
Example
{ "error": { "code": "parameter_missing", "doc_url": "https://docs.morevoice.ai/api/errors#parameter-missing", "message": "Missing required parameter: to.", "param": "to", "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ", "type": "invalid_request_error" }}Headers
Section titled “Headers”The request’s ID (req_…). Quote it when you contact support.
No valid API key was sent.
Every /v1 error.
object
object
A stable, machine-readable code from the error-code catalogue.
Structured context, e.g. required_scope or the compliance verdict.
object
A link to the documentation of this code.
A human-readable explanation. Do not parse it.
The request parameter the error relates to, e.g. to or metadata[order_id].
The X-Request-Id of this request. Quote it when you contact support.
The category of the error.
Example
{ "error": { "code": "invalid_api_key", "doc_url": "https://docs.morevoice.ai/api/errors#invalid-api-key", "message": "Invalid API key.", "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ", "type": "authentication_error" }}Headers
Section titled “Headers”The request’s ID (req_…). Quote it when you contact support.
The key may not do this (a missing scope, a plan limit, or a compliance block).
Every /v1 error.
object
object
A stable, machine-readable code from the error-code catalogue.
Structured context, e.g. required_scope or the compliance verdict.
object
A link to the documentation of this code.
A human-readable explanation. Do not parse it.
The request parameter the error relates to, e.g. to or metadata[order_id].
The X-Request-Id of this request. Quote it when you contact support.
The category of the error.
Example
{ "error": { "code": "missing_scope", "doc_url": "https://docs.morevoice.ai/api/errors#missing-scope", "message": "This API key lacks the calls:write scope.", "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ", "type": "permission_error" }}Headers
Section titled “Headers”The request’s ID (req_…). Quote it when you contact support.
No object with this ID exists in this organisation and mode.
Every /v1 error.
object
object
A stable, machine-readable code from the error-code catalogue.
Structured context, e.g. required_scope or the compliance verdict.
object
A link to the documentation of this code.
A human-readable explanation. Do not parse it.
The request parameter the error relates to, e.g. to or metadata[order_id].
The X-Request-Id of this request. Quote it when you contact support.
The category of the error.
Example
{ "error": { "code": "resource_missing", "doc_url": "https://docs.morevoice.ai/api/errors#resource-missing", "message": "No such object: 'call_4Gk2'.", "param": "id", "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ", "type": "not_found" }}Headers
Section titled “Headers”The request’s ID (req_…). Quote it when you contact support.
The request conflicts with the object’s state, or the Idempotency-Key was reused with other parameters.
Every /v1 error.
object
object
A stable, machine-readable code from the error-code catalogue.
Structured context, e.g. required_scope or the compliance verdict.
object
A link to the documentation of this code.
A human-readable explanation. Do not parse it.
The request parameter the error relates to, e.g. to or metadata[order_id].
The X-Request-Id of this request. Quote it when you contact support.
The category of the error.
Example
{ "error": { "code": "idempotency_mismatch", "doc_url": "https://docs.morevoice.ai/api/errors#idempotency-mismatch", "message": "This Idempotency-Key was already used with different parameters.", "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ", "type": "idempotency_error" }}Headers
Section titled “Headers”The request’s ID (req_…). Quote it when you contact support.
Too many requests, or no call capacity right now. Retry after the Retry-After delay.
Every /v1 error.
object
object
A stable, machine-readable code from the error-code catalogue.
Structured context, e.g. required_scope or the compliance verdict.
object
A link to the documentation of this code.
A human-readable explanation. Do not parse it.
The request parameter the error relates to, e.g. to or metadata[order_id].
The X-Request-Id of this request. Quote it when you contact support.
The category of the error.
Example
{ "error": { "code": "rate_limited", "doc_url": "https://docs.morevoice.ai/api/errors#rate-limited", "message": "Too many requests. Retry after 1 second.", "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ", "type": "rate_limit_error" }}Headers
Section titled “Headers”Seconds to wait before retrying.
The request’s ID (req_…). Quote it when you contact support.
Something went wrong on MoreVoice’s side. Retry with the same Idempotency-Key.
Every /v1 error.
object
object
A stable, machine-readable code from the error-code catalogue.
Structured context, e.g. required_scope or the compliance verdict.
object
A link to the documentation of this code.
A human-readable explanation. Do not parse it.
The request parameter the error relates to, e.g. to or metadata[order_id].
The X-Request-Id of this request. Quote it when you contact support.
The category of the error.
Example
{ "error": { "code": "internal_error", "doc_url": "https://docs.morevoice.ai/api/errors#internal-error", "message": "Something went wrong on MoreVoice's side.", "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ", "type": "api_error" }}Headers
Section titled “Headers”The request’s ID (req_…). Quote it when you contact support.