How to use the ServeHQ Open API

With our Open API you can connect your account to many church management or database software available!

A basic development knowledge is required for this type of integration. If you are looking for our Planning Center integration to import your people, click here for more information.

Open API and How to Get Started

The ServeHQ API is enabled by the tokens generated in the Settings menu.

To make use of the token in your request, include it in the Authorization header as Bearer <token>All responses are in JSON format, and all requests likewise must be of the Content-type application/json. You need to add Accept: application/json and Content-type: application/json to your headers.

Endpoints and Use cases

Common Variables

All endpoints are scoped to the context of your Church’s account. The variable that denotes this is the <account_slug> variable. This is the first part of the path to your TrainedUp account, immediately before the ‘#’ in the URL.

Each Object’s id is found in the web app URLs, or can be found by requesting a list of all objects.

Every endpoint that returns a list of users accepts ministry_area=<ministry_area_id> and campus=<campus_id> parameters to filter the results by these taxonomies.

Reports

GET /api/<account_slug>/course/<course_id>/report?status=<completion_status>

Returns a paginated list of users with completion data. To get a report from the api, it’s required to pass a completion_status.

Valid completion statuses are as follows:

status=enrolled – Returns all users enrolled in the course

status=complete – Returns all users who are enrolled in the course and have completed it

status=incomplete – Returns all users who are enrolled in the course and have not completed it

status=unenrolled – Returns all users who are not enrolled in the course

Users

GET /api/<account_slug>/users – Lists all users

POST /api/<account_slug>/user – Create a user. This endpoint accepts the following parameters:

• name: required|string, // valid name for the user
• email: required|string, // valid email address for the user
• permissions:  array, // array of permissions to give the user (only will grant permissions with a “true” key)
• ministries: array, // array of Ministry Areas to add the user to.
• campus: integer // ID of Campus to add the user to.

Courses

POST /api/<account_slug>/course/<course_id>/learner – Enroll a team member in the given course. Accepts the following parameters:

Team Member: required|integer, // valid id of a user to enroll

GET /api/<account_slug>/course/<course_id>/learner/<user_id> – Check a user’s completion of a course: Returns the following information:

• id: int //user’s id
• email: string // user’s email
• created_at: string // user’s date of creation
• user_status: //unused(leftover from old data structure)
• name: string //users’ name
• spam: //unused, leftover from previous data structure
• deleted: //unused, leftover from previous data structure
• disable_notifications: int|bool //whether or not the user has disabled notifications
• updated_at: string // timestamp of last update made to user
• gravatar: string // user’s gravatar URL
• pivot: object //contains info about the relationship of the user to the course
• course_id: int //id of course
• user_id: int //id of user
• finished: string|null //timestamp of user’s course completion data, or null if incomplete. Older accounts may see “true” instead if the completion was before we added timestamps

For additional questions or support, please get in touch.