Skip to main content
The Create Contact endpoint adds a new contact record to your CharityStack account. firstName and lastName are required; all other fields are optional. Email uniqueness is enforced per organization — if an email in the request already belongs to another of your contacts, the request returns 409 email_taken with the existing contact’s ID.

​
Endpoint

​
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 contact you want to create. Reuse the same key when you retry and you get the original contact back instead of a duplicate. Required — a request without it is rejected with 400 idempotency_key_required. See Retrying safely.

​
Request body

​
string
required
Contact’s first name. Non-blank.
​
string
required
Contact’s last name. Non-blank.
​
string
Organization or company the contact belongs to.
​
object[]
Email entries. Duplicates (case-insensitive) are rejected.
​
object[]
Phone entries. Values are normalized to E.164 (e.g. +34613628904); bare national numbers are treated as US. Unparseable numbers return 400.
​
object[]
Address entries.
​
string
SUBSCRIBED or UNSUBSCRIBED. Omit to use the creation default: SUBSCRIBED (email is an opt-out regime).
​
string
SUBSCRIBED or UNSUBSCRIBED. Omit to use the creation default: NEVER_SUBSCRIBED (SMS is an opt-in regime — only set SUBSCRIBED when you have collected explicit SMS consent).

​
Response

On success returns 201 with the created contact:
​
object
required
The created contact, in the same shape as Get Contact — including its generated id.

​
Errors

​
Example

​
Retrying safely

If a create times out, you cannot tell from the client whether the contact was written. Retrying blindly is how duplicate donors appear — and a duplicate cannot be undone: it splits giving history, doubles marketing sends, and needs a manual merge. The Idempotency-Key header solves this. Generate one key per contact you intend to create (a UUID works well), and send that same key on every retry of that request.
1

Send the create with a key you generated

Idempotency-Key: 7f3c1b90-2d4e-4a51-9f88-6c2b0d1e5a77
2

If the request times out or fails, send it again — same key, same body

Do not generate a new key. A new key means a new contact.
3

You get the original result back

If the first attempt had already succeeded, the retry returns that same contact with 201 and an Idempotency-Replayed: true response header. The contact is not created twice.
A few rules worth knowing:
  • A replay returns the original response exactly, including the original contact id. Nothing is recomputed.
  • Reusing a key with a different body is rejected with 422 idempotency_key_reused, rather than silently applying one of the two. That is almost always a bug in the calling code.
  • Keys are scoped to your organization, so they can never collide with another organization’s.
  • Keys are remembered for 24 hours. After that the same key is treated as new. Retries happen in seconds, so this only matters if you deliberately replay an old request.
  • A rejected request does not consume the key. If your create fails validation, fix the body and retry with the same key.