Queries (v3)

📘

Please note

This guide explains how to use the v3 query endpoint. For the reference page where you can try out queries, click here.

Overview

The v3 query endpoint (POST /api/v3/query) accepts a structured JSON body and returns matching records from any object in your CRM. It supports filtering with logical operators, sorting, pagination, aggregation functions, and grouping.

Request body

📘

Query modes

The query operates in two modes depending on whether groupBy is provided:

• Simple mode (no groupBy): returns individual records. aggrFunc and alias on fields have no effect.
• Aggregation mode (with groupBy): returns grouped results. Fields must either appear in groupBy or have an aggrFunc. All orderBy fields must also appear in groupBy.

objectType

This property must be a valid object type code that exists in your system.

fields

A field object describes which fields to include in the response, and optionally how to aggregate them.

Example

[
  {
    "name": "accountname"
  },
  {
    "name": "ownerid_fullname"
  }
]

Field types in the response

Text fields are returned as-is:

{
  "pcfTextField": "text",
  "pcfUrlField": "url",
  "pcfTelephone": "phone-number-here",
  "pcfNumber": 999
}

Lookup fields return two entries — the ID and a name entry with the primary field value of the related record:

{
  "lookup": "1234-123456-123445-2222",
  "lookupName": "name of the record"
}

Related fields are returned as requested:

{
  "lookup_pcfTextField": "text here"
}

Picklist fields return two entries — the attribute value and a name entry with the display value:

{
  "picklist": "1",
  "picklistname": "value"
}

Errors

filter

A filter is an array of condition groups. All condition groups under the filter array are joined with AND logic between them.

conditionGroup

condition

Example

"filter": [
  {
    "type": "AND",
    "conditions": [
      {
        "fieldName": "accountname",
        "operator": "start-with",
        "value": "Y"
      }
    ]
  },
  {
    "type": "OR",
    "conditions": [
      {
        "fieldName": "ownerid",
        "operator": "eq",
        "value": "3b6b3b37-41fa-413e-bb42-f802128cc092"
      },
      {
        "fieldName": "originatingleadcode",
        "operator": "eq-in",
        "value": [4, 7]
      }
    ]
  }
]

In this example, the two condition groups are combined with AND. The first group requires accountname to start with "Y". The second group requires either a specific owner or a lead code of 4 or 7.

Errors

Operators

Providing a value for operators that expect none, or a non-array value for operators that expect an array, will return a 400 error.

Relative date values

When filtering on date or datetime fields, you can use relative date values instead of fixed dates. These are supported with operators eq, ne, lt, gt, le, and ge.

Example

{
  "fieldName": "createdon",
  "operator": "eq",
  "value": "today"
}

orderBy

An orderBy object specifies how to sort the results.

Example

[
  {
    "name": "accountname",
    "order": "asc"
  },
  {
    "name": "ownerid_fullname",
    "order": "desc"
  }
]

If orderBy is empty or omitted, results are sorted by the primary key field of the object. When the query contains groupBy and no orderBy, results are sorted by the first field in groupBy.

When the query includes groupBy, all orderBy fields must also appear in the groupBy array.

Errors

groupBy

A groupBy object specifies which fields to group results by. This is required when using aggregation functions (aggrFunc) in the fields array.

Example

[
  {
    "name": "statuscode"
  },
  {
    "name": "ownerid_fullname"
  }
]

Rules

• All non-aggregated fields in the fields array must also appear in groupBy.
• All orderBy fields must also appear in groupBy.

Errors

Aggregation

You can apply aggregation functions to fields when using groupBy. Set the aggrFunc property on a field object.

Supported functions: SUM, COUNT, MIN, MAX.

Example

{
  "objectType": 1,
  "fields": [
    {
      "name": "createdby"
    },
    {
      "name": "revenue",
      "alias": "Total",
      "aggrFunc": "SUM"
    }
  ],
  "groupBy": [
    {
      "name": "createdby"
    }
  ]
}

The aggregated value is returned under the alias (if provided) or under the field name.

Pagination

The response includes an isLastPage boolean. When false, increment pageNumber to fetch the next page.

Errors

Full example

Request

POST https://api.fireberry.com/api/v3/query HTTP/1.1
tokenid: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Content-Type: application/json

{
  "objectType": 1,
  "fields": [
    { "name": "accountname" },
    { "name": "telephone1" },
    { "name": "statuscode" }
  ],
  "filter": [
    {
      "type": "AND",
      "conditions": [
        {
          "fieldName": "accountname",
          "operator": "start-with",
          "value": "Bob"
        },
        {
          "fieldName": "statuscode",
          "operator": "eq-in",
          "value": [1, 2]
        }
      ]
    }
  ],
  "orderBy": [
    { "name": "accountname", "order": "asc" }
  ],
  "pageSize": 25,
  "pageNumber": 1
}

Response

{
  "data": [
    {
      "_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "accountname": "Bob Davis",
      "telephone1": "0501234567",
      "statuscode": 1
    },
    {
      "_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "accountname": "Bob Johnson",
      "telephone1": "0509876543",
      "statuscode": 2
    }
  ],
  "success": true,
  "message": "",
  "pageNumber": 1,
  "pageSize": 25,
  "isLastPage": true
}