GET /v1/contacts/{id} — retrieve a contact record

The Get Contact endpoint retrieves a single contact by its unique identifier. The contact must belong to your organization — fetching one owned by another organization returns 403 Forbidden. Use List Contacts to discover contact IDs. The fields below are the complete public contact object. CharityStack stores additional internal fields on a contact for its own bookkeeping; those are deliberately not part of this API and will never appear in a response. New fields may be added here over time, so parse defensively and ignore anything you do not recognize.

Endpoint

GET https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/contacts/{id}

Authentication

string

required

Bearer token using your API key. Format: Bearer cs_live_your_key

Path parameters

string

required

The unique identifier of the contact (UUID format).

Response

On success the endpoint returns a single Contact object directly (not wrapped in an array).

string

Unique identifier for the contact.

string

Contact’s first name.

string

Contact’s last name.

string

Full name derived from firstName and lastName.

string

The contact’s primary email address, for convenience. emails is authoritative.

object[]

List of email address objects.

Show email object

string

The email address.

boolean

Whether this is the primary email.

boolean

Whether the address has been verified.

object[]

List of phone number objects.

Show phone object

string

The phone number (E.164, e.g. +34613628904; legacy rows may carry older formats).

boolean

Whether this is the primary phone.

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.

SUBSCRIBED, UNSUBSCRIBED, NEVER_SUBSCRIBED or UNKNOWN. Always present — derived server-side with suppression rules applied, so a contact the platform will not send to never reads as subscribed.

Same enum and derivation rules as emailConsent. SMS is an opt-in regime.

Master consent flag, derived alongside the channel enums.

boolean

Read-only. Whether the contact has an active recurring subscription.

string

Read-only. ISO timestamp of the first donation. Absent if they have never donated.

string

Read-only. ISO timestamp of the most recent donation.

string

ISO 8601 timestamp of when the contact was created. Absent for contacts created before CharityStack began recording this, which is most historical contacts — treat it as optional.

string

ISO 8601 timestamp of the most recent update. Always present.

The giving fields (totalTransactionValue, totalTransactionCount, hasActiveSubscription, firstDonationAt, lastDonationAt) are computed by CharityStack. Sending any of them to Update Contact or Create Contact returns 400 validation_failed — they can never be edited through the public API.

Status codes

Code	Description
`200`	Contact returned successfully.
`401`	Missing or invalid API key.
`403`	Contact belongs to a different merchant.
`404`	No contact found with the given ID — also returned for a contact that has been deleted or merged into another.

Example

cURL

curl https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/contacts/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer cs_live_your_key"

200 response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "firstName": "Jane",
  "lastName": "Smith",
  "fullName": "Jane Smith",
  "email": "jane@smithfoundation.org",
  "emails": [
    { "value": "jane@smithfoundation.org", "isPrimary": true, "isVerified": true }
  ],
  "phones": [
    { "value": "+16175550101", "isPrimary": true }
  ],
  "addresses": [
    {
      "line1": "456 Park Ave",
      "line2": "",
      "city": "Boston",
      "region": "MA",
      "postal": "02101",
      "country": "United States",
      "isPrimary": true
    }
  ],
  "emailConsent": "SUBSCRIBED",
  "smsConsent": "NEVER_SUBSCRIBED",
  "communicationConsent": true,
  "totalTransactionCount": 12,
  "totalTransactionValue": 3250.00,
  "hasActiveSubscription": true,
  "firstDonationAt": "2024-03-15T10:24:11.000000",
  "lastDonationAt": "2025-01-02T09:14:52.000000",
  "createdAt": "2024-03-15T10:22:00.000000",
  "updatedAt": "2025-01-08T14:05:33.000000"
}

Organization

Payments

Subscriptions

Contacts

Forms

Prefilled-Checkout Links

Webhooks

Analytics

GET /v1/contacts/{id} — retrieve a contact record

Endpoint

Authentication

Path parameters

Response

Status codes

Example

​Endpoint

​Authentication

​Path parameters

​Response

​Status codes

​Example

Endpoint

Authentication

Path parameters

Response

Status codes

Example