Skip to content
MoreVoiceDevelopers

Add contacts to a campaign

POST
/campaigns/{id}/contacts
import { createClient, createResources } from "@morevoice/sdk";


const mv = createResources({
  client: createClient({ baseUrl: "https://api.morevoice.ai/v1", auth: process.env.MOREVOICE_API_KEY }),
});


const contactBatchResult = await mv.campaigns.contacts.create("cmp_ojFwMD7YNTROjaTP0i3ZFb", {
  contacts: [
    {
      consent: {
        channel: "web",
        granted_at: "2026-09-20T14:02:00+03:00",
        source: "website_form_2026",
      },
      name: "Dana Levi",
      phone: "+972501234567",
      variables: {
        plan: "Gold",
      },
    },
    {
      name: "Yossi Cohen",
      phone: "052-765-4321",
      variables: {
        plan: "Silver",
      },
    },
  ],
  default_country: "IL",
});
console.log(contactBatchResult);

Adds up to 1,000 contacts and answers what was added and what was left out, like a dashboard import of the same list: numbers are normalised and de-duplicated, do-not-call numbers are kept as dnc (never dialled), and in a marketing campaign a contact without consent evidence is added but skipped by the dialer (§30A).

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”
id
required
string
<= 200 characters /^cmp_[0-9A-Za-z]+$/

A campaign ID (cmp_…).

Header Parameters

Section titled “Header Parameters”
MoreVoice-Version
string
/^\d{4}-\d{2}-\d{2}$/

The API version to use for this request. Defaults to the version the API key is pinned to.

Example
2026-11-01
Idempotency-Key
string
>= 1 characters <= 255 characters

A 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-2b6d8e4c0a17

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Contacts to add, checked like a dashboard import: normalised, de-duplicated, scrubbed against the do-not-call list and, for marketing, consent.

object
contacts
required

Up to 1000 contacts.

Array<object>
>= 1 items <= 1000 items

A contact to add to a campaign.

object
consent

Marketing campaigns: the person’s consent with its evidence. Without it the contact is imported but not dialled.

object
channel
required

How they agreed.

string
Allowed values: web phone sms email whatsapp app written in_person other
granted_at
required

When the person agreed to marketing calls.

string format: date-time
source
required

Where they agreed, e.g. the form or campaign name.

string
>= 1 characters <= 200 characters
name
string
<= 200 characters
phone
required

The number, E.164 (+972…) or national (050-…, read with default_country).

string
>= 1 characters <= 40 characters
timezone

The contact’s IANA time zone, if not the campaign’s.

string
<= 64 characters
variables

Values for {{variables}} in the campaign’s first message and script.

object
key
additional properties
string
<= 500 characters
default_country

Country of numbers written without a country code (ISO 3166-1 alpha-2, default IL).

string
/^[A-Z]{2}$/
drop_dnc

Leave numbers on the do-not-call list out entirely (default false: they are kept with status dnc, for the record, and never dialled).

boolean

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json

What a batch added and why anything was left out.

object
campaign_id
required

A campaign ID (prefix cmp_).

string
/^cmp_[0-9A-Za-z]+$/
consent_recorded
required

Consent records created from the evidence sent.

integer
>= -9007199254740991 <= 9007199254740991
errors
required

Rejected contacts (the first 100).

Array<object>
object
index
required

Position in contacts (0-based).

integer
>= -9007199254740991 <= 9007199254740991
message
required
string
phone
required

The number as sent.

string
reason
required
string
Allowed values: invalid duplicate dnc consent_without_evidence
imported
required

Contacts added to the campaign for dialling.

integer
>= -9007199254740991 <= 9007199254740991
livemode
required

true in live mode, false in test mode.

boolean
object
required
string
Allowed value: contact_batch_result
received
required

Non-empty contacts / rows received.

integer
>= -9007199254740991 <= 9007199254740991
rejected
required

Contacts not added for dialling (invalid, duplicate, do-not-call).

integer
>= -9007199254740991 <= 9007199254740991
rejected_reasons
required

Rejected contacts per reason.

object
dnc
required

On the organisation’s do-not-call list.

integer
>= -9007199254740991 <= 9007199254740991
duplicate
required

Repeated in the request, or already in the campaign.

integer
>= -9007199254740991 <= 9007199254740991
invalid
required

Not a valid phone number.

integer
>= -9007199254740991 <= 9007199254740991
warnings
required

Contacts added with a problem, e.g. consent claimed without complete evidence (the first 100).

Array<object>
object
index
required

Position in contacts (0-based).

integer
>= -9007199254740991 <= 9007199254740991
message
required
string
phone
required

The number as sent.

string
reason
required
string
Allowed values: invalid duplicate dnc consent_without_evidence
without_consent
required

Marketing: contacts added without a consent record. The dialer skips them (§30A) unless consent is recorded first.

integer
>= -9007199254740991 <= 9007199254740991
Example
{
  "campaign_id": "cmp_2Yb7mCq9aPLk",
  "consent_recorded": 1,
  "errors": [
    {
      "index": 2,
      "message": "On the do-not-call list",
      "phone": "+972541112233",
      "reason": "dnc"
    }
  ],
  "imported": 2,
  "livemode": true,
  "object": "contact_batch_result",
  "received": 3,
  "rejected": 1,
  "rejected_reasons": {
    "dnc": 1,
    "duplicate": 0,
    "invalid": 0
  },
  "warnings": [],
  "without_consent": 1
}

400

Section titled “400”

The request is invalid: a parameter is missing, malformed or unknown, or the version header is unknown.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_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”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

401

Section titled “401”

No valid API key was sent.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_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”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

403

Section titled “403”

The key may not do this (a missing scope, a plan limit, or a compliance block).

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_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”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

404

Section titled “404”

No object with this ID exists in this organisation and mode.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_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”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

409

Section titled “409”

The request conflicts with the object’s state, or the Idempotency-Key was reused with other parameters.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_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”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

429

Section titled “429”

Too many requests, or no call capacity right now. Retry after the Retry-After delay.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_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”
Retry-After
integer

Seconds to wait before retrying.

X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

500

Section titled “500”

Something went wrong on MoreVoice’s side. Retry with the same Idempotency-Key.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_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”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.