Plinth
Plinth

Endpoints

Members

Members are at the centre of our company, and are the beating heart of what you do. The members API is orientated around allowing you to retrieve, filter, and create members for your organisation or an organisation whose data you have access to.

If you would like to have a webhook that is called on member creation/modification, please reach out & we will be happy to oblige. All routes in the below API will require an API key or a valid Firebase authentication token.

Overview

When a user signs up & attends an event, or is created by you, we create a member document with all their information embedded within it. If they fill in a form, their answers are embedded into their document. When a postcode is added, we also add the relevant ward, LSOA, LAD etc. information to enable automatic geographic analysis of trends within your membership.

The V1 API returns member data in a structured format, based on your organisation's schema. It also provides a link to fetch the schema itself for each member.

Members

GET (List and Filter Members)

Retrieve a list of members, with support for pagination and direct field filtering.

Endpoint

https://app.plinth.org.uk/api/v1/members

Query Parameters

Organisation Context (Required):

  • API Key Authentication: The organisationId is determined from your API key. If you include an organisationId query parameter, it must match the one associated with your API key.
  • Firebase Authentication: You must provide the organisationId as a query parameter (e.g., ?organisationId=your_org_id). This specifies the organisation whose members you wish to list.

Pagination (Optional):

  • limit (number, default: 100, max: 250): Specifies the maximum number of members to return per page.

  • offset (number, default: 0): Specifies the number of members to skip before starting to collect the result set. Used for pagination.

    Example: ?organisationId=your_org_id&limit=50&offset=100

Field Filtering (Optional):

Any other query parameters provided will be treated as direct field equality filters. The API will return members where the specified field exactly matches the provided value.

  • Field names are case-sensitive and should match the keys in your member data (which often align with your organisation's schema field names or IDs).

  • For nested fields (e.g., within a demographics object), use dot notation: demographics.city=London.

  • Values are typically strings. The API will attempt to parse numeric and boolean (true, false) values from the query string.

  • Currently, only exact equality (==) filters are supported.

  • You can combine multiple field filters (e.g., ?status=active&customField.region=North). Firestore indexing on these fields is crucial for performance.

    Example: ?email=test@example.com&demographics.postcode=AN1EX2P

Response Object

A JSON object containing an array of member data objects, along with pagination metadata.

{
  "members": [
    {
      "memberId": "firebaseGeneratedMemberId1",
      "fields": [
        {
          "key": "email",
          "label": "Email Address",
          "value": "test@example.com",
          "type": "email"
        },
        {
          "key": "name",
          "label": "Full Name",
          "value": "A. Example",
          "type": "text"
        }
        // ... other fields for this member based on schema
      ],
      "schemaInfo": {
        "organisationId": "your_org_id",
        "schemaId": "master",
        "_links": {
          "schema": {
            "href": "/api/v1/schemas/your_org_id"
          }
        }
      }
    },
    {
      "memberId": "firebaseGeneratedMemberId2",
      "fields": [
        // ... fields for this member
      ],
      "schemaInfo": {
        // ... schema info for this member
      }
    }
    // ... more members up to the limit
  ],
  "offset": 0,
  "limit": 100
}

Each object in the members array represents one member and includes:

  • memberId: The unique Firebase ID of the member.
  • fields: An array of objects, where each object represents a field from the organisation's schema that has a value for this member (see GET /api/v1/members/[memberId] for field object structure).
  • schemaInfo: Information about the schema used for this member, including a link to the schema definition (see GET /api/v1/members/[memberId] for schemaInfo structure).

Members/[memberId]

GET

Get a specific member by their ID. The data returned is based on the organisation's schema.

Endpoint

https://app.plinth.org.uk/api/v1/members/[memberId]

Replace [memberId] with the actual ID of the member.

Query Parameters

No client-supplied query parameters are required for this endpoint. The organisation context is determined automatically:

  • API Key Authentication: The organisationId is derived from your API key. The system ensures the key is valid for the organisation that manages the requested member.
  • Firebase Authentication: The system fetches the member and uses their managedBy field (the organisationId) to verify your access rights.

Response Object

The response contains the member's data structured as an array of fields, along with information about the schema used.

{
  "member": {
    "fields": [
      {
        "key": "email",
        "label": "Email Address",
        "value": "example.user@email.com",
        "type": "email"
      },
      {
        "key": "name",
        "label": "Full Name",
        "value": "A. Example",
        "type": "text"
      },
      {
        "key": "demographics.age",
        "label": "Age",
        "value": 30,
        "type": "number"
      },
      {
        "key": "customQuestion1",
        "label": "Why did you come to use us?",
        "value": "To find assistance.",
        "type": "textarea"
      }
      // ... other fields as defined in the organisation's schema
    ]
  },
  "schemaInfo": {
    "organisationId": "org_id_for_this_member",
    "schemaId": "master", // Currently always 'master'
    "_links": {
      "schema": {
        "href": "/api/v1/schemas/org_id_for_this_member"
      }
    }
  }
}

The fields array will contain an object for each field defined in your organisation's schema that has a value for the requested member.

  • key: The unique identifier for the field (can use dot-notation for nested fields, e.g., demographics.ethnicity).
  • label: The human-readable label for the field.
  • value: The value of the field for this member.
  • type: (Optional) The data type of the field (e.g., text, number, date, select).
  • options: (Optional) If the field is a 'select' or 'radio' type, this array will contain the available options, e.g., [{ "value": "opt1", "label": "Option 1" }].

Members

POST

Create a new member.

Endpoint

https://app.plinth.org.uk/api/v1/members

Request Body

The request body should be a JSON object containing the data for the new member. The keys in the object should correspond to the name (or id) of the fields in your organisation's schema.

{
  "email": "new.member@example.com",
  "name": "New Member Name",
  "demographics.dateOfBirth": "1990-01-01",
  "customFieldKeyFromSchema": "Answer to custom question"
  // ... other fields and their values
}

Organisation ID for Firebase Authentication: If you are authenticating with a Firebase token (instead of an API key), you must specify the organisationId under which to create the member. This is because a Firebase user can belong to multiple organisations. You can provide it in one of two ways:

  1. As a query parameter: POST /api/v1/members?organisationId=your_org_id
  2. As a field in the JSON request body: json { "organisationId": "your_org_id", "email": "new.member@example.com", // ... other data } If using an API key, the organisationId is automatically determined from the key, and you should not include it in the request.

Response Object

If successful, the API will return the ID of the newly created member.

{
  "member": {
    "id": "generatedMemberId"
  }
}
Previous
Programmes