Bulkit
Register

Create Multiple Contacts

Create many contacts in a single request with partial-success response handling.

Last updated · Markdown version

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

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

Parameters

ParameterRequiredTypeDescription
contactsYesarray of objectsList of contacts to create
contacts[].nameYesstringContact full name
contacts[].phone_numberYesstringContact mobile number
contacts[].emailNostringContact email address
contacts[].group_idsNoarray of integers/UUIDsOnly one group is supported for now
contacts[].custom_metadataNoobjectAccepted for compatibility

Request example

cURL / Bash
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"
      }
    ]
  }'

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
PreviousCreate ContactNextDelete Contact