Registration Entities

GET /api/v2/registration_entities

List registration entities.

Every live registration entity of the Organisation in ascending id order, at most 50 a page. No users: personal data is on the single record only.

• Operation ID: listRegistrationEntities
• Authentication: A Bearer token from a credential holding the read scope.
• Also served at /funding_system/api/v2/registration_entities, the documented product’s alias path.

curl "https://your-org.backed.giving/api/v2/registration_entities" \
  -H "Authorization: Bearer $BACKED_TOKEN"

Parameters

200 response

A JSON array of registration entities.

[
  {
    "id": 311,
    "created_at": "2026-03-02T21:15:04.000Z",
    "updated_at": "2026-06-18T03:40:11.000Z",
    "name": "Te Awa Restoration Trust",
    "registration_type": {
      "id": 2,
      "name": "Organisation"
    },
    "lock_version": 4
  }
]

400 response

A query parameter is invalid, or a write’s body is not a JSON object.

{
  "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.

{
  "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.

{
  "error": "https_required"
}

404 response

An unknown host or path, or an id that is unknown, deleted or of another Organisation.

{
  "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.

{
  "error": "rate_limited",
  "error_description": "Too many requests"
}

500 response

An unexpected server error.

{
  "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.

{
  "error": "temporarily_unavailable"
}

POST /api/v2/registration_entities

Add an applicant: a person and their registration entity.

Add Applicant as the run-as Administrator (applicants.add). Without invite nobody is told and the record reads Unclaimed.

• Operation ID: createRegistrationEntity
• Authentication: A Bearer token from a credential holding the write:registrations scope. Runs as the credential’s Administrator, and needs an Idempotency-Key header.

curl -X POST "https://your-org.backed.giving/api/v2/registration_entities" \
  -H "Authorization: Bearer $BACKED_TOKEN" \
  -H "Idempotency-Key: 7d1f0c2e-5b8a-4f3e-9c61-2a4b8e9d0f13" \
  -H "Content-Type: application/json" \
  -d '{"registration_type_id":2,"entity_name":"Te Awa Restoration Trust","first_name":"Aroha","last_name":"Ngata","email":"aroha@example.org","invite":true}'

Parameters

Request body

application/json, the RegistrationEntityCreate schema. Add Applicant: the Registration Type, the person, and for an organisation the entity’s name. invite sends the applicant invitation (default false).

{
  "registration_type_id": 2,
  "entity_name": "Te Awa Restoration Trust",
  "first_name": "Aroha",
  "last_name": "Ngata",
  "email": "aroha@example.org",
  "invite": true
}

201 response

The registration entity as the single read answers it.

Headers: Idempotent-Replayed.

{
  "id": 311,
  "created_at": "2026-03-02T21:15:04.000Z",
  "updated_at": "2026-06-18T03:40:11.000Z",
  "name": "Te Awa Restoration Trust",
  "registration_type": {
    "id": 2,
    "name": "Organisation"
  },
  "lock_version": 4,
  "users": [
    {
      "id": 5012,
      "email": "aroha@example.org",
      "first_name": "Aroha",
      "last_name": "Ngata"
    }
  ]
}

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.

{
  "error": "idempotency_key_required",
  "error_description": "A write needs an Idempotency-Key header of 1 to 255 characters"
}

{
  "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.

{
  "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.

{
  "error": "https_required"
}

{
  "error": "insufficient_scope",
  "error_description": "This credential lacks the write:applications scope"
}

{
  "error": "run_as_disabled",
  "error_description": "This credential has no enabled run-as Administrator"
}

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "error": "idempotency_key_reused",
  "error_description": "This Idempotency-Key was used for a different request"
}

{
  "error": "unknown_field",
  "error_description": "bank_account_number is not a writable field"
}

{
  "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.

{
  "error": "rate_limited",
  "error_description": "Too many requests"
}

500 response

An unexpected server error.

{
  "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.

{
  "error": "temporarily_unavailable"
}

GET /api/v2/registration_entities/{id}

Get one registration entity with its users.

Every list property, then users[]: the account owner first.

• Operation ID: getRegistrationEntity
• Authentication: A Bearer token from a credential holding the read scope.
• Also served at /funding_system/api/v2/registration_entities/{id}, the documented product’s alias path.

curl "https://your-org.backed.giving/api/v2/registration_entities/42" \
  -H "Authorization: Bearer $BACKED_TOKEN"

Parameters

200 response

The registration entity with its users.

{
  "id": 311,
  "created_at": "2026-03-02T21:15:04.000Z",
  "updated_at": "2026-06-18T03:40:11.000Z",
  "name": "Te Awa Restoration Trust",
  "registration_type": {
    "id": 2,
    "name": "Organisation"
  },
  "lock_version": 4,
  "users": [
    {
      "id": 5012,
      "email": "aroha@example.org",
      "first_name": "Aroha",
      "last_name": "Ngata"
    }
  ]
}

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.

{
  "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.

{
  "error": "https_required"
}

404 response

An unknown host or path, or an id that is unknown, deleted or of another Organisation.

{
  "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.

{
  "error": "rate_limited",
  "error_description": "Too many requests"
}

500 response

An unexpected server error.

{
  "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.

{
  "error": "temporarily_unavailable"
}

PATCH /api/v2/registration_entities/{id}

Edit an organisation’s Founded date and stage override.

The profile’s own edit (applicants.edit) at the If-Match version: a stale version is 412 before anything is written. Never the bank account.

• Operation ID: updateRegistrationEntity
• Authentication: A Bearer token from a credential holding the write:registrations scope. Runs as the credential’s Administrator, and needs an Idempotency-Key header.

curl -X PATCH "https://your-org.backed.giving/api/v2/registration_entities/42" \
  -H "Authorization: Bearer $BACKED_TOKEN" \
  -H "If-Match: 4" \
  -H "Idempotency-Key: 7d1f0c2e-5b8a-4f3e-9c61-2a4b8e9d0f13" \
  -H "Content-Type: application/json" \
  -d '{"founded_on":"2014-03-01","stage_override":"growth","stage_override_reason":"Confirmed by the 2025 annual report."}'

Parameters

Request body

application/json, the RegistrationEntityUpdate schema. An organisation’s Founded date and stage override. Only the properties sent change.

{
  "founded_on": "2014-03-01",
  "stage_override": "growth",
  "stage_override_reason": "Confirmed by the 2025 annual report."
}

200 response

The registration entity as the single read answers it.

Headers: Idempotent-Replayed.

{
  "id": 311,
  "created_at": "2026-03-02T21:15:04.000Z",
  "updated_at": "2026-06-18T03:40:11.000Z",
  "name": "Te Awa Restoration Trust",
  "registration_type": {
    "id": 2,
    "name": "Organisation"
  },
  "lock_version": 4,
  "users": [
    {
      "id": 5012,
      "email": "aroha@example.org",
      "first_name": "Aroha",
      "last_name": "Ngata"
    }
  ]
}

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.

{
  "error": "idempotency_key_required",
  "error_description": "A write needs an Idempotency-Key header of 1 to 255 characters"
}

{
  "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.

{
  "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.

{
  "error": "https_required"
}

{
  "error": "insufficient_scope",
  "error_description": "This credential lacks the write:applications scope"
}

{
  "error": "run_as_disabled",
  "error_description": "This credential has no enabled run-as Administrator"
}

{
  "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.

{
  "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.

{
  "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"
}

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.

{
  "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.

{
  "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.

{
  "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.

{
  "error": "idempotency_key_reused",
  "error_description": "This Idempotency-Key was used for a different request"
}

{
  "error": "unknown_field",
  "error_description": "bank_account_number is not a writable field"
}

{
  "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.

{
  "error": "rate_limited",
  "error_description": "Too many requests"
}

500 response

An unexpected server error.

{
  "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.

{
  "error": "temporarily_unavailable"
}

POST /api/v2/registration_entities/{id}/users

Invite a user to a registration entity.

Invite Applicant (applicants.invite): an existing person is attached, never duplicated; a new address is sent the applicant invitation, never a password.

• Operation ID: addRegistrationEntityUser
• Authentication: A Bearer token from a credential holding the write:registrations scope. Runs as the credential’s Administrator, and needs an Idempotency-Key header.

curl -X POST "https://your-org.backed.giving/api/v2/registration_entities/42/users" \
  -H "Authorization: Bearer $BACKED_TOKEN" \
  -H "Idempotency-Key: 7d1f0c2e-5b8a-4f3e-9c61-2a4b8e9d0f13" \
  -H "Content-Type: application/json" \
  -d '{"email":"rawiri@example.org","first_name":"Rawiri","last_name":"Ngata"}'

Parameters

Request body

application/json, the RegistrationEntityUserCreate schema. Invite Applicant: an existing person of the Organisation is attached; a new address is sent the applicant invitation.

{
  "email": "rawiri@example.org",
  "first_name": "Rawiri",
  "last_name": "Ngata"
}

201 response

The membership.

Headers: Idempotent-Replayed.

{
  "registration_entity_id": 311,
  "user_id": 5013,
  "email": "rawiri@example.org",
  "invited": true
}

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.

{
  "error": "idempotency_key_required",
  "error_description": "A write needs an Idempotency-Key header of 1 to 255 characters"
}

{
  "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.

{
  "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.

{
  "error": "https_required"
}

{
  "error": "insufficient_scope",
  "error_description": "This credential lacks the write:applications scope"
}

{
  "error": "run_as_disabled",
  "error_description": "This credential has no enabled run-as Administrator"
}

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "error": "idempotency_key_reused",
  "error_description": "This Idempotency-Key was used for a different request"
}

{
  "error": "unknown_field",
  "error_description": "bank_account_number is not a writable field"
}

{
  "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.

{
  "error": "rate_limited",
  "error_description": "Too many requests"
}

500 response

An unexpected server error.

{
  "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.

{
  "error": "temporarily_unavailable"
}