Contacts

Store and manage your contact list. Add contacts individually or import them in bulk.

Contacts are the recipients you send to. Organise them into groups to target campaigns at a segment. All endpoints require the contacts scope.

List contacts

GET/api/v1/contacts

Query params

pageinteger: Page number (default 1)
page_sizeinteger: Results per page (default 20, max 100)
searchstring: Filter by name or phone number

curl -X GET "https://bulksmsapi.inline.co.ke/api/v1/contacts?search=Jane&page_size=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Create a contact

POST/api/v1/contacts

Parameters

phonestringrequired: Phone number in E.164 format (e.g. +254712345678)
first_namestring: First name
last_namestring: Last name
emailstring: Email address
notesstring: Free-text notes

curl -X POST "https://bulksmsapi.inline.co.ke/api/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+254712345678",
  "first_name": "Jane",
  "last_name": "Doe"
}'

Get a contact

GET/api/v1/contacts/{uuid}

curl -X GET "https://bulksmsapi.inline.co.ke/api/v1/contacts/contact-uuid" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Update a contact

PUT/api/v1/contacts/{uuid}

Same fields as create. Only provided fields are updated.

curl -X PUT "https://bulksmsapi.inline.co.ke/api/v1/contacts/contact-uuid" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane@example.com"
}'

Delete a contact

DELETE/api/v1/contacts/{uuid}

curl -X DELETE "https://bulksmsapi.inline.co.ke/api/v1/contacts/contact-uuid" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Bulk import (CSV/XLSX)

POST/api/v1/contacts/uploadmultipart/form-data

Upload a CSV or XLSX file with a required phone column. The import runs asynchronously, so poll the uploads endpoint until the status settles on completed or failed.

Form fields

filefilerequired: CSV or XLSX file. Required column: phone. Optional: first_name, last_name, email

curl

# Upload file
curl -X POST https://bulksmsapi.inline.co.ke/api/v1/contacts/upload \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@contacts.csv"

# Poll upload status list
curl https://bulksmsapi.inline.co.ke/api/v1/contacts/uploads \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Upload response

{
  "success": true,
  "data": { "upload_uuid": "upl-uuid", "status": "processing", "total": 500 }
}

Status poll

{
  "success": true,
  "data": { "uuid": "upl-uuid", "status": "completed", "imported": 498, "failed": 2 }
}

Next step

Once contacts are loaded, group them under Groups to target campaigns, and add opt-outs to your Blacklist.