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 to your Centercode implementation. Note that technical documentation can be found at welcome.centercode.com/api.
General Integration Vocabulary
Stands for Application Programming Interface. Enables different systems to interact with each other programmatically.
Access to API endpoints may require identity verification through an authorization key that is included in your URL or headers when making a request.
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.
An Endpoint is a system or application that’s the target of integration. Jira, Slack, Salesforce, and even Centercode are examples of endpoints which receive and process requests.
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 allow you to define additional static values sent with each request. Not all API calls require headers to be defined. A common uses for headers it to provide authorization for your Webhook by adding your access key to your header and specify how you want returned values to be formatted.
- Authorization Header Example:
- Return value formatting example:
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 Value Pairs
Different than the “Key” above, Key Value Pairs (also known as Parameters) are 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.
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 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 requests retrieve data from an external system and enters it within your Centercode implementation to be stored and/or take action upon (through various platforms).
POST requests send data from your Centercode implementation to create or update a resource in a third-party system.
PUT requests sends 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 requests are to make partial update on a resource in a third-party system.
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 allows you to name the specific piece of data you’re capturing from third-party systems
Parameters are how you append data to your label and call out to specific parameters of data.
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.
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 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
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)
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 to for the integration has 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 the 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 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 to 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.