PUT /v1/contacts/{id} — update a contact record

The Update Contact endpoint modifies an existing contact. It uses partial-update semantics: only the fields present in the request body are applied — except firstName and lastName, which are required on every request — and unknown fields are rejected with 400. The contact must belong to your merchant account — attempting to update a contact owned by another merchant returns 403 Forbidden.

Endpoint

PUT 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

string

required

A unique string you generate for each distinct update. Reuse the same key when you retry and you get the original result back instead of applying the update twice. Required — a request without it is rejected with 400 idempotency_key_required. Same semantics as Create Contact.

Path parameters

string

required

The unique identifier of the contact (UUID format).

Request body

string

required

Contact’s first name. Required on every request; non-blank.

string

required

Contact’s last name. Required on every request; non-blank.

string

Organization or company the contact belongs to.

object[]

The desired active email entries. Existing entries missing from this array are soft-deleted (retained internally for history), and previously deleted entries stay deleted. Omit the array entirely to leave emails untouched.

Show email entry

string

required

The email address.

boolean

Exactly one entry may be primary; when none is marked, the first becomes primary.

object[]

The desired active phone entries. Same array semantics as emails. Values are normalized to E.164 (e.g. +34613628904); bare national numbers are treated as US. Unparseable numbers return 400.

Show phone entry

string

required

The phone number.

boolean

Exactly one entry may be primary.

object[]

The desired active address entries. Same array semantics as emails.

Show address entry

string

Street line 1.

string

Street line 2.

string

City.

string

State / region.

string

Postal code.

string

Country.

boolean

Exactly one entry may be primary.

SUBSCRIBED or UNSUBSCRIBED. Changes propagate to the marketing platform when your organization has marketing enabled (see meta.marketingSync in the response).

SUBSCRIBED or UNSUBSCRIBED. A contact who opted out of SMS by texting STOP cannot be re-subscribed through the API (409 sms_carrier_locked) — that requires the verified-START flow in the CharityStack dashboard.

Response

On success returns the updated Contact object:

object

required

The full updated contact record, in the same shape as Get Contact.

object

Present only when a consent change was requested. Per-channel outcome of the marketing sync: synced, skipped_marketing_not_enabled, skipped_no_marketing_link, or failed. A skipped/failed sync never discards the consent change itself.

Errors

Status	Code	Meaning
400	`validation_failed`	Missing/blank name, unknown field, invalid email/phone, duplicate entries, or more than one primary.
400	`idempotency_key_required`	The `Idempotency-Key` header was missing.
401	—	Missing or invalid API key.
403	—	Contact belongs to a different merchant account.
404	—	Contact not found, or it has been deleted or merged into another contact.
409	`email_taken`	An email in the request already belongs to another of your contacts. The response includes `existingContactID`.
409	`sms_carrier_locked`	The contact texted STOP; SMS re-subscribe requires the dashboard’s verified-START flow.
409	`request_in_progress`	A request with this `Idempotency-Key` is still being processed. Retry shortly to receive the original result.
422	`idempotency_key_reused`	This `Idempotency-Key` was already used with a different request body. Use a new key.

A request rejected before the update is applied — a validation failure, or sms_carrier_locked — does not consume the idempotency key. Fix the body and retry with the same key.

Example — update name and add an email

curl -X PUT https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/contacts/contact_123 \
  -H "Authorization: Bearer cs_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Ali",
    "lastName": "Ahmed",
    "emails": [
      {"email": "ali@example.com", "is_primary": true},
      {"email": "ali.work@example.com"}
    ]
  }'

Example — unsubscribe from email updates

curl -X PUT https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/contacts/contact_123 \
  -H "Authorization: Bearer cs_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"firstName": "Ali", "lastName": "Ahmed", "emailConsent": "UNSUBSCRIBED"}'

In rare cases a slow update can return a gateway 504 while the update still completes server-side. The request body is a declarative desired state, so retrying the same PUT is safe and converges. Successful updates emit the contact.updated webhook event.

Organization

Payments

Subscriptions

Contacts

Forms

Prefilled-Checkout Links

Webhooks

Analytics

PUT /v1/contacts/{id} — update a contact record

Endpoint

Authentication

Path parameters

Request body

Response

Errors

Example — update name and add an email

Example — unsubscribe from email updates

​Endpoint

​Authentication

​Path parameters

​Request body

​Response

​Errors

​Example — update name and add an email

​Example — unsubscribe from email updates

Endpoint

Authentication

Path parameters

Request body

Response

Errors

Example — update name and add an email

Example — unsubscribe from email updates