Some of the most powerful features in FreeAgent 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 FreeAgent CRM API you can do everything in FreeAgent 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 as well!
Contents
API Introduction
FreeAgent CRM platform exposes a graphql API endpoint, essentially any data/operation you can access via FreeAgent 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/token
FreeAgent CRM 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.
List App Records
https://freeagent.network/api/graphql
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 FreeAgent CRM as admin navigate to:
Admin Settings > App Setup > {your_app} > Form Fields Example: ["seq_id","full_name", "contact_field01"] |
Example Request
query listEntityValues($entity: String!, $fields: [String], $order: [[String]], $limit: Int, $offset: Int, $pattern: String, $filters: [Filter]) {
listEntityValues(entity: $entity, fields: $fields, order: $order, limit: $limit, offset: $offset, pattern: $pattern, filters: $filters) {
count
entity_values {
id
seq_id
field_values
}
}
}Example Variables
{
"entity" : "contact",
"fields" : ["seq_id","full_name","contact_field14","work_email","work_phone","lead_owner_id"],
"limit" : 10,
"filters" : [
{
"field_name" : "seq_id",
"operator" : "does not contains",
"values" : ["CON106633"]
}
],
"offset" : 0,
"pattern" : "",
"order" : [["seq_id","ASC"]]
}Example Response
{
"data": {
"listEntityValues": {
"count": 1,
"entity_values": [
{
"id": "897cd2cd-1dbb-4f48-a248-5760ccf18bfa",
"seq_id": "CON106633",
"field_values": {
"work_email": {
"id": "74f6a80b-a4cd-47c7-9005-c56a57bcca43",
"value": "ivan.carrillo@softwaretp.com",
"display_value": "ivan.carrillo@softwaretp.com",
"type": "email",
"metadata": null
},
"seq_id": {
"id": "ad5fe3ed-5e14-401b-8440-f76e511783fd",
"value": "CON106633",
"display_value": "CON106633",
"type": "ID",
"metadata": null
},
"work_phone": {
"id": "7ebe2480-c5ae-4d7d-b6f6-01e273f84925",
"value": "+5213311195701",
"display_value": "+5213311195701",
"type": "phone",
"metadata": null
},
"contact_field14": {
"id": "53961155-deb9-40a8-8a38-10f13c98c6f9",
"type": "Catalog",
"metadata": null
},
"lead_owner_id": {
"id": "175c7887-1841-4e8a-a784-426c1c6137a6",
"value": "5ba14f13-eb2c-4bb0-8a76-6a84c1751cca",
"display_value": "Angel Arredondo",
"type": "immutableReference",
"metadata": {
"full_name": "Angel Arredondo",
"first_name": "Angel",
"last_name": "Arredondo",
"portrait_url": null,
"email_address": "angel.arredondo@freeagentsoftware.com",
"extra_info": true,
"id": "5ba14f13-eb2c-4bb0-8a76-6a84c1751cca",
"display_name": "Angel Arredondo",
"deleted": false
}
}
}
}
]
}
}
}List Apps
https://freeagent.network/api/graphql
GraphQL Parameters
Get a list of all the entities in your account. It's useful to quickly get the id/label of a entity without the need to open FreeAgent CRM
| 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 and Next Steps
https://freeagent.network/api/graphql
Get a list of activities from your records, such as emails, notes, calls, and meetings.
Depending on the category, you can also get Next Steps.
| Parameter | GraphQL Type | Description | ||||||
| limit | Int | Limit the number of results returned by the query. | ||||||
| parent_entity_id | String | Entity UUID. In order to know the id of the entity, you can use the endpoint "getEntities" or from FreeAgent CRM as Admin, navigate to
Admin Settings > App Setup > {your_app} > App configuration The entity Id is visible in the URL as an UUID |
||||||
| parent_reference_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 FreeAgent CRM, the URL includes the ID. | ||||||
| category | String |
Category time, there are only two valid values: NextStep and Activity.
|
||||||
| types | [String] | If you want to delimit the type of Activities/Next Steps you want to get, the possible values in the array can be:
If you want to get all of them, leave the "Types" as null:
|
||||||
| search | String | The search param will retrive all text coincidences in the description or the note of the Activity/Next Step |
List Changes on App Records
https://freeagent.network/api/graphql
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 |
| form_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. |
| fields | [String] | Every request must contain the fields you want to get. In order to know the system name of your fields, in FreeAgent CRM as admin navigate to:
Admin Settings > App Setup > {your_app} > Form Fields Example: ["seq_id","full_name", "contact_field01"] |
Example Request
query getChangesOnEntity($entity: String!, $id: String!, $from_date:Date,$limit:Int,$fields:[String]) {
getChangesOnEntity(entity: $entity, id: $id, from_date:$from_date,limit:$limit,fields:$fields){
changes{
is_create
updated_at
updated_by
field_values
}
}
}Example Variables
{
"entity": "documentation",
"id": "aa780132-9892-4fb7-9602-b7da1e1ed0cb",
"from_date" : "2020-10-22",
"limit" : 2,
"fields" : ["documentation_field28"]
}Example Response
{
"data": {
"getChangesOnEntity": {
"changes": [
{
"is_create": false,
"updated_at": "2020-10-22T19:24:22.716Z",
"updated_by": "b6d7659a-735b-4076-bc44-d2ef8c895cbe",
"field_values": {
"documentation_field28": "test"
}
},
{
"is_create": false,
"updated_at": "2020-10-22T19:24:22.716Z",
"updated_by": "dd3129cf-ff7e-4ef5-8d5b-daf027a913f1",
"field_values": {
"documentation_field28": "test"
}
}
]
}
}
}List Account Users
https://freeagent.network/oauth/token
Get a list of all users in your account, this list contains valuable information such as full name, email address, access level, roles, and more.
GraphQL Parameters
| Parameter | GraphQL Type | Description |
|---|---|---|
| active | Boolean | If the value is tru, it will retrive only the active users |
| 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 |
| show_hidden_rows | Boolean | If the active parameter is true, you can decide if you want to get only active users or both (Active and Suspended) |
Example Request
query getTeamMembers($active: Boolean, $order: [[String]], $show_hidden_rows: Boolean) {
getTeamMembers(active: $active, order: $order, show_hidden_rows: $show_hidden_rows) {
agents {
id
full_name
teamId
email_address
access_level
status
job_title
roles {
id
name
import
export
bulk_edit
bulk_delete
task_delete
is_admin
}
subteams {
id
name
description
}
}
}
} Example Variables
{
"active": true,
"order": [["full_name","ASC"]],
"show_hidden_rows": false
}Example Response
{
"data": {
"getTeamMembers": {
"agents": [
{
"id": "e9a9a29b-3b2e-4834-8c7e-d1dee6d1c6e9",
"full_name": "Adrián Madrid",
"teamId": "012dbd4d-4b3b-47ee-a7d2-0c531e88f793",
"email_address": "test@test.com",
"access_level": "team",
"status": "Active",
"job_title": "Some Job Title",
"roles": [
{
"id": "9559",
"name": "Product",
"import": false,
"export": false,
"bulk_edit": true,
"bulk_delete": false,
"task_delete": true,
"is_admin": false
}
],
"subteams": []
}
]
}
}
}List App Fields
https://freeagent.network/api/graphql
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
https://freeagent.network/api/graphql
Get a list of your choice list values based on the field id.
GraphQL Parameters
| Parameter | GraphQL Type | Description |
|---|---|---|
| fa_field_config_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. |
Example Request
query getFieldItems($fa_field_config_id:String,$pattern:String,$limit:Int) {
getFieldItems(fa_field_config_id:$fa_field_config_id,pattern:$pattern,limit:$limit){
id
name
order
}
} Example Variables
{
"fa_field_config_id": "9a4833c0-5e0c-46b6-a875-3f5be942960c",
"pattern": "",
"limit": 3
}Example Response
{
"data": {
"getFieldItems": [
{
"id": "d762cef2-7767-4cdb-9347-11e443108cf1",
"name": "Ghosted (no interactions)",
"order": 1
},
{
"id": "1c90d2ab-3cca-4681-919e-2c2152eb5b17",
"name": "Ghosted (after interactions)",
"order": 1
},
{
"id": "82c49dd8-3288-4f75-85b2-66fe72cb78f0",
"name": "Project On Hold",
"order": 1
}
]
}
}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
curl https://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
https://freeagent.network/api/graphql
Get a list with
https://freeagent.network/api/graphql
Create a 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 |
| !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
https://freeagent.network/api/graphql
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
https://freeagent.network/api/graphql
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. 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 and'ed 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" : null,
"pattern" : null
}Example Response
{
"data": {
"bulkUpdateEntities": {
"sent_to_job": null
}
}
}Delete App Record
https://freeagent.network/api/graphql
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. 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 |
| !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": "documentation",
"id": "aa780132-9892-4fb7-9602-b7da1e1ed0cb"
}Example Response
{
"data": {
"deleteEntity": {
"entity_value": {
"id": "aa780132-9892-4fb7-9602-b7da1e1ed0cb"
}
}
}
}Bulk Delete App Records
https://freeagent.network/api/graphql
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. 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" : null,
"pattern" : null
}Example Response
{
"data": {
"bulkDeleteEntities": {
"sent_to_job": null,
}
}
}Create/Update App with Lines
https://freeagent.network/api/graphql
Create or update a record, a line, 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 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 |
| 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
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"
}
}
}
]
}
}
}Create Notes
Create a note in the activity time line of any of your records.
GraphQL Parameters
| Parameter | GraphQL Type | Description |
|---|---|---|
| parent_entity_id | String | Id of parent entity the activity needs to be posted on, use getEntities API to get access to entity_id. |
| parent_reference_id | String | Id of the parent record on which the activity needs to be posted to. |
| description | String | Note body to post to activity, can be formatted via html. |
| task_mentions | [String] | Use the agent/user ID as value to generate a mention notification. |
Example Request
mutation addTask($parent_entity_id: String, $parent_reference_id: String, $note: String, $type: String, $status: String, $closed_at: Date,$task_mentions:[String]) {
addTask(parent_entity_id: $parent_entity_id,note:$note, parent_reference_id: $parent_reference_id,type: $type, status: $status, closed_at: $closed_at,task_mentions:$task_mentions) {
id
note
closed_at
}
} Example Variables
{
"parent_entity_id": "f546b246-18c3-4494-b870-6f299f2253f5",
"parent_reference_id": "2b75c70a-0be3-4405-885e-5faa4b8bf8ec",
"note": "Test Note",
"type": "Note",
"closed_at": "2020-11-03T22:55:43.146Z",
"status": "closed",
"task_mentions": ["dd3129cf-ff7e-4ef5-8d5b-daf027a913f1"]
}Example Response
{
"data": {
"addTask": {
"id": "b4b3ef6f-a268-4f03-abe2-8eee83f94e85",
"note": "Test Note",
"closed_at": "2020-11-03T22:55:43.146Z"
}
}
}
