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. 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. 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.
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",
    "allocations": [
      { "recipient_org_account_link_id": "cm3lnk...", "amount_cents": 25000 }
    ]
  }'

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

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.