NAV

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 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

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"
}

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 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.

Rate Limits

Integrations API calls are subject to the limit of 50 requests per 10 seconds window. Please reach out to Support team in case you need this limit changed.

Integrations exceeding the limits will receive error responses with a 429 response code.

It is recommended to implement an exponential backoff approach on 429 response code.

Error Handling

API errors typically include the errors attribute in graphql response payload indicating the reason for 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

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
                            }
                        }
                    }
                }
            ]
        }
    }
}

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 Acconts

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
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:

[ { "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

Field Type Operators
Non Date Fields contains does not contains equals not equals starts with
Date Fields after before between

Lines

If your app contain lines, the way to get the app lines is filtering by "parent_entity_reference_id" in the following way:

[ { "field_name" : "parent_entity_reference_id", "value" : ["parent app id"] } ]

Notes:

  • In this case is not necessary to use an operator
  • The "entity" parameter must be the line app name

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"]

List Apps

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"
            }
        ]
    }
}

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 GraphQL Type Description
alphabetical_order Boolean To get the list ordered alphabetically

List Activities & Next Steps

Example Request

query getTasks($parent_entity_id: String, $parent_reference_id: String, $limit: Int, $category: String, $types: [String], $search: String) {
    getTasks(parent_entity_id: $parent_entity_id, parent_reference_id: $parent_reference_id, limit: $limit, category: $category, types: $types, search: $search) {
      tasks {
        id
        note
        owner {
          id
          full_name
        }
        description
        to
        from
        subject
      }
    }
  }

Example Variables

{
    "limit": 1,
    "parent_entity_id": "ac12096d-027b-57f5-b389-93c1920222a3",
    "parent_reference_id": "897cd2cd-1dbb-4f48-a248-5760ccf18bfa",
    "category": "Activity",
    "types": ["Email"],
    "search": null
}

Example Response

{
    "data": {
      "getTasks": {
        "tasks": [
          {
            "id": "0f39c219-12a0-40f8-b2b2-556a24fa7bd1",
            "note": "96 ...",
            "owner": null,
            "description": "Email to Ivan Andres Carrillo Bustos",
            "to": "ivan andres carrillo bustos , ivan.carrillo@softwaretp.com",
            "from": "ivan.carrillo@freeagentsoftware.com",
            "subject": "test"
          }
        ]
      }
    }

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.

GraphQL Parameters

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.

Category Description
Activity All the activities you see in the activity time line of your record
NexSteps All open next steps in you record
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:
  • Email
  • Phone
  • Event
  • Task
  • Note
  • Attachment

If you want to get all of them, leave the "Types" as null:

"types" : 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

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"
                    }
                }
            ]
        }
    }
}

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"]

List Account Users

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": []
                }
            ]
        }
    }
}

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)

List App Fields

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
            }
        ]
    }
}

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)

List Choice List Values

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
            }
        ]
    }
}

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.

Mutations

Mutation queries modify data in your account, mutations can be used to insert, update or delete data.

Create App Record

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

https://freeagent.network/api/graphql

Get a list with

{
    "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
                    },
                    ...
                }
            }
        }
    }
}

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

Update App Record

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
                        }
                    }
                }
            }
        }
    }
}

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

Bulk Update App Records

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
      }
    }
}

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

Field Type Operators
Non Date Fields contains does not contains equals not equals starts with
Date Fields after before between

Delete App Record

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"
            }
        }
    }
}

https://freeagent.network/api/graphql

Delete one record from 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

Bulk Delete App Records

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,
        }
    }
}

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
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

Field Type Operators
Non Date Fields contains does not contains equals not equals starts with
Date Fields after before between

Create/Update App With Lines

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"
                        }
                    }
                }
            ]
        }
    }
}

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:
  • entity
  • field_values

Create Notes

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"
      }
    }
  }

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.

Deprecated

In this section, you will find deprecated endpoints. We are still providing support to these endpoints but we highly recommend you to migrate to the new ones.

The support provided to the following endpoints is limited and is highly possible that at some point stop working properly.

In this section, we will also provide you an alternative to the new ones.

Contact List

Example Request

query getLeadsWithCount($limit:Int,$offset:Int,$order:[[String]],$pattern:String,$filters:[Filter]) {
    getLeadsWithCount(limit:$limit,offset:$offset,order:$order,pattern:$pattern,filters:$filters){
      count
      leads {
        id
        seq_id
        owner_id
        full_name
        work_email
        mobile_phone
        logo {
          id
          name
        }
        lead_status_id
        custom_fields {
          value
          display_value
          field_name
        }
      }
      error
    }
  }

Example Variables

{
    "limit": 1,
    "offset": 0,
    "order": [["created_at","DESC"]]
}

Example Response

{
    "data": {
        "getLeadsWithCount": {
            "count": 14156,
            "leads": [
                {
                    "id": "cff904c5-abc2-401a-b3e1-a6c3937eae9b",
                    "seq_id": "CON122742",
                    "owner_id": "b73e6895-0951-4c02-9d17-0cac9c00411b",
                    "full_name": "Amanda Anderson",
                    "work_email": "example@example.com",
                    "mobile_phone": "33333333333",
                    "logo": {
                        "id": "f04d0b4e-363c-4a67-9786-6bd0c1949431",
                        "name": "test"
                    },
                    "lead_status_id": "53774c02-88c4-4d4d-8ca0-2a5f7a2da036",
                    "custom_fields": [
                        {
                            "value": "0e10178b-63a6-4080-95b9-1e6f1e561bc8",
                            "display_value": "IT",
                            "field_name": "contact_field45"
                        },
                        {
                            "value": "6e06cd5b-90b0-41f8-b54a-1ee4d87d949e",
                            "display_value": "Maintenance & Field Service",
                            "field_name": "contact_field14"
                        },
                        {
                            "value": "b73e6895-0951-4c02-9d17-0cac9c00411b",
                            "display_value": "Margaret Garry",
                            "field_name": "contact_field44"
                        }
                    ]
                }
            ],
            "error": null
        }
    }
}

https://freeagent.network/api/graphql

Get a list of your out-of-the-box contacts app.

Alternative Endpoint: listEntityValues

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
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:

[ { "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

Field Type Operators
Non Date Fields contains does not contains equals not equals starts with
Date Fields after before between

Contact by ID

Example Request

query getLead($id: String!) {
    getLead(id: $id) {
        id
        seq_id
        owner_id
        full_name
        work_email
        mobile_phone
        logo {
          id
          name
        }
        lead_status_id
        custom_fields {
          value
          display_value
          field_name
        }
      }
  }

Example Variables

{
    "id": "cff904c5-abc2-401a-b3e1-a6c3937eae9b"
}
{
    "data": {
        "getLead": {
            "id": "cff904c5-abc2-401a-b3e1-a6c3937eae9b",
            "seq_id": "CON122742",
            "owner_id": "b73e6895-0951-4c02-9d17-0cac9c00411b",
            "full_name": "Amanda Anderson",
            "work_email": "test@test.com",
            "mobile_phone": "33333333",
            "logo": {
                "id": "f04d0b4e-363c-4a67-9786-6bd0c1949431",
                "name": "test"
            },
            "lead_status_id": "53774c02-88c4-4d4d-8ca0-2a5f7a2da036",
            "custom_fields": [
                {
                    "value": "6e06cd5b-90b0-41f8-b54a-1ee4d87d949e",
                    "display_value": "Maintenance & Field Service",
                    "field_name": "contact_field14"
                },
                {
                    "value": "b73e6895-0951-4c02-9d17-0cac9c00411b",
                    "display_value": "Margaret Garry",
                    "field_name": "contact_field44"
                },
                {
                    "value": "0e10178b-63a6-4080-95b9-1e6f1e561bc8",
                    "display_value": "IT",
                    "field_name": "contact_field45"
                },
                {
                    "value": "0",
                    "display_value": "0",
                    "field_name": "contact_field49"
                },
                {
                    "value": "Fri Oct 30 2020 23:20:15 GMT+0000 (Coordinated Universal Time)",
                    "display_value": "Fri Oct 30 2020 23:20:15 GMT+0000 (Coordinated Universal Time)",
                    "field_name": "contact_field21"
                }
            ]
        }
    }
}

https://freeagent.network/api/graphql

Get a specific contact by id

Alternative Endpoint: listEntityValues

GraphQL Parameters

Parameter GraphQL Type Description
id String Contact Id to lookup

Deals List

Example Request

query getDealsWithCount($limit:Int,$offset:Int,$order:[[String]],$pattern:String,$filters:[Filter]) {
    getDealsWithCount(limit:$limit,offset:$offset,order:$order,pattern:$pattern,filters:$filters){
      count
      deals {
        id
        seq_id
        owner_id
        name
        amount
        status
        forecast_category {
          id
          name
        }
        logo {
          id
          name
        }
        custom_fields {
          value
          display_value
          field_name
        }
      }
    }
  }  

Example Variables

{
    "limit": 1,
    "offset": 0,
    "order": [["created_at","DESC"]]
}

Example Response

{
    "data": {
        "getDealsWithCount": {
            "count": 2073,
            "deals": [
                {
                    "id": "dd7b1a31-a7b7-4bb2-a8ad-dfc4ccb8eb96",
                    "seq_id": "OPP105941",
                    "owner_id": "af59c67d-cba3-4306-b116-5451ea26dc17",
                    "name": "Caster - Pro x 15",
                    "amount": 13500,
                    "status": "Open",
                    "forecast_category": null,
                    "logo": {
                        "id": "7481e3c7-fccf-4143-998c-006882e0df98",
                        "name": "Caster Technology Corporation"
                    },
                    "custom_fields": [
                        {
                            "value": "5d933600-5f27-4b53-bae7-47c7c8b475e0",
                            "display_value": "New Business",
                            "field_name": "deal_field39"
                        },
                        {
                            "value": "28bbb8a0-2b1c-48dd-bd83-a86f48cc0fb7",
                            "display_value": "David Elles",
                            "field_name": "deal_field15"
                        },
                        {
                            "value": "975b52a4-cb12-4498-9631-651410ddaece",
                            "display_value": "Manufacturing",
                            "field_name": "deal_field70"
                        },
                        {
                            "value": "2cb6bd4a-5a6e-476c-827d-8a47d19e8103",
                            "display_value": "11 to 20 users",
                            "field_name": "deal_field13"
                        },
                        {
                            "value": "2020-10-30T22:35:06.588Z",
                            "display_value": "2020-10-30T22:35:06.588Z",
                            "field_name": "deal_field8"
                        },
                        {
                            "value": "6a1ca2df-21b8-4d72-8e1f-6b3ad8795af3",
                            "display_value": "Pipeline (5%)",
                            "field_name": "deal_field45"
                        },
                        {
                            "value": "b73e6895-0951-4c02-9d17-0cac9c00411b",
                            "display_value": "Margaret Garry",
                            "field_name": "deal_field36"
                        },
                        {
                            "value": "2020-11-02T15:41:51.000Z",
                            "display_value": "2020-11-02T15:41:51.000Z",
                            "field_name": "deal_field38"
                        },
                        {
                            "value": "2020-10-30T22:35:06.588Z",
                            "display_value": "2020-10-30T22:35:06.588Z",
                            "field_name": "deal_field40"
                        },
                        {
                            "value": "608e46fb-6bdb-42ed-875f-b15607730e0c",
                            "display_value": "Professional",
                            "field_name": "deal_field20"
                        },
                        {
                            "value": "86a7bef1-719e-42f1-a2bd-776e8588b8b6",
                            "display_value": "Guided",
                            "field_name": "deal_field29"
                        }
                    ]
                }
            ]
        }
    }
}

https://freeagent.network/api/graphql`

Get a list of your out-of-the-box deals/opportunities app.

Alternative Endpoint: listEntityValues

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
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:

[ { "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

Field Type Operators
Non Date Fields contains does not contains equals not equals starts with
Date Fields after before between

Deal by ID

Example Request

query getDeal($id: String!) {
    getDeal(id: $id) {
            amount  
        id
        seq_id
        owner_id
        name
        logo {
          id
          name
        }
        status
            forecast_category{
          id
          name
        }
        custom_fields {
          value
          display_value
          field_name
        }
      }
  }

Example Variables

{
    "id": "dd7b1a31-a7b7-4bb2-a8ad-dfc4ccb8eb96"
}

Example Response

{
    "data": {
        "getDeal": {
                "id": "dd7b1a31-a7b7-4bb2-a8ad-dfc4ccb8eb96",
                "seq_id": "OPP105941",
                "owner_id": "af59c67d-cba3-4306-b116-5451ea26dc17",
                "name": "Caster - Pro x 15",
                "amount": 13500,
                "status": "Open",
                "forecast_category": null,
                "logo": {
                    "id": "7481e3c7-fccf-4143-998c-006882e0df98",
                    "name": "Caster Technology Corporation"
                },
                "custom_fields": [
                    {
                        "value": "5d933600-5f27-4b53-bae7-47c7c8b475e0",
                        "display_value": "New Business",
                        "field_name": "deal_field39"
                    },
                    {
                        "value": "28bbb8a0-2b1c-48dd-bd83-a86f48cc0fb7",
                        "display_value": "David Elles",
                        "field_name": "deal_field15"
                    },
                    {
                        "value": "975b52a4-cb12-4498-9631-651410ddaece",
                        "display_value": "Manufacturing",
                        "field_name": "deal_field70"
                    },
                    {
                        "value": "2cb6bd4a-5a6e-476c-827d-8a47d19e8103",
                        "display_value": "11 to 20 users",
                        "field_name": "deal_field13"
                    },
                    {
                        "value": "2020-10-30T22:35:06.588Z",
                        "display_value": "2020-10-30T22:35:06.588Z",
                        "field_name": "deal_field8"
                    },
                    {
                        "value": "6a1ca2df-21b8-4d72-8e1f-6b3ad8795af3",
                        "display_value": "Pipeline (5%)",
                        "field_name": "deal_field45"
                    },
                    {
                        "value": "b73e6895-0951-4c02-9d17-0cac9c00411b",
                        "display_value": "Margaret Garry",
                        "field_name": "deal_field36"
                    },
                    {
                        "value": "2020-11-02T15:41:51.000Z",
                        "display_value": "2020-11-02T15:41:51.000Z",
                        "field_name": "deal_field38"
                    },
                    {
                        "value": "2020-10-30T22:35:06.588Z",
                        "display_value": "2020-10-30T22:35:06.588Z",
                        "field_name": "deal_field40"
                    },
                    {
                        "value": "608e46fb-6bdb-42ed-875f-b15607730e0c",
                        "display_value": "Professional",
                        "field_name": "deal_field20"
                    },
                    {
                        "value": "86a7bef1-719e-42f1-a2bd-776e8588b8b6",
                        "display_value": "Guided",
                        "field_name": "deal_field29"
                    }
                ]
            }
        }
    }

https://freeagent.network/api/graphql

Get a specific deal by id

Alternative Endpoint: listEntityValues

GraphQL Parameters

Parameter GraphQL Type Description
id String Contact Id to lookup

Accounts list

Example Request

query logosWithCount($limit:String,$offset:String,$order:[[String]],$pattern:String,$filters:[Filter]) {
    logosWithCount(limit:$limit,offset:$offset,order:$order,pattern:$pattern,filters:$filters){
      count
      logos {
        id
        seq_id
        name
        status
        owner{
          full_name
          id
        }
        custom_fields {
          value
          display_value
          field_name
        }
      }
    }
  }

Example Variables

{
    "limit": 1,
    "offset": 0,
    "order": [["created_at","DESC"]]
}

Example Response

{
    "data": {
        "logosWithCount": {
            "count": 12880,
            "logos": [
                {
                    "id": "9efb7dab-996b-4302-a585-b944e0277259",
                    "seq_id": "ACC116866",
                    "name": "Bank of America",
                    "status": null,
                    "owner": null,
                    "custom_fields": [
                        {
                            "value": "88f95f7d-0f57-44b3-9116-fe321665cec1",
                            "display_value": "Ramesh Kalapatapu",
                            "field_name": "logo_field43"
                        },
                        {
                            "value": "1fe4e2d0-c2af-4b7e-abad-9c10d506014b",
                            "display_value": "Re-Market",
                            "field_name": "logo_field49"
                        },
                        {
                            "value": "950cfd0d-5153-4b56-bee2-652add027e42",
                            "display_value": "SEO",
                            "field_name": "logo_field62"
                        },
                        {
                            "value": "b73e6895-0951-4c02-9d17-0cac9c00411b",
                            "display_value": "Margaret Garry",
                            "field_name": "logo_field46"
                        }
                    ]
                }
            ]
        }
    }
}

https://freeagent.network/api/graphql`

Get a list of your out-of-the-box accounts app.

Alternative Endpoint: listEntityValues

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
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:

[ { "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

Field Type Operators
Non Date Fields contains does not contains equals not equals starts with
Date Fields after before between

Account ID

Example Request

query logo($id: String!) {
    logo(id: $id) {
      id
      seq_id
      name
      status
      owner {
        full_name
        id
      }
      custom_fields {
        value
        display_value
        field_name
      }
    }
  }

Example Variables

{
    "id": "6672ebd1-c48a-4302-90d3-f3b7ad31ed5b"
}

Example Response

{
    "data": {
        "logo": {
            "id": "6672ebd1-c48a-4302-90d3-f3b7ad31ed5b",
            "seq_id": "ACC116867",
            "name": "Tanzania",
            "status": null,
            "owner": null,
            "custom_fields": [
                {
                    "value": "gimail.com",
                    "display_value": "gimail.com",
                    "field_name": "logo_field31"
                },
                {
                    "value": "linkedin.com/",
                    "display_value": "linkedin.com/",
                    "field_name": "logo_field35"
                },
                {
                    "value": "1041480",
                    "display_value": "1041480",
                    "field_name": "logo_field36"
                },
                {
                    "value": "a27824ed-465a-4434-a111-b181dc036db6",
                    "display_value": "Jeremiah Ngulwa Kessy",
                    "field_name": "logo_field43"
                },
                {
                    "value": "cd7b769a-2097-48ed-9e74-d9151a0c81e5",
                    "display_value": "Google Search",
                    "field_name": "logo_field45"
                },
                {
                    "value": "756a8530-953b-4f85-8a84-80e3db28adf8",
                    "display_value": "SAL",
                    "field_name": "logo_field49"
                },
                {
                    "value": "ecf8ecb0-346f-42c7-be48-6a2861c44768",
                    "display_value": "SEM",
                    "field_name": "logo_field62"
                },
                {
                    "value": "b73e6895-0951-4c02-9d17-0cac9c00411b",
                    "display_value": "Margaret Garry",
                    "field_name": "logo_field46"
                }
            ]
        }
    }
}

https://freeagent.network/api/graphql

Get a specific account by ID

Alternative Endpoint: listEntityValues

GraphQL Parameters

Parameter GraphQL Type Description
id String Contact Id to lookup

Custom Object List

Example Request

query getEntityValuesWithCount($entity:String!,$limit:Int,$offset:Int,$order:[[String]],$pattern:String,$filters:[Filter]) {
    getEntityValuesWithCount(entity:$entity,limit:$limit,offset:$offset,order:$order,pattern:$pattern,filters:$filters){
      count
      values{
        faEntity {
          id
          name
          display_name
        }
        id
        seq_id
        custom_fields{
          value
          display_value
          field_name
        }
      }
    }
  }

Example Variables

{
    "entity": "ticket",
      "limit": 1,
      "offset": 0,
      "order": [["created_at","DESC"]]
  }

Example Response

{
    "data": {
        "getEntityValuesWithCount": {
            "count": 5233,
            "values": [
                {
                    "faEntity": {
                        "id": "70038b50-8b2a-479e-aa89-ed375ec6fbc7",
                        "name": null,
                        "display_name": null
                    },
                    "id": "8ebcd3a8-2188-411f-a7f8-028c9912f856",
                    "seq_id": "TIC108367",
                    "custom_fields": [
                        {
                            "value": "Add PWA JSON Manifest",
                            "display_value": "Add PWA JSON Manifest",
                            "field_name": "ticket_field0"
                        },
                        {
                            "value": "6a1acfab-6e1a-407b-bd1d-b7ec0c507da0",
                            "display_value": "Miguel Palomera",
                            "field_name": "ticket_field6"
                        },
                        {
                            "value": "e77da363-5051-48d1-8c7c-eb3a35477a37",
                            "display_value": "Phone",
                            "field_name": "ticket_field21"
                        },
                        {
                            "value": "f5f78452-9381-49da-83a4-122fbe036a87",
                            "display_value": "Jimmy Nguyen",
                            "field_name": "ticket_field1"
                        },
                        {
                            "value": "7a918e36-e5b5-491e-97b4-c67c34622f2e",
                            "display_value": "Feature Request (Enhancement)",
                            "field_name": "ticket_field3"
                        },
                        {
                            "value": "c0e78d87-adf8-4664-baf7-ee2d71a7376c",
                            "display_value": "UI",
                            "field_name": "ticket_field9"
                        },
                        {
                            "value": "c6bebab8-b582-4ce4-8dd8-b101ae441e03",
                            "display_value": "High",
                            "field_name": "ticket_field5"
                        },
                        {
                            "value": "1124b9d2-430a-44d9-b0f6-2182f1d0033a",
                            "display_value": "Open",
                            "field_name": "ticket_field4"
                        }
                    ]
                }
            ]
        }
    }
}

https://freeagent.network/api/graphql`

Get a list of your custom apps.

Alternative Endpoint: listEntityValues

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
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:

[ { "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

Field Type Operators
Non Date Fields contains does not contains equals not equals starts with
Date Fields after before between

Custom Object by ID

Example Request

query getEntityValuesWithCount($id: String, $entity: String!) {
    getEntityValuesWithCount(id: $id, entity: $entity) {
      count
      values {
        faEntity {
          id
          name
          display_name
        }
        id
        seq_id
        custom_fields {
          value
          display_value
          field_name
        }
      }
    }
  }  

Example Variables

{
    "entity": "documentation",
    "id": "d0a88ee7-1de9-4040-a67a-3a3ffb7e54f9"
  }

Example Response

{
    "data": {
      "getEntityValuesWithCount": {
        "count": 1,
        "values": [
          {
            "faEntity": {
              "id": "f546b246-18c3-4494-b870-6f299f2253f5",
              "name": null,
              "display_name": null
            },
            "id": "d0a88ee7-1de9-4040-a67a-3a3ffb7e54f9",
            "seq_id": "DOC101058",
            "custom_fields": [
              {
                "value": "360050198931",
                "display_value": "360050198931",
                "field_name": "documentation_field28"
              },
              {
                "value": "Calculating the Cycle Time of a Deal",
                "display_value": "Calculating the Cycle Time of a Deal",
                "field_name": "documentation_field18"
              },
              {
                "value": "2020-10-15T02:30:08.568Z",
                "display_value": "2020-10-15T02:30:08.568Z",
                "field_name": "created_at"
              },
              {
                "value": "a405b113-9d0a-43c1-abf0-a7ba413057b7",
                "display_value": "FAQ",
                "field_name": "documentation_field26"
              },
              {
                "value": "DOC101058",
                "display_value": "DOC101058",
                "field_name": "seq_id"
              },
            ]
          }
        ]
      }
    }
  }

https://freeagent.network/api/graphql`

Get a specific custom record by ID

Alternative Endpoint: listEntityValues

GraphQL Parameters

Parameter GraphQL Type Description
id String Contact Id to lookup
!entity String In order to know the entity object name, you can consult the object name in your Apps configuration.

Required

Create Contact

Example Request

mutation addLead($first_name: String, $last_name: String) {
    addLead(first_name: $first_name, last_name: $last_name) {
      lead{
        id
        full_name
      }
        error
    }
  }

Example Variables

{
    "first_name": "test",
    "last_name":  "test"
}

Example Response

{
    "data": {
      "addLead": {
        "lead": {
          "id": "d992fabd-d94d-4c98-85f8-82ac38599d15",
          "full_name": "test test"
        },
        "error": null
      }
    }
  }

https://freeagent.network/api/graphql`

Create a new contact record

Alternative Endpoint: createEntity

Graphql Parameters can be used also as fields in the request to get the desired fields from within the response.

GraphQL Parameters

Parameter GraphQL Type Description
first_name String First name of contact.
last_name String Last name of contact.
buying_power Int Buying power of contact, valid values 0, 1, 2 and 3.
logo_id String ID of Account to associate the contact being created.
logo_name String Name of the new account contact is associated with, if specified will create a new account if there is no exact match.
location_name String Address of contact.
portrait_url String Portrait image url to use for the contact.
work_phone String Work Phone of contact.
home_phone String Home Phone of contact.
mobile_phone String Mobile Phone of contact.
personal_email String Personal Email of contact.
work_email String Work email of contact.
linkedIn String Linkedin url of contact.
facebook String Facebook url of contact.
twitter String Twitter url of contact.
lead_score Int Lead score of the contact.
lead_status_id String Id of the existing lead status, use getFieldItems API to lookup id based on status name.
lead_source_id String Id of the existing lead source, use getFieldItems API to lookup id based on source name.
lead_owner_id String agent id to set the owner of the contact created.
industry_id String Id of the existing industry, use getFieldItems API to lookup id based on industry name.
custom_fields [[String]] 2d Array of field/value pairs to set custom fields on the contact being created. eg: [["contact_field1", "Text"], ["contact_field4", "a12d8598-1f78-42e3-ab3d-a83f608b37e7"]]

Update/Delete Contact

Example Request

mutation updateLeadFields($recordId:String!,$values:[updateInstanceBody]!) {
    updateLeadFields(recordId: $recordId, values: $values) {
      id
      seq_id
      full_name
      custom_fields {
        field_name
        value
      }
      }
  }

Example Variables

{
    "recordId": "83efbbae-c8eb-47ac-afea-161e951f7564",
    "values": [
      {
        "field_name": "first_name",
        "value": "Ivan Andres"
      }
    ]
  }

Example Response

{
    "data": {
      "addLead": {
        "lead": {
            "id": "83efbbae-c8eb-47ac-afea-161e951f7564",
            "seq_id": "CON122470",
            "full_name": "Ivan Andres Carrillo"
            custom_fields : null
        }
      }
    }
  }

Update or delete a contact

Alternative Endpoints: updateEntity and deleteEntity

Graphql Parameters can be used also as fields in the request to get the desired fields from within the response.

GraphQL Parameters

Parameter GraphQL Type Description
recordId String Id of the contact being updated.
values [{field_name: "String", value: "String"}] array of field_name and value pairs, set "deleted" field to "true" to delete the record.

Create Deal

Example Request

mutation addDeal($name: String, $amount: Float) {
    addDeal(name: $name, amount: $amount) {
      id
      seq_id
      name
      amount
      owner {
        id
        full_name
      }
      custom_fields {
        field_name
        value
        display_value
      }
    }
  }

Example Variables

{
    "name":"test",
    "amount":10
}

Example Response

{
    "data": {
      "addDeal": {
        "id": "f0276976-8e71-4ca2-b3e6-693d8e1c7dd0",
        "seq_id": "OPP105974",
        "name": "Test",
        "amount": 10,
        "owner": null,
        "custom_fields": null
      }
    }
  }

https://freeagent.network/api/graphql

Create a new deal record

Alternative Endpoint: createEntity

Graphql Parameters can be used also as fields in the request to get the desired fields from within the response.

GraphQL Parameters

Parameter GraphQL Type Description
name String name of the deal
location_name String set location of deal
logoname String Create and set account for the deal
logo_id String existing account ID to associate for the deal
win_probability Int win probability percentage 0-100
amount Float Deal amount
close_date Date Expected close date of the deal
sales_stage_id String Id of sales stage to associate with the deal
type_id String Id of deal type to associate with the deal
lead_source_id String Id of lead_source to associate with the deal
forecast_category_id String Id of forcast category to associate with the deal
owner_id String agent id to set the owner of the deal created.
status_id String Id of forcast category to associate with the deal.
custom_fields [[String]] 2d Array of field/value pairs to set custom fields on the contact being created. eg: [["deal_field1", "Text"], ["deal_field4", "a12d8598-1f78-42e3-ab3d-a83f608b37e7"]]

Update/Delete Deal

Example Request

mutation updateDealFields($recordId: String!, $values: [updateInstanceBody]!) {
    updateDealFields(recordId: $recordId, values: $values) {
      id
      seq_id
      name
      amount
      custom_fields {
        field_name
        value
      }
    }
  }  

Example Variables

{
    "recordId": "83efbbae-c8eb-47ac-afea-161e951f7564",
    "values": [
      {
        "field_name": "name",
        "value": "Test"
      }
    ]
  }

Example Response

{
    "data": {
      "updateDealFields": {
        "id": "8734ce29-96c3-42a9-a51e-f29ab3d398d8",
        "seq_id" : "OPP105974",
        "name": "Sample Deal",
        "custom_fields": [
          {
            "field_name": "name",
            "value": "Test"
          }
        ]
      }
    }
  }

https://freeagent.network/api/graphql`

Update or delete a deal

Alternative Endpoints: updateEntity and deleteEntity

Graphql Parameters can be used also as fields in the request to get the desired fields from within the response.

GraphQL Parameters

Parameter GraphQL Type Description
recordId String Id of the dea; being updated.
values [{field_name: "String", value: "String"}] array of field_name and value pairs, set "deleted" field to "true" to delete the record.

Create Account

Example Request

mutation addLogo($name: String, $website: String) {
    addLogo(name: $name, website: $website) {
      id
      seq_id
      name
      website
      custom_fields {
        field_name
        value
      }
    }
  }

Example Variables

{
    "name": "test",
    "website": "https://www.google.com"
  }

Example Response

{
    "data": {
      "addLogo": {
        "id": "02cbd40d-1618-47a1-bf50-46514ca27e5b",
        "seq_id": "ACC116870",
        "name": "Text",
        "website": "https://www.google.com",
        "custom_fields": null
      }
    }
  }

Create a new account record

Alternative Endpoint: createEntity

Graphql Parameters can be used also as fields in the request to get the desired fields from within the response.

GraphQL Parameters

Parameter GraphQL Type Description
name String Name of the account
logo_src String Logo image to use for account
hq_location String Location of account
industry_catalog_id String Industry of account
website String Website url
num_employees String Number of employees for the company
revenue String Revenue of the company
summary String Description of the account
business_phone String Accounts contact phone number
owner_id String Agent Id owning the account
custom_fields [[String]] 2d Array of field/value pairs to set custom fields on the contact being created. eg: [["logo_field1", "Text"], ["logo_field4", "a12d8598-1f78-42e3-ab3d-a83f608b37e7"]]

Update/Delete Account

Example Request

mutation updateLogoFields($recordId: String!, $values: [updateInstanceBody]!) {
    updateLogoFields(recordId: $recordId, values: $values) {
      id
      seq_id
      name
      website
      custom_fields {
        field_name
        value
      }
    }
  }

Example Variables

{
    "recordId": "fc4e6a5b-3c17-4a74-a9be-f7e7618fab5b",
    "values": [
      {
        "field_name": "name",
        "value": "test"
      }
    ] 
  }

Example Response

{
    "data": {
      "getDeal": {
        "id": "02cbd40d-1618-47a1-bf50-46514ca27e5b",
        "seq_id": "ACC116870",
        "name": "Text",
        "website": "https://www.google.com",
        "custom_fields": null
      }
    }
  }

https://freeagent.network/api/graphql

Update or delete a account

Alternative Endpoints: updateEntity and deleteEntity

Graphql Parameters can be used also as fields in the request to get the desired fields from within the response.

GraphQL Parameters

Parameter GraphQL Type Description
recordId String Id of the account being updated.
values [{field_name: "String", value: "String"}] array of field_name and value pairs, set "deleted" field to "true" to delete the record.

Create Custom Record

Example Request

mutation addEntityValue($entity: String!, $custom_fields: [[String]]) {
    addEntityValue(entity: $entity, custom_fields: $custom_fields) {
      id
      seq_id
      custom_fields {
        value
        display_name
        field_name
      }
    }
  }

Example Variables

{
    "entity": "documentation",
    "custom_fields": [
      ["documentation_field18","test"]
    ]
  }

Example Response

{
    "data": {
      "addEntityValue": {
        "id": "2b75c70a-0be3-4405-885e-5faa4b8bf8ec",
        "seq_id": "DOC101123",
        "custom_fields": {
            "value" : "test"
            "display_name" : "Title",
            "field_name" : "documentation_field18"
        }
      }
    }
  }

https://freeagent.network/api/graphql

Create a new custom app record

Alternative Endpoint: createEntity

GraphQL Parameters

Parameter GraphQL Type Description
entity String The custom object name to create record on.
custom_fields [[String]] 2d Array of field/value pairs to set custom fields on the contact being created. eg: [["documentation_field1", "Text"], ["documentation_field4", "a12d8598-1f78-42e3-ab3d-a83f608b37e7"]]

Update/Delete Custom Record

Example Request

mutation updateEntityValueFields($recordId: String!, $values: [updateInstanceBody]!) {
    updateEntityValueFields(recordId: $recordId, values: $values) {
      id
      seq_id
      custom_fields {
        value
        display_name
        field_name
      }
    }
  }

Example Variables

{
    "recordId": "2b75c70a-0be3-4405-885e-5faa4b8bf8ec",
     "values":[
       {
         "field_name": "documentation_field18",
         "value": "Test 2"
       }
     ]
   }

Example Response

{
    "data": {
      "addEntityValue": {
        "id": "2b75c70a-0be3-4405-885e-5faa4b8bf8ec",
        "seq_id": "DOC101123",
        "custom_fields": {
            "value" : "test"
            "display_name" : "Title",
            "field_name" : "documentation_field18"
        }
      }
    }
  }

Update or delete a custom app record

Alternative Endpoints: updateEntity and deleteEntity

GraphQL Parameters

Parameter GraphQL Type Description
recordId String Id of the custom object being updated.
values [{field_name: "String", value: "String"}] array of field_name and value pairs, set "deleted" field to "true" to delete the record.

Create Next Step

Example Request

mutation addTask($parent_entity_id: String, $parent_reference_id: String, $assigned_to: [String], $description: String, $note: String, $type: String, $due_date: Date, $status: String, $all_day: Boolean) {
    addTask(parent_entity_id: $parent_entity_id, parent_reference_id: $parent_reference_id, assigned_to: $assigned_to, description: $description, note: $note, type: $type, due_date: $due_date, status: $status, all_day: $all_day) {
      id
      note
      description
      owner {
        id
        full_name
      }
    }
  }

Example Variables

{
    "parent_entity_id": "f546b246-18c3-4494-b870-6f299f2253f5",
    "parent_reference_id": "2b75c70a-0be3-4405-885e-5faa4b8bf8ec",
    "assigned_to": ["dd3129cf-ff7e-4ef5-8d5b-daf027a913f1"],
    "description": "Description",
    "note": "Note",
    "type": "Task",
    "due_date": "2020-11-03T22:55:43.146Z",
    "all_day": false,
    "status": "open"
  }

Example Response

{
    "data": {
      "addTask": {
        "id": "5fcb9fbf-b4e0-4d85-be82-79ba6b05b43f",
        "note": "Note",
        "description": "Description",
        "owner": null
      }
    }
  }

https://freeagent.network/api/graphql

Create a new next step for a specific record.

Note:

Next Steps are no longer a special record. Next Steps are now a regular entity, which means that in order to create, update or delete a next step now you must to use the regular createEntity, deleteEntity and updateEntity endpoints.

Alternative Endpoint: createEntity

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 Primary description of next step created.
note String Additional note added to Next Step, can be formatted via HTML.
assigned_to [String] agent id the next step created should be assigned to.
due_date String ISO standard format date, indicating when the next step is due by.
type  String  Available options are: Task (Reminders), Phone, Email
all_day  Boolean  If the due_date is all day, you can leave only the date in due_date and this value must be true
status  String It must be "open" otherwise the record will be created as a note in the activity time line