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

The Get Contact endpoint retrieves a single contact record by its unique identifier. The contact must belong to your merchant account — attempting to fetch a contact owned by another merchant returns 403 Forbidden. Use List Contacts to discover contact IDs.

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

Organization or company name, if provided.

object[]

List of email address objects.

Show email object

string

The email address.

boolean

Whether this is the primary email.

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.

string

Read-only. Computed giving status — e.g. new_donor, repeat_donor, active_recurring, churned_recurring.

boolean

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

boolean

Read-only. Gave last year but not this year.

string

Read-only. ISO timestamp of the first donation.

string

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

string[]

Read-only via this API — tags are managed in the CharityStack dashboard.

boolean

Read-only. The contact chose to donate anonymously.

The analytics fields above (donor_status, has_active_subscription, is_lybunt, first_donation_at, last_donation_at, tags, anonymousDonation) 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.

string

ISO 8601 timestamp of when the contact was created.

string

ISO 8601 timestamp of the most recent update.

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.

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",
  "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"
}

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