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

# Bulk import contacts

`POST /v1/contacts/bulk-import`

## Request

- Base URL: `https://api.samva.dev`
- URL: `https://api.samva.dev/v1/contacts/bulk-import`
- Auth: API key in header `x-api-key`

Creates contacts in bulk from a list of entries shaped like a create request, returning per-entry results with created, updated, skipped, and error counts. An entry whose identities match an existing contact is skipped, or updates it with `onConflict: "update"`.

## Request body

- object
  - `namespaceId` string
  - `contacts` object[], required
    - `name` string, required
    - `displayName` string, nullable
    - `avatar` string, nullable
    - `identities` ContactIdentityInput[], nullable
      - `type` 'email' | 'phone', required
      - `identifier` string, required
      - `verified` boolean, nullable
    - `profile` ContactProfile
      - `firstName` string, nullable
      - `lastName` string, nullable
      - `company` string, nullable
      - `jobTitle` string, nullable
      - `location` ContactLocation
        - `country` string, required
        - `state` string, required
        - `city` string, required
        - `timezone` string, required
      - `customFields` ContactCustomFields
      - `source` 'api' | 'import' | 'manual' | 'form', nullable
    - `preferences` ContactPreferences
      - `preferredChannels` string[], nullable
      - `language` string, nullable
      - `timezone` string, nullable
      - `notifications` object, nullable
        - `email` boolean, nullable
        - `quiet_hours` object, nullable
          - `start` string, required
          - `end` string, required
    - `tags` string[], nullable
    - `status` 'active' | 'paused' | 'blocked' | 'archived', nullable
    - `statusReason` string, nullable
    - `externalId` string, nullable
    - `metadata` JsonObject
  - `onConflict` 'skip' | 'update', nullable

## Response `200`

Success

- object
  - `total` integer, required
  - `created` integer, required
  - `updated` integer, required
  - `skipped` integer, required
  - `errors` integer, required
  - `results` object[], required
    - `index` integer, required
    - `status` 'created' | 'updated' | 'skipped' | 'error', required
    - `contactId` string
    - `error` string, nullable

## Other responses

- `401`: UnauthorizedError
- `402`: PaymentRequiredError
- `403`: ForbiddenError
- `404`: ResourceNotFoundError
- `422`: ValidationError
- `500`: InternalError
- `502`: BillingProviderError
- `504`: GatewayTimeoutError

---

[API](https://skmtc.dev/samva/apis/samva-api.md) · [All operations](https://skmtc.dev/samva/apis/samva-api/llms.txt) · [OpenAPI document](https://skmtc.dev/samva/apis/samva-api/revisions/a99408542cc3?raw)