Skip to main content

Developers

Backed developer documentation

What the Backed API is, a quick start from credential to first request, and a link to every guide, reference page, the event catalogue, the changelog and the OpenAPI document.

The Backed API lets your organisation’s own systems, such as a finance, CRM or reporting system, read and change its records in Backed: funding rounds, applications, registrations, assessments, contracts, milestones, payments and files. It is a REST API with JSON bodies, served on your organisation’s own address, such as https://your-org.backed.giving. Signed webhooks tell your systems when something happens, and an OData feed loads your records into Power BI, Tableau and data warehouses.

This site holds no organisation’s data: every address and record on it is an example. You need no account to read it.

Quick start

  1. An Administrator creates an API credential under Settings > Profile and terms, on the API Access tab, and gives your system its Client ID and Client Secret.
  2. Your system exchanges the pair for a Bearer token at POST /oauth/token.
  3. It sends the token on every request, in the Authorization header.
Step 1: get a token
curl -X POST "https://your-org.backed.giving/oauth/token" \
  -d grant_type=client_credentials \
  -d client_id=your-client-id \
  -d client_secret=your-client-secret
Step 2: make your first request
curl "https://your-org.backed.giving/api/v2/funding_rounds?limit=50" \
  -H "Authorization: Bearer $BACKED_TOKEN"

The answer is a JSON array of your funding rounds, oldest first. Read the next page with gt: see Pagination. Every write also needs an Idempotency-Key: see Idempotency.

The OpenAPI document

The whole API is described by one OpenAPI 3.1 document, which code generators and API tools such as Postman or Insomnia read. Download openapi.json. Each organisation’s own host serves the same document at /api/v2/openapi.json, with its own address as the server, such as https://your-org.backed.giving/api/v2/openapi.json. Neither needs a credential.

Guides

  • Authentication: Get a 5-day Bearer token from a credential with the OAuth 2.0 client-credentials grant, send it on every request, and choose the scopes a credential holds.
  • Pagination: Read a long list 50 records at a time with the limit, gt and lt parameters, in ascending id order.
  • Errors: What every error code means, the status it comes with, and which ones are safe to retry.
  • Idempotency: Make every write safe to retry with an Idempotency-Key, and update a record at the version you read with If-Match.
  • Webhook signature verification: Check the Backed-Signature header on every webhook delivery with HMAC-SHA256, in Node.js or Python, and answer in time.
  • Connect Power BI: Load the OData reporting feed into Power BI Desktop, with Basic authentication or a token query, and refresh it on a schedule.
  • Connect Tableau: Connect Tableau Desktop to the OData reporting feed with the credential as a user name and password, and load it into other tools and warehouses.
  • Versions and deprecation: Which version is current, why a breaking change only ever comes under a new version path, and how long a superseded version stays.

Reference

  • API reference: every operation, by resource.
  • Authentication: Exchange a credential for an access token. 1 operation: parameters, request body and answers, with examples.
  • Funding Rounds: The Organisation’s funding rounds. 2 operations: parameters, request body and answers, with examples.
  • Funding Applications: Applications, their entries, moves, notes and tags. 5 operations: parameters, request body and answers, with examples.
  • Registration Entities: Applicant organisations and individuals. 5 operations: parameters, request body and answers, with examples.
  • Assessment Rounds: Assessor assignments. 1 operation: parameters, request body and answers, with examples.
  • Contracts: Contracts and their recorded statuses. 3 operations: parameters, request body and answers, with examples.
  • Milestones: Milestones with their deliverables. 4 operations: parameters, request body and answers, with examples.
  • Payments: Payment batches. 1 operation: parameters, request body and answers, with examples.
  • File Inputs: Downloads of files held by application and deliverable inputs. 1 operation: parameters, request body and answers, with examples.
  • Files: The three-step file upload. 3 operations: parameters, request body and answers, with examples.
  • Reference: This document. 1 operation: parameters, request body and answers, with examples.

Events and changelog

For AI assistants

The site publishes itself for AI assistants too: llms.txt lists every page with a line on what it holds, llms-full.txt is every page in one file, and every page is also served as Markdown at its own address plus .md.