JSON-API

This API is built to conform to the JSON API 1.0 specification.

Some benefits:

• Excellent documentation is already available here and we do our best to stay true to it.

• Our API returns resources that contain links to related resources, making it easier to "browse" this API and learn about associated endpoints.

• You can include related resources by adding ?include=something to the URL. This makes grabbing what you need much simpler.

Data Format

Resources are wrapped in an object that always has at least a data key.

For an endpoint that returns multiple resources, e.g. /people/v2/people, the result will be an object having a data key with an array for its value:

{
  "data": [
    {
      "type": "Thing",
      "id": "1",
      "attributes": { /*..*/ }
    },
    {
      "type": "Thing",
      "id": "2",
      "attributes": { /*..*/ }
    }
  ]
}

For an endpoint that returns a single resource, e.g. /people/v2/people/123, the result will be an object having a data key with an object for its value:

{
  "data": {
    "type": "Thing",
    "id": "1",
    "attributes": { /*..*/ }
  }
}

Creating or updating resources also requires that same structure. Be sure to wrap the payload with the same { "data": { ... } } wrapper and put the resource's attributes inside the "attributes" object.

Filtering Results

Filtering results of an endpoint can be done a few different ways: either by using where or with a filter.

Where

Querying by where lets you restrict the results of an endpoint based on the value of one or more attributes. The format is where[ATTRIBUTE]=VALUE. By default, the condition is a simple equality check, e.g. https://api.planningcenteronline.com/people/v2/people?where[first_name]=Tim will return people whose first name exactly matches "Tim" (case insensitively).

Adding a URL-escaped ʼ%ʼ character (encoded as %25) to the beginning or end of the value lets you match part of a string, e.g. https://api.planningcenteronline.com/people/v2/people?where[first_name]=Tim%25 will return people whose first name starts with "Tim", and thus would match Tim, Timmy, Timothy, etc. Note there are some attributes that do not support this operator, due to performance reasons.

You can query for resources before or after certain dates and times by using gt, gte, lt, and lte. The construction of these operators is of the format where[ATTRIBUTE][OPERATOR]=VALUE, e.g. https://api.planningcenteronline.com/people/v2/people?where[birthdate][lte]=1981-04-28 will return people whose birthdate is on or before (less-than-or-equal to) April 28, 1981. You can learn more in the Dates & Times section of the documentation.

Lastly, you can query based on included resources (see the Including Related Resources section below) by using an additional set of square brackets of the format where[ASSOCIATION][ATTRIBUTE]=VALUE, e.g. https://api.planningcenteronline.com/people/v2/people?include=emails&where[emails][address]=tim@example.com will return people who have an email address equal to "tim@example.com".

Attributes available to query by where are documented in the Query By section of the API documentation for a resource.

Filter

Filtering is a way for an endpoint to provide advanced querying that a simple where might not allow. Use the filter parameter to enable a filter, e.g. https://api.planningcenteronline.com/people/v2/people/13/messages?filter=received. Available filters are documented in the Associations section of the API documentation for a resource, under the Filter By column.

Including Related Resources

Often, an endpoint will allow you to query a parent resource along with some child or other linked resource. For instance, you can query both a Person resource and all the associated email addresses (a one-to-many relationship) in a single query. You can also query a FieldDatum along with its associated FieldDefinition (a many-to-one relationship).

You use the include parameter to specify what resources to include, each one separated by a comma, e.g.: https://api.planningcenteronline.com/people/v2/people?include=emails,phone_numbers, which returns results like this:

{
  "data": [
    {
      "type": "Person",
      "id": "13",
      "attributes": {
        /* ... */
      },
      "relationships": {
        "emails": {
          "data": [
            { "type": "Email", "id": "11914559" },
            { "type": "Email", "id": "53967483" }
          ]
        },
        "phone_numbers": {
          "data": [
            { "type": "PhoneNumber", "id": "6706677" }
          ]
        }
      }
    }
  ],
  "included": [
    {
      "type": "Email",
      "id": "11914559",
      "attributes": {
        "address": "matt@example.com"
        /* ... */
      }
    },
    {
      "type": "Email",
      "id": "53967483",
      "attributes": {
        "address": "matthew@example.com"
        /* ... */
      }
    },
    {
      "type": "PhoneNumber",
      "id": "6706677",
      "attributes": {
        "number": "(123) 456-7890"
        /* ... */
      }
    }
  ]
}

You can read more about the include parameter in the JSON API documentation.