> ## Documentation Index
> Fetch the complete documentation index at: https://docs-staging.termii.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contacts

> Contacts API allows you manage (i.e. edit, update, & delete) contacts in your phonebook.

## Fetch contacts by phonebook ID

**Endpoint:** `https://BASE_URL/api/phonebooks/{phonebook_id}/contacts?api_key=YourAPIKey`

**Request Type:** `GET`

```
{
    "data": [
        {
            "id": 3,
            "pid": 4,
            "phone_number": "2347062609181",
            "email_address": null,
            "message": null,
            "company": null,
            "first_name": null,
            "last_name": null,
            "create_at": "2021-06-30 12:02:15",
            "updated_at": "2021-06-30 12:02:15"
        },
        {
            "id": 4,
            "pid": 4,
            "phone_number": "2347051428948",
            "email_address": null,
            "message": null,
            "company": null,
            "first_name": null,
            "last_name": null,
            "create_at": "2021-06-30 12:02:20",
            "updated_at": "2021-06-30 12:02:20"
        },
        {
            "id": 5,
            "pid": 4,
            "phone_number": "2348173343852",
            "email_address": null,
            "message": null,
            "company": null,
            "first_name": null,
            "last_name": null,
            "create_at": "2021-06-30 12:02:20",
            "updated_at": "2021-06-30 12:02:20"
        },
        {
            "id": 6,
            "pid": 4,
            "phone_number": "2348057616056",
            "email_address": null,
            "message": null,
            "company": null,
            "first_name": null,
            "last_name": null,
            "create_at": "2021-06-30 12:02:20",
            "updated_at": "2021-06-30 12:02:20"
        },
        {
            "id": 7,
            "pid": 4,
            "phone_number": "2348060463787",
            "email_address": null,
            "message": null,
            "company": null,
            "first_name": null,
            "last_name": null,
            "create_at": "2021-06-30 12:02:20",
            "updated_at": "2021-06-30 12:02:20"
        }
       
    ],
  
    "links": {
        "first": "https://BASE_URL/api/phonebooks/04c3ebcc-3a7e-485a-88c1-68e731386f77/contacts?page=1",
        "last": "https://BASE_URL/api/phonebooks/04c3ebcc-3a7e-485a-88c1-68e731386f77/contacts?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://BASE_URL/api/phonebooks/04c3ebcc-3a7e-485a-88c1-68e731386f77/contacts",
        "per_page": 25,
        "to": 22,
        "total": 22
    }
}
```

## Add single contacts to phonebook

**Endpoint:** `https://BASE_URL/api/phonebooks/{phonebook_id}/contacts`

**Request Type:** `POST`

**Body params:**

| Options        | Required | Description                                                                                                     |
| -------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| api\_key       | yes      | *string* <br /> Your API key (It can be found on your [Termii dashboard](https://app.termii.com))               |
| phone\_number  | yes      | *string* <br /> Phone number of the contact                                                                     |
| country\_code  | no       | *string* <br /> Represents short numeric geographical codes developed to represent countries (`Example: 234` ). |
| email\_address | no       | *string* <br /> email address of the contact                                                                    |
| first\_name    | yes      | *string* <br /> first name of the contact                                                                       |
| last\_name     | yes      | *string* <br /> last name of the contact                                                                        |
| company        | yes      | *string* <br /> name of the company of the contact                                                              |

<CodeGroup>
  ```json JSON theme={null}
  {
  "api_key": "Your API Key",
  "phone_number":"8123696237",
  "email_address":"test@gmail.com",
  "first_name": "test",
  "last_name": "contact",
  "company": "Termii",
  "country_code": "234"
  }
  ```

  ```json JavaScript theme={null}
  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);
  ```

  ```json NodeJs theme={null}
  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);
  });
  ```

  ```json Python theme={null}
  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)
  ```

  ```json C# theme={null}
  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);
  ```

  ```json Java theme={null}
  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();
  ```

  ```json Php theme={null}
  <?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;
  ?>
  ```
</CodeGroup>

**Response**

```
  {
    "data": {
      "id": 3647982,
      "phone_number": "2448123696237",
      "email_address": "test@gmail.com",
      "message": null,
      "company": "Termii",
      "first_name": "test",
      "last_name": "contact",
      "create_at": "2021-10-11 10:15:35",
      "updated_at": "2021-10-11 10:15:35"
    }
}
```

## Add multiple contacts to phonebook

**Endpoint:** `https://BASE_URL/api/phonebooks/contacts/upload`

**Request Type:** `POST`

Content-Type for "contact" should be "application/json". Content-Type in headers should be auto generated as multipart/form-data

| Options       | Required | Description                                                                                                     |
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| api\_key      | yes      | *string* <br /> Your API key (It can be found on your [Termii dashboard](https://app.termii.com))               |
| file          | yes      | *string* <br /> sample csv file containing phone numbers.                                                       |
| country\_code | no       | *string* <br /> Represents short numeric geographical codes developed to represent countries (`Example: 234` ). |
| pid           | yes      | *string* <br /> Phonebook ID                                                                                    |

<CodeGroup>
  ```json CURL theme={null}
  curl -X POST https://BASE_URL/api/phonebooks/contacts/upload \
  -F "file=@path/to/your/file.csv" \
  -F 'contact={"pid": "12345", "country_code": "234", "api_key": "your_api_key"}'
  ```

  ```json JavaScript theme={null}
  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));
  ```

  ```json NodeJs theme={null}
  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));
  ```

  ```json Python theme={null}
  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)
  ```

  ```json C# theme={null}
  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);
  ```

  ```json Java theme={null}
  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());
  }
  }
  ```

  ```json Php theme={null}
  <?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;
  ?>
  ```
</CodeGroup>

**Response:**

```
 {

    "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

**Endpoint:** `https://BASE_URL/api/phonebook/contacts/delete/contact_id?api_key=YourAPIKey`

**Request Type:** `DELETE`

**Response**

```
   {

        "message":"Contact deleted successfully"
  
  }
```