Bulk operations

Efficiently create multiple contacts at once. Perfect for importing large subscriber lists.

POST /api/v1/projects/:project_id/contacts/bulk

Create multiple contacts in a single request. The API processes contacts in batches and returns detailed results including any validation errors. Duplicate emails within the batch or existing contacts will be skipped.

Parameters

Name	Type	Required	Description
project_id	integer	Yes	The project ID

Request body

client.bulk_create_contacts(
  project_id: 1,
  contacts: [
    {
      email: 'user1@example.com',
      first_name: 'John',
      last_name: 'Doe'
    },
    {
      email: 'user2@example.com',
      first_name: 'Jane',
      last_name: 'Smith'
    }
  ]
)

Success response (201)

{
  "data" => {
    "created" => 2,
    "failed" => 0,
    "contacts" => [
      {
        "id" => 1,
        "email" => "user1@example.com",
        "first_name" => "John",
        "last_name" => "Doe",
        "created_at" => "2024-01-01T00:00:00Z"
      },
      {
        "id" => 2,
        "email" => "user2@example.com",
        "first_name" => "Jane",
        "last_name" => "Smith",
        "created_at" => "2024-01-01T00:00:00Z"
      }
    ],
    "errors" => []
  }
}

Error responses

Status: 422 - validation_error

{
  "data" => {
    "created" => 1,
    "failed" => 2,
    "contacts" => [
      {
        "id" => 1,
        "email" => "user1@example.com",
        "first_name" => "John",
        "last_name" => "Doe",
        "created_at" => "2024-01-01T00:00:00Z"
      }
    ],
    "errors" => [
      {
        "email" => "invalid-email",
        "errors" => {
          "email" => ["is not a valid email address"]
        }
      },
      {
        "email" => "user1@example.com",
        "errors" => {
          "email" => ["already exists in this project"]
        }
      }
    ]
  }
}

Status: 206 - partial_content

{
  "data" => {
    "created" => 5000,
    "failed" => 100,
    "contacts" => [],
    "errors" => [...],
    "batch_results" => {
      "successful_batches" => [1, 2],
      "failed_batches" => [3],
      "batch_errors" => [
        {
          "batch" => 3,
          "error" => "Database error",
          "record_count" => 100
        }
      ]
    },
    "message" => "Partially completed: 5000 contacts created, 1 batch(es) failed"
  }
}

Performance notes

Contacts are processed in batches of 10,000 for optimal performance
Duplicate emails within the batch are automatically skipped
Contacts that already exist in the project are skipped
Validation errors are returned for individual contacts without failing the entire request
For very large imports, the API may return a 206 Partial Content status if some batches fail