> ## Documentation Index
> Fetch the complete documentation index at: https://www.charitystack.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# GET /v1/contacts — list contacts
> Retrieve a paginated list of all contacts for your merchant account. Optionally filter by email address and page through results with a cursor token.
The List Contacts endpoint returns all contact records stored in your CharityStack account. Each contact includes identifying information, associated emails, phone numbers, addresses, and lifetime transaction totals. Use `limit` and `lastEvaluatedKey` to page through large contact lists.
## Endpoint
```
GET https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/contacts
```
## Authentication
Bearer token using your API key. Format: `Bearer cs_live_your_key`
## Query parameters
Maximum number of contacts to return. Accepted range is 1–100.
Pagination cursor returned by a previous response. Pass this value to retrieve the next page of results.
Filter results to contacts whose `emails` array contains this address.
Each returned contact carries the same fields as [Get Contact](/docs/api/contacts/get) — including the always-present derived consent enums (`emailConsent`, `smsConsent`, `communicationConsent`) and the read-only analytics fields (`donor_status`, `has_active_subscription`, `is_lybunt`, `tags`, `anonymousDonation`, `first_donation_at`/`last_donation_at`).
## Response
Array of contact objects belonging to your merchant account.
Unique identifier for the contact (UUID).
Contact's first name.
Contact's last name.
Full name derived from `firstName` and `lastName`.
Organization or company name, if provided.
List of email address objects.
The email address.
Whether this is the contact's primary email.
List of phone number objects.
The phone number.
Whether this is the contact's primary phone number.
List of address objects.
Street address line 1.
Street address line 2.
City.
State or region code (e.g., `MA`).
Postal or ZIP code.
Country name.
Whether this is the primary address.
Lifetime number of transactions associated with this contact.
Lifetime total transaction value in dollars.
ISO 8601 timestamp of when the contact was created.
ISO 8601 timestamp of the most recent update.
Number of contacts returned in this response page.
`true` if additional pages of results are available.
Pagination cursor to pass as `lastEvaluatedKey` in your next request. Only present when `hasMore` is `true`.
## Examples
```bash cURL theme={null}
curl https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/contacts?limit=10 \
-H "Authorization: Bearer cs_live_your_key"
```
```bash cURL — next page theme={null}
curl "https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/contacts?limit=10&lastEvaluatedKey=eyJpZCI6ImFiYzEyMyJ9" \
-H "Authorization: Bearer cs_live_your_key"
```
**200 response**
```json theme={null}
{
"contacts": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"firstName": "Jane",
"lastName": "Smith",
"fullName": "Jane Smith",
"organizationName": "Smith Foundation",
"emails": [
{ "value": "jane@smithfoundation.org", "is_primary": true }
],
"phones": [
{ "value": "16175550101", "is_primary": true }
],
"addresses": [
{
"line1": "456 Park Ave",
"line2": "",
"city": "Boston",
"region": "MA",
"postal": "02101",
"country": "United States",
"is_primary": true
}
],
"totalTransactionCount": 12,
"totalTransactionValue": 3250.00,
"created_at": "2024-03-15T10:22:00.000000",
"updated_at": "2025-01-08T14:05:33.000000"
}
],
"count": 1,
"hasMore": false
}
```
The `lastEvaluatedKey` value is a base64-encoded string. Treat it as an opaque cursor — do not parse or construct it manually.