Perform a find request

To perform a find request, use an HTTP POST method with the _find API endpoint specifying the database name and the layout, and additional information to specify the query fields and criteria, sort order, starting record, and number of records. You can also specify portal information to limit the number of related records that are returned.

HTTP method

POST

URL

/fmi/data/version/databases/database-name/layouts/layout-name/_find

version – the FileMaker Data API version requested can use v1, v2, or vLatest

  • version 1 (v1) - the structure for returned portal data is based on the view setting (Form View or Table View) of the specified layout.

    • Form View - returns all related records

    • Table View - returns the first related record

      Note  Changing the view setting alters the portal data structure for the returned value.

  • version 2 (v2) - the structure for returned portal data is based on Form View.

  • latest version (vLatest) - the behavior is based on the last version of the API.

database-name – the name of the hosted database

layout-name – the layout to use as the context for the find request

HTTP header

Content-Type: application/json

Authorization: Bearer session-token, where session-token is the unique X-FM-Data-Access-Token value for the database session
Parameters

A query in JSON format specifying the fields and find criteria. You can use optional parameters to specify omit requests (omit), the sort order (sort), starting record (offset), number of records (limit), and portals (portal) for limiting the number of related records that are returned. The offset, limit, and sort parameters work on records found in the layout's table and not related portal records. To restrict the number of records and rows to display in a related set, specify the offset.portal-name and limit.portal-name parameters.

For example:

Copy 
{
  "query": [
    {"Group": "=Surgeon"},
    {"Work State" : "NY", "omit" : "true"}
  ],
  "sort": [
    {"fieldName": "Work State", "sortOrder": "ascend"},
    {"fieldName": "First Name", "sortOrder": "ascend"}
  ]
}

Example with offset, limit, and portals:

Copy 
{
  "query": [
    {"Group": "=Surgeon"},
    {"Work State": "NY", "omit" : "true"}
  ],
  "portal": ["Portal1","Portal2"],
  "limit": "10",
  "offset": "1",
  "offset.Portal1": "1",
  "limit.Portal1": "5",
  "layout.response": "Doctors"
}

Other optional request body parameters:

  • layout.response - Returns the response data in the context of a different layout. The specified layout should be for the same base table as the current layout. Specifying a layout for a different base table can produce unexpected results.

  • dateformats - Specifies the format of date and timestamp fields. The value is 0 for US formats, 1 for the file locale's formats, or 2 for ISO 8601 formats. If not specified, the default value is 0.

  • script.prerequest, script.presort, script - Runs FileMaker scripts as part of the request. See Run a script with another request.
Response

The record data in JSON format and a messages array showing an error code of 0.

For example:

Copy 
{
  "response": {
    "data": [ 
      ...  
    ]
  },
  "messages": [
    {
      "code": "0",
      "message": "OK"
    }
  ]
}

See Error responses.

Notes