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
page
integer
Page number (default 1)
page_size
integer
Results per page (default 20, max 100)
search
string
Filter by name or phone number
curl -X GET "https://timisha-solutions-api.salamu.co.ke/api/v1/contacts?search=Jane&page_size=50" \
-H "Authorization: Bearer YOUR_API_TOKEN"Create a contact
POST/api/v1/contacts
Parameters
phonereq
string
Phone number in E.164 format (e.g. +254712345678)
first_name
string
First name
last_name
string
Last name
email
string
Email address
notes
string
Free-text notes
curl -X POST "https://timisha-solutions-api.salamu.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://timisha-solutions-api.salamu.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://timisha-solutions-api.salamu.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://timisha-solutions-api.salamu.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
filereq
file
CSV or XLSX file. Required column: phone. Optional: first_name, last_name, email
curl
# Upload file
curl -X POST https://timisha-solutions-api.salamu.co.ke/api/v1/contacts/upload \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-F "file=@contacts.csv"
# Poll upload status list
curl https://timisha-solutions-api.salamu.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 }
}