Albato's new "Custom API request" feature lets you create and customize API requests, no matter what method you want to use.
You can now request the API of any application in Albato, even if the action isn't in the list of standard features. This is useful if you need to use rare methods or if some action isn't available in Albato but is in the application API.
Why do you need this feature?
Let's say Albato has a public app like HubSpot, but you need to perform some action that isn't in the standard feature set. Instead of waiting for Albato to add that action, you can use a "Custom API request." This lets you simplify the setup of the HTTP request, because you don't have to worry about setting up authorization or handling errors. You just select a connection to an app that handles authorization, and the error text will be handled according to that app's rules.
You just need to know the API of the system you want to integrate with, and some basic HTTP requests. If you know the URL for the request, as well as its structure and response, you can customize the request and get the necessary information.
How it works
The action only allows requests to be made to authorized URLs. If the app uses its own custom domain, this is also taken into account. For example, if you use the action for the HubSpot app, requests can only be sent to URLs starting with https://api.hubapi.com/. The path after that URL can be anything. The list of allowed domains is in the tooltip for the field. Any other URLs will not work and the action will fail if you try to run the request in a running automation. The URL must be specified in full.
How to set it up
First, add the action to the automation. Next, choose the app. If the action is available, you'll see it at the bottom of the list (Custom API request).
Then, select a connection or create a new one.
Next, set up the action.
Let's break down which field is responsible for what:
- URL: In this field, you need to specify the full URL to which the request should be made. Only the domains specified in the field hint are allowed.
- Request Method: Select the method to be used when making the request (e.g., GET, POST, PUT).
- Request Format: The format of the request body (Content-type) is set. Albato generates the request body automatically based on the mapping in the "Request Parameters" section.
- Request Parameters: This is a section with lots of different fields. Here you can create the fields you need to be passed in the request. You just need to specify the key, type and value.
- Request Headers: This is similar to the Request parameters field, but it’s used for customizing headers. Just a heads-up: The content type and authorization will be set automatically.
- Response Parameters: This is where you set up the response fields and specify where to get the values from. You can use these values in the next steps to process the response from the request.
Next, depending on your case study, you just need to fill in all the fields.
Let's take a look at an example of how it's done. Let's say we need to create a call in HubSpot using their API documentation.
The request body is:
- Format: JSON
- Method: POST
- URL: https://api.hubapi.com/crm/v3/objects/calls
Here's an example of the original request:
Let's get down to business and complete the setup.
Then create the fields to be passed in the request. Click the + Add a field button and set up key mapping for correct data transfer.
Next, let's look at how to set up key mapping properly, using an example.
If you need to fill in the name variable, the JSON looks like this:
The key is specified by name.
If you need to fill in a variable that's in an object, you'll need to specify the path to the object with a dot. Here's an example of the JSON:
Now, to fill the name variable, you just need to specify the key mapping in the left field in this format: cоntact.nаme.
If the variable is in an array of objects, you can specify the mapping with a dot, but you have to include the position of the object in the array (starts from zero). Here's an example of the JSON:
If you need to fill in the name field in the first object, the mapping is contаcts.0.namе. If you need to fill in the second object, the mapping is cоntaсts.1.nаme.
Now let's go back to our example. Let's say we need to specify the value of the associationCategory parameter as HUBSPOT_DEFINED, which is a string. To do this, create a Request parameters field and specify the mapping as follows: associations.0.types.0.associationCategory. Then, select the String type and enter the value.
Do the same for associationTypeId, but use an integer.
Once you've filled in all the required fields, you should get the following result:
You can also specify fields from previous steps in the required fields, just like you can with normal fields in normal actions.
This customization will generate a piece of JSON that looks like the HubSpot example. If you have other keys, you can also change them.
You can also configure to get a response immediately. According to the documentation, this request gets a JSON response.
Just write down the key you need and select the type. In this case, it's the ID.
The rule for writing keys here is the same as for Request parameters.
The action setup is done! Now you can run the automation and send the request.
Parameter field typing
It's important to choose the right type for each parameter, as this affects how the data is transferred and the response you get. You've got the following types to choose from:
- String
- Int: Integer.
- Decimal: A number with a decimal point.
- Boolean: Sends true or false.
- DateTime: This is for a date and time type. If you choose this option, specify the format and time zone for the date you want to send.
- Date: This is the same as DateTime, but without time.
- Phone: This is another internal type. When you select this type, fields for the variable format and final type (int or string) will be added to the gear. This script is useful when you need to pass an API field with a phone number in a specific format (note +{{{countryCode}}}##########). Just select the mask in the settings, even if the field contains a phone number in the format +1(111)111-222-3333, and Albato will automatically convert it to the correct format for the API.
- ObjectArray: The Object Array uses the String Section.
If you select "Date," "Date and Time," or "Phone," you'll see an additional format setting in the field.
You need to customize them. If it's a date, the format for sending it is in the gear.
If "String" is selected, then you must specify the date format according to the PHP rules available in the PHP Manual , as well as the timezone.
If "Number" is selected, then Unixtime (number of seconds since January 1, 1970) or millisecond (same thing, only in milliseconds) can be selected. Albato automatically converts the date into the format required by the API. It does not matter what format the date is in; the main thing is that it should be an initially valid date format.
If the "Phone" type is selected, then a mask is specified, by which the phone number will always be generated.
If you need to send an array of objects in a dynamic way, it goes something like this:
Here we have products—an array of objects, to be exact. This is the set of products in the order. If the previous step gives you a "String Section," and you also want to pass an array based on the number of items you got from the previous step, you need to set the "Object Array" type for the field.
First, set the key for the array, and then go over the fields for that array.
Following the example above, we set up the fields like this:
This means we can pass an array of data and automatically fill it with the same number of items that we got in the previous step.
Configuring this type in the response parameters, as well as all the others, is basically the same process.
