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.
Response Array of contact objects belonging to your merchant account. Show Contact object fields
Unique identifier for the contact (UUID).
Full name derived from firstName and lastName.
Organization or company name, if provided.
List of email address objects. Whether this is the contact’s primary email.
List of phone number objects. Whether this is the contact’s primary phone number.
List of address objects. State or region code (e.g., MA).
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 curl https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/contacts?limit= 10 \ -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.