Contacts
The Contacts API enables you to add, update, delete, and manage individual contacts within your phonebooks.
Fetch contacts by phonebook ID
This endpoint retrieves a list of all contacts stored within a specified phonebook. The phonebook_id required for this request can be obtained using the Fetch Phonebooks endpoint.
Endpoint :
https://BASE_URL/api/phonebooks/{phonebook_id}/contacts?api_key=YourAPIKey
Request Type : GET
Sample Response - 200 OK
{
"headers": [
"phone number"
],
"phonebook": {
"id": "6821eb366a25331e3c159362",
"applicationId": "33217",
"description": "",
"createdAt": "2025-05-12 12:36:06",
"phonebook_name": "12 contacts",
"total_contact": 12,
"total_campaign": 9
},
"data": {
"content": [
{
"id": "6821eb376a25331e3c159364",
"pid": "6821eb366a25331e3c159362",
"phone_number": "2348139538813",
"contact_list_key_value": [
{
"key": "phone number",
"value": "8139538813"
}
]
},
{
"id": "6821eb376a25331e3c159365",
"pid": "6821eb366a25331e3c159362",
"phone_number": "2348034258098",
"contact_list_key_value": [
{
"key": "phone number",
"value": "8034258098"
}
]
},
{
"id": "6821eb376a25331e3c159366",
"pid": "6821eb366a25331e3c159362",
"phone_number": "2347065250817",
"contact_list_key_value": [
{
"key": "phone number",
"value": "7065250817"
}
]
},
{
"id": "6821eb376a25331e3c159367",
"pid": "6821eb366a25331e3c159362",
"phone_number": "2349055240370",
"contact_list_key_value": [
{
"key": "phone number",
"value": "9055240370"
}
]
},
{
"id": "6821eb376a25331e3c159368",
"pid": "6821eb366a25331e3c159362",
"phone_number": "2348140982424",
"contact_list_key_value": [
{
"key": "phone number",
"value": "8140982424"
}
]
},
{
"id": "6821eb376a25331e3c159369",
"pid": "6821eb366a25331e3c159362",
"phone_number": "2349063674054",
"contact_list_key_value": [
{
"key": "phone number",
"value": "9063674054"
}
]
},
{
"id": "6821eb376a25331e3c15936a",
"pid": "6821eb366a25331e3c159362",
"phone_number": "2348108664000",
"contact_list_key_value": [
{
"key": "phone number",
"value": "8108664000"
}
]
},
{
"id": "6821eb376a25331e3c15936b",
"pid": "6821eb366a25331e3c159362",
"phone_number": "2348088355539",
"contact_list_key_value": [
{
"key": "phone number",
"value": "8088355539"
}
]
},
{
"id": "6821eb376a25331e3c15936c",
"pid": "6821eb366a25331e3c159362",
"phone_number": "2347035592428",
"contact_list_key_value": [
{
"key": "phone number",
"value": "7035592428"
}
]
},
{
"id": "6821eb376a25331e3c15936d",
"pid": "6821eb366a25331e3c159362",
"phone_number": "2347089509657",
"contact_list_key_value": [
{
"key": "phone number",
"value": "7089509657"
}
]
},
{
"id": "6821eb376a25331e3c15936e",
"pid": "6821eb366a25331e3c159362",
"phone_number": "2349011485199",
"contact_list_key_value": [
{
"key": "phone number",
"value": "9011485199"
}
]
},
{
"id": "6821eb376a25331e3c159363",
"pid": "6821eb366a25331e3c159362",
"phone_number": "2349015576494",
"contact_list_key_value": [
{
"key": "phone number",
"value": "9015576494"
}
]
}
],
"pageable": {
"sort": {
"empty": false,
"sorted": true,
"unsorted": false
},
"offset": 0,
"pageNumber": 0,
"pageSize": 15,
"paged": true,
"unpaged": false
},
"totalPages": 1,
"totalElements": 12,
"last": true,
"sort": {
"empty": false,
"sorted": true,
"unsorted": false
},
"size": 15,
"number": 0,
"first": true,
"numberOfElements": 12,
"empty": false
}
}
Add single contacts to phonebook
This endpoint allows you to add an individual contact to an existing phonebook.
Endpoint :
https://BASE_URL/api/phonebooks/{phonebook_id}/contacts
Request Type : POST
`
Request Body Params:
Options | Required | Description |
---|---|---|
api_key | yes | string Your API key (It can be found on your Termii dashboard). |
phone_number | yes | string This is the phone number to be added to the phonebook |
country_code | no | string Represents short numeric geographical codes developed to represent countries ( Example: 234 ) . |
email_address | no | string This is the email address of the contact to be added |
first_name | no | string This is the first name of the contact to be added |
last_name | no | string This is the last name of the contact to be addedt |
company | no | string This is the name of the company of the contact to be added |
{
"api_key": "Your API Key",
"phone_number":"8123696237",
"email_address":"test@gmail.com",
"first_name": "test",
"last_name": "contact",
"company": "Termii",
"country_code": "234"
}
var data = {
"api_key": "Your API Key",
"phone_number":"8123696237",
"email_address":"test@gmail.com",
"first_name": "test",
"last_name": "contact",
"company": "Termii",
"country_code": "234"
};
var data = JSON.stringify(data);
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://BASE_URL/api/phonebooks/{phonebook_id}/contacts");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.send(data);
var request = require('request');
var data = {
"api_key": "Your API Key",
"phone_number":"8123696237",
"email_address":"test@gmail.com",
"first_name": "test",
"last_name": "contact",
"company": "Termii",
"country_code": "234"
};
var options = {
'method': 'POST',
'url': 'https://BASE_URL/api/phonebooks/{phonebook_id}/contacts',
'headers': {
'Content-Type': ['application/json', 'application/json']
},
body: JSON.stringify(data)
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
import requests
url = "https://BASE_URL/api/phonebooks/{phonebook_id}/contacts"
payload = {
"api_key": "Your API Key",
"phone_number":"8123696237",
"email_address":"test@gmail.com",
"first_name": "test",
"last_name": "contact",
"company": "Termii",
"country_code": "234"
}
headers = {
'Content-Type': 'application/json',
}
response = requests.request("POST", url, headers=headers, json=payload)
print(response.text)
RestClient restClient = new RestClient("https://BASE_URL/api/phonebooks/{phonebook_id}/contacts");
//Creating Json object
JObject objectBody = new JObject();
objectBody.Add("api_key","Your API Key");
objectBody.Add("phone_number", "8123696237");
objectBody.Add("email_address", "test@gmail.com");
objectBody.Add("first_name", "test");
objectBody.Add("last_name", "contact");
objectBody.Add("company", "Termii");
objectBody.Add("country_code", "234");
RestRequest restRequest = new RestRequest(Method.POST);
restRequest.AddHeader("Content-Type", "application/json");
restRequest.AddParameter("application/json", objectBody, ParameterType.RequestBody);
IRestResponse restResponse = restClient.Execute(restRequest);
Console.WriteLine(restResponse.Content);
Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://BASE_URL/api/phonebooks/{phonebook_id}/contacts")
.header("Content-Type", "application/json")
.body(" {\r\n \"api_key\": \"Your API Key\",\r\n \
"phone_number\":\"8123696237\",\r\n \
"email_address\":\"test@gmail.com\",\r\n \
"first_name\": \"test\",\r\n \
"last_name\": \"contact\",\r\n \
"company\": \"Termii\",\r\n \
"country_code\": \"234\"\r\n}")
.asString();
<?php
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://BASE_URL/api/phonebooks/{phonebook_id}/contacts',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>' {
"api_key": "Your API Key",
"phone_number":"8123696237",
"email_address":"test@gmail.com",
"first_name": "test",
"last_name": "contact",
"company": "Termii",
"country_code": "234"
}',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
Sample Response - 200 OK
{
"Contact added successfully": {
"id": "68946d4de81586185107a96c",
"company": "Termii",
"created_at": "2025-08-07 09:09:33",
"updated_at": "2025-08-07 09:09:33",
"phone_number": "2347068410455",
"email_address": "test@gmail.com",
"first_name": "Promise",
"last_name": "John"
}
}
Add multiple contacts to phonebook
This endpoint allows you to add multiple contacts to an existing phonebook in a single request.
Endpoint :
https://BASE_URL/api/phonebooks/contacts/upload
Request Type : POST
Options | Required | Description |
---|---|---|
api_key | yes | string Your API key (It can be found on your Termii dashboard). |
file | yes | string sample csv file containing phone numbers. |
country_code | yes | string Represents short numeric geographical codes developed to represent countries ( Example: 234 ) . |
pid | yes | string The unique ID of the phonebook where the contacts should be uploaded |
curl --location 'https://BASE_URL/api/phonebooks/contacts/upload' \
--form 'file=@"/Users/vpicg/Desktop/Contact - Sheet1.csv"' \
--form 'contact="{\"pid\": \"6821eb366a25331e3c159362\", \"country_code\": \"234\", \"api_key\": \"Your API Key\"}";type=application/json'
const formData = new FormData();
formData.append("file", document.querySelector("#fileInput").files[0]);
formData.append(
"contact",
JSON.stringify({
pid: "12345",
country_code: "234",
api_key: "your_api_key",
})
);
fetch("https://BASE_URL/api/phonebooks/contacts/upload", {
method: "POST",
body: formData,
})
.then((response) => response.json())
.then((data) => console.log(data))
.catch((error) => console.error("Error:", error));
const axios = require("axios");
const FormData = require("form-data");
const fs = require("fs");
const formData = new FormData();
formData.append("file", fs.createReadStream("path/to/your/file.csv"));
formData.append(
"contact",
JSON.stringify({
pid: "12345",
country_code: "234",
api_key: "your_api_key",
})
);
axios.post("https://BASE_URL/api/phonebooks/contacts/upload", formData, {
headers: formData.getHeaders(),
})
.then((response) => console.log(response.data))
.catch((error) => console.error("Error:", error));
import requests
url = "https://BASE_URL/api/phonebooks/contacts/upload"
file_path = "path/to/your/file.csv"
files = {"file": open(file_path, "rb")}
data = {
"contact": '{"pid": "12345", "country_code": "234", "api_key": "your_api_key"}'
}
response = requests.post(url, files=files, data=data)
print("Status Code:", response.status_code)
print("Response:", response.text)
using System;
using System.IO;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
static async Task Main(string[] args)
{
var client = new HttpClient();
var url = "https://BASE_URL/api/phonebooks/contacts/upload";
using var form = new MultipartFormDataContent();
using var fileStream = File.OpenRead("path/to/your/file.csv");
form.Add(new StreamContent(fileStream), "file", "file.csv");
form.Add(new StringContent("{\"pid\": \"12345\", \"country_code\": \"234\", \"api_key\": \"your_api_key\"}"), "contact");
var response = await client.PostAsync(url, form);
Console.WriteLine(await response.Content.ReadAsStringAsync());
}
}
import java.io.File;
import java.io.IOException;
import okhttp3.*;
public class FileUploadExample {
public static void main(String[] args) throws IOException {
OkHttpClient client = new OkHttpClient();
File file = new File("path/to/your/file.csv");
RequestBody requestBody = new MultipartBody.Builder()
.setType(MultipartBody.FORM)
.addFormDataPart("file", file.getName(),
RequestBody.create(file, MediaType.parse("text/csv")))
.addFormDataPart(
"contact",
"{\"pid\": \"12345\", \"country_code\": \"234\", \"api_key\": \"your_api_key\"}"
)
.build();
Request request = new Request.Builder()
.url("https://BASE_URL/api/phonebooks/contacts/upload")
.post(requestBody)
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
}
}
<?php
<?php
$curl = curl_init();
$filePath = "path/to/your/file.csv";
$file = new CURLFile($filePath);
$data = [
"file" => $file,
"contact" => json_encode([
"pid" => "12345",
"country_code" => "234",
"api_key" => "your_api_key",
]),
];
curl_setopt_array($curl, [
CURLOPT_URL => "https://BASE_URL/api/phonebooks/contacts/upload",
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $data,
CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
Sample Response - 200 OK
{
"message": "Your list is being uploaded in the background. Go ahead with other things while we handle this. Please note that it could take a couple minutes to get it done."
}
Delete Contact in a Phonebook
This endpoint allows you to delete an existing contact from a specified phonebook.
Endpoint :
https://BASE_URL/api/phonebooks/{phonebook_id}/contacts
Request Type : DELETE
Sample Response - 200 OK
{
"code": 200,
"data": {
"message": "Contact has been deleted"
},
"message": "Deleted Successfully",
"status": "success"
}