Our current integrations, like Outlook and Salesforce, are required to unlock new functionality with these systems, but if you have an on-premise system or application we haven’t integrated with yet, you can create your own custom integrations using our API and Webhook capabilities.
APIs are a real-time, fast, and reliable way to create a connection between two systems. Our API actions enable Workflows to request data from other systems, and open up ways to automate the exchange information between two unconnected systems.
Setting up a Web API framework is a technical process and requires some set up in 3rd party system like Postman, cURL, or other development tools. We recommend developers set up the API framework for your team, then your Catalytic builders rapidly build around it.
Because setting up a Web API requires development time, it’s helpful to learn some API basics and clearly identify where a Web API action is useful and enables new automation.
Web API actions send individual request to a system, and the system sends back a response. This is the basic structure of all Web API actions. There are 5 major types of requests, GET, POST, PUSH, PATCH, DELETE; these work like they sound:
- GET requests data about a customer record from the system,
- POST adds new data to a customer record in the system.
In this example, a GET request is used to GET information. The GET request sends the account number
1010 to a system that stores account information. The system responds with the
employees associated with the account number
Depending on the request, the system sends a unique response back, like a confirmation of completion, or a piece of data (like shown above).
The different types of requests and responses supported are already defined in your system’s API documentation. The documentation will cover what you can request and how the response is formatted. To find the right type of request to make, start by asking:
- What information does your Workflow need from this system, or what information does the system need from the Workflow?
- Does the Workflow need a piece of data? Or does the Workflow need to add new data to the system?
Once you have identified a need for a Web API action, the next step is to collect some system requirements and configure the Web API actions to work with the system you’re integrating with.
For Web API actions to work, the configuration must meet your system’s requirements as each system handles requests and responses differently. To set up a custom integration means to set up the authentication with the system, define the necessary request (like GET customer ID from the system) and set up a way to interpret the response (The Customer ID is 1112233).
Our API actions support the most common request standards: JSON, REST, and SOAP. All our Web API actions can integrate with any HTTP based API using these standards.
We also support the most common API responses, XML or JSON. We have actions to convert these responses into corresponding Catalytic fields.
If you have a good case for a Web API action, there are 4 parameters to define based on the system you’re integrating with. A developer or analyst for your system will be able to help answer these question.
- Determine the authentication method the system requires each request to have.
- Determine the content type, or what format or language the request should be made in.
- Determine the correct API call type, or the type of request that is made.
- Determine how the Workflow should handle the response depending on what the system responds with.
The rest of this article goes into more detail about these 4 parameters: authentication method, content type, API call type, and handle the response. After collecting information on each parameter, reach out to a Catalytic admin, manager, or the system’s developer to talk about next steps.
Our Webhook and Web API actions support basic auth or token authentication out of the box.
To determine which authentication method your system uses and authenticate any API request with the system, check the system’s API documentation to see which authentication methods are supported. Many systems support using an auth token or username and password for API requests.
If the authentication supports basic auth or a token, these values can be set as confidential Workflow level fields in a Workflow and then referenced by each Web API. This will make sure each request is authenticated.
Another common authentication method is OAuth. If any of your systems require OAuth, we can help you set this up. Contact us at firstname.lastname@example.org to talk through this option.
The API documentation for your system will explain the required request and response content type, like whether the request should be in JSON or XML, and the response’s format. Knowing the content type is required to make the right request. This information will help a developer send and request the right information.
We have web API actions for 5 different methods. Each API method is a type of request, and each method is useful in specific situations. The most common methods are GET and POST, which are used globally.
- Web API: Send GET request
- Use GET to retrieve data from a system. GET data from your system for a specific vendor or customer in a Workflow instance that automates contract renewal.
- Web API: Send POST request
- Use POST to create new data on a system. POST data to your system as part of a Workflow that parses incoming emails. For each incoming email, make a unique POST request.
- Web API: Send PUT request
- Use PUT to update data on a system. PUT data into your system as part of a weekly report that’s managed through a Workflow. Mirror report results to your internal system.
- Web API: Send PATCH request
- Use PATCH similarly to PUT.
- Web API: Send DELETE request
- Use DELETE to delete data from a system. DELETE data as part of a SKU or database management Workflow that automatically parses and updates inventory.
Each request has a unique response. Depending on the response type, use different Workflow to convert the response into a format that’s compatible for the next action.
If the API response is in JSON, the Field: Create fields from JSON action maps JSON key/value pairs to Catalytic fields or data tables. Catalytic has the widest support for JSON responses.
If the API response is in XML, the XML: Convert XML to JSON or XML: Parse string field action converts the entire XML response into JSON format, or parses the XML response with an xpath expression to save individual values from the string.