# GET /contacts/ — Get Contacts

> Product: **Pabbly Chatflow** (v1)
> Base URL: `https://chatflow.pabbly.com/api/v1`
> Auth: Bearer via `Authorization` header
> Canonical: `/chatflow/contacts/get-contacts`

Hit the API with GET method to retrieve the list of contacts. Query Params:

**Query parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| name | string | No | Name of the contact to search for. |
| mobile | string | No | Mobile number of the contact to search for. |
| tags | string | No | Tags associated with the contact, separated by commas (e.g., tag1,tag2). |
| order | string | No | Sorting order of the results. Use -1 for descending and 1 for ascending. |
| optin | string | No | Filter contacts by opt-in status. Use true or false. |
| source | string | No | Source of contact creation. Allowed values: api, csv, user, sync, wa, manual. |
| incomingBlocked | string | No | Filter by incoming blocked status. Use true or false. |
| limit | string | No | Page size. Defaults to 25. Currently capped at 25 per request. |
| page | string | No | 1-indexed page number. When provided, skip is auto-calculated as (page - 1) * limit. Takes precedence over skip. |
| attributes | string | No | Filter by custom fields. Use bracket notation in the query string: attributes[0][name]=email&attributes[0][value]=user@example.com. Multiple attributes are AND-combined (all must match). |

**Response (200)** — Success Response:

```json
{
    "status": "success",
    "message": "Contacts retrieved successfully",
    "data": {
        "contacts": [
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36805",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "active",
                "source": "csv",
                "optin": true,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [
                    "list test",
                    "marketingtyf"
                ],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.757Z",
                "updatedAt": "2026-04-08T06:47:04.757Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36795",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "active",
                "source": "csv",
                "optin": true,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [
                    "list test",
                    "marketingtyf"
                ],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.757Z",
                "updatedAt": "2026-04-08T06:47:04.757Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36804",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "inactive",
                "source": "csv",
                "optin": false,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.757Z",
                "updatedAt": "2026-04-08T06:47:04.757Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36801",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "active",
                "source": "csv",
                "optin": true,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [
                    "list test",
                    "marketingtyf"
                ],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.757Z",
                "updatedAt": "2026-04-08T06:47:04.757Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36799",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "active",
                "source": "csv",
                "optin": true,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [
                    "list test",
                    "marketingtyf"
                ],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.757Z",
                "updatedAt": "2026-04-08T06:47:04.757Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36807",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "active",
                "source": "csv",
                "optin": true,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [
                    "list test",
                    "marketingtyf"
                ],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.757Z",
                "updatedAt": "2026-04-08T06:47:04.757Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36806",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "inactive",
                "source": "csv",
                "optin": false,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.757Z",
                "updatedAt": "2026-04-08T06:47:04.757Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36803",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "active",
                "source": "csv",
                "optin": true,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [
                    "list test",
                    "marketingtyf"
                ],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.757Z",
                "updatedAt": "2026-04-08T06:47:04.757Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36800",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "inactive",
                "source": "csv",
                "optin": false,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.757Z",
                "updatedAt": "2026-04-08T06:47:04.757Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36802",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "inactive",
                "source": "csv",
                "optin": false,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.757Z",
                "updatedAt": "2026-04-08T06:47:04.757Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36797",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "active",
                "source": "csv",
                "optin": true,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [
                    "list test",
                    "marketingtyf"
                ],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.757Z",
                "updatedAt": "2026-04-08T06:47:04.757Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36798",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "inactive",
                "source": "csv",
                "optin": false,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.757Z",
                "updatedAt": "2026-04-08T06:47:04.757Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36796",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "inactive",
                "source": "csv",
                "optin": false,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.757Z",
                "updatedAt": "2026-04-08T06:47:04.757Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36792",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "inactive",
                "source": "csv",
                "optin": false,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.756Z",
                "updatedAt": "2026-04-08T06:47:04.756Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36793",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "active",
                "source": "csv",
                "optin": true,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [
                    "list test",
                    "marketingtyf"
                ],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.756Z",
                "updatedAt": "2026-04-08T06:47:04.756Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36791",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "active",
                "source": "csv",
                "optin": true,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [
                    "list test",
                    "marketingtyf"
                ],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.756Z",
                "updatedAt": "2026-04-08T06:47:04.756Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36789",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "active",
                "source": "csv",
                "optin": true,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [
                    "list test",
                    "marketingtyf"
                ],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.756Z",
                "updatedAt": "2026-04-08T06:47:04.756Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36794",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "inactive",
                "source": "csv",
                "optin": false,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.756Z",
                "updatedAt": "2026-04-08T06:47:04.756Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36790",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "inactive",
                "source": "csv",
                "optin": false,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.756Z",
                "updatedAt": "2026-04-08T06:47:04.756Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36773",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "active",
                "source": "csv",
                "optin": true,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [
                    "list test",
                    "marketingtyf"
                ],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.756Z",
                "updatedAt": "2026-04-08T06:47:04.756Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36786",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "inactive",
                "source": "csv",
                "optin": false,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.756Z",
                "updatedAt": "2026-04-08T06:47:04.756Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36787",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "active",
                "source": "csv",
                "optin": true,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [
                    "list test",
                    "marketingtyf"
                ],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.756Z",
                "updatedAt": "2026-04-08T06:47:04.756Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36785",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "active",
                "source": "csv",
                "optin": true,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [
                    "list test",
                    "marketingtyf"
                ],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.756Z",
                "updatedAt": "2026-04-08T06:47:04.756Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36783",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "active",
                "source": "csv",
                "optin": true,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [
                    "list test",
                    "marketingtyf"
                ],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.756Z",
                "updatedAt": "2026-04-08T06:47:04.756Z"
            },
            {
                "_id": "69d5f9e61a8e351bXXXXXXXX",
                "name": "Name 36788",
                "countryCode": "7",
                "mobile": "7745603XXXX",
                "status": "inactive",
                "source": "csv",
                "optin": false,
                "attributes": [],
                "incomingBlocked": false,
                "broadcastIds": [],
                "list": [],
                "tags": [],
                "__v": 0,
                "createdAt": "2026-04-08T06:47:04.756Z",
                "updatedAt": "2026-04-08T06:47:04.756Z"
            }
        ],
        "next": "https://chatflow.pabbly.com/api/v1/contacts?limit=25&page=2",
        "totalCount": 138,
        "currentPage": 1,
        "remainingCount": 113,
        "count": 25
    }
}
```

**Code examples:**

_cURL_

```curl
curl https://chatflow.pabbly.com/api/v1/contacts/?name={{name}}&mobile={{mobile}}&tags={{tags}}&order={{order}}&optin={{optin}}&source={{source}}&incomingBlocked={{incomingBlocked}}&limit={{limit}}&page={{page}}&attributes={{attributes}} \
  -H "Authorization: Bearer {{YOUR_API_KEY}}"
```

_Ruby_

```ruby
require 'net/http'
require 'json'

uri = URI('https://chatflow.pabbly.com/api/v1/contacts/?name={{name}}&mobile={{mobile}}&tags={{tags}}&order={{order}}&optin={{optin}}&source={{source}}&incomingBlocked={{incomingBlocked}}&limit={{limit}}&page={{page}}&attributes={{attributes}}')
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer {{YOUR_API_KEY}}'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(request)
end

data = JSON.parse(response.body)
```

_Python_

```python
import requests

response = requests.get(
    'https://chatflow.pabbly.com/api/v1/contacts/?name={{name}}&mobile={{mobile}}&tags={{tags}}&order={{order}}&optin={{optin}}&source={{source}}&incomingBlocked={{incomingBlocked}}&limit={{limit}}&page={{page}}&attributes={{attributes}}',
    headers={'Authorization': 'Bearer {{YOUR_API_KEY}}'},
)

data = response.json()
```

_PHP_

```php
<?php
$ch = curl_init('https://chatflow.pabbly.com/api/v1/contacts/?name={{name}}&mobile={{mobile}}&tags={{tags}}&order={{order}}&optin={{optin}}&source={{source}}&incomingBlocked={{incomingBlocked}}&limit={{limit}}&page={{page}}&attributes={{attributes}}');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer {{YOUR_API_KEY}}']);

$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
```

_Java_

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest.Builder builder = HttpRequest.newBuilder()
    .uri(URI.create("https://chatflow.pabbly.com/api/v1/contacts/?name={{name}}&mobile={{mobile}}&tags={{tags}}&order={{order}}&optin={{optin}}&source={{source}}&incomingBlocked={{incomingBlocked}}&limit={{limit}}&page={{page}}&attributes={{attributes}}"))
    .header("Authorization", "Bearer {{YOUR_API_KEY}}")
    .GET();

HttpRequest request = builder.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```

_Node.js_

```node
const response = await fetch('https://chatflow.pabbly.com/api/v1/contacts/?name={{name}}&mobile={{mobile}}&tags={{tags}}&order={{order}}&optin={{optin}}&source={{source}}&incomingBlocked={{incomingBlocked}}&limit={{limit}}&page={{page}}&attributes={{attributes}}', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer {{YOUR_API_KEY}}',
  },
});

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

_Go_

```go
package main

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

func main() {
    req, _ := http.NewRequest("GET", "https://chatflow.pabbly.com/api/v1/contacts/?name={{name}}&mobile={{mobile}}&tags={{tags}}&order={{order}}&optin={{optin}}&source={{source}}&incomingBlocked={{incomingBlocked}}&limit={{limit}}&page={{page}}&attributes={{attributes}}", nil)
    req.Header.Set("Authorization", "Bearer {{YOUR_API_KEY}}")

    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()
    body, _ := io.ReadAll(res.Body)
    fmt.Println(string(body))
}
```

_.NET_

```dotnet
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://chatflow.pabbly.com/api/v1/contacts/?name={{name}}&mobile={{mobile}}&tags={{tags}}&order={{order}}&optin={{optin}}&source={{source}}&incomingBlocked={{incomingBlocked}}&limit={{limit}}&page={{page}}&attributes={{attributes}}");
request.Headers.TryAddWithoutValidation("Authorization", "Bearer {{YOUR_API_KEY}}");

var response = await client.SendAsync(request);
var data = await response.Content.ReadAsStringAsync();
Console.WriteLine(data);
```

---

**Other endpoints in Contacts:**

- [POST /contacts — Create Contacts](/chatflow/contacts/create-contacts)
- [PUT /contacts/{{id}} — Update Contact](/chatflow/contacts/update-contact)
- [GET /contacts/{{id}} — Get Contact by Id](/chatflow/contacts/get-contact-by-id)
- [GET /contacts/lists — Get Contact-lists](/chatflow/contacts/get-contact-lists)