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!
Table of Contents
- API Introduction
- Authentication
- Fetching oAth Access Token
- Retrieve Access Token and Start Using the Same as Bearer Header Across any API
- Rate Limits
- Error Handling
- Queries
- List App Records
- List Apps
- List Activities
- List Changes on App Records
- List Account Users
- List App Fields
- List Choice List Values
- Mutations
- Automated Import
- Create App Record
- Update App Record
- Bulk Update App Records
- Delete App Record
- Bulk Delete App Records
- Create/Update App with Lines
- Create Notes
- Create Tasks
- Connect Postman to Servis.ai
- Install Postman
- Importing Servis.ai API collection
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.
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
|
||||||||||||||||||
| 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:
Example: ["seq_id","full_name", "contact_field01"]
|
||||||||||||||||||
| 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 " Filters" as empty:"filters" : []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 Filter the list by a set of entities, if multiple entities are specified will be and 'ed between the fields. Example: "filters": [{"field_name": "object_entity_id", "operator": "includes", "values": [ "22fb2a43-b232-581d-b2f5-16be87e41e7a", "898f7649-9406-42d2-8fbe-e2db24337b4b"]}]
|
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
}
}
}
},
]
}
}
}
]
List Changes on App Records
Get a list of the latest changes made to a record.
GraphQL Parameters
| Parameter | GraphQL Type | Description |
| entity | String | In order to know the entity object name, you can consult the object name in your Apps configuration. Required |
| id | String |
The id must be the UUID record id. In order to know the id of a record you can use the endpoint listEntityValues Required |
| from_date | Date | The format can be YYYY-MM-DD or ISO Date YYYY-MM-DD:HH:MM:SS.000z |
| to_date | Date | The format can be YYYY-MM-DD or ISO Date YYYY-MM-DD:HH:MM:SS.000z |
| 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 |
Example Request
query fetchChangeHistory($entity: String!, $id: String, $entity_id: String, $from_date: Date, $to_date: Date, $offset: Int, $limit: Int, $fields: [String]) {
fetchChangeHistory(entity: $entity, id: $id, entity_id: $entity_id, from_date: $from_date, to_date: $to_date, offset: $offset, limit: $limit, fields: $fields) {
record_changes {
seq_id
instance_id
is_create
created_at
created_by
updated_at
updated_by
field_changes
updated_by_job
job_detail
}
}
}
Example Variables
{
"entity": "contact",
"id": "8f721091-5b4a-4af1-882c-8aea3cf891e6",
"from_date": "2015-01-01T00:00:00.000Z",
"to_date": "2030-01-01T23:59:00.000Z",
"offset": 0,
"limit": 100
}
Example Response
{
"data": {
"fetchChangeHistory": {
"record_changes": [
{
"seq_id": "CON101751",
"instance_id": "8f721091-5b4a-4af1-882c-8aea3cf891e6",
"is_create": false,
"created_at": {
"id": "e29cfaf5-accd-41dc-a6fd-fcf26329d941",
"value": "2022-05-25T12:57:48.287Z",
"instanceId": "8f721091-5b4a-4af1-882c-8aea3cf891e6",
"display_value": "2022-05-25T12:57:48.287Z",
"formatted_value": "2022-05-25T12:57:48.287Z",
"type": "DateTimeComplete",
"metadata": null
},
"created_by": {
"id": "cab5f807-33e0-4ddf-9207-e48f6c039ae1",
"value": "d33b9d0c-1b5d-4ae6-a3e0-87f6e83c6f1d",
"instanceId": "8f721091-5b4a-4af1-882c-8aea3cf891e6",
"display_value": "Jamie Oliver",
"formatted_value": "Jamie Oliver",
"type": "reference",
"metadata": {
"full_name": "Jamie Oliver",
"first_name": "Jamie",
"last_name": "Oliver",
"portrait_url": null,
"email_address": "jamieoliver@gmail.com",
"extra_info": true,
"id": "d33b9d0c-1b5d-4ae6-a3e0-87f6e83c6f1d",
"display_name": "Jamie Oliver",
"deleted": false
}
},
"updated_at": {
"id": "3a746264-61c3-4955-b649-c37b96cddccb",
"value": "2024-09-10T18:06:27.007Z",
"instanceId": "8f721091-5b4a-4af1-882c-8aea3cf891e6",
"display_value": "2024-09-10T18:06:27.007Z",
"formatted_value": "2024-09-10T18:06:27.007Z",
"type": "DateTimeComplete",
"metadata": null
},
"updated_by": {
"id": "cab5f807-33e0-4ddf-9207-e48f6c039ae1",
"value": "d33b9d0c-1b5d-4ae6-a3e0-87f6e83c6f1d",
"instanceId": "8f721091-5b4a-4af1-882c-8aea3cf891e6",
"display_value": "Jamie Oliver",
"formatted_value": "Jamie Oliver",
"type": "reference",
"metadata": {
"full_name": "Jamie Oliver",
"first_name": "Jamie",
"last_name": "Oliver",
"portrait_url": null,
"email_address": "jamieoliver@gmail.com",
"extra_info": true,
"id": "d33b9d0c-1b5d-4ae6-a3e0-87f6e83c6f1d",
"display_name": "Jamie Oliver",
"deleted": false
}
},
"field_changes": [
{
"changed_field": {
"formatted_value": "Last Status Change Date",
"display_value": "Last Status Change Date",
"value": "contact_field2"
},
"current_value": {
"id": "6cf8c73b-a9f1-4063-bf87-0ab1da163f03",
"value": "2024-09-10T18:06:26.997Z",
"instanceId": "8f721091-5b4a-4af1-882c-8aea3cf891e6",
"display_value": "2024-09-10T18:06:26.997Z",
"formatted_value": "2024-09-10T18:06:26.997Z",
"type": "DateTimeComplete",
"metadata": null
},
"previous_value": {
"id": "6cf8c73b-a9f1-4063-bf87-0ab1da163f03",
"value": "2023-05-26T11:36:57.927Z",
"instanceId": "8f721091-5b4a-4af1-882c-8aea3cf891e6",
"display_value": "2023-05-26T11:36:57.927Z",
"formatted_value": "2023-05-26T11:36:57.927Z",
"type": "DateTimeComplete",
"metadata": null
}
},
{
"changed_field": {
"formatted_value": "Lead Status",
"display_value": "Lead Status",
"value": "lead_status_id"
},
"current_value": {
"id": "b24b967e-5403-4c60-ae7d-daaf295a1593",
"value": "01788c1f-f030-4f72-baad-a2bc27f13840",
"instanceId": "8f721091-5b4a-4af1-882c-8aea3cf891e6",
"display_value": "Qualified",
"formatted_value": "Qualified",
"user_defined_value": null,
"type": "reference",
"metadata": {
"custom_fields": {
"color": "#329288"
},
"user_defined_value": null,
"extra_info": true,
"id": "01788c1f-f030-4f72-baad-a2bc27f13840",
"display_name": "Qualified",
"deleted": false,
"catalog_type.id": "9847708a-71b5-460d-b5ee-b0324a309ff2",
"catalog_type.name": "Lead Status - Lead",
"catalog_type.deleted": false,
"catalog_type.metadata": null
}
},
"previous_value": {
"id": "b24b967e-5403-4c60-ae7d-daaf295a1593",
"value": "04d022b9-c405-427d-b1c2-0295a337d34c",
"instanceId": "8f721091-5b4a-4af1-882c-8aea3cf891e6",
"display_value": "Connected",
"formatted_value": "Connected",
"user_defined_value": null,
"type": "reference",
"metadata": {
"custom_fields": {
"color": "#52b0a4"
},
"user_defined_value": null,
"extra_info": true,
"id": "04d022b9-c405-427d-b1c2-0295a337d34c",
"display_name": "Connected",
"deleted": false,
"catalog_type.id": "9847708a-71b5-460d-b5ee-b0324a309ff2",
"catalog_type.name": "Lead Status - Lead",
"catalog_type.deleted": false,
"catalog_type.metadata": null
}
}
}
],
"updated_by_job": {
"id": "671e182f-edd7-403d-94f9-dd94a282b89b",
"value": null,
"instanceId": "8f721091-5b4a-4af1-882c-8aea3cf891e6",
"display_value": null,
"formatted_value": null,
"type": "bot_job_info",
"metadata": null
},
"job_detail": {
"is_job_run": false
}
},
]
}
}
}List Account Users
Get a list of all users in your account, this list contains valuable information such as full name, email address, access level and more.
GraphQL Parameters
| Parameter | GraphQL Type | Description |
|---|---|---|
| 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 |
Example Request
query getTeamMembers {
getTeamMembers {
agents {
id
full_name
first_name
last_name
job_title
signature
presence
teamId
email_address
access_level
access_level_option
language
language_iso
version
phone
last_activity
timezone
network_status
status
deleted
blacklisted
is_visible
pair_email
}
}
}
Example Variables
{
"limit": 50,
"offset": 0
}
Example Response
[
{
"data": {
"getTeamMembers": {
"agents": [
{
"id": "552c198f-f806-45a0-990f-08586c5a8c95",
"full_name": "Tony Stark",
"first_name": "Tony",
"last_name": "Stark",
"job_title": "CEO",
"signature": null,
"presence": false,
"teamId": "e719b4a1-b109-497e-b79a-fa746cfc37e4",
"email_address": "tony.stark@gmail.com",
"access_level": null,
"access_level_option": "46e49665-a5d9-4cce-8d15-ab7ebd4240bb",
"language": "b3a499cd-818f-4db2-a494-4cfd350d4865",
"language_iso": "en",
"version": null,
"phone": null,
"last_activity": "2022-08-26T06:56:37.310Z",
"timezone": null,
"network_status": true,
"status": null,
"deleted": false,
"blacklisted": true,
"is_visible": true,
"pair_email": []
}
]
}
}
}
]
List App Fields
Get a list of fields from specific entities.
GraphQL Parameters
| Parameter | GraphQL Type | Description |
|---|---|---|
| !entity | String | In order to know the entity object name, you can consult the object name in your Apps configuration. Required |
| show_hidden | Boolean | If true, the response will contain deactivated fields (Deleted fields will not be available) |
Example Request
query getFields($entity:String,$show_hidden:Boolean) {
getFields(entity:$entity,show_hidden:$show_hidden){
id
name
name_label
main_type
is_required
is_visible
is_unique
default_value
catalog_type_id
reference_field_id
reference_fa_entity_id
reference_fa_entity_name
}
}Example Variables
{
"entity": "contact",
"show_hidden": false
}Example Response
{
"data": {
"getFields": [
{
"id": "74f6a80b-a4cd-47c7-9005-c56a57bcca43",
"name": "work_email",
"name_label": "Work Email",
"main_type": "email",
"is_required": null,
"is_visible": true,
"is_unique": null,
"default_value": null,
"catalog_type_id": null,
"reference_field_id": null,
"reference_fa_entity_id": null,
"reference_fa_entity_name": null
},
{
"id": "a4bf7d16-d9bb-44ac-b0cc-00d3735c9117",
"name": "contact_field68",
"name_label": "Account Status",
"main_type": "reference_join",
"is_required": null,
"is_visible": true,
"is_unique": false,
"default_value": null,
"catalog_type_id": null,
"reference_field_id": "0b5e4659-166a-4e46-aae8-fc69e1fba366",
"reference_fa_entity_id": "d72a990d-7bfa-55e7-9651-0b2b3889c311",
"reference_fa_entity_name": "logo"
},
{
"id": "ad5fe3ed-5e14-401b-8440-f76e511783fd",
"name": "seq_id",
"name_label": "ID",
"main_type": "ID",
"is_required": null,
"is_visible": true,
"is_unique": null,
"default_value": null,
"catalog_type_id": null,
"reference_field_id": null,
"reference_fa_entity_id": null,
"reference_fa_entity_name": null
},
{
"id": "8076169f-a9df-4443-ad12-764067c2f65c",
"name": "contact_field57",
"name_label": "Thumbnail",
"main_type": "thumbnail",
"is_required": null,
"is_visible": true,
"is_unique": null,
"default_value": null,
"catalog_type_id": null,
"reference_field_id": null,
"reference_fa_entity_id": null,
"reference_fa_entity_name": null
},
{
"id": "9a4833c0-5e0c-46b6-a875-3f5be942960c",
"name": "contact_field4",
"name_label": "Re-Market Reason",
"main_type": "reference",
"is_required": null,
"is_visible": true,
"is_unique": null,
"default_value": null,
"catalog_type_id": "6b772527-1dee-4cdd-8ba7-f48f79199830",
"reference_field_id": null,
"reference_fa_entity_id": "6fc34d02-c890-5661-a157-565d99a4fe37",
"reference_fa_entity_name": "catalog_type"
},{
"id": "16279de3-1044-4d27-b916-cea213236856",
"name": "created_at",
"name_label": "Created",
"main_type": "datetimecomplete",
"is_required": null,
"is_visible": true,
"is_unique": null,
"default_value": null,
"catalog_type_id": null,
"reference_field_id": null,
"reference_fa_entity_id": null,
"reference_fa_entity_name": null
}
]
}
}List Choice List Values
Get a list of your choice list values based on the field id.
GraphQL Parameters
| Parameter | GraphQL Type | Description |
|---|---|---|
| id | String | Id of the field, you can use getFields API to fetch the id of the field. Required |
| pattern | String | Search pattern, you can add any string value to search for any text field in your records. |
| limit | Int | Limit the number of results returned by the query. |
| subtype | String | Based on the type of choice list, the possible values can be one of the following: • “catalogs” - for basic choicelist items • “agents” - for list of Users • “fa_entities” - for references to Apps e.g Contacts, Accounts etc. |
Example Request
query getFieldItems($id: String, $limit: Int, $offset: Int, $no_nulls: Boolean, $withEmpty: Boolean, $withDynamic: Boolean, $subtype: String, $fromForm: Boolean, $fromWidgetForm: Boolean, $fromLineForm: Boolean) {
getFieldItems(fa_field_config_id: $id, limit: $limit, offset: $offset, no_nulls: $no_nulls, withEmpty: $withEmpty, withDynamic: $withDynamic, subtype: $subtype, fromForm: $fromForm, fromWidgetForm: $fromWidgetForm, fromLineForm: $fromLineForm) {
id
name
sub_name
order
metadata
}
}
Example Variables
{
"id": "94537ed4-d773-4103-9317-0ba3f9f5e0b6",
"offset": 0,
"limit": 20,
"subtype": "catalogs"
}
Example Response
{
"data": {
"getFieldItems": [
{
"__typename": "faFieldReference",
"id": "f122f1db-f23c-4cf3-bcb5-c42fb4aeef5c",
"name": "Lead",
"sub_name": null,
"order": 1,
"hide_in_cycle_time": false,
"metadata": {
"custom_fields": null,
"user_defined_value": null
},
"entity": null,
"entity_value": null,
"cache_key": null
},
{
"__typename": "faFieldReference",
"id": "b24992ad-edf1-4868-b203-4518d6c69524",
"name": "Customer",
"sub_name": null,
"order": 2,
"hide_in_cycle_time": false,
"metadata": {
"custom_fields": null,
"user_defined_value": null
},
"entity": null,
"entity_value": null,
"cache_key": null
},
{
"__typename": "faFieldReference",
"id": "e63c5307-1221-43a5-bb18-6e34db469371",
"name": "Partner",
"sub_name": null,
"order": 3,
"hide_in_cycle_time": false,
"metadata": {
"custom_fields": null,
"user_defined_value": null
},
"entity": null,
"entity_value": null,
"cache_key": null
},
{
"__typename": "faFieldReference",
"id": "43808a36-e1ee-43fe-a663-07f29f323d90",
"name": "Other",
"sub_name": null,
"order": 4,
"hide_in_cycle_time": false,
"metadata": {
"custom_fields": null,
"user_defined_value": null
},
"entity": null,
"entity_value": null,
"cache_key": null
}
]
}
}Mutations
Mutation queries modify data in your account, mutations can be used to insert, update or delete data.
Automated Import
For integrating 3rd party systems like your organization's ERP or other enterprise systems. Often it's used to both 'create' new records as well as for 'updates' to keep systems in sync.
Example Curl Request
curlhttps://freeagent.network/api/graphql \
--header "Content-Type: multipart/form-data" \
--header "Authorization: Bearer XXXXXXXX
-F operations='{ "query": "mutation importEntities($upload: Upload!){ importEntities(entity: \"contact\", file: \"demo\", upload: $upload) { importId}}", "variables": {"upload": null} }' \
-F map='{ "0": ["variables.upload"] }' \
-F 0=@/Users/ram/Desktop/contact_import_test.csv
Create App Record
Create a record for any of your apps without line items.
GraphQL Parameters
| Parameter | GraphQL Type | Description |
|---|---|---|
| entity | String | In order to know the entity object name, you can consult the object name in your Apps configuration. Required |
| field_values | {field_name : value} | The field name must be the system field name. In order to know the system name of the field you want to affect, from FreeAgent CRM as administrator navigate to: Admin Settings > App Setup > {your_app} > Form Fields. Example: { "work_email" : "test@test.com", "contact_field1" : "text" }
For references and choice list it's required to use the ID of the value Required |
Example Request
mutation createEntity($entity: String!, $field_values: JSON!) {
createEntity(entity: $entity, field_values: $field_values) {
entity_value {
id
seq_id
field_values
}
}
}
Example Variables
{
"entity" : "contact",
"field_values" : {
"first_name" : "Test",
"last_name" : "test",
"work_email" : "test@test.com"
}
}Example Response
{
"data": {
"createEntity": {
"entity_value": {
"id": "7a16dd45-75a1-4cb5-9aba-b15002364772",
"seq_id": "CON122389",
"field_values": {
"work_email": {
"id": "74f6a80b-a4cd-47c7-9005-c56a57bcca43",
"value": "test@test.com",
"display_value": "test@test.com",
"type": "email",
"metadata": null
},
"seq_id": {
"id": "ad5fe3ed-5e14-401b-8440-f76e511783fd",
"value": "CON122389",
"display_value": "CON122389",
"type": "ID",
"metadata": null
},
"full_name": {
"id": "cfbae798-bb08-401f-a358-aa86bd3c6bff",
"value": "Test test",
"display_value": "Test test",
"type": "text",
"metadata": null
},
"first_name": {
"id": "7e29968c-b6d9-4584-bbc1-3a0b03b6aae1",
"value": "Test",
"display_value": "Test",
"type": "text",
"metadata": null
},
"last_name": {
"id": "1ed560e9-0d1a-44b9-b2ec-8e56d1baecc5",
"value": "test",
"display_value": "test",
"type": "text",
"metadata": null
},
...
}
}
}
}
}Update App Record
Update one record for any of your apps.
GraphQL Parameters
| Parameter | GraphQL Type | Description |
|---|---|---|
| !entity | String | In order to know the entity object name, you can consult the object name in your Apps configuration. Required |
| !id | String | The id must be the UUID record id. In order to know the id of a record you can use the endpoint listEntityValues Required |
| !field_values | {field_name : value} | The field name must be the system field name. In order to know the system name of the field you want to affect, from FreeAgent CRM as administrator navigate to: Admin Settings > App Setup > {your_app} > Form Fields Example: { "work_email" : "test@test.com", "contact_field1" : "text" }
For references and choice list it's required to use the ID of the value Required |
Request Example
mutation updateEntity($entity: String!, $id: String!, $field_values: JSON!) {
updateEntity(entity: $entity, id: $id,field_values: $field_values) {
entity_value {
id
seq_id
field_values
}
}
}Example Variables
{
"entity": "contact",
"id": "83efbbae-c8eb-47ac-afea-161e951f7564",
"field_values": {
"first_name" : "Ivan Andres",
"lead_owner_id" : "dd3129cf-ff7e-4ef5-8d5b-daf027a913f1"
}
}Example Response
{
"data": {
"updateEntity": {
"entity_value": {
"id": "83efbbae-c8eb-47ac-afea-161e951f7564",
"seq_id": "CON122470",
"field_values": {
"seq_id": {
"id": "ad5fe3ed-5e14-401b-8440-f76e511783fd",
"value": "CON122470",
"display_value": "CON122470",
"type": "ID",
"metadata": null
},
"work_email": {
"id": "74f6a80b-a4cd-47c7-9005-c56a57bcca43",
"value": "ivan.carrillo@softwaretp.com",
"display_value": "ivan.carrillo@softwaretp.com",
"type": "email",
"metadata": null
},
"full_name": {
"id": "cfbae798-bb08-401f-a358-aa86bd3c6bff",
"value": "Ivan Andres Carrillo Bustos",
"display_value": "Ivan Andres Carrillo Bustos",
"type": "text",
"metadata": null
},
"last_name": {
"id": "1ed560e9-0d1a-44b9-b2ec-8e56d1baecc5",
"value": "Carrillo Bustos",
"display_value": "Carrillo Bustos",
"type": "text",
"metadata": null
},
"logo_id": {
"id": "87a33d95-fd4e-4dc2-a7ee-633b7780aae7",
"value": "dba4e7f4-8762-4a3e-b279-052dd0774127",
"display_value": "Software TP - Test - Ivan",
"type": "reference"
},
"contact_field44": {
"id": "bf341295-947d-47f2-a211-297e6bebda93",
"value": "dd3129cf-ff7e-4ef5-8d5b-daf027a913f1",
"display_value": "Ivan Carrillo",
"type": "reference",
"metadata": {
"full_name": "Ivan Carrillo",
"first_name": "Ivan",
"last_name": "Carrillo",
"portrait_url": "https://freeagent-network-public.s3.us-west-2.amazonaws.com/dd3129cf-ff7e-4ef5-8d5b-daf027a913f1/Screen%20Shot%202020-01-10%20at%204.25.36%20PM_1582359214016.png",
"email_address": "ivan.carrillo@freeagentsoftware.com",
"extra_info": true,
"id": "dd3129cf-ff7e-4ef5-8d5b-daf027a913f1",
"display_name": "Ivan Carrillo",
"deleted": false
}
},
"lead_owner_id": {
"id": "175c7887-1841-4e8a-a784-426c1c6137a6",
"value": "dd3129cf-ff7e-4ef5-8d5b-daf027a913f1",
"display_value": "Ivan Carrillo",
"type": "reference",
"metadata": {
"full_name": "Ivan Carrillo",
"first_name": "Ivan",
"last_name": "Carrillo",
"portrait_url": "https://freeagent-network-public.s3.us-west-2.amazonaws.com/dd3129cf-ff7e-4ef5-8d5b-daf027a913f1/Screen%20Shot%202020-01-10%20at%204.25.36%20PM_1582359214016.png",
"email_address": "ivan.carrillo@freeagentsoftware.com",
"extra_info": true,
"id": "dd3129cf-ff7e-4ef5-8d5b-daf027a913f1",
"display_name": "Ivan Carrillo",
"deleted": false
}
}
}
}
}
}
}Bulk Update App Records
Update one or multiple records for any of your apps.
If you update more than 250 records, the process will occur in an async process and can be tracked in the Jobs page. The sent_to_job response value will be "True"
GraphQL Parameters
| Parameter | GraphQL Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| !entity | String | In order to know the entity object name, you can consult the object name in your Apps configuration. Required |
||||||||||||
| pattern | String | Search pattern, you can add any string value to search for any text field in your records. | ||||||||||||
| !ids | [String] | The array must contain the id of the record/records you want to update. In order to know the id of a record you can use the endpoint listEntityValues Required |
||||||||||||
| !field_values | {field_name : value} | The field name must be the system field name. In order to know the system name of the field you want to affect, from FreeAgent CRM as administrator navigate to: Admin Settings > App Setup > {your_app} > Form Fields Example: { "work_email" : "test@test.com", "contact_field1" : "text" }
For references and choice list it's required to use the ID of the value Required |
||||||||||||
| filters | [ { field_name : String, operator : String, values : [String] } ] |
Filter the list by a set of fields, if multiple fields are specified will be added between the fields.
Example: [ { "field_name": "seq_id", "operator" : "contains" "values": ["CON106633"] }, { "field_name" : "date_field", "operator" : "between", "values" : [ "2020-10-07T05:00:00.000Z", "2020-10-09T04:59:59.000Z" ] } ]
Available operators
|
Example Request
mutation bulkUpdateEntities($entity: String!, $ids: [String]!, $field_values: JSON!, $filters: [Filter], $pattern: String) {
bulkUpdateEntities(entity: $entity, ids: $ids, field_values: $field_values, filters: $filters, pattern: $pattern) {
sent_to_job
}
}Example Variables
{
"entity" : "contact",
"field_values" : {
"first_name": "Ivan Andres"
},
"ids" : ["897cd2cd-1dbb-4f48-a248-5760ccf18bfa"],
"filters" : [],
"pattern" : ""
}Example Response
{
"data": {
"bulkUpdateEntities": {
"sent_to_job": null
}
}
}Delete App Record
Delete one record for any of your apps.
GraphQL Parameters
| Parameter | GraphQL Type | Description |
|---|---|---|
| !entity | String | In order to know the entity object name, you can consult the object name in your Apps configuration. Required |
| !id | String | The id must be the UUID record id. In order to know the id of a record you can use the endpoint listEntityValues Required |
Example Request
mutation deleteEntity($entity: String!, $id: String!) {
deleteEntity(entity: $entity, id: $id) {
entity_value {
id
}
}
} Example Variables
{
"entity": "contact",
"id": "aa780132-9892-4fb7-9602-b7da1e1ed0cb"
}Example Response
{
"data": {
"deleteEntity": {
"entity_value": {
"id": "aa780132-9892-4fb7-9602-b7da1e1ed0cb"
}
}
}
}Bulk Delete App Records
Delete one or multiple records for any of your apps.
If you delete more than 250 records, the process will occur in an async process and can be tracked in the Jobs page. The sent_to_job response value will be "True"
GraphQL Parameters
| !entity | String | In order to know the entity object name, you can consult the object name in your Apps configuration. Required |
||||||||||||
| pattern | String | Search pattern, you can add any string value to search for any text field in your records. | ||||||||||||
| !ids | [String] | The array must contain the id of the record/records you want to update. In order to know the id of a record you can use the endpoint listEntityValues Required |
||||||||||||
| 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. [ { "field_name": "seq_id", "operator" : "contains" "values": ["CON106633"] }, { "field_name" : "date_field", "operator" : "between", "values" : [ "2020-10-07T05:00:00.000Z", "2020-10-09T04:59:59.000Z" ] } ]Available operators
|
Example Request
mutation bulkDeleteEntities($entity: String!, $ids: [String]!, $filters: [Filter], $pattern: String) {
bulkDeleteEntities(entity: $entity, ids: $ids, filters: $filters, pattern: $pattern) {
sent_to_job
}
}Example Variables
{
"entity" : "contact",
"ids" : ["897cd2cd-1dbb-4f48-a248-5760ccf18bfa"],
"filters" : [],
"pattern" : ""
}Example Response
{
"data": {
"bulkDeleteEntities": {
"sent_to_job": null,
}
}
}Create/Update App with Lines
Create or update a record with a line item, and/or both simultaneously.
GraphQL Parameters
| Parameter | GraphQL Type | Description |
|---|---|---|
| !entity | String | In order to know the entity object name, you can consult the object name in your Apps configuration. Required |
| id | String | The id must be the UUID record id. In order to know the id of a record you can use the endpoint listEntityValues Note: If the id is not specified, a new record will be created. |
| !field_values | {field_name : value} |
The field name must be the system field name. In order to know the system name of the field you want to affect, from servis.ai as administrator navigate to:Admin Settings > App Setup > {your_app} > Form FieldsExample:{"work_email": "test@test.com", "contact_field1": "text"}For references and choice list it's required to use the ID of the value Required |
| children | {id: String, entity: !String, !field_values: {field_name: value}} | The rules for child parameters are the same as the above described. Required Values:
|
Example Request
mutation upsertCompositeEntity($entity: String!, $id: String, $field_values: JSON!, $children:[JSON!]) {
upsertCompositeEntity(entity: $entity, id: $id, field_values:$field_values,children:$children){
entity_value {
id
seq_id
field_values
}
children {
id
field_values
}
}
}
Example Variables
{
"entity": "quote",
"field_values": {
"quote_field8" : "2020-10-06",
"quote_field9" : "2020-10-06",
"owner_id":"dd3129cf-ff7e-4ef5-8d5b-daf027a913f1"
},
"children": [
{
"entity":"sub",
"field_values":{
"sub_field0" : "b630c9ed-62c8-4792-894f-745074fed29a",
"sub_field2" : 1
}
}
]
}Example Response
{
"data": {
"upsertCompositeEntity": {
"entity_value": {
"id": "d8bf6756-5eec-4f9a-8d5c-fd22837412ae",
"field_values": {
"seq_id": {
"id": "83f8d35e-2f98-4a98-898b-ff2c5ea59178",
"value": "QUO102346",
"display_value": "QUO102346",
"type": "ID",
"metadata": null
},
"owner_id": {
"id": "75673de4-06b7-44a1-9311-97567daf328c",
"value": "dd3129cf-ff7e-4ef5-8d5b-daf027a913f1",
"display_value": "Ivan Carrillo",
"type": "reference",
"metadata": {
"full_name": "Ivan Carrillo",
"first_name": "Ivan",
"last_name": "Carrillo",
"email_address": "ivan.carrillo@freeagentsoftware.com",
"id": "dd3129cf-ff7e-4ef5-8d5b-daf027a913f1",
"display_name": "Ivan Carrillo",
"deleted": false
}
},
"quote_field8": {
"id": "fa47e9e9-34f1-430a-a35d-4f306ed7a255",
"value": "2020-10-06",
"display_value": "2020-10-06",
"type": "Date",
"metadata": null
},
"quote_field9": {
"id": "0daf29fa-deb0-4b20-8946-ebe10811275f",
"value": "2020-10-06",
"display_value": "2020-10-06",
"type": "Date",
"metadata": null
}
}
},
"children": [
{
"id": "5b1ef68c-1429-4681-a419-7fd76e103143",
"field_values": {
"sub_field0": {
"id": "648dc449-6ad9-4a68-8385-dd6c2ff0be13",
"value": "b630c9ed-62c8-4792-894f-745074fed29a",
"type": "reference"
},
"sub_field2": {
"id": "44c1fea6-a775-41a1-99b2-8dcd1cb51ef9",
"value": 1,
"display_value": 1,
"type": "number"
}
}
}
]
}
}
}Example Request - Update Record Scenario
mutation upsertCompositeEntity($entity: String!, $id: String, $field_values: JSON!, $children:[JSON!]) {
upsertCompositeEntity(entity: $entity, id: $id, field_values:$field_values,children:$children){
entity_value {
id
seq_id
field_values
}
children {
id
field_values
}
}
}Example Variables
{
"entity": "quote",
"id" : "d8bf6756-5eec-4f9a-8d5c-fd22837412ae"
"field_values": {
"quote_field8" : "2022-10-06",
"quote_field9" : "2022-10-06"
},
"children": [
{
"entity":"sub",
"field_values":{
"sub_field0" : "b630c9ed-62c8-4792-894f-745074fed29a",
"sub_field2" : 1
}
}
]
}Example Response
{
"data": {
"upsertCompositeEntity": {
"entity_value": {
"id": "d8bf6756-5eec-4f9a-8d5c-fd22837412ae",
"field_values": {
"seq_id": {
"id": "83f8d35e-2f98-4a98-898b-ff2c5ea59178",
"value": "QUO102346",
"display_value": "QUO102346",
"type": "ID",
"metadata": null
},
"owner_id": {
"id": "75673de4-06b7-44a1-9311-97567daf328c",
"value": "dd3129cf-ff7e-4ef5-8d5b-daf027a913f1",
"display_value": "Ivan Carrillo",
"type": "reference",
"metadata": {
"full_name": "Ivan Carrillo",
"first_name": "Ivan",
"last_name": "Carrillo",
"email_address": "ivan.carrillo@freeagentsoftware.com",
"id": "dd3129cf-ff7e-4ef5-8d5b-daf027a913f1",
"display_name": "Ivan Carrillo",
"deleted": false
}
},
"quote_field8": {
"id": "fa47e9e9-34f1-430a-a35d-4f306ed7a255",
"value": "2022-10-06",
"display_value": "2022-10-06",
"type": "Date",
"metadata": null
},
"quote_field9": {
"id": "0daf29fa-deb0-4b20-8946-ebe10811275f",
"value": "2022-10-06",
"display_value": "2022-10-06",
"type": "Date",
"metadata": null
}
}
},
"children": [
{
"id": "5b1ef68c-1429-4681-a419-7fd76e103143",
"field_values": {
"sub_field0": {
"id": "648dc449-6ad9-4a68-8385-dd6c2ff0be13",
"value": "b630c9ed-62c8-4792-894f-745074fed29a",
"type": "reference"
},
"sub_field2": {
"id": "44c1fea6-a775-41a1-99b2-8dcd1cb51ef9",
"value": 1,
"display_value": 1,
"type": "number"
}
}
}
]
}
}
}
Create Notes
Create a note in the activity time line of any of your records.
GraphQL Parameters
| Parameter | GraphQL Type | Description |
|---|---|---|
| entity | String | In order to know the entity object name, you can consult the object name in your Apps configuration. Required e.g “note_fa” |
| note_fa_field0 | String | Note body to post to activity, can be formatted via html. |
| note_fa_field1 | String | Id of parent entity (Source App) the activity needs to be posted on, use getEntities API to get access to entity_id. |
| task_mentions | String | Id of the parent record(Source Record) on which the activity needs to be posted to. |
| note_type | String | Id of type of note if needed, use getFieldItems API to get the UUID of the desired type |
Example Request
mutation createEntity($entity: String!, $field_values: JSON!) {
createEntity(entity: $entity, field_values: $field_values) {
entity_value {
id
seq_id
field_values
}
}
}
Example Variables
{
"entity": "note_fa",
"field_values": {
"note_fa_field0": "<div>Test Note goes here</div>",
"note_fa_field1": "ac12096d-027b-57f5-b389-93c1920222a3",
"note_fa_field2": "8f721091-5b4a-4af1-882c-8aea3cf891e6",
"note_type": "d5ba68aa-4252-4f47-a66e-64713b2f75b1",
}
}
Example Response
{
"data": {
"createEntity": {
"entity_value": {
"id": "7740cf43-48a6-4ad9-9bb3-e3e120911e39",
"seq_id": "NOT120726",
"field_values": {
"seq_id": {
"id": "3901d627-5f22-420f-aef6-9a5f7543b64e",
"value": "NOT120726",
"instanceId": "7740cf43-48a6-4ad9-9bb3-e3e120911e39",
"display_value": "NOT120726",
"formatted_value": "NOT120726",
"type": "ID",
"metadata": null
},
"note_fa_field0": {
"id": "3d282a8c-92c2-45d3-aabd-ca0b3c79e3ee",
"value": "<div>Test Note goes here 2</div>",
"instanceId": "7740cf43-48a6-4ad9-9bb3-e3e120911e39",
"display_value": "Test Note goes here",
"formatted_value": "Test Note goes here",
"type": "rich_text",
"metadata": null
},
"note_fa_field1": {
"id": "9a8c6d13-96a4-4102-9757-117243408bad",
"value": "ac12096d-027b-57f5-b389-93c1920222a3",
"instanceId": "7740cf43-48a6-4ad9-9bb3-e3e120911e39",
"display_value": "Contact",
"formatted_value": "Contact",
"type": "reference",
"metadata": {
"subtitles": [
{"field": {"text": "Contact Type", "type": "reference", "label": "Contact Type", "value": "contact_field1" }},
{"field": {"text": "Contact Owner", "type": "reference", "label": "Contact Owner", "value": "lead_owner_id" }},
{"field": {"text": "Speed to Lead", "type": "duration", "label": "Speed to Lead", "value": "virtual--speed_to_lead" }},
{"field": {"text": "First Outreach", "type": "datetimecomplete", "label": "First Outreach", "value": "virtual--first_outreach" }}
],
"default_sorts": [[ "seq_id", "desc"]],
"unique_fields": ["94a10986-b767-4b35-842d-599e9f775551"],
"form_layout_style": "792107e7-a652-4d89-9e1a-f23ffd44b269",
"enable_speed_to_lead": true,
"enable_approval_rules": false,
"set_sections_as_pages": null,
"quick_add_smart_fields": [],
"enable_assignment_rules": false,
"negative_stage_changes_list": [
null
],
"positive_stage_changes_list": [
null
]
}
},
"note_fa_field2": {
"id": "5b2f36ff-1962-4f0d-b3c4-7d96857f68ad",
"value": "8f721091-5b4a-4af1-882c-8aea3cf891e6",
"instanceId": "7740cf43-48a6-4ad9-9bb3-e3e120911e39",
"display_value": "Sharan Murali",
"formatted_value": "Sharan Murali",
"type": "reference"
},
"created_at": {
"id": "7b2ef3fb-7fde-427a-9d8a-b64829d4bbcd",
"value": "2024-12-05T06:24:58.812Z",
"instanceId": "7740cf43-48a6-4ad9-9bb3-e3e120911e39",
"display_value": "2024-12-05T06:24:58.812Z",
"formatted_value": "2024-12-05T06:24:58.812Z",
"type": "DateTimeComplete",
"metadata": null
},
"updated_at": {
"id": "54e63e0c-6b90-447b-baad-c887237537f7",
"value": "2024-12-05T06:24:58.812Z",
"instanceId": "7740cf43-48a6-4ad9-9bb3-e3e120911e39",
"display_value": "2024-12-05T06:24:58.812Z",
"formatted_value": "2024-12-05T06:24:58.812Z",
"type": "DateTimeComplete",
"metadata": null
},
"created_by": {
"id": "717db41e-5f2e-4e2d-a258-88f4bbcdb7fa",
"value": "d33b9d0c-1b5d-4ae6-a3e0-87f6e83c6f1d",
"instanceId": "7740cf43-48a6-4ad9-9bb3-e3e120911e39",
"display_value": "Sharan Murali",
"formatted_value": "Sharan Murali",
"type": "reference",
"metadata": {
"full_name": "Sharan Murali",
"first_name": "Sharan",
"last_name": "Murali",
"portrait_url": "https://freeagent-network-public.s3.us-west-2.amazonaws.com/d33b9d0c-1b5d-4ae6-a3e0-87f6e83c6f1d/1687515142455",
"email_address": "mbastida1992@gmail.com",
"extra_info": true,
"id": "d33b9d0c-1b5d-4ae6-a3e0-87f6e83c6f1d",
"display_name": "Sharan Murali",
"deleted": false
}
},
"updated_by": {
"id": "011c27d6-f1c6-466c-bbe0-a00997760918",
"value": "d33b9d0c-1b5d-4ae6-a3e0-87f6e83c6f1d",
"instanceId": "7740cf43-48a6-4ad9-9bb3-e3e120911e39",
"display_value": "Sharan Murali",
"formatted_value": "Sharan Murali",
"type": "reference",
"metadata": {
"full_name": "Sharan Murali",
"first_name": "Sharan",
"last_name": "Murali",
"portrait_url": "https://freeagent-network-public.s3.us-west-2.amazonaws.com/d33b9d0c-1b5d-4ae6-a3e0-87f6e83c6f1d/1687515142455",
"email_address": "mbastida1992@gmail.com",
"extra_info": true,
"id": "d33b9d0c-1b5d-4ae6-a3e0-87f6e83c6f1d",
"display_name": "Sharan Murali",
"deleted": false
}
},
"note_type": {
"id": "21a11cc1-a416-4699-8761-4ad2e7d6494f",
"instanceId": "7740cf43-48a6-4ad9-9bb3-e3e120911e39",
"type": "reference",
"metadata": null
}
}
}
}
}
}Create Task
Create a Task in the activity time line of any of your records.
GraphQL Parameters
| Parameter | GraphQL Type | Description |
|---|---|---|
| entity | String | In order to know the entity object name, you can consult the object name in your Apps configuration. Required e.g “task” |
| description | String | Task Title |
| fa_entity_id | String | Id of parent entity (Source App) the activity needs to be posted on, use getEntities API to get access to entity_id. |
| fa_entity_reference_id | String | Id of the parent record(Source Record) on which the activity needs to be posted to. |
| task_type | String | Id of type of task if needed, use getFieldItems API to get the UUID of the desired type |
| due_date | Date | The format can be YYYY-MM-DD or ISO Date YYYY-MM-DD:HH:MM:SS.000z |
| assigned_to | String | The id must be the UUID of the user to whom the task needs to be assigned to. In order to know the id of a user you can use the endpoint getTeamMembers |
| note | Note body for the Task to post to activity, can be formatted via html. |
Example Request
mutation createEntity($entity: String!, $field_values: JSON!) {
createEntity(entity: $entity, field_values: $field_values) {
entity_value {
id
seq_id
field_values
}
}
}Example Variables
{
"entity": "task",
"field_values": {
"fa_entity_id": "5e5ed92e-46a1-4a7d-bd53-f45956758ccd",
"fa_entity_reference_id": "21550c26-243d-4183-8b2f-55ffe04a9528",
"task_type": "280e8dcf-e9f3-44dd-97ca-8dab2711d509",
"description": "Sample Task Title",
"due_date": "2024-12-06T11:30:00.000Z",
"due_date_reminder": "52331445-4e49-4e98-9a19-a3776b9156ab",
"task_status": false,
"assigned_to": "f8d7bf51-5b3e-431c-bd62-4702d0d934ab",
"note": "Notes for the Task"
}
}Example Response
[
{
"data": {
"createEntity": {
"entity_value": {
"id": "9a785c60-0606-489a-a392-465577099a25",
"seq_id": "TAS115488",
"field_values": {
"created_at": {
"id": "718d0237-4051-4574-a821-fffd88a61128",
"value": "2024-12-05T07:12:47.650Z",
"instanceId": "9a785c60-0606-489a-a392-465577099a25",
"display_value": "2024-12-05T07:12:47.650Z",
"formatted_value": "Thursday, December 5th 2024, 12:42:47 pm",
"type": "DateTimeComplete",
"metadata": null
},
"description": {
"id": "0b1db3f2-ea8e-40eb-88e7-31650c5f7e8a",
"value": "Sample Task Title",
"instanceId": "9a785c60-0606-489a-a392-465577099a25",
"display_value": "Sample Task Title",
"formatted_value": "Sample Task Title",
"type": "text",
"metadata": null
},
"task_type": {
"id": "4c739a7b-b99f-4546-99af-8ab25eb41865",
"value": "280e8dcf-e9f3-44dd-97ca-8dab2711d509",
"instanceId": "9a785c60-0606-489a-a392-465577099a25",
"display_value": "Todo",
"formatted_value": "Todo",
"user_defined_value": "todo",
"type": "reference",
"metadata": {"custom_fields": {"icon": "fac5b80f-932a-4214-8de5-1ba77b30cd22","color": "#ff9800"},
"user_defined_value": "todo",
"extra_info": true,
"id": "280e8dcf-e9f3-44dd-97ca-8dab2711d509",
"display_name": "Todo",
"deleted": false,
"catalog_type.id": "9eca0e0e-1b76-40f3-874f-f268b5d9548e",
"catalog_type.name": "Task Type - Task",
"catalog_type.deleted": false,
"catalog_type.metadata": null
}
},
"updated_at": {
"id": "33e45dcb-68a8-4a41-9da0-ef7015805370",
"value": "2024-12-05T07:12:47.650Z",
"instanceId": "9a785c60-0606-489a-a392-465577099a25",
"display_value": "2024-12-05T07:12:47.650Z",
"formatted_value": "Thursday, December 5th 2024, 12:42:47 pm",
"type": "DateTimeComplete",
"metadata": null
},
"note": {
"id": "ca07a66f-22dc-4f79-ab6d-384a945647dc",
"value": "Notes for the Task",
"instanceId": "9a785c60-0606-489a-a392-465577099a25",
"display_value": "Notes for the Task",
"formatted_value": "Notes for the Task",
"type": "rich_text",
"metadata": null
},
"created_by": {
"id": "96e9d2e4-1093-404c-ae34-4ceaaa4e1b8f",
"value": "f8d7bf51-5b3e-431c-bd62-4702d0d934ab",
"instanceId": "9a785c60-0606-489a-a392-465577099a25",
"display_value": "Sharan Murali",
"formatted_value": "Sharan Murali",
"type": "reference",
},
"task_status": {
"id": "4270c048-b977-46fc-9cb3-b5845998abc6",
"value": false,
"instanceId": "9a785c60-0606-489a-a392-465577099a25",
"display_value": false,
"formatted_value": false,
"type": "boolean",
"metadata": null
},
"fa_entity_id": {
"id": "5935970e-3202-4040-ba48-57fcefe5c7a2",
"value": "5e5ed92e-46a1-4a7d-bd53-f45956758ccd",
"instanceId": "9a785c60-0606-489a-a392-465577099a25",
"display_value": "Contact",
"formatted_value": "Contact",
"type": "reference"
}
},
"updated_by": {
"id": "66d95b18-95e5-4940-b960-247f8ccac5fe",
"value": "f8d7bf51-5b3e-431c-bd62-4702d0d934ab",
"instanceId": "9a785c60-0606-489a-a392-465577099a25",
"display_value": "QA Clone 7",
"formatted_value": "QA Clone 7",
"type": "reference"
},
"created_by_job": {
"id": "68f03d2a-0b94-42b2-8dde-6007f24d4214",
"value": null,
"instanceId": "9a785c60-0606-489a-a392-465577099a25",
"display_value": null,
"formatted_value": null,
"type": "bot_job_info",
"metadata": null
},
"fa_entity_reference_id": {
"id": "77d91f80-5163-4a8c-b80d-40ab66bd4d0a",
"value": "21550c26-243d-4183-8b2f-55ffe04a9528",
"instanceId": "9a785c60-0606-489a-a392-465577099a25",
"display_value": "Fax Contact",
"formatted_value": "Fax Contact",
"type": "reference"
},
"due_date": {
"id": "eef77ca3-f27c-4690-b0cc-6e368423d338",
"value": "2024-12-06T11:30:00.000Z",
"instanceId": "9a785c60-0606-489a-a392-465577099a25",
"display_value": "2024-12-06T11:30:00.000Z",
"formatted_value": "Friday, December 6th 2024, 5:00:00 pm",
"type": "DateTimeComplete",
"metadata": null
},
"updated_by_job": {
"id": "6c25c56b-a7be-4d2d-9a7e-7e83548a4899",
"value": null,
"instanceId": "9a785c60-0606-489a-a392-465577099a25",
"display_value": null,
"formatted_value": null,
"type": "bot_job_info",
"metadata": null
},
"assigned_to": {
"id": "9e90ef2f-a6e4-402c-b9a6-e874346bd876",
"value": "f8d7bf51-5b3e-431c-bd62-4702d0d934ab",
"instanceId": "9a785c60-0606-489a-a392-465577099a25",
"display_value": "Sharan Murali",
"formatted_value": "Sharan Murali",
"type": "reference",
"metadata": {
"full_name": "Sharan Murali",
"first_name": "Sharan",
"last_name": "Murali",
"email_address": "sharan+8dec@gmail.com",
"extra_info": true,
"id": "f8d7bf51-5b3e-431c-bd62-4702d0d934ab",
"display_name": "Sharan Murali",
"deleted": false
}
},
"seq_id": {
"id": "1005da52-8402-4370-8bf4-400e01be9b7e",
"value": "TAS115488",
"instanceId": "9a785c60-0606-489a-a392-465577099a25",
"display_value": "TAS115488",
"formatted_value": "TAS115488",
"type": "ID",
"metadata": null
},
}
}
}
}
}
]
Connect Postman to Servis.ai
Directly execute queries using the REST client Postman. To interact with GraphQL API, use the Postman Collection. The Postman Collection comes with a configurable environment and variables that let you easily authenticate.
Install Postman
Before you can connect Postman to Servis.ai, fork/import and configure the collection. See the installation instructions.
Sign Up for Postman and Create a Workspace
Postman has two options for working with its app: desktop and web. You use the web browser app for this project.
- Sign in to your Postman account or sign up for an account.
- Select the Workspaces menu.
- Select Create Workspace.
- Name your workspace
ServisCollection. - Set Visibility to Personal.
- Click Create Workspace button.
Import Servis.ai API Collection
- Download the Servis.ai API Collection file by clicking here.
- Open Postman and navigate to the Collections tab on the left-hand side. Click on the "Import" button located in the top-left corner of the screen.
- In the "Import File" modal, click on the "Choose Files" button and select the Postman collection file you need to import. Or you can pass the URL of the file
- Once the file has been selected, click on the "Import" button to initiate the import process.
- After the import process is complete, you should see your newly imported Servis.ai API collection listed in the Collections tab.
You now have the collection ready in Postman. Let's use the collection to authorize your org and test it.
Authorize Your Org
You need to authenticate with Servis.ai to access the APIs. Authentication grants you an access token that's valid for a certain duration. Repeat this process whenever your access token expires.
- 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
- In Postman, under Collections, Servis.ai APIs should be selected.
- Be sure No Environment is selected.
- Open the Variable tab
- In the client_id row, CURRENT VALUE column, paste the Client ID value that you get in step 3.
- In the client_secret row, CURRENT VALUE column, paste the Client Secret value that you get in step 3.
- The Authorization tab should be open.
- Type should be OAuth 2.0.
- Click Get New Access Token.
- A success message appears briefly, and then you're redirected to the Manage Access Tokens dialog.
- Verify that a new access token is generated
- Click Use Token.
A Quick Connection Test
Let's verify that the connection is working.
- In Collections, select Servis.ai APIs to expand it.
- Select Queries to expand it.
- Select List Account Users.It opens in the main panel.
- Click Send.
- Verify that the status is 200 OK.
Excellent! You've successfully authenticated with Servis.ai. Now you can use other requests in the collection. The Servis.ai APIs for Postman collection that you loaded will aid you in your quest to discover the Servis.ai APIs.