---
title: "Bulk-import contacts"
method: POST
path: "/numbers/contacts/import"
tags: ["Contacts"]
---

# Bulk-import contacts

`POST /numbers/contacts/import`

Imports up to 1,000 contacts in one request. Each phoneNumber is normalized to E.164; rows that fail normalization are skipped (`invalid_phone`) rather than failing the whole request. Duplicate phone numbers within the batch are deduplicated, keeping the last occurrence (earlier ones are reported as `duplicate_in_file`). Existing contacts are updated by matching phone number; new ones are created. Rate-limited per owner — returns 429 when the limit is exceeded.

## Request body

- ImportContactsInput
  - `items` object[], required — At most 1000 rows per request.
    - `name` string, required
    - `phoneNumber` string, required — Raw, as typed. Normalized/validated server-side; a row that doesn't survive normalization, OR whose raw length exceeds 32 characters, is SKIPPED (not batch-failed) with reason "invalid_phone". This field's own 512-char schema cap is a memory bound only, not the real semantic limit.

## Response `200`

Import processed

- object
  - `data` ImportContactsResponse, required
    - `created` integer, required
    - `updated` integer, required
    - `skipped` ImportSkippedRow[], required
      - `row` integer, required — 0-based index into the request's `items` array.
      - `reason` 'invalid_phone' | 'duplicate_in_file', required

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `429` — Too many import requests — per-owner rate limit exceeded
- `500` — Internal Server Error

## Changes

- **2026-08-13** `02da4f9ce3fd` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/droidrun/apis/droidrun-cloud/changes/numbers/contacts/import/post.md)

---

[API](https://skmtc.dev/droidrun/apis/droidrun-cloud.md) · [All operations](https://skmtc.dev/droidrun/apis/droidrun-cloud/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/droidrun/droidrun-cloud/revisions/02da4f9ce3fd/schema)