---
title: "Batch Create Contact Entries"
method: POST
path: "/v1/contact-entries"
tags: ["contacts"]
---

# Batch Create Contact Entries

`POST /v1/contact-entries`

Add entries to existing contact lists in batch (up to 100 items per request).

Unlike single-resource `POST` endpoints, the body wraps the payloads in
`items` and the response reports a per-item status.

Requires the `contact_lists:write` scope on the API key.

## Request body

- CreateContactEntriesInput
  - `items` ContactEntryInput[], required — Contact entries to create.
    - `contact_list_id` string, uuid, required — ID of the contact list to add this entry to.
    - `first_name` string, nullable — First name.
    - `last_name` string, nullable — Last name.
    - `email` string, nullable — Email. At least one of `email` or `linkedin_url` is required.
    - `linkedin_url` string, nullable — LinkedIn profile URL. At least one of `email` or `linkedin_url` is required.
    - `company_name` string, nullable — Employer name.
    - `company_domain` string, nullable — Employer's primary domain.
    - `job_title` string, nullable — Job title.
    - `phone` string, nullable — Phone number.
    - `external_contact_id` string, nullable — External CRM contact identifier for CRM-backed list entries.

## Response `200`

Successful Response

- BatchResponseContactEntryOutput
  - `items` BatchItemResultContactEntryOutput[], required
    - `index` integer, required
    - `status` 'CREATED' | 'UPDATED' | 'FAILED', required
    - `resource` ContactEntryOutput
      - `id` string, uuid, required — Unique identifier.
      - `contact_list_id` string, uuid, required — ID of the list this entry belongs to.
      - `contact_id` string, uuid, nullable, required — ID of the contact this entry resolved to, once matched.
      - `external_contact_id` string, nullable, required — External CRM contact identifier when supplied at import.
      - `first_name` string, nullable, required — First name.
      - `last_name` string, nullable, required — Last name.
      - `email` string, nullable, required — Email.
      - `linkedin_url` string, nullable, required — LinkedIn URL.
      - `company_name` string, nullable, required — Employer name.
      - `company_domain` string, nullable, required — Employer domain.
      - `job_title` string, nullable, required — Job title.
      - `phone` string, nullable, required — Phone number.
      - `description` string, nullable, required — Free-form notes.
      - `location` string, nullable, required — Person's location.
      - `created_at` string, date-time, required — When the entry was created.
      - `updated_at` string, date-time, required — When the entry last changed.
    - `error` BatchItemError
      - `type` string, required
      - `message` string, required
  - `summary` BatchSummary, required
    - `total` integer, required
    - `succeeded` integer, required
    - `failed` integer, required

---

[API](https://skmtc.net/topo/apis/topo-public-api.md) · [All operations](https://skmtc.net/topo/apis/topo-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/topo/topo-public-api/revisions/80f4fd40b75e/schema)