How to Use the Open API

Benjamin Staton Updated by Benjamin Staton

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.

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 useremail: required|string, // valid email address for the userpermissions:  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. Only available in Standard or Multi-site tierscampus: integer // ID of Campus to add the user to. Only available in Multi-site tier

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, reach out to us via the chat screen in the lower right-hand corner of this page.

Did you find this helpful?

How do User Permissions work?

How to get receipts of past payments

Get in touch