Quickstart

Create an API key, hit /whoami to confirm it works, then list a few donors. Two minutes, start to finish.

1. Create an API key

Sign in to Together and open /settings/api. Click Create key, give it a name, pick READ scope, and copy the plaintext key. Together shows it exactly once.

Prefer an isolated playground? Hit Switch to sandbox at the top of the page before creating the key. Sandbox keys are scoped to {slug}-sandbox and run against Stripe test mode. See the sandbox guide.

2. Confirm the key works

Every request carries one header: Authorization: Bearer <key>. The key identifies both the caller and the organisation, so no separate tenancy header is needed. On any request that declares a Content-Type, it must be application/json - a non-JSON Content-Type is rejected with 400 invalid_request (a missing Content-Type is fine, so bodyless GETs need no header). When you send a body (POST and PATCH), set Content-Type: application/json.

curl -sS https://alltogether.giving/api/v1/whoami \
  -H "Authorization: Bearer pc_your_key_here"

You should see:

{
  "organisation_id": "cm3org...",
  "scope": "READ"
}

3. List donors

curl -sS "https://alltogether.giving/api/v1/donors?limit=5" \
  -H "Authorization: Bearer pc_your_key_here"

The response is { data: [...], has_more: boolean }. Page forward with ?starting_after=<last-id>. Filter with ?email=alice@example.com or ?created_at[gte]=2026-01-01.

4. Add a donation

POST /api/v1/donations records a donation directly into Together — an offline monetary donation, or an in-kind donation of donated goods or services. It needs a WRITE-scoped key. The donation is created with source: MANUAL and status: CONFIRMED; the organisation comes from the key.

curl -sS https://alltogether.giving/api/v1/donations \
  -H "Authorization: Bearer pc_your_write_key" \
  -H "Content-Type: application/json" \
  -d '{
    "donor_id": "cm3abcde0001abc123xyz456",
    "donation_type": "IN_KIND",
    "amount_cents": 420000,
    "donation_date": "2027-03-15",
    "in_kind_category": "SERVICES",
    "in_kind_description": "Pro bono legal advice on candidate eligibility"
  }'

For an in-kind donation, amount_cents is the fair value of what was donated, and in_kind_category and in_kind_description are required. For a monetary donation, send "donation_type": "MONETARY" and an optional payment_method. In-kind donations count toward disclosure thresholds and donor caps exactly like cash. Pair the call with an Idempotency-Key header to make retries safe.

5. Handle errors

Every error response uses the same envelope:

{
  "error": {
    "type": "https://alltogether.giving/developer/api/errors/not_found",
    "code": "not_found",
    "message": "Donor not found",
    "request_id": "req_abc123...",
    "doc_url": "https://alltogether.giving/developer/api/errors/not_found"
  }
}

Grab error.request_id and include it in any support enquiry - it maps one-to-one to our server logs. The errors guide lists every code; each operation in the API reference also shows its specific 4xx responses.

Next steps

Browse the full API reference. Click Authorize once, then use Try it on any endpoint.
Rate limits: 100 req/s per organisation. Watch RateLimit-Remaining and Retry-After.
Idempotency: send Idempotency-Key: <uuid> on any POST or PATCH to make retries safe.
Sandbox: build against test data and Stripe test mode without touching live.