Volunteers

The Volunteers API allows you to retrieve volunteer information for your organisation. Volunteers are individuals who give their time to support your events and activities.

List Volunteers

Retrieve a paginated list of volunteers with optional filtering.

Endpoint

GET /api/v1/volunteers

Query Parameters

Pagination:

• limit (number, default: 100, max: 250) - Maximum number of volunteers to return
• offset (number, default: 0) - Number of volunteers to skip for pagination

Filtering:

• postcode (string) - Filter volunteers by postcode
• Any other volunteer field can be used as a filter

Response

{
  "volunteers": [
    {
      "volunteerId": "vol_abc123",
      "fields": [
        {
          "key": "email",
          "label": "Email Address",
          "value": "volunteer@example.com",
          "type": "email"
        },
        {
          "key": "name",
          "label": "Full Name",
          "value": "Jane Smith",
          "type": "text"
        },
        {
          "key": "phone",
          "label": "Phone Number",
          "value": "+44 7700 900123",
          "type": "phone"
        },
        {
          "key": "postcode",
          "label": "Postcode",
          "value": "SW1A 1AA",
          "type": "text"
        }
      ]
    }
  ],
  "schemaInfo": {
    "organisationId": "org123",
    "schemaId": "master",
    "name": "Volunteer Schema",
    "_links": {
      "self": {
        "href": "/api/v1/schemas/org123"
      }
    }
  },
  "offset": 0,
  "limit": 100,
  "total": 45
}

Example Request

curl -X GET "https://app.plinth.org.uk/api/v1/volunteers?limit=50" \
  -H "x-api-key: sk_your_api_key"

Filter by Postcode

curl -X GET "https://app.plinth.org.uk/api/v1/volunteers?postcode=SW1A" \
  -H "x-api-key: sk_your_api_key"

Get Single Volunteer

Retrieve a specific volunteer by their ID.

Endpoint

GET /api/v1/volunteers/:volunteerId

Path Parameters

• volunteerId (string, required) - The unique identifier of the volunteer

Response

{
  "volunteer": {
    "volunteerId": "vol_abc123",
    "fields": [
      {
        "key": "email",
        "label": "Email Address",
        "value": "volunteer@example.com",
        "type": "email"
      },
      {
        "key": "name",
        "label": "Full Name",
        "value": "Jane Smith",
        "type": "text"
      },
      {
        "key": "phone",
        "label": "Phone Number",
        "value": "+44 7700 900123",
        "type": "phone"
      },
      {
        "key": "availability",
        "label": "Availability",
        "value": "Weekends",
        "type": "select"
      },
      {
        "key": "skills",
        "label": "Skills",
        "value": ["First Aid", "Event Management"],
        "type": "multiselect"
      }
    ]
  },
  "schemaInfo": {
    "organisationId": "org123",
    "schemaId": "master",
    "_links": {
      "self": {
        "href": "/api/v1/schemas/org123"
      }
    }
  }
}

Example Request

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

Response Fields

Each volunteer in the response contains:

Field Object Structure

Error Responses