> ## 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/{id} — retrieve a contact record

> Fetch a single contact by its unique ID, returning its name, emails, phones, addresses, consent state, and lifetime giving totals.

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](/docs/api/contacts/list) 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

<ParamField header="Authorization" type="string" required>
  Bearer token using your API key. Format: `Bearer cs_live_your_key`
</ParamField>

## Path parameters

<ParamField path="id" type="string" required>
  The unique identifier of the contact (UUID format).
</ParamField>

## Response

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

<ResponseField name="id" type="string">
  Unique identifier for the contact.
</ResponseField>

<ResponseField name="firstName" type="string">
  Contact's first name.
</ResponseField>

<ResponseField name="lastName" type="string">
  Contact's last name.
</ResponseField>

<ResponseField name="fullName" type="string">
  Full name derived from `firstName` and `lastName`.
</ResponseField>

<ResponseField name="email" type="string">
  The contact's primary email address, for convenience. `emails` is
  authoritative.
</ResponseField>

<ResponseField name="emails" type="object[]">
  List of email address objects.

  <Expandable title="email object">
    <ResponseField name="value" type="string">The email address.</ResponseField>
    <ResponseField name="isPrimary" type="boolean">Whether this is the primary email.</ResponseField>
    <ResponseField name="isVerified" type="boolean">Whether the address has been verified.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="phones" type="object[]">
  List of phone number objects.

  <Expandable title="phone object">
    <ResponseField name="value" type="string">The phone number (E.164, e.g. `+34613628904`; legacy rows may carry older formats).</ResponseField>
    <ResponseField name="isPrimary" type="boolean">Whether this is the primary phone.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="addresses" type="object[]">
  List of address objects.

  <Expandable title="address object">
    <ResponseField name="line1" type="string">Street address line 1.</ResponseField>
    <ResponseField name="line2" type="string">Street address line 2.</ResponseField>
    <ResponseField name="city" type="string">City.</ResponseField>
    <ResponseField name="region" type="string">State or region code (e.g., `MA`).</ResponseField>
    <ResponseField name="postal" type="string">Postal or ZIP code.</ResponseField>
    <ResponseField name="country" type="string">Country name.</ResponseField>
    <ResponseField name="isPrimary" type="boolean">Whether this is the primary address.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="totalTransactionCount" type="number">
  Lifetime number of transactions associated with this contact.
</ResponseField>

<ResponseField name="totalTransactionValue" type="number">
  Lifetime total transaction value in dollars.
</ResponseField>

<ResponseField name="emailConsent" type="string">
  `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.
</ResponseField>

<ResponseField name="smsConsent" type="string">
  Same enum and derivation rules as `emailConsent`. SMS is an opt-in regime.
</ResponseField>

<ResponseField name="communicationConsent" type="boolean">
  Master consent flag, derived alongside the channel enums.
</ResponseField>

<ResponseField name="hasActiveSubscription" type="boolean">
  Read-only. Whether the contact has an active recurring subscription.
</ResponseField>

<ResponseField name="firstDonationAt" type="string">
  Read-only. ISO timestamp of the first donation. Absent if they have never
  donated.
</ResponseField>

<ResponseField name="lastDonationAt" type="string">
  Read-only. ISO timestamp of the most recent donation.
</ResponseField>

<ResponseField name="createdAt" type="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.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp of the most recent update. Always present.
</ResponseField>

<Note>
  The giving fields (`totalTransactionValue`, `totalTransactionCount`,
  `hasActiveSubscription`, `firstDonationAt`, `lastDonationAt`) are computed by
  CharityStack. Sending any of them to
  [Update Contact](/docs/api/contacts/update) or
  [Create Contact](/docs/api/contacts/create) returns `400 validation_failed` —
  they can never be edited through the public API.
</Note>

## 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

```bash cURL theme={null}
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**

```json theme={null}
{
  "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"
}
```