> ## Documentation Index
> Fetch the complete documentation index at: https://usegately.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk Import Contacts

> Import up to 1,000 contacts in a single request

Duplicate emails within the project are skipped. The response includes a per-row error list for any contacts that failed validation.

## Headers

<ParamField header="Authorization" type="string" required>
  `Bearer YOUR_API_KEY`
</ParamField>

<ParamField header="X-Project-ID" type="string">
  Your project UUID. Not required if the API key already encodes the project.
</ParamField>

## Request Body

<ParamField body="contacts" type="object[]" required>
  Array of contact objects to import (max 1,000).

  <Expandable title="Contact fields">
    <ParamField body="name" type="string" required>Full name</ParamField>
    <ParamField body="email" type="string" required>Email address</ParamField>
    <ParamField body="phone" type="string">Phone number</ParamField>
    <ParamField body="company" type="string">Company name</ParamField>
    <ParamField body="status" type="string">Initial status (default `new`)</ParamField>
    <ParamField body="tags" type="string[]">Tag names to attach</ParamField>
    <ParamField body="custom_fields" type="object">Custom field key-value pairs</ParamField>
    <ParamField body="external_id" type="string">Your own identifier for this contact</ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="success" type="boolean">Whether the import completed without a fatal error</ResponseField>
<ResponseField name="imported" type="number">Number of contacts successfully created</ResponseField>
<ResponseField name="skipped" type="number">Number of contacts skipped (duplicates or validation failures)</ResponseField>

<ResponseField name="errors" type="object[]">
  Per-row error details

  <Expandable title="Error fields">
    <ResponseField name="row" type="number">0-based row index in the input array</ResponseField>
    <ResponseField name="email" type="string">Email of the failed contact</ResponseField>
    <ResponseField name="error" type="string">Reason for failure</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="message" type="string">Human-readable summary</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.usegately.com/api/v1/contacts/bulk-import" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "X-Project-ID: YOUR_PROJECT_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "contacts": [
        { "name": "Alice", "email": "alice@example.com", "tags": ["Newsletter"] },
        { "name": "Bob",   "email": "bob@example.com",   "company": "Acme" }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch('https://api.usegately.com/api/v1/contacts/bulk-import', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'X-Project-ID': 'YOUR_PROJECT_ID',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      contacts: [
        { name: 'Alice', email: 'alice@example.com', tags: ['Newsletter'] },
        { name: 'Bob',   email: 'bob@example.com',   company: 'Acme' },
      ],
    }),
  })
  const result = await res.json()
  ```

  ```typescript SDK theme={null}
  import { GatelyContacts } from '@gately/sdk'

  const crm = new GatelyContacts({ projectId: 'YOUR_PROJECT_ID' })

  const result = await crm.bulkImport([
    { name: 'Alice', email: 'alice@example.com', tags: ['Newsletter'] },
    { name: 'Bob',   email: 'bob@example.com',   company: 'Acme' },
  ])

  console.log(`Imported: ${result.imported}, Skipped: ${result.skipped}`)
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "success": true,
    "imported": 2,
    "skipped": 0,
    "errors": [],
    "message": "Successfully imported 2 contacts"
  }
  ```

  ```json Partial success theme={null}
  {
    "success": true,
    "imported": 1,
    "skipped": 1,
    "errors": [
      { "row": 1, "email": "bob@example.com", "error": "Email already exists" }
    ],
    "message": "Successfully imported 1 contacts"
  }
  ```
</ResponseExample>