Actions are a very important part of an integration. It is a step that is executed on your app like post a message, create a task and many more (depending on your app). To perform an action in an app, we need to execute the respective action endpoint. These endpoints are specified in the app’s documentation. The purpose of this article is to guide you through the whole process of creating an action endpoint using Integry. These endpoints are created either under the Endpoints tab in your app or when you create an action, you select Create a new endpoint option in the Endpoint field. 

How to create an Action Endpoint?

Let us walk through an example of how to create an action endpoint. When you select the Create a new endpoint option from the drop-down menu  as shown below, you need to fill the endpoint creation form. 


The basics of this procedure can be learned here. We want to create an action “Create a message in Basecamp”. We will enter the name of the endpoint and select Outgoing endpoint type (as we are going to post to in Basecamp).  

Request URL

We know from API docs of Basecamp that we should send a request to the following endpoint to post the message.

POST /buckets/1/message_boards/3/messages.json

The URL above publishes a message in the project with ID 1 and under the message board with an ID of 3. Furthermore, we also know that the base part of this URL is https://3.basecampapi.com/5 where 5 is the Account ID.

The URL takes the values Account, Project and Message Board IDs for integrations of different users. So how do we get those? These dynamic values are added to the URL using the requestBody.data Twig object. requestBody object can access the information required by the URL and the request template.
We will create the following activity fields in our action ‘Create a message in Basecamp”.

Their values for the current integration can be read off of the requestBody.data object in combination with the respective field machine names in the endpoint URL. So, Our URL will look like this:

https://3.basecampapi.com/{{requestBody.data.basecamp_account}}/buckets/{{requestBody.data.basecamp_project}}/message_boards/{{requestBody.data.basecamp_message_board}}/messages.json 

These values will be replaced with actual values and the URL will be processed. 

Request Template Structure

If the HTTP Verb chosen by you supports Request body, you can compose that in this field. The Create a Message endpoint documentation also specifies the structure of the request payload. The following example that we are using requires activity fields’ values for subject and content whereas the value of status is provided as a string because it will always be “active”.

{
"subject": "{{ requestBody.data.basecamp_message_subject }}",
"status": "active",
"content": "{{ requestBody.data.basecamp_message_content }}"
}

Like URL, we will again access the values of subject and content by using the combination of requestBody.data object with the machine names of the respective fields. 

Response Template Structure

The response received in return of the request we sent, will be the output of our endpoint. In the Create a Message endpoint example, we let the response received intact and will leave the field empty. 

This example is Basecamp specific, these templates and their syntax differ from app to app. 

Custom Fields and Request Template

Let us say we want to create an action “Create a contact in SendinBlue”. We add custom fields in this action so we can fetch custom data fields of the contact form from the SendinBlue. Custom fields are fetched through an endpoint, Field Lists source endpoint, details

From the SendinBlue API DOCs we know, we need to send a request to the following URL

POST https://api.sendinblue.com/v3/contacts

Request Template

The Request Template will take the data saved in custom fields and attach it to the request body as shown below along with other objects. From the API DOCs we know, the request body should have the email, attributes, ID of the list to add the contact to etc. The following code explains how the template will look like: 

{
   "email":"{{requestBody.data.email}}",
   "attributes":{
        {% for property_name, property_value in requestBody.data.sendinblue_attributes %}
                  "{{ property_name }}":"{{ property_value }}" {% if not loop.last %} , {% endif %}
           {% endfor %}
                 },
"listIds":[{{requestBody.data.listid}}]
}


The code above iterates through the sendinblue_attribute (the machine name of the custom field as explained here), the values of these attributes are available through the requestBody.data object. The attributes are saved as key-value pair and sent as request body to SendinBlue API.

Testing Endpoints

You can test the endpoints you create, right away. To learn how to test the endpoint, click here

Did this answer your question?