Skip to content
Pidgely Docs

API reference · Contacts

List contacts

GEThttps://api.pidgely.com/contacts
View as Markdown

Lists contacts, newest first. Filter by segment_id (or the legacy audience_id).

Authorization: Bearer pdg_…. An API key with full_access. A sending_access key gets 401 restricted_api_key.

Query parameters

Name Type Required Description
segment_id string No UUID.
audience_id string No Legacy alias of segment_id. UUID.
limit integer No Page size (1-100). Between 1 and 100.
after string No Id of the last item of the previous page (older items). UUID.
before string No Id of the first item of the current page (newer items). UUID.
q string No Prefix of the e-mail, first or last name (Pidgely extension).

Request

Node.js
import { Pidgely } from 'pidgely';

const pidgely = new Pidgely(process.env.PIDGELY_API_KEY);

const { data, error } = await pidgely.contacts.list({
  segmentId: '0199d7f5-9a3e-7d4b-a1c2-7e5f0b3d6c48',
  limit: 50,
});
console.log(data ?? error);
Python
import os
import pidgely

pidgely.api_key = os.environ["PIDGELY_API_KEY"]

result = pidgely.Contacts.list({
    "segment_id": "0199d7f5-9a3e-7d4b-a1c2-7e5f0b3d6c48",
    "limit": 50,
})
print(result)
PHP
<?php

require __DIR__ . '/vendor/autoload.php';

$pidgely = Pidgely::client(getenv('PIDGELY_API_KEY'));

$result = $pidgely->contacts->list([
    'segment_id' => '0199d7f5-9a3e-7d4b-a1c2-7e5f0b3d6c48',
    'limit' => 50,
]);
var_dump($result);
Go
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/pidgely/pidgely-go"
)

func main() {
	ctx := context.Background()
	client := pidgely.NewClient(os.Getenv("PIDGELY_API_KEY"))

	result, err := client.Contacts.List(ctx, &pidgely.ListContactsParams{
		SegmentId:  "0199d7f5-9a3e-7d4b-a1c2-7e5f0b3d6c48",
		ListParams: pidgely.ListParams{
			Limit: 50,
		},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(result)
}
Ruby
require "pidgely"

Pidgely.api_key = ENV["PIDGELY_API_KEY"]

result = Pidgely::Contacts.list({
  segment_id: "0199d7f5-9a3e-7d4b-a1c2-7e5f0b3d6c48",
  limit: 50
})
puts result
cURL
curl -X GET 'https://api.pidgely.com/contacts?segment_id=0199d7f5-9a3e-7d4b-a1c2-7e5f0b3d6c48&limit=50' \
  -H "Authorization: Bearer $PIDGELY_API_KEY"

Response

200 OK

JSON
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact",
      "id": "0199d7f4-5d7b-7a2c-b4e1-9f3c2a6d8e05",
      "email": "steve@example.com",
      "first_name": "Steve",
      "last_name": "Wozniak",
      "created_at": "2026-10-12 16:44:41.000000+00",
      "unsubscribed": false,
      "properties": {
        "plan": {
          "value": "pro",
          "type": "string"
        },
        "seats": {
          "value": 5,
          "type": "number"
        }
      }
    }
  ]
}

Response fields

Name Type Required Description
object string Yes Object type. One of list.
has_more boolean Yes Whether another page exists.
data object[] Yes Items of this page.
data[].object string No Object type.
data[].id string No Unique id (UUID). UUID.
data[].email string No Email address.
data[].first_name string No First name, up to 200 characters. Available as {{{FIRST_NAME}}} in broadcasts.
data[].last_name string No Last name, up to 200 characters. Available as {{{LAST_NAME}}} in broadcasts.
data[].created_at string No Timestamp in UTC (2026-10-12 16:44:41.000000+00).
data[].unsubscribed boolean No Whether the contact opted out of broadcasts. Kept in sync with the suppression list.
data[].properties object (map of object) No Custom properties: up to 100 keys matching ^[A-Za-z_][A-Za-z0-9_]{0,49}$, values string (up to 2,000 characters), number, boolean, or null to delete.

Errors

Errors have the shape {"statusCode", "name", "message"}. See Errors for the full list.

Status Name When
401 missing_api_key, restricted_api_key No Authorization: Bearer header, or a sending_access key called an endpoint that needs full_access.
403 invalid_api_key, validation_error The API key is invalid or revoked, or the request is not allowed for this account (unverified domain, plan limit, paused account).
404 not_found The resource does not exist in this account (or the id is not a valid UUID).
422 validation_error A field is missing or invalid; message names it.
429 rate_limit_exceeded Too many requests per second. Wait for Retry-After seconds.