The MCASuite REST API allows companies to integrate into MCA Suite system through a HTTP RESTful web service. The API is designed to ease the painful process of hand entering data from one system to another system. All responses will be in JSON format.
Login
All calls require two identifying header parameters for credentialing:
1. X_MCASUITE_APP_ID
2. X_MCASUITE_APP_TOKEN
Both of these values will be generated by MCA Suite and provided to our customers. Please contact your representative to get these credentials.
URLS:
The Base REST URL will be provided to the customer upon API request.
Format:
The API will accept form encoded or json encoded parameters.
Testing:
To test the rest url and parameter, we recommend to use the Rested app on Mac OS. Alternatively, you can use the “Advanced Rest Client” extension on google Chrome. If using the Chrome extension, please verify you use application/json as content type, and paste the json parameters into the Raw tab.
Adding a Contact
When adding a contact through the REST api, the contact will appear in the 'Pending Contacts' page in MCA Suite. You can directly add the contact via "autoAdd" field and set it to true. If an existing company (by name) exists, it will re-use the same company. If the same person by name AND (either company or email or phone) are the same, the same contact will be re-used. To create a new duplicate in all cases, see the addDuplicate field below.
Function:
Name: addContact
Type: POST
Parameters:
| Field Name | Required? | Type | Description |
contactType | Yes | String | The category of the contact:
|
| contactStatus | String | Must be:
For the contact to show up on the leads page, the status must be 'Lead' | |
| companyName | String - Max 150 | Contact’s company name | |
| firstName | Yes | String - Max 30 | First name of contact |
| lastName | Yes | String - Max 30 | Last name of contact |
| title | String | Contact's title | |
| businessPhone | String | Business Phone | |
| mobilePhone | String | Mobile Phone | |
| email | String | Email address | |
| website | String | Website address | |
| street1 | String | Street line 1 | |
| street2 | String | Street line 2 | |
| city | String | City | |
| state | String | State (Two Lettter Abbr) | |
| zip | String | Zip Code | |
| country | String | Country | |
| industry | String | Must match industry name (Case sensitive) in MCA Suite or error | |
| additionalInfo | String - Max 500 | Person's additional info. Max 500 characters. | |
| campaign | String | Must match campaign in (Case sensitive) MCA Suite, otherwise skipped | |
| assignedTo | String | Must match username in MCA Suite, otherwise skipped | |
| autoAdd | Boolean | Use 'true' if you want the contact automatically added to the system and bypass the Pending contacts page. | |
| addDuplicate | Boolean | This will create a new person and company even if the same one exists in the system. | |
| thirdPartyId | String - Max 30 | Another system's ID |
Return Response
| Field Name | Type | Description |
| success | boolean | true/false |
| error | String | Error message if available |
Example (URL not real):
PHP code example using Curl:
<?php
$service_url = 'http://XXXXXXXXXXXX/rest/addContact/';
$app_id = XXXXXXXXXXX';
$token = 'XXXXXXXXXXX’;
$curl = curl_init($service_url);
$curl_post_data = array("contactType" =>"Merchant",
"companyName"=> "Test Company",
"firstName"=> "Bob",
"lastName"=> "Smith",
"title"=> "Test CEO",
"businessPhone"=> "4564564568",
"mobilePhone"=> "8978978978",
"email"=> "[email protected]",
"website"=>"test.com",
"address1"=> "123 fake St",
"address2"=> "Suite 230",
"city"=> "Saint Louis",
"state"=> "MO",
"zip"=> "11100",
"country"=> "USA");
$headr = array();
$headr[] = 'X_MCASUITE_APP_ID: ' . $app_id;
$headr[] = 'X_MCASUITE_APP_TOKEN: ' . $token;
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $curl_post_data);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headr);
$curl_response = curl_exec($curl);
curl_close($curl);
// Check out response message, it will be in json format.
echo $curl_response;
?>