Skip to main content
Together
Sign in

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 POST and PATCH, also send Content-Type: application/json — a request with a non-JSON Content-Type is rejected with 400 invalid_request.

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. Build a recommendation set end-to-end

A recommendation set distributes a single donation across one or more recipient organisations you're authorised to direct funds to. Its amount_mode controls how the donor form treats the per-recipient amounts: FIXED (locked, the default), SUGGESTED (pre-filled but editable), or OPEN (the set is just a recipient list and the donor enters every amount). The two-step flow:

  1. GET /api/v1/recipient-accountsto find the link IDs you're authorised to allocate against.
  2. POST /api/v1/recommendation-sets with one or more allocations referencing those IDs. The order of allocations in the request body sets the donor-facing display order on the giving form.
curl -sS "https://alltogether.giving/api/v1/recipient-accounts" \
  -H "Authorization: Bearer pc_your_key_here"
# {
#   "data": [
#     {
#       "id": "cm3lnk...",
#       "label": "ACF main donations",
#       "recipient_org_name": "Australian Conservation Foundation",
#       "is_active": true,
#       ...
#     }
#   ],
#   "has_more": false
# }

curl -sS https://alltogether.giving/api/v1/recommendation-sets \
  -H "Authorization: Bearer pc_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Climate distribution - March 2026",
    "amount_mode": "FIXED",
    "allocations": [
      { "recipient_org_account_link_id": "cm3lnk...", "amount_cents": 25000 }
    ]
  }'

For an OPEN set, send "amount_mode": "OPEN" and "amount_cents": 0 for every allocation - the donor chooses each amount on the form.

To establish a new link, ask the recipient organisation for their distribution passphrase (they generate one from their /settings/engage/distribution page) and exchange it via POST /api/v1/recipient-accounts with { passphrase, label }.

6. 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.