---
title: "Create Multiple Contacts"
description: "Create many contacts in a single request with partial-success response handling."
---

# Create Multiple Contacts

Use this endpoint to create multiple contacts in one request.

## HTTP method and path

```http
POST /api/v2/contacts/bulk
```

## Authorization requirements

Authenticate using standard HTTP Bearer token:

```http
Authorization: Bearer bk_live_8n6JQv3K1h9Lp0Md
Content-Type: application/json
```

<Info>
For backward compatibility, Bulkit also accepts `apikey` and `apisecret` in the JSON request body or `X-API-Key` / `X-API-Secret` headers.
</Info>

## Parameters

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `contacts` | Yes | array of objects | List of contacts to create |
| `contacts[].name` | Yes | string | Contact full name |
| `contacts[].phone_number` | Yes | string | Contact mobile number |
| `contacts[].email` | No | string | Contact email address |
| `contacts[].group_ids` | No | array of integers/UUIDs | Only one group is supported for now |
| `contacts[].custom_metadata` | No | object | Accepted for compatibility |

## Request example

<CodeGroup>

```bash curl
curl -X POST "https://api.bulkitsms.com/api/v2/contacts/bulk" \
  -H "Authorization: Bearer bk_live_8n6JQv3K1h9Lp0Md" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "name": "Jane Doe",
        "phone_number": "0710000000",
        "email": "jane@doe.com",
        "group_ids": [14]
      },
      {
        "name": "Mark Otieno",
        "phone_number": "0722000000"
      }
    ]
  }'
```

```python python.py
import requests

headers = {
    "Authorization": "Bearer bk_live_8n6JQv3K1h9Lp0Md",
    "Content-Type": "application/json",
}

payload = {
    "contacts": [
        {"name": "Jane Doe", "phone_number": "0710000000", "email": "jane@doe.com", "group_ids": [14]},
        {"name": "Mark Otieno", "phone_number": "0722000000"}
    ]
}

response = requests.post(
    "https://api.bulkitsms.com/api/v2/contacts/bulk",
    json=payload,
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

```go main.go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	payload := map[string]interface{}{
		"contacts": []map[string]interface{}{
			{"name": "Jane Doe", "phone_number": "0710000000", "group_ids": []int{14}},
			{"name": "Mark Otieno", "phone_number": "0722000000"},
		},
	}

	body, err := json.Marshal(payload)
	if err != nil {
		panic(err)
	}

	req, _ := http.NewRequest(http.MethodPost, "https://api.bulkitsms.com/api/v2/contacts/bulk", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer bk_live_8n6JQv3K1h9Lp0Md")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]interface{}
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		panic(err)
	}
	fmt.Printf("%+v\n", result)
}
```

```php php
<?php

$payload = [
    "contacts" => [
        ["name" => "Jane Doe", "phone_number" => "0710000000", "group_ids" => [14]],
        ["name" => "Mark Otieno", "phone_number" => "0722000000"]
    ]
];

$ch = curl_init("https://api.bulkitsms.com/api/v2/contacts/bulk");

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer bk_live_8n6JQv3K1h9Lp0Md",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_THROW_ON_ERROR),
]);

$response = curl_exec($ch);

if ($response === false) {
    throw new Exception(curl_error($ch));
}

curl_close($ch);
echo $response . PHP_EOL;
```

</CodeGroup>

## Success response example

```json
{
  "status": "success",
  "message": "Contacts processed",
  "data": {
    "created_count": 2,
    "failed_count": 1,
    "contacts": [
      {
        "id": 501,
        "first_name": "Jane",
        "last_name": "Doe",
        "mobile": "254710000000"
      }
    ],
    "failures": [
      {
        "index": 2,
        "phone_number": "12345",
        "message": "Invalid phone number"
      }
    ],
    "warnings": []
  }
}
```

## Error response examples

```json
{
  "status": "error",
  "message": "Invalid credentials"
}
```

```json
{
  "status": "error",
  "message": "Invalid input"
}
```

## Notes

- bulk create supports partial success, so valid contacts can still be created when some rows fail
- use the `failures` array to identify records that should be corrected and retried