> This is the Markdown of https://backed.giving/developers/reference/funding-applications, a page of the Backed developer documentation. Every page is listed at https://backed.giving/developers/llms.txt. # Funding Applications Applications, their entries, moves, notes and tags. 5 operations: parameters, request body and answers, with examples. - [GET /api/v2/funding\_applications](#listFundingApplications) — List funding applications. - [GET /api/v2/funding\_applications/{id}](#getFundingApplication) — Get one funding application with its form entry. - [POST /api/v2/funding\_applications/{id}/notes](#createApplicationNote) — Add a note to a funding application. - [PUT /api/v2/funding\_applications/{id}/tags](#replaceApplicationTags) — Replace a funding application’s tags. - [POST /api/v2/funding\_applications/{id}/transitions](#transitionFundingApplication) — Move a funding application. ## GET /api/v2/funding_applications **List funding applications.** The Organisation's live funding applications in ascending id order, at most 50 a page, narrowed by the filter flags and `q`. `bank_account_number` is null unless the credential may read bank account numbers. - Operation ID: `listFundingApplications` - Authentication: A Bearer token from a credential holding the `read` scope. - Also served at `/funding_system/api/v2/funding_applications`, the documented product’s alias path. Example request: ```bash curl "https://your-org.backed.giving/api/v2/funding_applications" \ -H "Authorization: Bearer $BACKED_TOKEN" ``` ### Parameters Parameters of GET /api/v2/funding_applications: | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `limit` | query | No | `integer` | Results per page (default 50, at most 50; a larger value is read as 50). Not an integer, or below 1: 400. Example: `50`. | | `gt` | query | No | `integer` | Return records with an id greater than this value. Page forward by passing the last id you received. Example: `1287`. | | `lt` | query | No | `integer` | Return records with an id less than this value. | | `submitted` | query | No | `string` | Set to `1` to return only submitted applications; any other value is ignored. Example: `1`. | | `with_contract` | query | No | `string` | Set to `1` to return only applications with a contract. Example: `1`. | | `not_initial` | query | No | `string` | Set to `1` to exclude applications in their initial state. Example: `1`. | | `q` | query | No | `string` | Text search; blank is ignored. Example: `river`. | | `extra_methods[]` | query | No | `array of string` | Additional properties to include, each once, in the order named. Any other value is 400. One of `requested_amount`, `recommended_amount`, `bank_account_number`, `registration_entity_id`. Example: `requested_amount, recommended_amount`. | ### 200 response A JSON array of funding applications. Fields of FundingApplication: | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | `integer` | Yes | | | `created_at` | `string` | Yes | | | `updated_at` | `string` | Yes | | | `funding_round_id` | `integer` | Yes | | | `state` | `string` | Yes | | | `title` | `string \| null` | Yes | | | `submitted_at` | `string \| null` | Yes | | | `funding_category` | `object \| null` | Yes | | | `registration_entity` | `object` | Yes | | | `lock_version` | `integer` | Yes | | | `requested_amount` | `string \| null` | No | | | `recommended_amount` | `string \| null` | No | | | `bank_account_number` | `string \| null` | No | | | `registration_entity_id` | `integer` | No | | Example 200 response: ```json [ { "id": 1287, "created_at": "2026-03-02T21:15:04.000Z", "updated_at": "2026-06-18T03:40:11.000Z", "funding_round_id": 42, "state": "submitted", "title": "Te Awa river restoration", "submitted_at": "2026-05-20T04:12:55.000Z", "funding_category": { "id": 7, "name": "Community" }, "registration_entity": { "id": 311, "name": "Te Awa Restoration Trust" }, "lock_version": 3, "requested_amount": "24500.0" } ] ``` ### 400 response A query parameter is invalid, or a write’s body is not a JSON object. Example 400 response: ```json { "error": "invalid_request", "error_description": "limit is invalid" } ``` ### 401 response The token is missing, invalid, expired or revoked, of another Organisation, or API access is not Full. Ask for a new token. Headers: `WWW-Authenticate`. Example 401 response: ```json { "error": "invalid_token", "error_description": "The access token is invalid or has expired" } ``` ### 403 response The request was sent over plain HTTP and was not processed. Example 403 response: ```json { "error": "https_required" } ``` ### 404 response An unknown host or path, or an id that is unknown, deleted or of another Organisation. Example 404 response: ```json { "error": "not_found" } ``` ### 429 response A rate limit was exceeded: 120 requests a minute per credential, 30 token requests a minute per client\_id. Headers: `Retry-After`. Example 429 response: ```json { "error": "rate_limited", "error_description": "Too many requests" } ``` ### 500 response An unexpected server error. Example 500 response: ```json { "error": "server_error" } ``` ### 503 response The Organisation’s API access cannot be determined, or a dependency is unavailable. Retry after the given seconds. Headers: `Retry-After`. Example 503 response: ```json { "error": "temporarily_unavailable" } ``` ## GET /api/v2/funding_applications/{id} **Get one funding application with its form entry.** Every list property (and the named extra methods), then `entry` with every input. Answers hidden by form logic are included and not marked. - Operation ID: `getFundingApplication` - Authentication: A Bearer token from a credential holding the `read` scope. - Also served at `/funding_system/api/v2/funding_applications/{id}`, the documented product’s alias path. Example request: ```bash curl "https://your-org.backed.giving/api/v2/funding_applications/42" \ -H "Authorization: Bearer $BACKED_TOKEN" ``` ### Parameters Parameters of GET /api/v2/funding_applications/{id}: | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `id` | path | Yes | `integer` | The record id. Anything but a positive integer is 404. Example: `42`. | | `extra_methods[]` | query | No | `array of string` | Additional properties to include, each once, in the order named. Any other value is 400. One of `requested_amount`, `recommended_amount`, `bank_account_number`, `registration_entity_id`. Example: `requested_amount, recommended_amount`. | ### 200 response The funding application with its form entry. Fields of FundingApplicationDetail: | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | `integer` | Yes | | | `created_at` | `string` | Yes | | | `updated_at` | `string` | Yes | | | `funding_round_id` | `integer` | Yes | | | `state` | `string` | Yes | | | `title` | `string \| null` | Yes | | | `submitted_at` | `string \| null` | Yes | | | `funding_category` | `object \| null` | Yes | | | `registration_entity` | `object` | Yes | | | `lock_version` | `integer` | Yes | | | `requested_amount` | `string \| null` | No | | | `recommended_amount` | `string \| null` | No | | | `bank_account_number` | `string \| null` | No | | | `registration_entity_id` | `integer` | No | | | `entry` | `object` | Yes | | Example 200 response: ```json { "id": 1287, "created_at": "2026-03-02T21:15:04.000Z", "updated_at": "2026-06-18T03:40:11.000Z", "funding_round_id": 42, "state": "submitted", "title": "Te Awa river restoration", "submitted_at": "2026-05-20T04:12:55.000Z", "funding_category": { "id": 7, "name": "Community" }, "registration_entity": { "id": 311, "name": "Te Awa Restoration Trust" }, "lock_version": 3, "requested_amount": "24500.0", "entry": { "id": 9001, "created_at": "2026-03-02T21:15:04.000Z", "updated_at": "2026-05-20T04:12:55.000Z", "inputs": [ { "id": 55120, "value": "Te Awa river restoration", "input_group_id": null, "input_group_order": null, "field": { "id": 801, "internal_identifier": "project_title", "name": "Project title", "order": 1 }, "file": null, "tahua_file_url": null }, { "id": 55121, "value": "budget.pdf", "input_group_id": null, "input_group_order": null, "field": { "id": 802, "internal_identifier": "budget", "name": "Budget", "order": 2 }, "file": { "filename": "budget.pdf", "content_type": "application/pdf", "byte_size": 182044 }, "tahua_file_url": "https://your-org.backed.giving/api/v2/file_inputs/55121" } ] } } ``` ### 400 response A query parameter is invalid, or a write’s body is not a JSON object. Example 400 response: ```json { "error": "invalid_request", "error_description": "limit is invalid" } ``` ### 401 response The token is missing, invalid, expired or revoked, of another Organisation, or API access is not Full. Ask for a new token. Headers: `WWW-Authenticate`. Example 401 response: ```json { "error": "invalid_token", "error_description": "The access token is invalid or has expired" } ``` ### 403 response The request was sent over plain HTTP and was not processed. Example 403 response: ```json { "error": "https_required" } ``` ### 404 response An unknown host or path, or an id that is unknown, deleted or of another Organisation. Example 404 response: ```json { "error": "not_found" } ``` ### 429 response A rate limit was exceeded: 120 requests a minute per credential, 30 token requests a minute per client\_id. Headers: `Retry-After`. Example 429 response: ```json { "error": "rate_limited", "error_description": "Too many requests" } ``` ### 500 response An unexpected server error. Example 500 response: ```json { "error": "server_error" } ``` ### 503 response The Organisation’s API access cannot be determined, or a dependency is unavailable. Retry after the given seconds. Headers: `Retry-After`. Example 503 response: ```json { "error": "temporarily_unavailable" } ``` ## POST /api/v2/funding_applications/{id}/notes **Add a note to a funding application.** Kept as an Internal Comment (`internal_comments.create`), labelled with the credential and the run-as Administrator. - Operation ID: `createApplicationNote` - Authentication: A Bearer token from a credential holding the `write:applications` scope. Runs as the credential’s Administrator, and needs an `Idempotency-Key` header. Example request: ```bash curl -X POST "https://your-org.backed.giving/api/v2/funding_applications/42/notes" \ -H "Authorization: Bearer $BACKED_TOKEN" \ -H "Idempotency-Key: 7d1f0c2e-5b8a-4f3e-9c61-2a4b8e9d0f13" \ -H "Content-Type: application/json" \ -d '{"body":"Budget checked against the supplier quote."}' ``` ### Parameters Parameters of POST /api/v2/funding_applications/{id}/notes: | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `id` | path | Yes | `integer` | The record id. Anything but a positive integer is 404. Example: `42`. | | `Idempotency-Key` | header | Yes | `string` | A key of 1 to 255 characters, unique per write. A retry with the same key, method, path and body within 24 hours answers the first response again (with `Idempotent-Replayed: true`) and writes nothing. Example: `7d1f0c2e-5b8a-4f3e-9c61-2a4b8e9d0f13`. | ### Request body `application/json`, the `ApplicationNoteCreate` schema. The note’s text, kept on the application as an Internal Comment. Fields of the ApplicationNoteCreate body: | Field | Type | Required | Notes | | --- | --- | --- | --- | | `body` | `string` | Yes | | Example request body: ```json { "body": "Budget checked against the supplier quote." } ``` ### 201 response The note. Headers: `Idempotent-Replayed`. Fields of ApplicationNote: | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | `integer` | Yes | | | `body` | `string` | Yes | | | `author_label` | `string` | Yes | | | `created_at` | `string` | Yes | | Example 201 response: ```json { "id": 7781, "body": "Budget checked against the supplier quote.", "author_label": "API: Finance sync as Mere Tane", "created_at": "2026-05-20T04:12:55.000Z" } ``` ### 400 response `idempotency_key_required`: The write has no Idempotency-Key header of 1 to 255 characters. `invalid_request`: A query parameter is invalid, or a write’s body is not a JSON object. Example 400 response: idempotency_key_required: ```json { "error": "idempotency_key_required", "error_description": "A write needs an Idempotency-Key header of 1 to 255 characters" } ``` Example 400 response: invalid_request: ```json { "error": "invalid_request", "error_description": "limit is invalid" } ``` ### 401 response The token is missing, invalid, expired or revoked, of another Organisation, or API access is not Full. Ask for a new token. Headers: `WWW-Authenticate`. Example 401 response: ```json { "error": "invalid_token", "error_description": "The access token is invalid or has expired" } ``` ### 403 response `https_required`: The request was sent over plain HTTP and was not processed. `insufficient_scope`: The credential does not hold the scope the route needs. `run_as_disabled`: The credential has no run-as Administrator, or that person is no longer one. `forbidden`: The run-as Administrator lacks the permission, or the record is outside their Data Access Rules. Headers: `WWW-Authenticate`. Example 403 response: https_required: ```json { "error": "https_required" } ``` Example 403 response: insufficient_scope: ```json { "error": "insufficient_scope", "error_description": "This credential lacks the write:applications scope" } ``` Example 403 response: run_as_disabled: ```json { "error": "run_as_disabled", "error_description": "This credential has no enabled run-as Administrator" } ``` Example 403 response: forbidden: ```json { "error": "forbidden", "error_description": "The run-as Administrator may not do this to this record" } ``` ### 404 response An unknown host or path, or an id that is unknown, deleted or of another Organisation. Example 404 response: ```json { "error": "not_found" } ``` ### 409 response The first request with this Idempotency-Key has not finished. Nothing was written; retry after the given seconds. Headers: `Retry-After`. Example 409 response: ```json { "error": "idempotency_in_progress", "error_description": "The first request with this Idempotency-Key has not finished. If this persists it stopped part-way: check whether the record exists before writing again with a new key" } ``` ### 413 response The body, or the declared file, is larger than the limit that applies. Example 413 response: ```json { "error": "payload_too_large", "error_description": "The request body is too large" } ``` ### 415 response The body is not application/json, or the target does not accept the file’s content type. Example 415 response: ```json { "error": "unsupported_media_type", "error_description": "The request body must be application/json" } ``` ### 422 response `idempotency_key_reused`: The Idempotency-Key was used in the last 24 hours for a different method, path or body. `unknown_field`: The body has a property the route does not document; the first is named. `validation_failed`: Body values the product’s own form would refuse; `fields` names each. Example 422 response: idempotency_key_reused: ```json { "error": "idempotency_key_reused", "error_description": "This Idempotency-Key was used for a different request" } ``` Example 422 response: unknown_field: ```json { "error": "unknown_field", "error_description": "bank_account_number is not a writable field" } ``` Example 422 response: validation_failed: ```json { "error": "validation_failed", "error_description": "Invalid fields: due_date", "fields": [ "due_date" ] } ``` ### 429 response A rate limit was exceeded: 120 requests a minute per credential, 30 token requests a minute per client\_id. Headers: `Retry-After`. Example 429 response: ```json { "error": "rate_limited", "error_description": "Too many requests" } ``` ### 500 response An unexpected server error. Example 500 response: ```json { "error": "server_error" } ``` ### 503 response The Organisation’s API access cannot be determined, or a dependency is unavailable. Retry after the given seconds. Headers: `Retry-After`. Example 503 response: ```json { "error": "temporarily_unavailable" } ``` ## PUT /api/v2/funding_applications/{id}/tags **Replace a funding application’s tags.** The hand-set tags become exactly these existing tags of the Organisation (`applications.tags`). A tag not in the Organisation’s vocabulary is 422 `unknown_tag`; none is created. Needs the Assessments module. - Operation ID: `replaceApplicationTags` - Authentication: A Bearer token from a credential holding the `write:applications` scope. Runs as the credential’s Administrator, and needs an `Idempotency-Key` header. Example request: ```bash curl -X PUT "https://your-org.backed.giving/api/v2/funding_applications/42/tags" \ -H "Authorization: Bearer $BACKED_TOKEN" \ -H "Idempotency-Key: 7d1f0c2e-5b8a-4f3e-9c61-2a4b8e9d0f13" \ -H "Content-Type: application/json" \ -d '{"tags":["priority","rural"]}' ``` ### Parameters Parameters of PUT /api/v2/funding_applications/{id}/tags: | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `id` | path | Yes | `integer` | The record id. Anything but a positive integer is 404. Example: `42`. | | `Idempotency-Key` | header | Yes | `string` | A key of 1 to 255 characters, unique per write. A retry with the same key, method, path and body within 24 hours answers the first response again (with `Idempotent-Replayed: true`) and writes nothing. Example: `7d1f0c2e-5b8a-4f3e-9c61-2a4b8e9d0f13`. | ### Request body `application/json`, the `ApplicationTags` schema. The application’s hand-set tags, each an existing tag of the Organisation. Answered lower-cased and sorted. Fields of the ApplicationTags body: | Field | Type | Required | Notes | | --- | --- | --- | --- | | `tags` | `array of string` | Yes | | Example request body: ```json { "tags": [ "priority", "rural" ] } ``` ### 200 response The tags now set. Headers: `Idempotent-Replayed`. Fields of ApplicationTags: | Field | Type | Required | Notes | | --- | --- | --- | --- | | `tags` | `array of string` | Yes | | Example 200 response: ```json { "tags": [ "priority", "rural" ] } ``` ### 400 response `idempotency_key_required`: The write has no Idempotency-Key header of 1 to 255 characters. `invalid_request`: A query parameter is invalid, or a write’s body is not a JSON object. Example 400 response: idempotency_key_required: ```json { "error": "idempotency_key_required", "error_description": "A write needs an Idempotency-Key header of 1 to 255 characters" } ``` Example 400 response: invalid_request: ```json { "error": "invalid_request", "error_description": "limit is invalid" } ``` ### 401 response The token is missing, invalid, expired or revoked, of another Organisation, or API access is not Full. Ask for a new token. Headers: `WWW-Authenticate`. Example 401 response: ```json { "error": "invalid_token", "error_description": "The access token is invalid or has expired" } ``` ### 403 response `https_required`: The request was sent over plain HTTP and was not processed. `insufficient_scope`: The credential does not hold the scope the route needs. `run_as_disabled`: The credential has no run-as Administrator, or that person is no longer one. `forbidden`: The run-as Administrator lacks the permission, or the record is outside their Data Access Rules. Headers: `WWW-Authenticate`. Example 403 response: https_required: ```json { "error": "https_required" } ``` Example 403 response: insufficient_scope: ```json { "error": "insufficient_scope", "error_description": "This credential lacks the write:applications scope" } ``` Example 403 response: run_as_disabled: ```json { "error": "run_as_disabled", "error_description": "This credential has no enabled run-as Administrator" } ``` Example 403 response: forbidden: ```json { "error": "forbidden", "error_description": "The run-as Administrator may not do this to this record" } ``` ### 404 response `not_found`: An unknown host or path, or an id that is unknown, deleted or of another Organisation. `module_disabled`: The Organisation has the module this route belongs to turned off. Example 404 response: not_found: ```json { "error": "not_found" } ``` Example 404 response: module_disabled: ```json { "error": "module_disabled", "error_description": "This module is not enabled for the Organisation" } ``` ### 409 response The first request with this Idempotency-Key has not finished. Nothing was written; retry after the given seconds. Headers: `Retry-After`. Example 409 response: ```json { "error": "idempotency_in_progress", "error_description": "The first request with this Idempotency-Key has not finished. If this persists it stopped part-way: check whether the record exists before writing again with a new key" } ``` ### 413 response The body, or the declared file, is larger than the limit that applies. Example 413 response: ```json { "error": "payload_too_large", "error_description": "The request body is too large" } ``` ### 415 response The body is not application/json, or the target does not accept the file’s content type. Example 415 response: ```json { "error": "unsupported_media_type", "error_description": "The request body must be application/json" } ``` ### 422 response `idempotency_key_reused`: The Idempotency-Key was used in the last 24 hours for a different method, path or body. `unknown_field`: The body has a property the route does not document; the first is named. `validation_failed`: Body values the product’s own form would refuse; `fields` names each. `unknown_tag`: A tag is not one of the Organisation’s tags. None is created. Example 422 response: idempotency_key_reused: ```json { "error": "idempotency_key_reused", "error_description": "This Idempotency-Key was used for a different request" } ``` Example 422 response: unknown_field: ```json { "error": "unknown_field", "error_description": "bank_account_number is not a writable field" } ``` Example 422 response: validation_failed: ```json { "error": "validation_failed", "error_description": "Invalid fields: due_date", "fields": [ "due_date" ] } ``` Example 422 response: unknown_tag: ```json { "error": "unknown_tag", "error_description": "urgent is not a tag of this Organisation" } ``` ### 429 response A rate limit was exceeded: 120 requests a minute per credential, 30 token requests a minute per client\_id. Headers: `Retry-After`. Example 429 response: ```json { "error": "rate_limited", "error_description": "Too many requests" } ``` ### 500 response An unexpected server error. Example 500 response: ```json { "error": "server_error" } ``` ### 503 response The Organisation’s API access cannot be determined, or a dependency is unavailable. Retry after the given seconds. Headers: `Retry-After`. Example 503 response: ```json { "error": "temporarily_unavailable" } ``` ## POST /api/v2/funding_applications/{id}/transitions **Move a funding application.** One of the Administrator’s record moves through the application’s own rules, with the messages and audit entries the screen makes. A move not open from the current status is 409 `invalid_transition` naming it. An `unlock` needs a `deadline` that is a future UTC timestamp with milliseconds, such as `2027-06-07T11:59:00.000Z`. - Operation ID: `transitionFundingApplication` - Authentication: A Bearer token from a credential holding the `write:applications` scope. Runs as the credential’s Administrator, and needs an `Idempotency-Key` header. Example request: ```bash curl -X POST "https://your-org.backed.giving/api/v2/funding_applications/42/transitions" \ -H "Authorization: Bearer $BACKED_TOKEN" \ -H "Idempotency-Key: 7d1f0c2e-5b8a-4f3e-9c61-2a4b8e9d0f13" \ -H "Content-Type: application/json" \ -d '{"transition":"unlock","message":"Please attach the updated budget.","deadline":"2027-06-07T11:59:00.000Z"}' ``` ### Parameters Parameters of POST /api/v2/funding_applications/{id}/transitions: | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `id` | path | Yes | `integer` | The record id. Anything but a positive integer is 404. Example: `42`. | | `Idempotency-Key` | header | Yes | `string` | A key of 1 to 255 characters, unique per write. A retry with the same key, method, path and body within 24 hours answers the first response again (with `Idempotent-Replayed: true`) and writes nothing. Example: `7d1f0c2e-5b8a-4f3e-9c61-2a4b8e9d0f13`. | ### Request body `application/json`, the `ApplicationTransition` schema. One of the Administrator’s record moves, with its parameters: `unlock` takes `message` and `deadline`, `request_more_information` `form_template_id`, the edit-request decisions `edit_request_id`. An unlock’s `deadline` is a future UTC timestamp with milliseconds (`2027-06-07T11:59:00.000Z`), the moment the editing window closes by itself; a date alone, or a moment already past, is 422 `validation_failed`. Fields of the ApplicationTransition body: | Field | Type | Required | Notes | | --- | --- | --- | --- | | `transition` | `string` | Yes | One of `withdraw`, `unlock`, `request_more_information`, `allow_edit_request`, `decline_edit_request`, `release_from_verifier`. | | `lock_version` | `integer` | No | | | `message` | `string` | No | | | `deadline` | `string` | No | | | `form_template_id` | `integer` | No | | | `edit_request_id` | `integer` | No | | Example request body: ```json { "transition": "unlock", "message": "Please attach the updated budget.", "deadline": "2027-06-07T11:59:00.000Z" } ``` ### 200 response The funding application as the list answers it. Headers: `Idempotent-Replayed`. Fields of FundingApplication: | Field | Type | Required | Notes | | --- | --- | --- | --- | | `id` | `integer` | Yes | | | `created_at` | `string` | Yes | | | `updated_at` | `string` | Yes | | | `funding_round_id` | `integer` | Yes | | | `state` | `string` | Yes | | | `title` | `string \| null` | Yes | | | `submitted_at` | `string \| null` | Yes | | | `funding_category` | `object \| null` | Yes | | | `registration_entity` | `object` | Yes | | | `lock_version` | `integer` | Yes | | | `requested_amount` | `string \| null` | No | | | `recommended_amount` | `string \| null` | No | | | `bank_account_number` | `string \| null` | No | | | `registration_entity_id` | `integer` | No | | Example 200 response: ```json { "id": 1287, "created_at": "2026-03-02T21:15:04.000Z", "updated_at": "2026-06-18T03:40:11.000Z", "funding_round_id": 42, "state": "submitted", "title": "Te Awa river restoration", "submitted_at": "2026-05-20T04:12:55.000Z", "funding_category": { "id": 7, "name": "Community" }, "registration_entity": { "id": 311, "name": "Te Awa Restoration Trust" }, "lock_version": 3, "requested_amount": "24500.0" } ``` ### 400 response `idempotency_key_required`: The write has no Idempotency-Key header of 1 to 255 characters. `invalid_request`: A query parameter is invalid, or a write’s body is not a JSON object. Example 400 response: idempotency_key_required: ```json { "error": "idempotency_key_required", "error_description": "A write needs an Idempotency-Key header of 1 to 255 characters" } ``` Example 400 response: invalid_request: ```json { "error": "invalid_request", "error_description": "limit is invalid" } ``` ### 401 response The token is missing, invalid, expired or revoked, of another Organisation, or API access is not Full. Ask for a new token. Headers: `WWW-Authenticate`. Example 401 response: ```json { "error": "invalid_token", "error_description": "The access token is invalid or has expired" } ``` ### 403 response `https_required`: The request was sent over plain HTTP and was not processed. `insufficient_scope`: The credential does not hold the scope the route needs. `run_as_disabled`: The credential has no run-as Administrator, or that person is no longer one. `forbidden`: The run-as Administrator lacks the permission, or the record is outside their Data Access Rules. Headers: `WWW-Authenticate`. Example 403 response: https_required: ```json { "error": "https_required" } ``` Example 403 response: insufficient_scope: ```json { "error": "insufficient_scope", "error_description": "This credential lacks the write:applications scope" } ``` Example 403 response: run_as_disabled: ```json { "error": "run_as_disabled", "error_description": "This credential has no enabled run-as Administrator" } ``` Example 403 response: forbidden: ```json { "error": "forbidden", "error_description": "The run-as Administrator may not do this to this record" } ``` ### 404 response An unknown host or path, or an id that is unknown, deleted or of another Organisation. Example 404 response: ```json { "error": "not_found" } ``` ### 409 response `idempotency_in_progress`: The first request with this Idempotency-Key has not finished. Nothing was written; retry after the given seconds. `invalid_transition`: The move is not open from where the record stands; `current_status` says where that is. `invalid_state`: The record is not in a state that admits this write. Headers: `Retry-After`. Example 409 response: idempotency_in_progress: ```json { "error": "idempotency_in_progress", "error_description": "The first request with this Idempotency-Key has not finished. If this persists it stopped part-way: check whether the record exists before writing again with a new key" } ``` Example 409 response: invalid_transition: ```json { "error": "invalid_transition", "error_description": "The record cannot make this move from approved", "current_status": "approved" } ``` Example 409 response: invalid_state: ```json { "error": "invalid_state", "error_description": "The target does not take files in its current state" } ``` ### 412 response If-Match is missing, malformed or not the record’s current lock\_version, or the record changed under the write. Nothing was written. Example 412 response: ```json { "error": "precondition_failed", "error_description": "If-Match must carry the record’s current lock_version" } ``` ### 413 response The body, or the declared file, is larger than the limit that applies. Example 413 response: ```json { "error": "payload_too_large", "error_description": "The request body is too large" } ``` ### 415 response The body is not application/json, or the target does not accept the file’s content type. Example 415 response: ```json { "error": "unsupported_media_type", "error_description": "The request body must be application/json" } ``` ### 422 response `idempotency_key_reused`: The Idempotency-Key was used in the last 24 hours for a different method, path or body. `unknown_field`: The body has a property the route does not document; the first is named. `validation_failed`: Body values the product’s own form would refuse; `fields` names each. Example 422 response: idempotency_key_reused: ```json { "error": "idempotency_key_reused", "error_description": "This Idempotency-Key was used for a different request" } ``` Example 422 response: unknown_field: ```json { "error": "unknown_field", "error_description": "bank_account_number is not a writable field" } ``` Example 422 response: validation_failed: ```json { "error": "validation_failed", "error_description": "Invalid fields: due_date", "fields": [ "due_date" ] } ``` ### 429 response A rate limit was exceeded: 120 requests a minute per credential, 30 token requests a minute per client\_id. Headers: `Retry-After`. Example 429 response: ```json { "error": "rate_limited", "error_description": "Too many requests" } ``` ### 500 response An unexpected server error. Example 500 response: ```json { "error": "server_error" } ``` ### 503 response The Organisation’s API access cannot be determined, or a dependency is unavailable. Retry after the given seconds. Headers: `Retry-After`. Example 503 response: ```json { "error": "temporarily_unavailable" } ```