> This is the Markdown of https://backed.giving/developers, a page of the Backed developer documentation. Every page is listed at https://backed.giving/developers/llms.txt. # 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: ```bash 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: ```bash 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](https://backed.giving/developers/guides/pagination.md). Every write also needs an `Idempotency-Key`: see [Idempotency](https://backed.giving/developers/guides/idempotency.md). ## 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](https://backed.giving/developers/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](https://backed.giving/developers/guides/authentication.md): 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](https://backed.giving/developers/guides/pagination.md): Read a long list 50 records at a time with the limit, gt and lt parameters, in ascending id order. - [Errors](https://backed.giving/developers/guides/errors.md): What every error code means, the status it comes with, and which ones are safe to retry. - [Idempotency](https://backed.giving/developers/guides/idempotency.md): 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](https://backed.giving/developers/guides/webhook-signatures.md): Check the Backed-Signature header on every webhook delivery with HMAC-SHA256, in Node.js or Python, and answer in time. - [Connect Power BI](https://backed.giving/developers/guides/power-bi.md): Load the OData reporting feed into Power BI Desktop, with Basic authentication or a token query, and refresh it on a schedule. - [Connect Tableau](https://backed.giving/developers/guides/tableau.md): 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](https://backed.giving/developers/guides/versioning.md): 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](https://backed.giving/developers/reference.md): every operation, by resource. - [Authentication](https://backed.giving/developers/reference/authentication.md): Exchange a credential for an access token. 1 operation: parameters, request body and answers, with examples. - [Funding Rounds](https://backed.giving/developers/reference/funding-rounds.md): The Organisation’s funding rounds. 2 operations: parameters, request body and answers, with examples. - [Funding Applications](https://backed.giving/developers/reference/funding-applications.md): Applications, their entries, moves, notes and tags. 5 operations: parameters, request body and answers, with examples. - [Registration Entities](https://backed.giving/developers/reference/registration-entities.md): Applicant organisations and individuals. 5 operations: parameters, request body and answers, with examples. - [Assessment Rounds](https://backed.giving/developers/reference/assessment-rounds.md): Assessor assignments. 1 operation: parameters, request body and answers, with examples. - [Contracts](https://backed.giving/developers/reference/contracts.md): Contracts and their recorded statuses. 3 operations: parameters, request body and answers, with examples. - [Milestones](https://backed.giving/developers/reference/milestones.md): Milestones with their deliverables. 4 operations: parameters, request body and answers, with examples. - [Payments](https://backed.giving/developers/reference/payments.md): Payment batches. 1 operation: parameters, request body and answers, with examples. - [File Inputs](https://backed.giving/developers/reference/file-inputs.md): Downloads of files held by application and deliverable inputs. 1 operation: parameters, request body and answers, with examples. - [Files](https://backed.giving/developers/reference/files.md): The three-step file upload. 3 operations: parameters, request body and answers, with examples. - [Reference](https://backed.giving/developers/reference/reference.md): This document. 1 operation: parameters, request body and answers, with examples. ## Events and changelog - [Event catalogue](https://backed.giving/developers/events.md): every webhook event type and the payload. - [Changelog](https://backed.giving/developers/changelog.md): every API change, with its date. ## For AI assistants The site publishes itself for AI assistants too: [llms.txt](https://backed.giving/developers/llms.txt) lists every page with a line on what it holds, [llms-full.txt](https://backed.giving/developers/llms-full.txt) is every page in one file, and every page is also served as Markdown at its own address plus `.md`.