Skip to content

Bulk import contacts

POST
/v1/organizations/{org}/contacts/import
curl --request POST \
--url https://api.caller9.app/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/contacts/import \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "rows": [ { "number": "example", "name": "example", "location": "example", "notes": "example", "tags": "example" } ], "skipDuplicates": true }'

Imports up to 5000 contacts in one request. The body is JSON (parse CSV or spreadsheet files client-side into rows). Rows without a usable number are skipped, as are duplicates when skipDuplicates is true.

org
required
string format: uuid

Organization ID (UUID). Must be the organization that owns the API key.

Media typeapplication/json
object
rows
required
Array<object>
<= 5000 items
object
number
required

Phone number, normalized to E.164 where possible.

string
name

Full name; split into first name and the rest as last name.

string
location
string
notes
string
tags

Comma-separated tags, e.g. vip, regular.

string
skipDuplicates

Skip rows whose number already exists in the organization or appears earlier in the same import.

boolean
default: true

Import result.

Media typeapplication/json
object
imported
required

Number of contacts created.

integer
skipped
required

Number of rows skipped (invalid or duplicate).

integer

Example generated

{
"imported": 1,
"skipped": 1
}

The request was invalid.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Missing, invalid, expired or revoked API key.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Not found, or belongs to another organization.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Too many requests for this API key. Retry after Retry-After seconds.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}
Retry-After
integer

Seconds until the rate-limit window resets.