Thanks to visit codestin.com
Credit goes to developer.termii.com

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":"[email protected]",
    "first_name": "test",
    "last_name": "contact",
    "company": "Termii",
    "country_code": "234"
}
 var data = {
              "api_key": "Your API Key",
              "phone_number":"8123696237",
              "email_address":"[email protected]",
              "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":"[email protected]",
                "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":"[email protected]",
              "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", "[email protected]");
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\":\"[email protected]\",\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":"[email protected]",
  "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": "[email protected]",
    "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, Tuesday, April 14, 2026