This article applies to All editions.
If you’re new to API Integrations, you’ll want to briefly review the following terminology in order to help you integrate various third-party applications into your Centercode implementation. Note that technical documentation can be found at welcome.centercode.com/api.
General Integration Vocabulary
API
Stands for Application Programming Interface. Enables different systems to interact with each other programmatically.
Authorization key
Access to API endpoints may require identity verification through an authorization key that is included in your URL or headers when making a request.
Basic authentication
This encodes a username and password into base64 and adds to the header of API requests (see Header example) allowing your API request to access login credentials with every use.
Endpoint
An Endpoint is a system or application that’s the target of integration. Jira, Slack, Salesforce, and even Centercode are examples of endpoints that receive and process requests.
Endpoint URL
Endpoints typically indicate where/how you access their resources. One system reaches out to another by targeting the endpoint URL - an endpoint URL is essential to connect systems via API.
Headers
Headers allow you to define additional static values sent with each request. Not all API calls require headers to be defined. A common use for headers is to provide authorization for your Webhook by adding your access key to your header and specifying how you want returned values to be formatted.
- Authorization Header Example:
Authorization: 2nt6cs2EyDmZ5fhNNV6cvAIP
- Return value formatting example:
Content-Type: application/json
JSON
JavaScript Object Notation is a lightweight data-interchange format, meaning this is the language you may send and receive data from systems. Below is an example of JSON formatting.
Key
Keys are often required when creating any integration resource. The Key can be a short, descriptive entry to separate your integration from other functions that use the same Community API key for easier use. Another way to consider Keys is as a “friendly identifier”.
Key walue pairs
Different than the “Key” above, Key Value Pairs (also known as Parameters) is a set of two linked data items: a key, which is a unique identifier for some item of data, and the value, which is either the data that is identified or a pointer to the location of that data.
Webhook
Webhooks enable systems (ex: Centercode) to send data to other systems and optionally receive data in return. Webhooks typically target specific endpoints via URL and often carry Authorization Keys required by those endpoints.
- Please note that when sending a Post request to your Centercode API endpoint, the JSON body must be JSON encoded.
-
Web methods
Web Methods define a set of request methods to indicate the desired action to be performed for a given resource, also known as HTTP request methods. When creating Webhooks within your Centercode implementation, you’ll be selecting from the below Web Methods to accomplish your goals. External Listeners, Record Lookups, and Data Returns will select the appropriate Web Method for you.
GET
GET requests retrieve data from an external system and enter it within your Centercode implementation to be stored and/or take action upon (through various platforms).
POST
POST requests send data from your Centercode implementation to create or update a resource in a third-party system.
PUT
PUT requests send data from your Centercode implementation to update an existing resource in a third-party system. PUT should only be used if you’re replacing a resource in its entirety. Otherwise, you may want to consider using PATCH.
PATCH
PATCH requests are to make partial updates on a resource in a third-party system.
DELETE
DELETE requests a resource within a third-party system to be removed.
-
Centercode integration vocabulary
Capture return values
Return Values store responses from third-party systems when your Webhook is used in order to add data to your Centercode platform, further extending your data. This allows you to use that external data anywhere via the Data Engine - as Dynamic Tags, in User and Feedback Management, Reporting, and even other integrations.
Data group label
This designates the label in which your returned data is stored as to be called upon via Centercode Data Engine.
Label
Label allows you to name the specific piece of data you’re capturing from third-party systems
Parameter
Parameters are how you append data to your label and call out to specific parameters of data.
Data type
Type refers to the form the data is returned as.
- Boolean refers to values returned as true and false
- Date and Time refers to dates and times returned
- Integer basically refers to numbers to be returned
- String refers to textual data returned
-
Common status codes for troubleshooting
When working with API integrations, results are binary - either succeeded or failed. Below are common responses that you may see within API testing tools, your Centercode implementation, and/or your third-party application.
2XX Series
This class of status codes indicates the action requested by the client was received, understood, accepted, and processed successfully.
- 200 - OK - Successful request
- 201 - Created - Successful request, resulting in the creation of a resource
- 202 - Accepted - The request was accepted, but not completed
- 204 - No Content - The request was accepted, but the resource did not exist
4XX Series
The 4XX class of status code indicates the client seems to have errored out
- 400 - Bad Request - Request could not be understood due to misconfigured syntax
- 401 - Unauthorized - Request received, but authorization is incorrect or missing
- 403 - Forbidden - Request and authorization received, but authorization is denied
- 404 - Not Found - Resource not found, meaning your endpoint URL may not direct to the desired resource
- 405 - Wrong Method - This occurs when the improper request was attempted (e.g. POST used when PUT is more appropriate)
4XX Troubleshooting
400 - Bad request
This status indicates that your JSON isn’t formatted correctly in your request. Here’s an example of correct JSON formatting. Even something as small as a missing quote or comma may result in the entire request failing.
401 - Unauthorized
Access to API endpoints may require identity verification through an authorization key or token that should be included in your URL or headers when making a request. Request received, but ensure that your authorization is correct and present in your header or URL. If tokens are used, they may have expired and may need to be replaced or refreshed.
403 - Forbidden
Request and authorization received, but authorization is denied. Ensure that the account you’re using for the integration has the correct permissions to carry out your request. You may want to take a close look at your request headers and URL, then try again.
404 - Not found
Resource not found, meaning your endpoint URL may not direct to an existing resource. Ensure that your endpoint URL directs correctly to your desired resource and try again.
405 - Wrong method
This occurs when the improper request was attempted (e.g. POST is used when PUT is more appropriate). You’ll want to change your request method.
415 - Unsupported media type
This indicates that the request’s return format is unsupported. You’ll typically resolve this by including the expected content type in your request’s header.
For example, your GET Webhook request receives a 415 error. Adding “Content-Type: application/json” to your request’s header may resolve this.
-