Schemas

The Schemas API allows you to retrieve the field schema for an organisation. Schemas define the custom fields available for members, volunteers, and partners in your organisation.

Get Organisation Schema

Retrieve the schema for a specific organisation.

Endpoint

GET /api/v1/schemas/:organisationId

Path Parameters

• organisationId (string, required) - The unique identifier of the organisation

Response

{
  "organisationId": "org123",
  "schemaId": "master",
  "name": "Member Schema",
  "fields": [
    {
      "id": "Full Name",
      "name": "Full Name",
      "label": "Full Name",
      "type": "text",
      "order": 1
    },
    {
      "id": "Email",
      "name": "Email",
      "label": "Email Address",
      "type": "email",
      "order": 2
    },
    {
      "id": "Phone",
      "name": "Phone",
      "label": "Phone Number",
      "type": "phone",
      "order": 3
    },
    {
      "id": "Postcode",
      "name": "Postcode",
      "label": "Postcode",
      "type": "text",
      "order": 4
    },
    {
      "id": "Date of Birth",
      "name": "Date of Birth",
      "label": "Date of Birth",
      "type": "date",
      "order": 5
    },
    {
      "id": "demographics.ethnicity",
      "name": "Ethnicity",
      "label": "Ethnicity",
      "type": "select",
      "order": 6
    },
    {
      "id": "customQuestion1",
      "name": "How did you hear about us?",
      "label": "How did you hear about us?",
      "type": "select",
      "order": 7
    }
  ]
}

Example Request

curl -X GET "https://app.plinth.org.uk/api/v1/schemas/org123" \
  -H "x-api-key: sk_your_api_key"

Response Fields

Schema Object

Field Object

Field Types

Member and registration schemas support the following field types:

Text & Input Types

Contact Types

Selection Types

Specialised Types

Display Types

Using Schema Information

Selecting Profile Fields in Bookings

When using the Bookings API, you can specify which profile fields to return using the profileFields parameter. Use the field id values from the schema:

curl -X GET "https://app.plinth.org.uk/api/v1/bookings?profileFields=Full Name,Email,Date of Birth" \
  -H "x-api-key: sk_your_api_key"

Creating Members with Custom Fields

When creating members via the Members API, use the field id or name as the key in your request body:

curl -X POST "https://app.plinth.org.uk/api/v1/members" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "Full Name": "John Smith",
    "Email": "john@example.com",
    "Postcode": "SW1A 1AA",
    "demographics.ethnicity": "Prefer not to say"
  }'

Nested Fields

Some fields use dot notation (e.g., demographics.ethnicity) to indicate they belong to a nested object. When filtering or creating records, use the full dot-notation path.

Schema Info in API Responses

Many endpoints return a schemaInfo object that includes a link to the schema endpoint:

{
  "schemaInfo": {
    "organisationId": "org123",
    "schemaId": "master",
    "_links": {
      "self": {
        "href": "/api/v1/schemas/org123"
      }
    }
  }
}

This follows HATEOAS principles, allowing you to discover the schema dynamically.

Error Responses