In previous tutorials, we discovered how to manage all the various aspects of MSP volunteer records.
For the next few tutorials, we’ll focus on managing all the various aspects of MSP service records.
In this step-by-step tutorial, I’ll share how to create a service record using the MSP REST API using both PHP and Python.
We’ll start with PHP as the primary language and then explore how to achieve the same task using Python. But first, before we write one line of code, be sure you have reviewed and adhered to the requirements on the “Getting Started” page.
And no worries, whether you’re a tech-savvy individual or a non-tech person eager to learn, I’ll guide you through the process at every step. It’ll be easy (or at least that’s the hope!).
Overview of the Services Collection
In addition to volunteers, we all know that services are the foundation of what makes MSP go. Next to volunteers, the services are one of the most accessed collections of the MSP REST API. To access its data, the Services collection consists of the following endpoints:
- CREATE uses this endpoint, /services, which allows API requests to create a single service record.
- GET uses this endpoint, /services/{serviceId}, which allows API requests to retrieve and access a single service record based on the unique service’s MSP ID.
- PUT uses this endpoint, /services/{serviceId}, which allows API requests to access and update a single service record based on the unique service’s MSP ID.
- DELETE uses this endpoint, /services/{serviceId}, which allows API requests to access and delete a single service record based on the unique service’s MSP ID.
- POST uses this endpoint, /services/list, which allows API requests to retrieve and access a list of service records.
There are 12 Service properties to consider (see codebase below or MSP REST API documentation) when accessing the Services collection.
In this tutorial, we’ll focus on mastering the CREATE endpoint of the Services collection.
As I know you’re eager to get started, so let’s dive in and explore the world of creating a service record using MSP REST API without further ado.
How to create a service record using PHP.
First, I’ll share how to create a service record via MSP REST API using PHP. And no worries if PHP is not your cup of tea.
In addition, after this tutorial, I’ll share how to do the same task, but instead of using PHP, you’ll use Python. But for now, let’s rock and roll with PHP.
Setting up API Variables.
Before we start, ensure you have your MSP API Key ready. You can obtain one from your MSP account representative if you don’t have one. Once you have it, open your chosen text editor and name and save a PHP file: create_service.php.
Next, please copy and paste the following code that contains mspApiKey, apiBaseUrl, and endPoint variables with their respective values (don’t forget to add your MSP API Key) as shown in the code below:
1 2 3 4 5 6 |
// Define MSP API variables $mspApiKey = 'YOUR_MSP_API_KEY'; // Your MSP API Key $apiBaseUrl = "https://api.ministryschedulerpro.com/2/"; // MSP API base URL $endPoint = 'services'; // MSP API Endpoints |
Define the Service properties using a data array.
In this step, we’ll define the parameters for our new service record. The $data
array contains various properties that define the service. For instance, we’ll set the name, label, description, type, and more.
Feel free to customize the values according to your needs, uncommenting the desired properties and setting their respective values.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
$data = array( "name" => "Children's Church", "label" => "Children's church service", "description" => "Children's church service for kids age zero to 5th grade.", "type" => "Weekly", "inactive" => false, "requiredMinistries" => array( "a5e87a2e200aae5040" => 2, "a5f46a3db00af90003" => 4, ), "titleRules" => array( "a5cb6361c3069cf0000" => array( "type" => "breakdown", "typeQualifiers" => array( "breakdown" => array( "A5e6b951f00a8d1018" => 2, "ANY" => 1, ), ), ), ), "choirs" => array(), "timeOffset" => array( "hour" => 12, "minute" => 0, "type" => "daysOfTheWeek", "typeQualifiers" => array( "daysOfTheWeek" => array(0, 1), ), ), ); |
Making the MSP REST API Request Using PHP cURL.
It’s time to make the API request. Should you need to, review how to make an MSP REST API request using PHP cURL to understand the mechanics and inner workings of the API request.
Let’s make the API request using cURL by passing the API key, content type, and service data as JSON in the request.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 |
$postData = json_encode($data); $url = $apiBaseUrl . $endPoint; $header = array( "Authorization: Bearer $mspApiKey", "Content-Type: application/json", ); $ch = curl_init(); $timeout = 60; // Set the URL and other options for cURL curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, $timeout); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST'); curl_setopt($ch, CURLOPT_POSTFIELDS, $postData); curl_setopt($ch, CURLOPT_HTTPHEADER, $header); // Execute call and return response data $result = curl_exec($ch); // Close cURL connection curl_close($ch); // Decode the JSON response $rez = json_decode($result, true); // Display the response (optional) var_dump($rez); |
After making the API request, we can analyze the response. The $rez
variable now holds the response data in a PHP array. You can perform further operations or display the response as per your needs.
Time to Test PHP and Review the Results.
Okay, it’s now time to test your technical prowess. Resembling the code example below, upload your create_service.php file to your web directory.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 |
// How to Create a Service Record via MSP REST API. /*********************************** **** **** create_service.php **** **** This file allows for authentication using your MSP API Key and creating a new service record. **** ***********************************/ // define MSP API variables $mspApiKey = 'Enter key area'; // Your MSP API Key $apiBaseUrl = "https://api.ministryschedulerpro.com/2/"; // MSP API base URL $endPoint = 'services'; // MSP API Endpoints // if the endpoint is not defined and still equals the default of `Enter API Endpoint`, then create an empty $endpoint variable. if($endPoint == "Enter API Endpoint"){ $endPoint = ''; } // define the 'fields' and 'where' arguments as a JSON object $data = array( //"id" => "12384929ABD" // The integer (e.g. 374) or 18 character string (e.g. "a5f887a8300aee6006") ID of the service. Read-only. "name" => "Children's Church" ,"label" => "Children's church service" ,"description" => "Children's church service for kids age zero to 5th grade." ,"type" => "Weekly" //"replaceWeekly" => true // Boolean field specifies if a "Monthly" service should replace the weekly one for the same time. For non-monthly services this field is not used. ,"inactive" => false //,"dateChangesYearly" => true // Boolean field used for "Yearly" services only. If true MSP will show a reminder for the administrator to set the exact date for the service each year. ,"requiredMinistries" => array( "a5e87a2e200aae5040" => 2 "a5f46a3db00af90003" => 4 ) ,"titleRules" => array( "a5cb6361c3069cf0000" => array( "type" => "breakdown", "typeQualifiers" => array( "breakdown" => array( "A5e6b951f00a8d1018" => 2, "ANY" => 1 ) ) ) ) ,"choirs" => array() // there are daysOfTheWeek, dayOfTheMonth, and nthWeekOfTheMonth; Review the MSP API Documentation ,"timeOffset" => array( "hour" => 12, "minute" => 0, "type" => "daysOfTheWeek", "typeQualifiers" => array( "daysOfTheWeek" array(0,1) ) ) ); // MSP API uses JSON objects as a means of exchange for all endpoints; therefore, json_encode the PHP $data variable value. $postData = json_encode($data); $url = $apiBaseUrl.$endPoint; // set your MSP API Key. Also uncomment the content type if you are attempting to instantiate a request using an MSP API endpoint. $header = array( "Authorization: Bearer $mspApiKey", "Content-Type: application/json" ); // Time to initiate cURL request using MSP API variables $ch = curl_init(); $timeout = 60; // set the url and other options for curl curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, $timeout); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST'); // Values: GET, POST, PUT, DELETE, PATCH, UPDATE curl_setopt($ch, CURLOPT_POSTFIELDS, $postData); // uncomment if you are using MSP API endpoint query parameters -- see lines 24-30 // curl_setopt($ch, CURLOPT_POST, true); // uncomment if the previous line is uncommented. ;) curl_setopt($ch, CURLOPT_HTTPHEADER, $header); // execute call and return response data. $result = curl_exec($ch); // close curl connection curl_close($ch); // decode the json response $rez = json_decode($result, true); var_dump($rez); ?> |
Then access the file using a web browser. This executes the PHP script. The response should be displayed on the page.
Fingers crossed, and a prayer was said! Do you have a new service record displayed on the web browser page?
If successful, you’ll see the service record details printed, including any newly generated IDs or other relevant service information.
In addition, you can also check Ministry Scheduler Pro to confirm that the new service has been created.
And there you have it! Creating a new service record using PHP using the MSP REST API is easy. Any questions?
How to create a service record using Python.
Let me guess, PHP isn’t your thing, but Python is! Hey, there is no judgment here at all. They both get the job done either way. So without further ado, let’s rock and roll with Python.
First, open your preferred text editor or use the editor in cPanel File Manager, name and save the following Python file: create_service.py.
And before we start Python coding, don’t forget that you’ll need to have the ‘requests’ library installed. If you don’t already have it installed, you can install it using ‘pip install requests’ from Terminal (Mac) or your preferred command-line interface.
PYTHON HELP :: For more assistance with Python, including downloads and documentation, please visit https://www.python.org/.
Let’s code now! I’ll spare you the code breakdown as it is the same as PHP only written in Python. So, if you prefer using Python, here’s the PHP equivalent code below to create a service using MSP REST API in its entirety:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 |
import requests import json msp_api_key = 'YOUR_MSP_API_KEY' # Your MSP API Key api_base_url = 'https://api.ministryschedulerpro.com/2/' end_point = 'services' data = { 'name': "Children's Church", 'label': "Children's church service", 'description': "Children's church service for kids age zero to 5th grade.", 'type': 'Weekly', 'inactive': False, 'requiredMinistries': { 'a5e87a2e200aae5040': 2, 'a5f46a3db00af90003': 4, }, 'titleRules': { 'a5cb6361c3069cf0000': { 'type': 'breakdown', 'typeQualifiers': { 'breakdown': { 'A5e6b951f00a8d1018': 2, 'ANY': 1, }, }, }, }, 'choirs': [], 'timeOffset': { 'hour': 12, 'minute': 0, 'type': 'daysOfTheWeek', 'typeQualifiers': { 'daysOfTheWeek': [0, 1], }, }, } url = api_base_url + end_point headers = { 'Authorization': 'Bearer ' + msp_api_key, 'Content-Type': 'application/json', } response = requests.post(url, headers=headers, data=json.dumps(data)) # Print the response data (optional) print(response.json()) |
As with the PHP code, when executed from a web browser, the Python script sends the API request and prints the response, allowing you to review the service record details.
Also, don’t forget that you can check and confirm in Ministry Scheduler Pro that your new service record was successfully created.
And there you have it! Creating a new service record using Python via the MSP REST API is easy. Any questions?
Tutorial Summary
Congratulations! You’ve successfully learned how to create a service record using the MSP REST API.
Whether you followed the PHP or Python approach, you can now interact with the MSP REST API and handle service-related tasks. Feel free to explore further by customizing the MSP services’ collection data or incorporating additional fields.
In addition, refer to the MSP API documentation for more advanced functionalities and options. Feel free to reach out if you have any questions or encounter technical roadblocks.
Oh, and one last thing: don’t forget to add error handling to your code.
Stay tuned for the follow-up tutorials covering the remaining MSP REST API Service endpoints!