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:

OptionsRequiredDescription
api_keyyesstring
Your API key (It can be found on your Termii dashboard).
phone_numberyesstring
This is the phone number to be added to the phonebook
country_codenostring
Represents short numeric geographical codes developed to represent countries (Example: 234 ) .
email_addressnostring
This is the email address of the contact to be added
first_namenostring
This is the first name of the contact to be added
last_namenostring
This is the last name of the contact to be addedt
companynostring
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

Content-Type for "contact" should be set to "application/json". Content-Type in headers should be auto generated as multipart/form-data
OptionsRequiredDescription
api_keyyesstring
Your API key (It can be found on your Termii dashboard).
fileyesstring
sample csv file containing phone numbers.
country_codeyesstring
Represents short numeric geographical codes developed to represent countries (Example: 234 ) .
pidyesstring
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"
}

Updated at, Thursday, September 11, 2025