GET /v1/contacts — list contacts

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

string

required

Bearer token using your API key. Format: Bearer cs_live_your_key

Query parameters

number

default:"100"

Maximum number of contacts to return. Accepted range is 1–100.

string

Pagination cursor returned by a previous response. Pass this value to retrieve the next page of results.

string

Filter results to contacts whose emails array contains this address.

Each returned contact carries the same fields as Get Contact — 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

Contact[]

required

Array of contact objects belonging to your merchant account.

Show Contact object fields

string

Unique identifier for the contact (UUID).

string

Contact’s first name.

string

Contact’s last name.

string

Full name derived from firstName and lastName.

string

Organization or company name, if provided.

object[]

List of email address objects.

Show email object

string

The email address.

boolean

Whether this is the contact’s primary email.

object[]

List of phone number objects.

Show phone object

string

The phone number.

boolean

Whether this is the contact’s primary phone number.

object[]

List of address objects.

Show address object

string

Street address line 1.

string

Street address line 2.

string

City.

string

State or region code (e.g., MA).

string

Postal or ZIP code.

string

Country name.

boolean

Whether this is the primary address.

number

Lifetime number of transactions associated with this contact.

number

Lifetime total transaction value in dollars.

string

ISO 8601 timestamp of when the contact was created.

string

ISO 8601 timestamp of the most recent update.

number

required

Number of contacts returned in this response page.

boolean

required

true if additional pages of results are available.

string

Pagination cursor to pass as lastEvaluatedKey in your next request. Only present when hasMore is true.

Examples

curl https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/contacts?limit=10 \
  -H "Authorization: Bearer cs_live_your_key"

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

{
  "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.

Organization

Payments

Subscriptions

Contacts

Forms

Prefilled-Checkout Links

Webhooks

Analytics

GET /v1/contacts — list contacts

Endpoint

Authentication

Query parameters

Response

Examples

​Endpoint

​Authentication

​Query parameters

​Response

​Examples

Endpoint

Authentication

Query parameters

Response

Examples