One of the first things to master when using the CCB API, whether migrating data to CCB or using 3rd party apps integrated to CCB, is learning how to create CCB profiles or individuals.

For this tutorial, be sure you have access to a text editor, and a private (local) or public web server available to execute php files.

Check the Getting Started Toolbox for more tools information pertaining to tutorials. Let’s get started

Setting up basic variables

Using your text editor of choice, create a new php file named createIndividual.php and save it to your desktop or a folder of your choice.

The next step we’ll perform is to create variables or containers for storing data we’ll use later when we start programming.  Variables in PHP start with a dollar sign (“$”) and consist of letters, numbers, and the underscore character.

In addition, variables are case-sensitive so be careful how you name them (i.e., $ccbData is not the same as $CCBData).  Learn more about PHP variables.

In short, get acclimated with using variables because this is how you will capture and transfer data throughout PHP.

As shown below, create variables for your church domain name without the extension, CCB API Username, CCB API Password, and the create_individual API service.

<?PHP

$churchdomain = 'example'; // your domain without the .com

$apiUsername = 'ccbapiuser'; // your CCB api username
$apiPassword = 'p@55w0rd!'; // your CCB api password

$apiService = 'create_individual';  // CCB api service

?>

Create individual data variables for input

The next line of business is creating variables for individual data.  This data is simple individual data such as first name, last name, email, date of birth, and gender to name a few.  Refer to the CCB API documentation for a full list of required and optional input parameters for the create_individual api service.

You’ll notice below in our example that the familyid variable is set to 0.  When creating an individual using the API, 0 will be the default value for familyid.

When you are creating an individual using the API and would like to associate the new individual to an existing individual’s family (i.e., adding a spouse, child or other family member), then you simply enter the family id of the respective existing individual. I’ll create another tutorial for retrieving an individual’s id shortly, but for now in tutorial we will assume a few things.

In addition, other variables to pay close attention to are campusid, membershiptype, familyposition.

In CCB, there can be more than one campus if your church has more than one location so be sure to update the campusid variable to your respective location’s campus id value found in CCB.

You’ll have to check your CCB configuration to obtain the member type numeric value for the membershiptype variable.

When creating an individual using the CCB API, your options are the following when setting the familyposition variable: headofhousehold (h), spouse (s), child (s), or other member (o).

Below is example of how to create individual data variables.  For this tutorial, I’m only using a select few of the available required and optional parameters.  Again, be sure to the review the CCB API documentation for more details on the various types of required and optional parameters for the create_individual api service.

<?PHP

$familyid = '0';
$familyposition = 'h';
$campusid = 1;
$membershiptype = '3';
$prefix = 'Mr.';
$firstname = 'Joe';
$middlename = 'A';
$lastname = 'Doe';
$gender = 'm';
$dateofbirth = '1962-01-01';
$emailaddress = 'joedoe@gmail.com';
$contactphone = '512-890-1234';
$mailingstreetaddress = 'Add Your Address';
$mailingcity = 'Austin';
$mailingstate = 'TX';
$mailingzip = '78758';
$mailingcountry = 'US';

?>

Prepare and bind api labels to individual data variables

Moving right along, now we are ready to bind or associate the individual data variables we created in the last step with the CCB API labels or field names of the create_individual API service.  This binding will help us to create the array we’ll use when we create our urlData variable shortly, but more on that later.

To bind api labels and variables, we’ll need to create a variable array.  Arrays, much like variables, are containers but differ because arrays can hold more than one value at time.

Building an array to bind api labels and variables is a shortcut and much easier way to capture data than building single variables and having to concatenate, also known as daisy chaining, variables one after the other.  Learn more about Arrays.

Shown below is newly created variable urlData that contains array data consisting of CCB API labels binded to their respective individual data variable we created in the previous step.

<?PHP

$urlData = array(
'family_id' => "$familyid",
'campus_id' => "$campusid",
'salutation' => "$prefix",
'first_name' => "$firstname",
'middle_name' => "$middlename",
'last_name' => "$lastname",
'gender' => "$gender",
'birthday' => "$dateofbirth",
'email' => "$emailaddress",
'contact_phone' => "$contactphone",
'mailing_street_address' => "$mailingstreetaddress",
'mailing_city' => "$mailingcity",
'mailing_state' => "$mailingstate",
'mailing_zip' => "$mailingzip",
'mailing_country' => "$mailingcountry",
'home_street_address' => "$mailingstreetaddress",
'home_city' => "$mailingcity",
'home_state' => "$mailingstate",
'home_zip' => "$mailingzip",
'home_country' => "$mailingcountry",
'membership_type_id' => "$membershiptype"
);

?>

Generating a URL-encoded query string

Don’t let the heading of this section confuse or intimidate you one bit.  Simply put, we’re going to create web url using a special URL function that is built into PHP called http_build_query.

And yes, I know you may be a bit in the dark on why you’ll need a web url, but sit tight, follow me, and you’ll soon see it all come together.

If you remember in the last step, we discussed arrays could contain more than one value unlike single variables.  In addition, we said that single variables could be concatenated or daisy chained (see example below).

<?PHP

// This $objData variable took about 5-10 minutes to type up, and an additional 5-10 minutes to error check.  This is the long way to grandma's house when constructing a web url address

$objData = 'family_id='.$familyid.'&campus_id='$campusid.'&salutation='.$prefix.'&first_name='.$firstname.'&middle_name='.$middlename.'&last_name='.$lastname.'&gender='.$gender.'&birthday='.$dateofbirth.'&email='.$emailaddress.'&contact_phone='.$contactphone.'&mailing_street_address='.$mailingstreetaddress.'&mailing_city='.$mailingcity.'&mailing_state='.$mailingstate.'&mailing_zip='.$mailingzip.'&mailing_country='.$mailingcountry.'&home_street_address='.$mailingstreetaddress.'&home_city='.$mailingcity.'&home_state='.$mailingstate.'&home_zip='.$mailingzip.'&home_country='.$mailingcountry.'&membership_type_id='.$membershiptype';

$finalUrl = 'http://example.com/index.php?'.$objData;

echo $finalUrl;

// output url: http://example.com/index.php?family_id=0&campus_id=1&salutation=Mr.&first_name=Joe&middle_name=A&last_name=Doe&gender=m&birthday=1962-01-01&email=joedoe@gmail.com&contact_phone=512-890-1234&mailing_street_address=Add+Your+Address&mailing_city=Austin&mailing_state=TX&mailing_zip=78729&mailing_country=US&home_street_address=Add+Your+Address&home_city=Austin&home_state=TX&home_zip=78729&home_country=US&membership_type_id=3

?>

Well, concatenating variables to build a web url can be performed as shown above, but it is quite inefficient and a laborious task when you can simply use the http_build_query built-in PHP function as shown below to produce the output of the example code above.  Remember, work smarter and not harder! 😉

Nevertheless, we’ve created a objData variable that consists of the http_build_query function using the urlData as its argument.  Or said a different way: simply pass the urlData variable data as the input data, which is an array, to http_build_query that outputs a web url to the objData variable.

<?PHP

$objData = http_build_query($urlData);

?>

Don’t CURL up in the fetal position just yet

We’re almost to the finish line, so hang in there!  We’re now ready to use all of the previous mentioned variables to construct the CCB API Client URL Library (cURL) call.  cURL is another PHP library and service that allows one to make HTTP requests to retrieve a HTML response.  Said another way: I want to use cURL to retrieve a web url (web page) and it’s respective html or other output to display within my web page or application.

A simple CCB API cURL call looks like the following:

curl -u user:pass -d "" "https://churchdomain.ccbchurch.com/api.php?srv=example_service"

For this tutorial, your CCB API cURL call will look like the following example below.  Notice that the CCB API cURL call is encapsulated or enclosed within a PHP exec command.  Simply put, exec is a command directive to initiate a certain action.  Exec commands consist of three arguments: command, output, and return_var.

Said another way: run the exec command which, in this example, will initiate a cURL call, returning the output (if any) and return_var of 0 or greater than 0.

Also notice the cURL call has added the apiUsername, apiPassword, objData, churchdomain, and apiService variables in their respective places.

<?PHP

exec('curl -u '.$apiUsername.':'.$apiPassword.' -d "'.$objData.'" "https://'.$churchdomain.'.ccbchurch.com/api.php?srv='.$apiService.'&"',$output, $result); 

?>

Finally, it’s time to check to see if the exec command has been initiated successfully.  If successfully initiated, we’ll echo or print to the web browser page a “SUCCESS: Individual created.” message or a “ERROR: Individual not created.” if exec command fails or errors.

<?PHP

$msg = 'ERROR: Individual not created.'
if($result > 0) $msg = 'SUCCESS: Individual created.';

echo $msg;

?>

Finally, putting everything together and testing

Well, you’ve made it to the very end, and now it’s time to put everything we’ve learned in this tutorial together in the createIndividual.php file and test it in your web browser.

If you’re using XAMPP, then you’ll want to place this file in your htdocs folder and use localhost to access it (e.g. http://localhost/createIndividual.php).

If you’re using a 3rd-party web hosting provider, then you’ll want to upload the file to your root web directory folder, accessing the file using the domain or ip address of your web server (e.g., http://10.23.12.23/createIndividual.php or http://yourdomain.com/createIndividual.php).

<?PHP

$churchdomain = 'example'; // your domain without the .com

$apiUsername = 'ccbapiuser'; // your CCB api username
$apiPassword = 'p@55w0rd!'; // your CCB api password

$apiService = 'create_individual';  // CCB api service

// Individual data to be entered into CCB
$familyid = '0';
$familyposition = 'h';
$campusid = 1;
$membershiptype = '3';
$prefix = 'Mr.';
$firstname = 'Joe';
$middlename = 'A';
$lastname = 'Doe';
$gender = 'm';
$dateofbirth = '1962-01-01';
$emailaddress = 'joedoe@gmail.com';
$contactphone = '512-890-1234';
$mailingstreetaddress = 'Add Your Address';
$mailingcity = 'Austin';
$mailingstate = 'TX';
$mailingzip = '78758';
$mailingcountry = 'US';

// Bind the CCB API labels to individual variables as an array
$urlData = array(
'family_id' => "$familyid",
'campus_id' => "$campusid",
'salutation' => "$prefix",
'first_name' => "$firstname",
'middle_name' => "$middlename",
'last_name' => "$lastname",
'gender' => "$gender",
'birthday' => "$dateofbirth",
'email' => "$emailaddress",
'contact_phone' => "$contactphone",
'mailing_street_address' => "$mailingstreetaddress",
'mailing_city' => "$mailingcity",
'mailing_state' => "$mailingstate",
'mailing_zip' => "$mailingzip",
'mailing_country' => "$mailingcountry",
'home_street_address' => "$mailingstreetaddress",
'home_city' => "$mailingcity",
'home_state' => "$mailingstate",
'home_zip' => "$mailingzip",
'home_country' => "$mailingcountry",
'membership_type_id' => "$membershiptype"
);

// Create the web url for the cURL call
$objData = http_build_query($urlData);

// Create the cURL call with the respective variables and encapsulate it within an exec command
exec('curl -u '.$apiUsername.':'.$apiPassword.' -d "'.$objData.'" "https://'.$churchdomain.'.ccbchurch.com/api.php?srv='.$apiService.'&"',$output, $result); 

// by default, error message is set as $msg variable
$msg = 'ERROR: Individual not created.'

//if result is greater than 0, then the exec command was initiated successfully
if($result > 0) $msg = 'SUCCESS: Individual created.';

// echo or print to the screen informing whether or not the individual was created in CCB
echo $msg;

?>

Well, CONGRATULATIONS, you should now be able to execute the script, and then search for and find your newly added individual in CCB.

My hope is that you’ve found this simple tutorial to be a great help as it pertains to using the CCB API to create an individual profile.

There is much room to expand upon this tutorial in terms of automating the creation of multiple profiles, and associating profiles to an existing profile using a family id.

Stay tuned, and we’ll cover the mentioned topics in the near future.

Related Posts

Subscribe and receive the following...

  • Inside CCB tips and tricks
  • Instant CCB tutorial alerts and updates
  • CCB How To's, Videos, Webinars and more...