---
title: "Create Contact"
description: "Create a single contact in your Bulkit account and optionally assign it to one group."
---

# Create Contact

Use this endpoint to create a single contact from your application.

## HTTP method and path

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

## 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>

## Request example

<CodeGroup>

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

```python python.py
import requests

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

payload = {
    "name": "John Doe",
    "phone_number": "0700000000",
    "email": "john@doe.com",
    "group_ids": [14],
}

response = requests.post(
    "https://api.bulkitsms.com/api/v2/contacts",
    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{}{
		"name":         "John Doe",
		"phone_number": "0700000000",
		"email":        "john@doe.com",
		"group_ids":    []int{14},
	}

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

	req, _ := http.NewRequest(http.MethodPost, "https://api.bulkitsms.com/api/v2/contacts", 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 = [
    "name" => "John Doe",
    "phone_number" => "0700000000",
    "email" => "john@doe.com",
    "group_ids" => [14]
];

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

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>

## Parameters

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `name` | Yes | string | Contact full name |
| `phone_number` | Yes | string | Contact mobile number |
| `email` | No | string | Contact email address |
| `group_ids` | No | array of integers/UUIDs | Group IDs for assignment. Only one group is supported for now |
| `custom_metadata` | No | object | Integration metadata payload accepted for compatibility |

## Success response example

```json
{
  "status": "success",
  "message": "Contact created successfully",
  "data": {
    "id": 442,
    "first_name": "John",
    "last_name": "Doe",
    "mobile": "254700000000",
    "email": "john@doe.com"
  }
}
```

## Error response examples

```json
{
  "status": "error",
  "message": "Invalid phone number"
}
```

```json
{
  "status": "error",
  "message": "Contact already exists"
}
```

```json
{
  "status": "error",
  "message": "Group not found"
}
```