Some of the most powerful features in servis.ai exist in a low-code environment. The coding process is quick and easy! You’ll need full access to our API and/or refer to the use-case tutorials in this Knowledge Base with copy-and-paste code to hit the ground running.
With servis.ai API you can do everything in servis.ai CRM’s Web Interface allowing you to interact with other applications (API stands for Application Programming Interface).
Through the GraphQL API you can perform any typical CRUD operations (create, read, update, delete) on any of your Apps whether they are our out-of-the-box Apps such as Contacts, Deals, Accounts, Tasks, or any Custom App you create. You can create Notes or Tasks as well!
Unleash the power of Servis.ai APIs with our curated collection of requests for Postman! This collection provides a valuable starting point for exploring various APIs. If you are new to Postman? No worries! Before diving in, we recommend checking out Postman’s basic documentation to get comfortable with the tool.
Ready to Get Started? Click here to download the Servis.ai Postman collection and unlock the full potential of Servis.ai APIs!
API Introduction
Servis.ai platform exposes a graphql API endpoint, essentially any data/operation you can access via servis.ai web interface is available via APIs.
This includes typical CRUD operations on CRM objects like leads, deals, accounts or any custom app you may have configured in your account along with the ability to create Next Steps or post activities in the system.
We have documented common APIs typically needed for most integrations, in case you need access to specific data or operations not included in this document, please reach out to support for assistance.
More info on graphql and comparison with REST can be found here: GraphQL vs REST
Authentication
API authentication is via standard and secure OAuth2 protocol, using client credential grants.
Below you will find a few sample requests, you can use any language/library of choice for actual integration.
Reach out to support to get access to your accounts client_id and secret, make sure to secure the API credentials appropriately. Here is how to generate both:
- Be sure you’re logged in to Servis.ai in your browser as an Admin user.
- Authentication needs Client ID & Client Secret also known as API Key, In order to know the API Key, in Servis.ai as admin navigate to:
Settings > Integrations > Integrations page.
- Click on “Generate API Key” button and then pass the email ID of the admin user. You will receive a new API Key – Client ID & Client Secret
Note: You must place the Admin’s email.
- Click on “View API Key” button to view and store your generated data.
Fetching OAuth Access Token
https://freeagent.network/oauth/tokenServis.ai supports client credential Oauth Authentication which should suffice for most backend integrations.
Here is a sample curl request to fetch the access token, access tokens are short-lived and typically expire within an hour, so make sure your integration re-fetches the access token on Auth error due to expiry while invoking the APIs.
Example Request
curl --request POST
--url 'https://freeagent.network/oauth/token'
--header 'content-type: application/json'
--data '{"grant_type":"client_credentials","client_id": "{client_id}","client_secret": "{fa_secret}"}'Response Example
{
"access_token": "31N2hEzxToeLDi2J...",
"expires_in": 3600,
"token_type": "Bearer"
}Once Access Token is fetched it can be used as Bearer Header across any API
curl --request POST --url 'https://freeagent.network/api/graphql' --header "Content-Type: application/json" --header "Authorization: Bearer XXXXXXXXXXX" --data '{"query": "query{listEntityValues(entity: "app_test", pattern: "APP100003") { values { id } } }"}'
Rate Limits
Integrations API calls are subject to the limit of 50 requests per 10 seconds window.
Integrations exceeding the limits will receive error responses with a 429 response code.
Error Handling
API errors typically include the errors attribute in graphql response payload indicating the reason for the error, following are typical HTTP error codes the integration should be programmed to handle.
| Error Code | Meaning |
|---|---|
| 400 | Bad Request — Your request is invalid, typically caused due to malformed graphql request or invalid parameters. |
| 401 | Unauthorized — Your access key is invalid, possibly needing refresh to get a new token. |
| 429 | Too Many Requests — Rate limit exceeded. |
| 500 | Internal Server Error — We had a problem with our server. Try again later. |
| 503 | Service Unavailable — We’re temporarily offline for maintenance. Please try again later. |
Queries
A GraphQL query is used to read or fetch values. This section is about fetch information from your apps and tasks.
https://freeagent.network/api/graphql
List App Records
GraphQL Parameters
Get a list of records from any of your apps. Every app in your account is an entity, even the lines and the out-of-the-box apps like Contacts, Deals and Accounts.
| Parameter | Graph QL Type | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| !entity | String | In order to know the entity object name, you can consult the object name in your Apps configuration.
Required |
||||||||||||||||||
| limit | Int | Limit the number of results returned by the query. | ||||||||||||||||||
| offset | Int | Page offset of the results returned, used along with limit to paginate results | ||||||||||||||||||
| order | [[String]] | Sort order of list query by a given field and sorting function (“ASC” or “DESC”), example: [ [ "full_name", "ASC" ] ] sorts by full_name in ascending order |
||||||||||||||||||
| pattern | String | Search pattern, you can add any string value to search for any text field in your records. | ||||||||||||||||||
| filters | [ { field_name : String, operator : String, values : [String] } ] |
Filter the list by a set of fields, if multiple fields are specified will be and’ed between the fields. Example:
Available operators
Lines If your app contain lines, the way to get the app lines is filtering by “parent_entity_reference_id” in the following way:
Notes:
|
||||||||||||||||||
| fields | [“String”] |
Every request must contain the fields you want to get. In order to know the system name of your fields, in servis.ai as admin navigate to: Admin Settings > App Setup > {your_app} > Form Fields
Example:
|
||||||||||||||||||
| count_only | Boolean |
Set this to true if you only the count of records is needed and not the details. By default its false |
Example Request
query listEntityValues($entity: String!, $fields: [String], $id: String, $order: [[String]], $limit: Int, $offset: Int, $pattern: String, $filters: [Filter], $count_only: Boolean) {
listEntityValues(entity: $entity, fields: $fields, id: $id, order: $order, limit: $limit, offset: $offset, pattern: $pattern, filters: $filters, count_only: $count_only) {
count
entity_values {
id
seq_id
field_values
is_editable
is_deletable
lines
}
}
}Example Variables
{
"entity" : "contact",
"fields" : ["seq_id","full_name","work_email","work_phone","lead_owner_id"],
"limit" : 10,
"filters" : [
{
"field_name" : "seq_id",
"operator" : "does not contains",
"values" : ["CON106633"]
"logical_operator": "and",
"is_drill_down": null,
"outer_group": 1,
"outer_group_logical_operator": "and"
}
],
"offset" : 0,
"pattern" : "",
"order" : [["seq_id","ASC"]],
"count_only": false
}Example Response
{
"data": {
"listEntityValues": {
"count": 1,
"entity_values": [
{
"__typename": "entityValue",
"id": "cb3e8a02-1356-40f7-80bc-59b3cbc7cbb8",
"cache_key": "list_6_cb3e8a02-1356-40f7-80bc-59b3cbc7cbb8",
"seq_id": "CON100001",
"field_values": {
"lead_owner_id": {
"id": "40e00a6f-2af5-48f4-b4ee-d28dd5515616",
"value": "33e5ea8d-4d55-4d64-b9c9-39c4f3b3084d",
"instanceId": "cb3e8a02-1356-40f7-80bc-59b3cbc7cbb8",
"display_value": "Servis Admin",
"formatted_value": "Servis Admin",
"type": "reference",
"metadata": {
"full_name": "Servis Admin",
"first_name": "Servis",
"last_name": "Admin",
"portrait_url": null,
"email_address": "admin-freeagent@freeagentsoftware.com",
"extra_info": true,
"id": "33e5ea8d-4d55-4d64-b9c9-39c4f3b3084d",
"display_name": "Servis Admin",
"deleted": false
}
},
"full_name": {
"id": "741116c9-9e68-484e-b227-a55b0eb08865",
"value": "Jamie Costa",
"instanceId": "cb3e8a02-1356-40f7-80bc-59b3cbc7cbb8",
"display_value": "Jamie Costa",
"formatted_value": "Jamie Costa",
"type": "text",
"metadata": null
},
"created_at": {
"id": "e29cfaf5-accd-41dc-a6fd-fcf26329d941",
"value": "2022-02-28T06:19:22.358Z",
"instanceId": "cb3e8a02-1356-40f7-80bc-59b3cbc7cbb8",
"display_value": "2022-02-28T06:19:22.358Z",
"formatted_value": "2022-02-28T06:19:22.358Z",
"type": "DateTimeComplete",
"metadata": null
},
"work_email": {
"id": "94a10986-b767-4b35-842d-599e9f775551",
"value": "jamiecosta@gmail.com",
"instanceId": "cb3e8a02-1356-40f7-80bc-59b3cbc7cbb8",
"display_value": "jamiecosta@gmail.com",
"formatted_value": "jamiecosta@gmail.com",
"type": "email",
"metadata": null
},
"work_phone": {
"id": "2cae926f-a932-4595-8293-a84fb18503b0",
"value": "1234569574",
"instanceId": "cb3e8a02-1356-40f7-80bc-59b3cbc7cbb8",
"display_value": "1234569574",
"formatted_value": "1234569574",
"type": "phone",
"metadata": null
},
"seq_id": {
"id": "b314e5fc-bf3d-423c-a728-18234dc6035e",
"value": "CON100001",
"instanceId": "cb3e8a02-1356-40f7-80bc-59b3cbc7cbb8",
"display_value": "CON100001",
"formatted_value": "CON100001",
"type": "ID",
"metadata": null
}
},
"is_editable": true,
"is_deletable": true,
"lines": null
}
],
"__typename": "listEntityValuesQL"
}
}
}
List Apps
GraphQL Parameters
Get a list of all the entities in your account. It’s useful to quickly get the id/label of an entity without the need to open servis.ai
| Parameter | GtraphQL Type | Description |
| alphabetical_order | Boolean | To get the list ordered alphabetically |
Example Request
query getEntities($alphabetical_order:Boolean) {
getEntities(alphabetical_order:$alphabetical_order) {
name
display_name
label
label_plural
entity_id
}
}Example Variables
{
"alphabetical_order": true
}Example Response
{
"data": {
"getEntities": [
{
"name": "contact",
"display_name": "full_name",
"label": "Contact",
"label_plural": "Contacts",
"entity_id": "ac12096d-027b-57f5-b389-93c1920222a3"
},
{
"name": "logo",
"display_name": "name",
"label": "Account",
"label_plural": "Accounts",
"entity_id": "d72a990d-7bfa-55e7-9651-0b2b3889c311"
},
{
"name": "documentation",
"display_name": "seq_id",
"label": "Documentation",
"label_plural": "Documentation",
"entity_id": "f546b246-18c3-4494-b870-6f299f2253f5"
}
]
}
}List Activities
Get a list of activities from your records, such as emails, notes, calls, meetings, etc.
| Parameter | GraphQL Type | Description |
| limit | Int | Limit the number of results returned by the query. |
| fa_entity_id | String | Entity UUID. In order to know the id of the entity, you can use the endpoint “getEntities” or from servis.ai as Admin, navigate to Admin Settings > App Setup > {your_app} > App configurationThe entity Id is visible in the URL as an UUID |
| instance_id | String | Record UUID. In order to know the id of the record, you can use the endpoint “listEntityValues”, or you can get navigate to the record detail in servis.ai, the URL includes the ID. |
| offset | Int |
Page offset of the results returned, used along with limit to paginate results |
| order | [[String]] |
Sort order of list query by a given field and sorting function (“ASC” or “DESC”), example: |
| pattern | String | The search param will retrieve all text coincidences in the description or the note of the Activity/Next Step |
| filters | [ { field_name : String, operator : String, values : [String] } ] | If you want to delimit the type of Activities you want to get, the possible values in the array can be: • Phone • Text • Task • Note • Meeting • Attachment If you want to get all of them, leave the “
Entity UUID. In order to know the id of the entity, you can use the endpoint “getEntities” or from servis.ai as Admin, navigate to Filter the list by a set of entities, if multiple entities are specified will be and ‘ed between the fields.
|
Example Request
query listEventLogs($entity: String!, $fa_entity_id: String!, $instance_id: String, $id: String, $order: [[String]], $limit: Int, $offset: Int, $pattern: String, $filters: [Filter]) {
listEventLogs(entity: $entity, fa_entity_id: $fa_entity_id, instance_id: $instance_id, id: $id, order: $order, limit: $limit, offset: $offset, pattern: $pattern, filters: $filters) {
count
entity_values {
id
seq_id
field_values
}
}
}
Example Variables
{
"entity": "fa_activity",
"fa_entity_id": "ac12096d-027b-57f5-b389-93c1920222a3",
"instance_id": "8f721091-5b4a-4af1-882c-8aea3cf891e6",
"order": [["created_at","desc"]],
"limit": 20,
"offset": 0,
"pattern": "",
"filters": [{
"field_name": "object_entity_id",
"operator": "includes",
"values": ["898f7649-9406-42d2-8fbe-e2db24337b4b"]}]
}
Example Response
[
{
"data": {
"listEventLogs": {
"count": 1,
"entity_values": [
{
"__typename": "entityValue",
"id": "7685a03b-0651-4d62-ba64-e27602bfb88f",
"cache_key": "list_0_7685a03b-0651-4d62-ba64-e27602bfb88f",
"seq_id": "ACT1158965",
"field_values": {
"seq_id": {
"id": "5892ccf4-98ed-4501-85b4-6a9087996a00",
"value": "ACT1158965",
"instanceId": "7685a03b-0651-4d62-ba64-e27602bfb88f",
"display_value": "ACT1158965",
"formatted_value": "ACT1158965",
"type": "text",
"metadata": null
},
"message": {
"id": "5892ccf4-98ed-4501-85ba-6a9087996aaa",
"value": {
"vars": {
"created_by": {
"id": "717db41e-5f2e-4e2d-a258-88f4bbcdb7fa",
"field": {
"id": "717db41e-5f2e-4e2d-a258-88f4bbcdb7fa",
"name": "created_by",
"type": "reference",
"entity": "note_fa"
},
"value": "011a342a-d3c1-4949-8bec-06c1c657ba64",
"instanceId": "a10f130e-e981-4f98-864e-86447fb8362b",
"display_value": "Freeagent Admin",
"formatted_value": "Freeagent Admin"
},
"note_fa_field1": {
"id": "9a8c6d13-96a4-4102-9757-117243408bad",
"field": {
"id": "9a8c6d13-96a4-4102-9757-117243408bad",
"name": "note_fa_field1",
"type": "reference",
"entity": "note_fa"
},
"value": "ac12096d-027b-57f5-b389-93c1920222a3",
"instanceId": "a10f130e-e981-4f98-864e-86447fb8362b",
"display_value": "Contact",
"formatted_value": "Contact"
},
"note_fa_field2": {
"id": "5b2f36ff-1962-4f0d-b3c4-7d96857f68ad",
"field": {
"id": "5b2f36ff-1962-4f0d-b3c4-7d96857f68ad",
"name": "note_fa_field2",
"type": "reference",
"entity": "note_fa"
},
"value": "8f721091-5b4a-4af1-882c-8aea3cf891e6",
"instanceId": "a10f130e-e981-4f98-864e-86447fb8362b",
"display_value": "Jamie Costa",
"formatted_value": "Jamie Costa"
}
},
"value": "Freeagent Admin added a note to Contact - Jamie Costa",
"entity": "note_fa",
"template": "{{created_by}} added a note to {{note_fa_field1}} - {{note_fa_field2}}",
"instanceId": "a10f130e-e981-4f98-864e-86447fb8362b"
},
"instanceId": "7685a03b-0651-4d62-ba64-e27602bfb88f",
"display_value": "Freeagent Admin added a note to Contact - Jamie Costa",
"formatted_value": "Freeagent Admin added a note to Contact - Jamie Costa",
"type": "json_template_value",
"metadata": null
},
"body": {
"id": "5892ccf4-98ed-4501-85ba-6a9087996aab",
"value": {
"vars": {
"note_fa_field0": {
"id": "ba6d2109-63d4-4c1c-bbc3-bb3562f22111",
"value": "<div>Email Has NOT been opened yet.</div>",
"display_value": "Email Has NOT been opened yet.",
"formatted_value": "Email Has NOT been opened yet.",
"metadata": null,
"field": {
"id": "ba6d2109-63d4-4c1c-bbc3-bb3562f22111",
"name": "note_fa_field0",
"entity": "note_fa",
"type": "rich_text"
}
},
"seq_id": {
"id": "7ddf03e3-e7f7-4a51-9fb4-8be6572294bb",
"value": "NOT119966",
"display_value": "NOT119966",
"formatted_value": "NOT119966",
"metadata": null,
"field": {
"id": "7ddf03e3-e7f7-4a51-9fb4-8be6572294bb",
"name": "seq_id",
"entity": "note_fa",
"type": "ID"
}
}
},
"value": "Email Has NOT been opened yet.",
"entity": "note_fa",
"template": "{{note_fa_field0}}",
"instanceId": "a10f130e-e981-4f98-864e-86447fb8362b"
},
"instanceId": "7685a03b-0651-4d62-ba64-e27602bfb88f",
"display_value": "Email Has NOT been opened yet.",
"formatted_value": "Email Has NOT been opened yet.",
"type": "json_template_value",
"metadata": null
},
"icon": {
"id": "a69b26cb-8119-456e-a9ed-6a4624cdfc31",
"value": "e283d1cd-6328-48c7-a92f-88203d93d61c",
"instanceId": "7685a03b-0651-4d62-ba64-e27602bfb88f",
"display_value": "e283d1cd-6328-48c7-a92f-88203d93d61c",
"formatted_value": "e283d1cd-6328-48c7-a92f-88203d93d61c",
"type": "icon",
"metadata": null
},
"object_entity_id": {
"id": "5892ccf4-98ed-4501-85b4-6a9087996a77",
"value": "898f7649-9406-42d2-8fbe-e2db24337b4b",
"instanceId": "7685a03b-0651-4d62-ba64-e27602bfb88f",
"display_value": "Note",
"formatted_value": "Note",
"type": "reference",
"metadata": {
"default_sorts": []
}
},
"object_reference_id": {
"id": "5892ccf4-98ed-4501-85b4-6a9087996a81",
"value": "a10f130e-e981-4f98-864e-86447fb8362b",
"instanceId": "7685a03b-0651-4d62-ba64-e27602bfb88f",
"display_value": "NOT119966",
"formatted_value": "NOT119966",
"type": "reference"
},
"activity_type_id": {
"id": "5892ccf4-98ed-4501-85b4-6a9087996a55",
"value": null,
"instanceId": "7685a03b-0651-4d62-ba64-e27602bfb88f",
"display_value": null,
"formatted_value": null,
"type": "reference",
"metadata": null
},
"actor_reference_id": {
"id": "5892ccf4-98ed-4501-85b4-6a9087996a33",
"value": "011a342a-d3c1-4949-8bec-06c1c657ba64",
"instanceId": "7685a03b-0651-4d62-ba64-e27602bfb88f",
"display_value": "FA Bot",
"formatted_value": "FA Bot",
"type": "reference",
"metadata": {
"full_name": "Freeagent Admin",
"first_name": "Freeagent",
"last_name": "Admin",
"portrait_url": null,
"email_address": "freeagentadmin-1673663891410@fabot.com",
"extra_info": true,
"id": "011a342a-d3c1-4949-8bec-06c1c657ba64",
"display_name": "Freeagent Admin",
"deleted": false
}
},
"created_at": {
"id": "c8d7fb94-a51c-404b-b03a-550a2dd54922",
"value": "2024-10-29T13:54:44.997Z",
"instanceId": "7685a03b-0651-4d62-ba64-e27602bfb88f",
"display_value": "2024-10-29T13:54:44.997Z",
"formatted_value": "10/29/24 7:24pm",
"type": "DateTimeComplete",
"metadata": null
},
"updated_by": {
"id": "5892ccf4-98ed-4501-85b4-6a9087996a11",
"value": "011a342a-d3c1-4949-8bec-06c1c657ba64",
"instanceId": "7685a03b-0651-4d62-ba64-e27602bfb88f",
"display_value": "Freeagent Admin",
"formatted_value": "Freeagent Admin",
"type": "reference",
"metadata": {
"full_name": "Freeagent Admin",
"first_name": "Freeagent",
"last_name": "Admin",
"portrait_url": null,
"email_address": "freeagentadmin-1673663891410@fabot.com",
"extra_info": true,
"id": "011a342a-d3c1-4949-8bec-06c1c657ba64",
"display_name": "Freeagent Admin",
"deleted": false
}
},
"updated_at": {
"id": "53232620-f23f-41e7-93f4-ab8841781344",
"value": "2024-10-29T13:54:44.997Z",
"instanceId": "7685a03b-0651-4d62-ba64-e27602bfb88f",
"display_value": "2024-10-29T13:54:44.997Z",
"formatted_value": "10/29/24 7:24pm",
"type": "DateTimeComplete",
"metadata": null
},
"pinned": {
"id": "5892ccf4-98ed-4501-85b4-6a9087996a82",
"instanceId": "7685a03b-0651-4d62-ba64-e27602bfb88f",
"formatted_value": null,
"type": "reference_array",
"metadata": null
},
"event_date": {
"id": "c69b2fcb-8119-456e-b9ed-6a4624cdfc3e",
"value": "2024-10-29T13:54:44.924Z",
"instanceId": "7685a03b-0651-4d62-ba64-e27602bfb88f",
"display_value": "2024-10-29T13:54:44.924Z",
"formatted_value": "10/29/24 7:24pm",
"type": "DateTimeComplete",
"metadata": null
},
"created_by": {
"id": "5892ccf4-98ed-4501-85b4-6a9087996a11",
"value": "011a342a-d3c1-4949-8bec-06c1c657ba64",
"instanceId": "7685a03b-0651-4d62-ba64-e27602bfb88f",
"display_value": "Freeagent Admin",
"formatted_value": "Freeagent Admin",
"type": "reference",
"metadata": {
"full_name": "Freeagent Admin",
"first_name": "Freeagent",
"last_name": "Admin",
"portrait_url": null,
"email_address": "freeagentadmin-1673663891410@fabot.com",
"extra_info": true,
"id": "011a342a-d3c1-4949-8bec-06c1c657ba64",
"display_name": "Freeagent Admin",
"deleted": false
}
}
}
},
]
}
}
}
]
