Retrieve a contact import

GET

/imports/{id}

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.imports.retrieve("imp_03Qu53ReMZGnf2tTFLIvVj");
console.log(contactImport);

import os

import requests

response = requests.get(
    "https://api.morevoice.ai/v1/imports/imp_03Qu53ReMZGnf2tTFLIvVj",
    headers={"Authorization": f"Bearer {os.environ['MOREVOICE_API_KEY']}"},
)
response.raise_for_status()
print(response.json())

Try it in the API playground with a test-mode key.

Authorizations

bearerAuth

Parameters

Path Parameters

required

string

<= 200 characters /^imp_[0-9A-Za-z]+$/

A import ID (imp_…).

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

Responses

200

application/json

A background contact-list import and its result. Poll it until status is succeeded or failed.

object

campaign_id

required

A campaign ID (prefix cmp_).

string

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

completed_at

required

Any of:

string
null

An ISO-8601 timestamp in UTC.

string format: date-time

consent_recorded

required

Consent records created from the evidence sent.

integer

>= -9007199254740991 <= 9007199254740991

created_at

required

An ISO-8601 timestamp in UTC.

string format: date-time

error

required

Any of:

object
null

object

code

required

string

message

required

string

errors

required

Rejected rows (the first 100).

Array<object>

object

message

required

string

phone

required

The number as sent.

string

reason

required

string

Allowed values: invalid duplicate dnc consent_without_evidence

row

required

Row in the file (1-based, the header is row 1).

integer

>= -9007199254740991 <= 9007199254740991

filename

required

string | null

required

A import ID (prefix imp_).

string

/^imp_[0-9A-Za-z]+$/

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: import

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

source

required

string

Allowed values: csv xlsx url

started_at

required

Any of:

string
null

An ISO-8601 timestamp in UTC.

string format: date-time

status

required

Pending → processing → succeeded | failed. Poll GET /v1/imports/{id}.

string

Allowed values: pending processing succeeded failed

warnings

required

Rows added with a problem (the first 100).

Array<object>

object

message

required

string

phone

required

The number as sent.

string

reason

required

string

Allowed values: invalid duplicate dnc consent_without_evidence

row

required

Row in the file (1-based, the header is row 1).

integer

>= -9007199254740991 <= 9007199254740991

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",
  "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
}

400

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

application/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

X-Request-Id

string

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

401

No valid API key was sent.

application/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

X-Request-Id

string

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

403

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

application/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

X-Request-Id

string

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

404

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

application/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

X-Request-Id

string

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

429

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

application/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

Retry-After

integer

Seconds to wait before retrying.

X-Request-Id

string

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

500

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

application/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

X-Request-Id

string

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