RESTful API: Internal Contact Management

Follow

Catalyst provides a RESTful API to manage the Internal Contacts module. With our RESTful API, internal contacts can be created, edited, deleted, and indexed. It is easy to get started, the first step is to get an Access Token. This unique key allows programmatic API requests to Catalyst.

Getting the Access Token

Follow these steps to get your access token.

  1. Go to Administration => User
  2. Open an existing user or create a new user
    1. If using an existing user, click Edit
    2. User must have Account Owner Role
  3. On the New/Edit form, set the Sign In Type to API or Any
  4. Complete updating the form and click Save
  5. Sign into Catalyst as the API user (Access tokens are only visible to the current user)
  6. Click the My Profile link in the top menu bar
  7. The user Access Token will appear on this view. The token is only visible to the user it is assigned to, and no other users will be able to view it.
  8. Copy the Access Token

Important Notes

  • The Access Token has a reset button available. Should the previous token become compromised, the reset button will provide a new token and remove access for the previous token.
  • There is a limit of 1000 contacts per index request. The following appears at the top of the index data:
“total_available_record_count”: [number],   (this shows the total number of contacts in Catalyst)
“current_page”: [number],   (Page of the internal contacts returned, 1000 contacts per page)
“returned_record_count:” [number],   (How many contacts in the current request)
“internal_contacts”: [array of internal contacts]   (the data for the internal contacts)
  • To access internal contacts 1001 and beyond, modify the request URL like below:
https://[site].bccatalyst.com/internal_contacts.json?current_page=2
  • Due to field customization, every instance of Catalyst is unique. Before editing internal contacts through the API, make a single item or index request. This displays what the system is expecting for key fields. Below is just a short JSON example, the full JSON example can be found at the end of this article along with an XML example.
{
  "internal_contact": {
    "id": 228178,
    "first_name": {
      "dispay_name": "First Name",
      "data": "John"
    },

“id” is the Catalyst-generated ID. The number associated with this ID is needed for editing, deleting, or displaying one item
“first_name” is the key. This is the content needed for New/Edit request forms. This is how the system will know to update the first name field.
Ex. form.append(“internal_contact[first_name]”, “[Data]”);

API Requests

API requests need to include a header with the key, “authorization”, and value, “Token token=[copied token key]”. The “[copied token key]” should be replaced with the Access Token from the “Obtaining Access Token” steps above.

Request Examples:

The following example is an AJAX request to return one internal contact.

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://[site].bccatalyst.com/internal_contacts/[id].json",
  "type": "GET",
  "headers": {
    "authorization": "Token token=[copied token key]"
  }
}
$.ajax(settings).done(function (response) {
  console.log(response);
}); 
  • Replace “[site]” with your Catalyst site prefix.
  • Replace “[id]” with the Catalyst ID of the internal contact you are retrieving.
  • Replace “[copied token key]” with your user Access Token.

The following example is a cURL request to return one internal contact.

curl -X GET -H “authorization: Token token=[copied token key]” -H “Cache-Control: no-cache” “https://[site].bccatalyst.com/internal_contacts/[id].json”

  • Replace “[site]” with your Catalyst site prefix.
  • Replace “[id]” with the Catalyst ID of the internal contact you are retrieving.
  • Replace “[copied token key]” with your user Access Token.

The following example is an AJAX request to return an index of internal contacts.

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://[site].bccatalyst.com/internal_contacts.json",
  "type": "GET",
  "headers": {
    "authorization": "Token token=[copied token key]"
  }
}
$.ajax(settings).done(function (response) {
  console.log(response);
});
  • Replace “[site]” with your Catalyst site prefix.
  • Replace “[copied token key]” with your user Access Token.

The following example is a cURL request to return an index of internal contacts.

curl -X GET -H “authorization: Token token=[copied token key]” -H “Cache-Control: no-cache” “https://[site].bccatalyst.com/internal_contacts.json”

  • Replace “[site]” with your Catalyst site prefix.
  • Replace “[copied token key]” with your user Access Token.

The following example is an AJAX request to create a new internal contact.

var form = new FormData();
form.append("internal_contact[first_name]", "[Data]");
form.append("internal_contact[last_name]", "[Data]");
form.append("internal_contact[job_title]", "[Data]");
form.append("internal_contact[department]", "[Data]");
form.append("internal_contact[location]", "[Data]");
form.append("internal_contact[work_email]", "[Data]");
form.append("internal_contact[work_phone]", "[Data]");
form.append("internal_contact[home_phone]", "[Data]");
form.append("internal_contact[mobile_phone]", "[Data]");
form.append("internal_contact[street_address]", "[Data]");
form.append("internal_contact[city]", "[Data]");
form.append("internal_contact[state]", "[Data]");
form.append("internal_contact[postal_code]", "[Data]");
form.append("internal_contact[country]", "[Data]");
form.append("internal_contact[additional_text_1]", "[Data]");
form.append("internal_contact[additional_text_2]", "[Data]");
form.append("internal_contact[tags]", "[Data]");
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://[site].bccatalyst.com/internal_contacts.json",
  "type": "POST",
  "processData": false,
  "contentType": false,
  "mimeType": "multipart/form-data",
  "data": form,
  "headers": {
    "authorization": "Token token=[copied token key]"
  }
}
$.ajax(settings).done(function (response) {
  console.log(response);
});
  • Replace “[site]” with your Catalyst site prefix.
  • Replace “[Data]” with the information you need for your new contact.
  • Replace “[copied token key]” with your user Access Token.

The following example is a cURL request to create a new internal contact.

curl -X POST -H “Authorization: Token token=[copied token key]” -H “Accept: application/json” -H “Content-Type: application/json” -H “Cache-Control: no-cache” -d ‘{“internal_contact”:{“first_name”:”[Data]”,“last_name”:”[Data]”}}’ “https://[site].bccatalyst.com/internal_contacts.json”

  • Replace “[site]” with your Catalyst site prefix.
  • Replace “[Data]” with the information you need for your new contact.
  • Replace “[copied token key]” with your user Access Token.

The following example is an AJAX request to edit an existing internal contact.

var form = new FormData();
form.append("internal_contact[first_name]", "John");
form.append("internal_contact[last_name]", "Doe");
form.append("internal_contact[job_title]", "CEO");
form.append("internal_contact[department]", "Corporate");
form.append("internal_contact[location]", "Cleveland");
form.append("internal_contact[work_phone]", "555-111-2222");
form.append("internal_contact[home_phone]", "555-111-2223");
form.append("internal_contact[mobile_phone]", "555-111-2224");
form.append("internal_contact[street_address]", "123 some street");
form.append("internal_contact[city]", "Cleveland");
form.append("internal_contact[state]", "Ohio");
form.append("internal_contact[postal_code]", "444113");
form.append("internal_contact[country]", "United States");
form.append("internal_contact[additional_text_1]", "addtl text 1");
form.append("internal_contact[additional_text_2]", "addtl text 2");
form.append("internal_contact[tags]", "tag1,tag2");
form.append("utf8", "✓")
form.append("authenticity_token", "A6YpwO+Sr5iqbcXaSiK53ahAD+QchSt2ygq8PdCTVYE=")
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://[site].bccatalyst.com/internal_contacts/[id].json",
  "type": "PATCH",
  "processData": false,
  "contentType": false,
  "mimeType": "multipart/form-data",
  "data": form,
  "headers": {
    "authorization": "Token token=[copied token key]"
  }
}
$.ajax(settings).done(function (response) {
  console.log(response);
});
  • This process will overwrite all fields in Catalyst, so only edit the items that need changed, and populate the rest with the original data.
  • Replace “[site]” with your Catalyst site prefix.
  • Replace “[Data]” with the information you need for your contact.
  • Replace “[id]” with the Catalyst ID of the internal contact you are editing.
  • Replace “[copied token key]” with your user Access Token.

The following example is an AJAX request to edit an existing internal contact.

curl -X PUT -H “Authorization: Token token=[copied token key]” -H “Accept: application/json” -H “Content-Type: application/json” -H “Cache-Control: no-cache” -d ‘{“internal_contact”:{“last_name”:”[Data]”}}’ “https://[site].bccatalyst.com/internal_contacts/[id].json”

  • This process will overwrite all fields in Catalyst, so only edit the items that need changed, and populate the rest with the original data.
  • Replace “[site]” with your Catalyst site prefix.
  • Replace “[Data]” with the information you need for your contact.
  • Replace “[id]” with the Catalyst ID of the internal contact you are editing.
  • Replace “[copied token key]” with your user Access Token.

The following example is an AJAX request to delete an internal contact.

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://[site].bccatalyst.com/internal_contacts/[id].json",
  "type": "DELETE",
  "headers": {
    "authorization": "Token token=[copied token key]"
  }
}
$.ajax(settings).done(function (response) {
  console.log(response);
});
  • Replace “[site]” with your Catalyst site prefix.
  • Replace “[id]” with the Catalyst ID of the internal contact you are deleting.
  • Replace “[copied token key]” with your user Access Token.

The following example is a cURL request to delete an internal contact.

curl -X DELETE -H “Authorization: Token token=[copied token key]” “https://[site].bccatalyst.com/internal_contacts/[id].json”

  • Replace “[site]” with your Catalyst site prefix.
  • Replace “[id]” with the Catalyst ID of the internal contact you are deleting.
  • Replace “[copied token key]” with your user Access Token.

In all of the URLs above, the data is being requested in JSON format. If you prefer, you can modify the URL to return XML data instead. To do so, replace the .json in the URL above with .xml like in the following:

https://[site].bccatalyst.com/internal_contacts/[id].xml

Returned Data

Here is an example of an internal contact returned in both JSON and XML:

JSON:

Returns the data in a series of nested JSON Hashes:

{
  "internal_contact": {
    "id": 228178,
    "first_name": {
      "dispay_name": "First Name",
      "data": "John"
    },
    "last_name": {
      "dispay_name": "Last Name",
      "data": "Doe"
    },
    "job_title": {
      "dispay_name": "Job Title",
      "data": "CEO"
    },
    "department": {
      "dispay_name": "Department",
      "data": "Corporate"
    },
    "location_id": {
      "dispay_name": "Location",
      "data": ""
    },
    "work_email": {
      "dispay_name": "Work Email",
      "data": "john.doe@example.com"
    },
    "work_phone": {
      "dispay_name": "Work Phone",
      "data": "1234567890"
    },
    "home_phone": {
      "dispay_name": "Home Phone",
      "data": "9876543210"
    },
    "mobile_phone": {
      "dispay_name": "Mobile Phone",
      "data": "1234567890"
    },
    "street_address": {
      "dispay_name": "Street Address",
      "data": "111 Test St"
    },
    "city": {
      "dispay_name": "City",
      "data": "Anywhere"
    },
    "state": {
      "dispay_name": "State",
      "data": "Ohio"
    },
    "postal_code": {
      "dispay_name": "Zip Code",
      "data": "44510"
    },
    "country": {
      "dispay_name": "Country",
      "data": "United States"
    },
    "tags": {
      "dispay_name": "Tags",
      "data": "State:OH,City:Anywhere"
    },
    "additional_text_1": {
      "dispay_name": "Additional Text Field 1",
      "data": ""
    },
    "additional_text_2": {
      "dispay_name": "Additional Text Field 2",
      "data": ""
    }
  }
}

XML

Below is the formatting for the data returned in XML.

<internal_contact>
    <id>228178</id>
    <first_name>
        <field_name>First Name</field_name>
        <data>John</data>
    </first_name>
    <last_name>
        <field_name>Last Name</field_name>
        <data>Doe</data>
    </last_name>
    <job_title>
        <field_name>Job Title</field_name>
        <data>CEO</data>
    </job_title>
    <department>
        <field_name>Department</field_name>
        <data>Corporate</data>
    </department>
    <location_id>
        <field_name>Location</field_name>
        <data>Cleveland<data/>
    </location_id>
    <work_email>
        <field_name>Work Email</field_name>
        <data>john.doe@example.com</data>
    </work_email>
    <work_phone>
        <field_name>Work Phone</field_name>
        <data>1234567890</data>
    </work_phone>
    <home_phone>
        <field_name>Home Phone</field_name>
        <data>9876543210</data>
    </home_phone>
    <mobile_phone>
        <field_name>Mobile Phone</field_name>
        <data>1234567890</data>
    </mobile_phone>
    <street_address>
        <field_name>Street Address</field_name>
        <data>111 Test St</data>
    </street_address>
    <city>
        <field_name>City</field_name>
        <data>Anywhere</data>
    </city>
    <state>
        <field_name>State</field_name>
        <data>Ohio</data>
    </state>
    <postal_code>
        <field_name>Zip Code</field_name>
        <data>44510</data>
    </postal_code>
    <country>
        <field_name>Country</field_name>
        <data>United States</data>
    </country>
    <tags>
        <field_name>Tags</field_name>
        <data>State:OH,City:Anywhere</data>
    </tags>
    <additional_text_1>
        <field_name>Additional Text Field 1</field_name>
        <data/>
    </additional_text_1>
    <additional_text_2>
        <field_name>Additional Text Field 2</field_name>
        <data/>
    </additional_text_2>
</internal_contact>

In XML, , would serve as the key field value when you are building out your edit/new request calls. Drop the “<” and “>” and you are left with the value to place between the “[]” in “internal_contact[]”“.
Ex. form.append(“internal_contact[first_name]”, “[Data]”);

Have more questions? Submit a request

Comments