Welcome to MSPTutorials.com!
First, before we write one line of code, be sure you have reviewed and adhered to the requirements on the “Getting Started” page.
Whether you’re a tech-savvy enthusiast or someone new to programming, I’ll guide you through the process step-by-step. We’ll start with PHP as the primary language and then explore how to achieve the same task using Python.
Overview of the Volunteers Collection
We all know that volunteers are the very heartbeat of every organization. One of the most accessed collections of the MSP REST API is the volunteers. To access its data, the Volunteers collection consists of the following endpoints:
- CREATE uses this endpoint, /volunteers, which allows API requests to create a single volunteer record.
- GET uses this endpoint, /volunteers/{volunteerId}, which allows API requests to retrieve and access a single volunteer record based on the unique volunteer’s MSP ID.
- PUT uses this endpoint, /volunteers/{volunteerId}, which allows API requests to access and update a single volunteer record based on the unique volunteer’s MSP ID.
- DELETE uses this endpoint, /volunteers/{volunteerId}, which allows API requests to access and delete a single volunteer record based on the unique volunteer’s MSP ID.
- POST uses this endpoint, /volunteers/list, which allows API requests to retrieve and access a list of volunteer records.
There are nearly 30+ Volunteer properties to consider (see codebase below or MSP REST API documentation) when accessing the Volunteers collection.
In this tutorial, we’ll focus our efforts on mastering the CREATE endpoint of the Volunteers collection.
As I know you’re eager to get started, so let’s dive in and explore the world of creating a volunteer record using MSP REST API without further ado.
How to create a volunteer record using PHP.
First, I’ll share with you how to create a volunteer record via MSP REST API using PHP. And no worries if PHP is not your cup of tea.
In addition, at the conclusion of 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 the API Variables in PHP.
First, open your preferred text editor or use the editor in cPanel File Manager, name and save the following PHP file: create_volunteer.php.
Let’s code now! You must define the MSP API variables, such as the API key, base URL, and endpoint. Replace 'Enter key area' with your actual MSP API key.
|
1 2 3 |
$mspApiKey = 'Enter key area'; // Your MSP API Key $apiBaseUrl = "https://api.ministryschedulerpro.com/2/"; // MSP API base URL $endPoint = 'volunteers'; // MSP API Endpoint |
Define the Volunteer properties using a data array.
While there are 30 different Volunteer properties to consider, to simplify this tutorial, only focus on the following properties to pass when creating a new volunteer record:
- firstName
- lastName
- emailUnlisted
- hasInternetAccess
- cell
- cellUnlisted
- phone
- phoneUnlisted
- address
- dateCreated
- dateModified
- externalID
Now, define the abovementioned properties for the volunteer record as an associative array. 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 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 |
// define the 'fields' and 'where' arguments as a JSON object $data = array( "firstName" => "John" ,"lastName" => "Doe" //,"isGroup" => true ,"email" => "johndoe@gmail.com" ,"emailUnlisted" => true ,"hasInternetAccess" => true ,"cell" => "817-123-4567" ,"cellUnlisted" => true ,"phone" => "817-890-1234" ,"phoneUnlisted" => true ,"address" => "340 S Lemon Ave, #3441\nWalnut, CA 91789" /* ,"bindPhoneAndAddress" => false ,"bindEmail" => false ,"bindServicePreferences" => false ,"comments" => "hi there!" ,"ministries"=> array( "10" => "none" ,"7" => 1 ,"a5e87a2e200aae5040" => "NONE" ,"a5f46a3db00af90003" => "SUB" ) ,"servicePreferences" => array( array( "serviceId" => "a5c741842008eb0002" ) ,array( "serviceId" => 5, ,"ministryId" => "a5b10269f007c53148" ) ) ,"onlyScheduleForDeclaredPrefs" => true ,"preferredServingFrequency" => array( ) ,"cantServeTimes" => array( ) ,"preassignmentsOnly" => true ,"substitute" => false ,"inactive" => false ,"customFieldValues" => array( "a5c1bc48368c20a0000" => "2019-05-01" ,"a5cb6361c3069cf0000" => false ,"a5cb636853069cf0001" => 5 ,"a5cb8900c33b7ba0000" => "I am lactose intolerant" ) ,"autoEmailReminderDaysInAdvance" => 4 ,"autoSMSReminderHoursInAdvance" => 72 ,"webTerminalUsername" => "jdoeboy" ,"hasBeenSentWebTerminalLogin" => true ,"lastWebTerminalFormSubmittedDates" =>array( ,"ASSIGNMENT" => "2020-12-29 16:02:00" ,"CANCEL_ASSIGNMENT" => "2020-02-25 11:28:15" ,"CANCEL_SWAP_REQUEST" => "2020-02-25 10:59:22" ,"LOGIN" => "2021-03-08 12:45:04" ,"PASSWORD_CHANGE" => "2018-10-10 14:50:31" ,"PROFILE_CHANGE" => "2020-10-23 15:59:00" ,"SWAP_ACCEPT" => "2020-04-20 15:42:18" ,"SWAP_REQUEST" => "2021-02-19 09:51:23" ,"TRADE" => "2020-03-25 10:42:52" ,"UNSUBSCRIBE_REQUEST" => "2019-09-10 11:53:44" ) ,"scheduledDuties" => array( array("532726" => array( "duration" => array( "hours" => 1, "minutes" => 0 ), "ministryId" => 7 ,"dateTime" => "2020-05-16 17:00:00" ,"massId" => "532726_a5e6b951f00a8d1018" ,"localMassId" => "a5e6b951f00a8d1018" ) ) ,array("538126" => array( "duration" => array( "hours" => 1, "minutes" => 0 ), "ministryId" => 7 ,"dateTime" => "2020-08-16 20:00:00" ,"massId" => "538126_a5e6b951f00a8d5008" ,"localMassId" => "a5e6b951f00a8d5008" ) ) ) */ ,"dateCreated" => "2017-07-21 13:00:00" // or use 'date("Y-m-d h:i:s")' without single quotes for dynamic date/time ,"dateModified" => "" ,"externalId" => 1231 ); |
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 volunteer 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 |
$postData = json_encode($data); $url = $apiBaseUrl.$endPoint; $header = array( "Authorization: Bearer $mspApiKey", "Content-Type: application/json" ); $ch = curl_init(); $timeout = 60; 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); $result = curl_exec($ch); curl_close($ch); $rez = json_decode($result, true); var_dump($rez); |
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_volunteer.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 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 |
<?PHP /*********************************** **** **** create_volunteer.php **** **** This file allows for authentication using your MSP API Key and creating a new volunteer record. **** ***********************************/ // define MSP API variables $mspApiKey = 'Enter key area'; // Your MSP API Key $apiBaseUrl = "https://api.ministryschedulerpro.com/2/"; // MSP API base URL $endPoint = 'volunteers'; // 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( "firstName" => "John" ,"lastName" => "Doe" //,"isGroup" => true ,"email" => "johndoe@gmail.com" ,"emailUnlisted" => true ,"hasInternetAccess" => true ,"cell" => "817-123-4567" ,"cellUnlisted" => true ,"phone" => "817-890-1234" ,"phoneUnlisted" => true ,"address" => "340 S Lemon Ave, #3441\nWalnut, CA 91789" /* ,"bindPhoneAndAddress" => false ,"bindEmail" => false ,"bindServicePreferences" => false ,"comments" => "hi there!" ,"ministries"=> array( "10" => "none" ,"7" => 1 ,"a5e87a2e200aae5040" => "NONE" ,"a5f46a3db00af90003" => "SUB" ) ,"servicePreferences" => array( array( "serviceId" => "a5c741842008eb0002" ) ,array( "serviceId" => 5, ,"ministryId" => "a5b10269f007c53148" ) ) ,"onlyScheduleForDeclaredPrefs" => true ,"preferredServingFrequency" => array( ) ,"cantServeTimes" => array( ) ,"preassignmentsOnly" => true ,"substitute" => false ,"inactive" => false ,"customFieldValues" => array( "a5c1bc48368c20a0000" => "2019-05-01" ,"a5cb6361c3069cf0000" => false ,"a5cb636853069cf0001" => 5 ,"a5cb8900c33b7ba0000" => "I am lactose intolerant" ) ,"autoEmailReminderDaysInAdvance" => 4 ,"autoSMSReminderHoursInAdvance" => 72 ,"webTerminalUsername" => "jdoeboy" ,"hasBeenSentWebTerminalLogin" => true ,"lastWebTerminalFormSubmittedDates" =>array( ,"ASSIGNMENT" => "2020-12-29 16:02:00" ,"CANCEL_ASSIGNMENT" => "2020-02-25 11:28:15" ,"CANCEL_SWAP_REQUEST" => "2020-02-25 10:59:22" ,"LOGIN" => "2021-03-08 12:45:04" ,"PASSWORD_CHANGE" => "2018-10-10 14:50:31" ,"PROFILE_CHANGE" => "2020-10-23 15:59:00" ,"SWAP_ACCEPT" => "2020-04-20 15:42:18" ,"SWAP_REQUEST" => "2021-02-19 09:51:23" ,"TRADE" => "2020-03-25 10:42:52" ,"UNSUBSCRIBE_REQUEST" => "2019-09-10 11:53:44" ) ,"scheduledDuties" => array( array("532726" => array( "duration" => array( "hours" => 1, "minutes" => 0 ), "ministryId" => 7 ,"dateTime" => "2020-05-16 17:00:00" ,"massId" => "532726_a5e6b951f00a8d1018" ,"localMassId" => "a5e6b951f00a8d1018" ) ) ,array("538126" => array( "duration" => array( "hours" => 1, "minutes" => 0 ), "ministryId" => 7 ,"dateTime" => "2020-08-16 20:00:00" ,"massId" => "538126_a5e6b951f00a8d5008" ,"localMassId" => "a5e6b951f00a8d5008" ) ) ) */ ,"dateCreated" => "2017-07-21 13:00:00" // or use 'date("Y-m-d h:i:s")' without single quotes for dynamic date/time ,"dateModified" => "" ,"externalId" => 1231 ); // 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 volunteer record displayed on the web browser page?
If successful, you’ll see the volunteer record details printed, including any newly generated IDs or other relevant volunteer information.
In addition, you can also check Ministry Scheduler Pro to confirm that the new volunteer has been created.
And there you have it! Creating a new volunteer record via the MSP REST API using PHP is easy. Any questions?
How to create a volunteer 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.
Setting up the API Variables in Python.
First, open your preferred text editor or use the editor in cPanel File Manager, name and save the following Python file: create_volunteer.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, then 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! Next, let’s import the necessary modules and define the MSP API variables, such as the MSP API Key, base URL, and MSP collections endpoint. Replace 'Enter key area' with your actual MSP API Key (Questions about MSP API Key?).
|
1 2 3 4 5 |
import requests msp_api_key = 'Enter key area' # Your MSP API Key api_base_url = "https://api.ministryschedulerpro.com/2/" # MSP API base URL endpoint = 'volunteers' # MSP API Endpoint |
Define the Volunteer properties using a data dictionary.
Just like in PHP, in Python, you’ll define the data for the volunteer record as a dictionary. 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 |
data = { "firstName": "John", "lastName": "Doe", "email": "johndoe@gmail.com", "emailUnlisted": true, "hasInternetAccess": true, "cell": "817-567-1234", "cellUnlisted": true, "phone": "817-080-8080", "phoneUnlisted": true, "address": "340 S Lemon Ave, #3441\nWalnut, CA 91789", "dateCreated": "2017-07-21 13:00:00", "dateModified": "", "externalId": 1231 } |
See “Define the Volunteer properties using a data array.” in the PHP section to review MSP Volunteer properties.
Making the MSP REST API Request Using Python.
It’s time to make the API request. Should you need to, review how to make an MSP REST API request using Python to understand the mechanics and inner workings of the API request.
Let’s make the API request using Python’s ‘requests’ library and pass the API key, content type, and volunteer data as JSON in the request.
|
1 2 3 4 5 6 7 8 9 10 |
url = api_base_url + endpoint headers = { "Authorization": "Bearer {msp_api_key}", "Content-Type": "application/json" } response = requests.post(url, json=data, headers=headers) result = response.json() print(result) |
Time to Test Python and Review the Results.
Okay, it’s now time to test your technical prowess. Resembling the code example below, save, upload, and execute your create_volunteer.py 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 |
import requests msp_api_key = 'Enter key area' # Your MSP API Key api_base_url = "https://api.ministryschedulerpro.com/2/" # MSP API base URL endpoint = 'volunteers' # MSP API Endpoint data = { "firstName": "John", "lastName": "Doe", "email": "johndoe@gmail.com", "emailUnlisted": true, "hasInternetAccess": true, "cell": "817-567-1234", "cellUnlisted": true, "phone": "817-080-8080", "phoneUnlisted": true, "address": "340 S Lemon Ave, #3441\nWalnut, CA 91789", "dateCreated": "2017-07-21 13:00:00", "dateModified": "", "externalId": 1231 } url = api_base_url + endpoint headers = { "Authorization": "Bearer {msp_api_key}", "Content-Type": "application/json" } response = requests.post(url, json=data, headers=headers) result = response.json() print(result) |
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 volunteer record details.
Also, don’t forget that you can check and confirm in Ministry Scheduler Pro that your new volunteer record was successfully created.
And there you have it! Creating a new volunteer record using Python via the MSP REST API is easy. Any questions?
Tutorial Summary
Congratulations! You’ve successfully learned how to create a volunteer 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 volunteer-related tasks. Feel free to explore further by customizing the MSP volunteers’ collection data or incorporating additional fields as needed.
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 along the way.
Oh, and one last thing: don’t forget to add error handling to your code.
Happy volunteering, and stay tuned for the follow-up tutorials covering the remaining MSP REST API Volunteer endpoints!