# List contacts

> GET https://api.nabrah.ai/api/ext/omni_v2/contact

Group: Contacts. Page: https://www.nabrah.ai/en/docs/api-reference/contacts/list-contacts

Returns a paginated list of all contacts in the project the API key is scoped to. Contacts are the people your workspace communicates with across every Omni v2 channel (WhatsApp, web chat, email, and so on). Each contact in the list includes its numeric `id` (the `contact_id` you pass to every other Contacts endpoint), core fields such as `name`, `email`, and `phone_number`, plus structured `additional_attributes` and free-form `custom_attributes`. Use the `sort` query parameter to control ordering and `page` to walk through large result sets.

## Authentication

All Omni v2 endpoints authenticate with a Web API key.

- **X-API-Key header**: Send your key in the `X-API-Key` header (e.g. `X-API-Key: nb_...`). Keys are created in the dashboard under the Developers tab and are prefixed with `nb_`. Each key is scoped to a single project, so there is no `project_id` parameter on this endpoint. You can validate a key with `GET /api/ext/test`.

## Pagination

Results are returned one page at a time.

- **Reading meta**: The response `meta` object reports the total `count` of contacts and the `current_page` you are viewing. Use these to decide whether more pages remain. Fields: `meta.count`, `meta.current_page`.
- **Paging through results**: Pass `?page=1` for the first page and increment `page` until the returned `payload` array is empty (or you have retrieved `meta.count` contacts). When `page` is omitted the first page is returned.

Each contact's `id` field is the `contact_id` used by the get, update, conversations, ticket, and WhatsApp endpoints.

## Contact fields

- **additional_attributes**: A structured object of standard profile fields: `city`, `country`, `description`, `company_name`, `country_code`, and `social_profiles`. Fields: `city`, `country`, `description`, `company_name`, `country_code`, `social_profiles`.
- **custom_attributes**: A free-form key/value object holding workspace-defined custom fields for the contact.

## Authorization

- `X-API-Key` (string, header, required): your workspace API key.

## Query parameters

- `page` (integer, optional): 1-based page number to retrieve. Omit to fetch the first page. Increment until the returned payload array is empty to iterate over all contacts.
- `sort` (string, optional): Attribute used to order the returned contacts. Accepted values: last_activity_at, name, email, phone_number. Prefix any value with a hyphen (e.g. -last_activity_at, -name, -email, -phone_number) to sort in descending order.

## Response

### 200 Successful Response

Content type: `application/json`

```json
{
  "meta": {
    "count": 0,
    "current_page": "string"
  },
  "payload": [
    {
      "id": 0,
      "additional_attributes": {
        "city": "string",
        "country": "string",
        "description": "string",
        "company_name": "string",
        "country_code": "string",
        "social_profiles": {}
      },
      "availability_status": "string",
      "email": "string",
      "name": "string",
      "phone_number": "string",
      "blocked": false,
      "identifier": "string",
      "thumbnail": "string",
      "custom_attributes": {},
      "last_activity_at": 0,
      "created_at": 0
    }
  ]
}
```

### 422 Validation Error

Content type: `application/json`

```json
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
```

## Request examples

### cURL

```bash
curl --request GET \
  --url 'https://api.nabrah.ai/api/ext/omni_v2/contact' \
  --header 'X-API-Key: <your-api-key>'
```

### Python

```python
import requests

url = "https://api.nabrah.ai/api/ext/omni_v2/contact"
headers = {"X-API-Key": "<your-api-key>"}

response = requests.get(url, headers=headers)
response.raise_for_status()
print(response.json())
```

### JavaScript

```javascript
const response = await fetch("https://api.nabrah.ai/api/ext/omni_v2/contact", {
  method: "GET",
  headers: { "X-API-Key": "<your-api-key>" },
});

const data = await response.json();
console.log(data);
```

### Go

```go
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.nabrah.ai/api/ext/omni_v2/contact", nil)
	req.Header.Set("X-API-Key", "<your-api-key>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
```