Skip to main content

FOQL — Facilio Object Query Language

FOQL (Facilio Object Query Language) is a SQL-like query language for retrieving records from Facilio modules through a single read endpoint. A FOQL query is a select statement that names the columns to return, the module to read from, and optional filtering, grouping, ordering, and pagination clauses.

Like SQL, you choose the columns, the source module, and optional where, group by, order by, limit, and offset clauses. Lookup fields can be traversed with dot notation to pull fields from related modules.

Purpose#

Retrieve records from a Facilio module using a single SQL-like select query — selecting exactly the fields you need, joining across related modules, aggregating, filtering, sorting, and paginating, all in one statement.

Endpoint#

ItemValue
HTTP methodPOST
Pathapi/platform/v5/foql
Parameterq — the FOQL select query

The query is sent in the request body as the q parameter:

{  "q": "<select_query>"}
Why POST for a read?

Although you are reading records, the HTTP method is POST because the query is posted in the request body rather than placed in the URL. This also means the query does not need to be URL-encoded.

Sample request#

curl -X POST "https://<your-domain>/api/platform/v5/foql" \  -H "Authorization: Bearer <access_token>" \  -H "Content-Type: application/json" \  -d '{ "q": "select id, serialNumber, subject, status from workorder where priority = '\''Low'\'' limit 100 offset 0" }'

Request body#

KeyTypeRequiredDescription
qstringYesThe FOQL select query to execute.
{  "q": "select id, serialNumber, subject, status from workorder where priority = 'Low' limit 100 offset 0"}

Core rules#

A few rules apply to every FOQL query:

  • Select only. Only the select statement is supported. insert / update / delete statements are rejected.
  • String literals use single quotes. Wrap string values in single quotes ('Low'). Identifiers — field names and module names — are not quoted.
  • Dates are epoch milliseconds or UTC strings. Date / DateTime values can be given either as epoch time in milliseconds (e.g. 1735669800000) or as a quoted UTC string in the format 'YYYY-MM-DDTHH:mm:ssZ' (e.g. '2024-12-31T18:30:00Z').
  • Keywords are case-insensitive. select, from, where, group by, order by, limit, offset, as, and, or, asc, desc can be written in any case.
  • Field and module names are exact. Use the field's and module's name exactly as defined in the module (e.g. serialNumber, totalCost, createdTime). Names are not normalized.

Next steps#

On This Topic