Making API Calls to Unified and Proxy APIs in Truto
Truto provides you two ways to access your integrated account's data: the 'Unified API' and the 'Proxy API'. Both options allow you to fetch data from the underlying APIs, but they present this data in different ways.
Unified API
The Unified API transforms the data into a common format, making it easier to work with if you're using multiple different integrations.
Proxy API
The Proxy API gives you the data exactly as it comes from the original source, without any transformations. It's more of a direct line to the underlying API.
Making API Calls via Truto interface
- Sign into Truto and go to the
Integrated Accountssection or click here.
- Select an Integrated Account. In the account details, you will find the options
Unified APIandProxy API. - Select either 'Unified API' or 'Proxy API' based on your requirements.
- Select a Resource to call from that API. Click on
Try it out. A new window will open.
- Click on
Call API
Querying Data
Both APIs allow you to limit the number of results you get in one go by using the limit parameter. You can also use the next_cursor parameter to navigate through pages of results.
In some cases, you might need to use specific query parameters like id to retrieve specific data.
In the Unified API, you'll find an option called Show remote_data. If this is enabled, you'll see both the transformed data and the original data from the underlying API. If it's disabled, you'll only see the transformed data.
Writing Data using Unified APIs
Writing data back into the integrations using Unified APIs is inherently a hard problem to solve. The remote APIs usually have their own set of required fields while creating or updating data. And certain fields which are required for writing data don't get sent in the responses.
Truto tries to solve this by
- Using the same fields you receive in the response of Unified APIs as the fields of the request body while writing data.
- Providing a
/metaAPI for each Unified API resource to help you generate the requests programmatically.
Structure of request body in the Unified API
Let's take an example of creating a CRM Contact using the Unified API.
A CRM Contact object has the following Unified fields,
- first_name
- last_name
- email_addresses
- and many more
We'll use the same set of Unified fields to create a CRM Contact irrespective of the underlying API integration.
So with these things in mind, a request body to create or update a Contact in Hubspot with the Unified API would like,
// POST https://api.truto.one/unified/crm/contacts
// example of a Hubspot Contact create request
{
// set of unified API fields,
"first_name": "John",
"last_name": "Doe",
// an object which gets passed as it to the underlying API.
"remote_data": {
"properties": {
"hs_some_hubspot_specific_property": "from_truto"
}
}
}In the example above, the first_name and last_name Unified API fields get transformed according to the Hubspot API rules and the object in the remote_data gets merged into the transformed object.
This is how the final request object would look like after all the transformations are applied by Truto,
{
// notice how first_name and last_name get added to the properties object.
"properties": {
"firstname": "John",
"lastname": "Doe",
"hs_some_hubspot_specific_property": "from_truto"
}
}first_name becomes properties.firstname and last_name becomes properties.lastname. The way Hubspot expects the request body to be.
/meta route to get request body schema
In the Hubspot example above, we had to refer to the Hubspot documentation to figure out the required fields to create a Contact. But we don't want to do that for every single CRM, so Truto provides a solution where you can query the fields required to create or update an entity using Unified API resource by calling the /meta route.
Taking the Hubspot example from above, you can call the following route to fetch the fields required to create a Contact in Hubspot,
GET /unified/crm/contacts/create/meta?integrated_account_id=<a_hubspot_integrated_account_id>GET /unified/crm/contacts/update/meta?integrated_account_id=<a_hubspot_integrated_account_id>GET /unified/crm/contacts/list/meta?integrated_account_id=<a_hubspot_integrated_account_id>GET /unified/crm/contacts/get/meta?integrated_account_id=<a_hubspot_integrated_account_id>It should return a response with request_body_schema attribute which contains the fields required to make the request.
{
"method": "create",
"schema": {
// JSON schema of the response
},
"query_schema": {
// JSON schema of the query parameters you need to pass
},
// The request body fields
"request_body_schema": {
"first_name": {
"type": "string",
"description": "The contact's first name",
"required": true,
"mapping": "first_name"
},
"last_name": {
"type": "string",
"description": "The contact's last name",
"mapping": "last_name"
},
"addresses": {
"type": "array",
"items": {
"type": "object",
"properties": {
"street_1": {
"type": "string",
"description": "Line 1 of the street address"
},
"street_2": {
"type": "string",
"description": "Line 2 of the street address"
},
"city": {
"type": "string",
"description": "The city"
},
"state": {
"type": "string",
"description": "The state"
},
"postal_code": {
"type": "string",
"description": "The postal code"
},
"country": {
"type": "string",
"description": "The country"
},
"type": {
"type": "string",
"description": "The address type"
}
}
},
"mapping": "addresses"
},
"email_addresses": {
"type": "array",
"items": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "The email address"
},
"type": {
"type": "string",
"description": "The email address type"
}
}
},
"required": true,
"mapping": "email_addresses"
},
"phone_numbers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"number": {
"type": "string",
"description": "The phone number"
},
"type": {
"type": "string",
"description": "The phone number type"
}
}
},
"mapping": "phone_numbers"
},
"custom_fields": {
"type": "object",
"description": "Custom fields to be set on the contact",
"mapping": "custom_fields"
}
},
"default_query": {}
}