# List contacts

> GET /contacts — list every contact on a sending domain.

`GET /contacts`

List the contacts on one of your **sending domains**, newest first. `?domain=` is required. Returns a list object whose `data` array holds the contacts.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | Yes | The sending domain whose contacts to list (one of your domains, e.g. `yourdomain.com`). |
| `segment_id` | string | No | Optional. Only return contacts that belong to this [segment](https://www.sendping.co/docs/segments/overview). |
| `limit` | integer | No | How many contacts to return. An integer between 1 and 100. Optional; if omitted, the whole pool comes back in a single response up to a ceiling of **1,000**, and `has_more` is `true` when that ceiling truncated the page. |
| `after` | string | No | Cursor: return the contacts that follow this contact id. The id itself is not included. See [Pagination](https://www.sendping.co/docs/api/pagination). |
| `before` | string | No | Cursor: return the contacts that precede this contact id. Cannot be combined with `after`. |

**Node.js**

```js
import { SendPing } from 'sendping';

const mb = new SendPing('mb_xxxxxxxxx');

const { data, error } = await mb.contacts.list({ domain: 'yourdomain.com' });
console.log({ data, error });
```

**Ruby**

```ruby
require "sendping"

SendPing.api_key = "mb_xxxxxxxxx"

SendPing::Contacts.list({
  "domain": "yourdomain.com"
})
```

**PHP**

```php
<?php
require 'vendor/autoload.php';

use SendPing\SendPing;

$sendping = SendPing::client('mb_xxxxxxxxx');

$sendping->contacts->list([
  'domain' => "yourdomain.com"
]);
```

**Python**

```python
import sendping

sendping.api_key = "mb_xxxxxxxxx"

sendping.Contacts.list({
  "domain": "yourdomain.com"
})
```

**Go**

```go
import "github.com/shekhu10/sendping-sdks/sendping-go"

client := sendping.NewClient("mb_xxxxxxxxx")

contacts, err := client.Contacts.List(&sendping.ListContactsRequest{
    Domain: "yourdomain.com",
})
```

**Rust**

```rust
use sendping::{ListContactsParams, SendPing};

let mb = SendPing::new("mb_xxxxxxxxx");

let _contacts = mb.contacts.list(ListContactsParams::for_domain("yourdomain.com")).await?;
```

**Java**

```java
import co.sendping.SendPing;
import co.sendping.SendPingResponse;

SendPing sendping = new SendPing("mb_xxxxxxxxx");

SendPingResponse response = sendping.contacts().list("yourdomain.com");
```

**.NET**

```csharp
using SendPing;

ISendPing sendping = SendPingClient.Create("mb_xxxxxxxxx");

var resp = await sendping.ContactListAsync(new ContactListOptions { Domain = "yourdomain.com" });
```

**cURL**

```bash
curl -X GET 'https://www.sendping.co/api/contacts?domain=yourdomain.com' \
  -H 'Authorization: Bearer mb_xxxxxxxxx'
```

**CLI**

```bash
sendping contacts list \
  --domain yourdomain.com
```

**Response (200)**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact",
      "id": "479e3145-dd0e-4f64-bf48-1d4b6d4cd8f6",
      "email": "steve@example.com",
      "first_name": "Steve",
      "last_name": "Wozniak",
      "unsubscribed": false,
      "properties": {
        "company_name": "Acme Corp"
      },
      "created_at": "2026-06-23T17:30:11.000Z"
    }
  ]
}
```

Each contact includes `object: "contact"` and a `properties` map (merged with registered fallback values). A missing `domain`, or one that is not one of yours, returns `422 validation_error` — as does a `limit` outside 1-100 (or a non-integer) or `after` and `before` together. An unknown cursor returns an empty page rather than an error. See [Pagination](https://www.sendping.co/docs/api/pagination) and [Errors](https://www.sendping.co/docs/api/errors).

## Audience-scoped variant

The nested route `GET /audiences/:audience_id/contacts` still works and lists the contacts of one audience (no `domain` query needed):

**Node.js**

```js
import { SendPing } from 'sendping';

const mb = new SendPing('mb_xxxxxxxxx');

const { data, error } = await mb.contacts.list({ audienceId: 'AUDIENCE_ID' });
console.log({ data, error });
```

**Ruby**

```ruby
require 'net/http'
require 'uri'

uri = URI('https://www.sendping.co/api/audiences/AUDIENCE_ID/contacts')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer mb_xxxxxxxxx'
res = http.request(req)
puts res.body
```

**PHP**

```php
<?php
require 'vendor/autoload.php';

use SendPing\SendPing;

$sendping = SendPing::client('mb_xxxxxxxxx');

$sendping->contacts->list([
  'audienceId' => "AUDIENCE_ID"
]);
```

**Python**

```python
import requests

res = requests.get(
    "https://www.sendping.co/api/audiences/AUDIENCE_ID/contacts",
    headers={"Authorization": "Bearer mb_xxxxxxxxx"},
)
print(res.json())
```

**Go**

```go
import "github.com/shekhu10/sendping-sdks/sendping-go"

client := sendping.NewClient("mb_xxxxxxxxx")

contacts, err := client.Contacts.List(&sendping.ListContactsRequest{
    AudienceId: "AUDIENCE_ID",
})
```

**Rust**

```rust
use sendping::{ListContactsParams, SendPing};

let mb = SendPing::new("mb_xxxxxxxxx");

let _contacts = mb.contacts.list(ListContactsParams::for_audience("AUDIENCE_ID")).await?;
```

**Java**

```java
import co.sendping.SendPing;
import co.sendping.SendPingResponse;
import co.sendping.requests.ListContactsParams;

SendPing sendping = new SendPing("mb_xxxxxxxxx");

SendPingResponse response = sendping.contacts().list(ListContactsParams.builder().audienceId("AUDIENCE_ID").build());
```

**.NET**

```csharp
using SendPing;

ISendPing sendping = SendPingClient.Create("mb_xxxxxxxxx");

var resp = await sendping.ContactListAsync(new ContactListOptions { AudienceId = "AUDIENCE_ID" });
```

**cURL**

```bash
curl -X GET 'https://www.sendping.co/api/audiences/AUDIENCE_ID/contacts' \
  -H 'Authorization: Bearer mb_xxxxxxxxx'
```