Welcome to the One Church Software API!

This API reference provides information on available endpoints and how to interact with them. This allows a third party system to communicate with One Church to read and write data.

Getting Started

A One Church Software account is required to access the API. To learn more about our platform or to sign up for an account, visit our website at https://www.onechurchsoftware.com.

Authentication / Authorization

• The API utilizes an API Key for authentication. To generate or manage API Keys, log into your One Church account, and click on the API / Webhooks option in the cog menu in the top header.
• Authorization (i.e. what data is accessible and which web services can be called) is determined by the access rights assigned to a given API Key.
• The API Key is passed as a Header in the web service call. The Header key is Ocs-Api-Key and the value is the API key itself.
• Do not expose the API Key publicly. It should only be used in server side code. Regenerate if you believe it has been compromised.

Rate Limiting

Web service calls are throttled at 30 requests per 10 seconds per API key. All calls contain the following response headers which provide insight into an API key's current quota:

• Ocs-Rate-Limit-Remaining - the number of requests remaining in the current time period window.
• Retry-After - if rate limit was exceeded, the number of seconds to wait before being able to make more calls.

Requests that exceed the current limit will return an HTTP status 429.

Base URL

The base URL for all web services is structured asfollows:

https://{tenant}.onechurchsoftware.com/api

Paging

Web services containing lists of records are returned in the format below to allow for easy paging through results.

{
    "total": 100,
    "limit": 25,
    "skip": 0,
    "max": 4,
    "data": []
}

• total - the total number of records across all pages
• limit - the number of records to return per page.
• skip - the number of records to skip.
• max - the total number of pages across all results. A page is determined by the limit value.
• data - the actual data. Schema is determined by the web service being called.

These web services typically contain query parameters limit and skip to support paging. For example, if the page size (i.e. limit) is 25 records, to access the 3nd page of results, pass limit=25 and skip=50 as parameters. In other words, this will skip 50 records and return the next 25.

The skip can be calculated with the following formula: limit * (page - 1)

Filtering by Custom Fields

Some endpoints (such as /people and /groups among others) support filtering by custom fields. These filters are passed as query strings such that id=value

• id: the unique id or field id of the custom field to filter
• value: the specific value to filter for. For dropdowns, checkbox list, and radio button list, this is a comma delimited list of ids. If custom field is not required, include -1 if you want records without any value set. For ranges such as numbers or dates, specify start and/or end as dot notation from the field id (see example below).

Example
The query string parameters below searches where a custom text field with ID = 34 has a value containing the word rainbow:

/api/people?34=rainbow

Another example showing a numeric range for a field with ID = 10 where the value is between 1 and 99:

/api/people?10.start=1&10.end=99

One more example for a field containing options such as a dropdown, radio button list or checkbox list. This finds results where a field with ID = 56 has a value of either dog or cat:

/api/people?56=dog,cat