Claris FileMaker Data API Guide

https://help.claris.com/en/data-api-guide/content/
Admin
The FileMaker Data API is a REST API that allows web services to access and manage data in databases...
Tokens:31,489
Snippets:186
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example response for GET /fmi/data/version/databases/database-name/scripts

Source: https://help.claris.com/en/data-api-guide/content/get-script-names.html

Example response from the scripts endpoint. Shows the scripts array with script names and folder structure, and a messages array with error code 0.

```json
{
  "response": {
    "scripts": [
      {
        "name": "GotoFirst",
        "isFolder": false
      },
      {
        "name": "A Folder",
        "isFolder": true,
        "folderScriptNames": [
          {
            "name": "script1",
            "isFolder": false
          },
          {
            "name": "-",
            "isFolder": false
          },
          {
            "name": "script2",
            "isFolder": false
          },
          {
            "name": "Another Folder",
            "isFolder": true,
            "folderScriptNames": [
              {
                "name": "script3",
                "isFolder": false
              }
            ]
          },
          {
            "name": "script4",
            "isFolder": false
          }
        ]
      }
    ]
  },
  "messages": [
    {
      "message": "OK",
      "code": "0"
    }
  ]
}
```

--------------------------------

### URL example for GET request with script parameters

Source: https://help.claris.com/en/data-api-guide/content/run-script-with-another-request.html

Example URL for a GET request that includes script parameters as URL parameters. The script 'UpdateProcessing' is run after the action, with parameter '14'.

```url
https://<host>/fmi/data/v1/databases/customers/layouts/entry/records/14?script=UpdateProcessing&script.param=14
```

--------------------------------

### GET /fmi/data/version/databases/database-name/layouts response example

Source: https://help.claris.com/en/data-api-guide/content/get-layout-names.html

Example JSON response returned by the layouts endpoint. It contains a messages array with an error code of 0 and a response object with a layouts array listing layout names, including nested folderLayoutNames.

```json
{
  "messages": [
    {
      "message": "OK",  
      "code": "0"
    }
  ],  
 "response": {
    "layouts": [
      {
        "name": "Customers"
      },  
      { 
        "name": "Details"
      }, 
      {
        "folderLayoutNames": [
          {
            "name": "Mark as sent"
          }, 
          {
            "name": "Mark as unsent"
          } 
        ]
      } 
    ]
  }
}
```

--------------------------------

### Example response for GET /fmi/data/version/productInfo

Source: https://help.claris.com/en/data-api-guide/content/get-product-information.html

Shows the JSON response body returned by the productInfo endpoint. The response includes product metadata (name, dateFormat, timeFormat, timeStampFormat) and a messages array with an error code of 0.

```json
{
  "response": {
    "productInfo": {
      "name": "FileMaker Data API Engine",
      "dateFormat": "MM/dd/yyyy",  
      "timeFormat": "HH:mm:ss",  
      "timeStampFormat": "MM/dd/yyyy HH:mm:ss"  
    }  
  },  
  "messages": [
    {
      "code": "0",
      "message": "OK"
    }
  ]
}
```

--------------------------------

### Create a record: example response to curl request

Source: https://help.claris.com/en/data-api-guide/content/create-record.html

Example response to the curl request, showing the created record's recordId and modId, along with a messages array indicating success.

```json
{
  "response": {
    "recordId": "324",
    "modId": "0"
  },
  "messages": [
    {
      "code": "0",
      "message": "OK"
    }
  ]
}
```

--------------------------------

### Find request response example

Source: https://help.claris.com/en/data-api-guide/content/perform-find-request.html

Example JSON response from a find request. The response contains the record data and a messages array with an error code of 0 and message OK.

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

--------------------------------

### Example response for running a script

Source: https://help.claris.com/en/data-api-guide/content/run-a-script.html

Shows the JSON response returned when the script executes successfully. The scriptError field is "0" and the message is "OK".

```json
{
  "response": {
    "scriptError": "0"
  },
  "messages": [
    {
      "code": "0",
      "message": "OK"
    }
  ]
}
```

--------------------------------

### GET /fmi/data/{version}/productInfo

Source: https://help.claris.com/en/data-api-guide/content/get-product-information.html

Retrieves product information about the host, including the product name and the date, time, and timestamp formats in use.

```APIDOC
## GET /fmi/data/{version}/productInfo

### Description
Retrieves product information about the host, including the product name and the date, time, and timestamp formats in use.

### Method
GET

### Endpoint
/fmi/data/{version}/productInfo

### Parameters
#### Path Parameters
- **version** (string) - Required - The FileMaker Data API version requested. Can use `v1`, `v2`, or `vLatest`.

### Response
#### Success Response (200)
- **response.productInfo.name** (string) - The product name, which is "FileMaker Data API Engine".
- **response.productInfo.dateFormat** (string) - The date format in use on the host.
- **response.productInfo.timeFormat** (string) - The time format in use on the host.
- **response.productInfo.timeStampFormat** (string) - The timestamp format in use on the host.
- **messages** (array) - A messages array showing an error code of 0.

#### Response Example
```
{
  "response": {
    "productInfo": {
      "name": "FileMaker Data API Engine",
      "dateFormat": "MM/dd/yyyy",
      "timeFormat": "HH:mm:ss",
      "timeStampFormat": "MM/dd/yyyy HH:mm:ss"
    }
  },
  "messages": [
    {
      "code": "0",
      "message": "OK"
    }
  ]
}
```
```

--------------------------------

### Example response JSON for getting a single record

Source: https://help.claris.com/en/data-api-guide/content/get-single-record.html

Shows the JSON structure returned when a record is successfully retrieved, including fieldData, portalData, recordId, modId, and a messages array with code 0.

```json
{
  "response": {
    "data": [
      {
        "fieldData": {
          ...
        },
        "portalData" : {
          "portalObject": [
            {
              ...
            }
          ]
        },
        "recordId" : "147",
        "modId" : "0"
      }
    ]
  },
  "messages": [
    {
      "code": "0",
      "message": "OK"
    }
  ]
}
```

--------------------------------

### Example response JSON for record ID 324

Source: https://help.claris.com/en/data-api-guide/content/get-single-record.html

The JSON response returned for the example request, showing the record data with fieldData, portalData, recordId, modId, and a messages array with code 0.

```json
{
  "response": {
    "data": [
      {
        "recordId": "324",
        "modId": "0",
        "fieldData": {
          "String Field": "value_1"
        },
        "portalData": {
          "portalObject": [
            {
              "PortalTable::String Field": "value_1"
            }
          ]
        }
      }
    ]
  },
  "messages": [
    {
      "code": "0",
      "message": "OK"
    }
  ]
}
```

--------------------------------

### validateSession response example

Source: https://help.claris.com/en/data-api-guide/content/validate-database-session.html

Example response from the validateSession endpoint showing the isSessionInUse parameter set to true, indicating an operation is still ongoing. The response includes a messages array with status code 0 and message OK.

```json
{
  "response": {
    "isSessionInUse": true
  },
  "messages": [
    {
      "message": "OK",  
      "code": "0"
    }
  ]
}
```

--------------------------------

### Create a record: example response with recordId and modId

Source: https://help.claris.com/en/data-api-guide/content/create-record.html

Example response from the FileMaker Data API when creating a record. The response contains the recordId of the created record and a messages array with an error code of 0.

```json
{
  "response": {
    "recordId":"147",
    "modId":"0"
  },
  "messages": [
    {
      "code": "0",
      "message":"OK"
    }
  ]
}
```

--------------------------------

### Find request body with script.prerequest parameters

Source: https://help.claris.com/en/data-api-guide/content/run-script-with-another-request.html

Example JSON request body for a find request that includes script.prerequest and script.prerequest.param parameters. The script 'Eliminate duplicates' runs before the find action, with parameter '100'.

```json
{  
  "query": [  
    {  
      "Title": "Office Manager"  
    }  
  ],  
  "script.prerequest": "Eliminate duplicates",  
  "script.prerequest.param": "100"  
}
```

--------------------------------

### Create a record: example curl request

Source: https://help.claris.com/en/data-api-guide/content/create-record.html

Example curl command to create a record using the FileMaker Data API. It sends a POST request to the records endpoint with an Authorization header containing a session token and a JSON body with fieldData and portalData.

```bash
curl --request POST \
  --url https://ServerDomain/fmi/data/vLatest/databases/DatabaseName/layouts/LayoutName/records \
  --header 'Authorization: Bearer c4d2e429122e9cdeda19bb23c55cd2a8f282c3cc50c60943a110' \
  --header 'content-type: application/json' \
  --data '{"fieldData": {"String Field": "value_1"}, "portalData": {"portalObject": [{"String Field": "value_1"}]}}'
```

--------------------------------

### GET /fmi/data/version/databases/{database-name}/layouts/{layout-name}/script/{script-name}

Source: https://help.claris.com/en/data-api-guide/content/run-a-script.html

Runs a FileMaker script using the FileMaker Data API. The script runs in the context of the specified layout and can receive an optional parameter.

```APIDOC
## [GET] /fmi/data/version/databases/{database-name}/layouts/{layout-name}/script/{script-name}

### Description
Runs a FileMaker script using the FileMaker Data API. The script runs in the context of the specified layout and can receive an optional parameter.

### Method
GET

### Endpoint
/fmi/data/version/databases/{database-name}/layouts/{layout-name}/script/{script-name}

### Parameters
#### Path Parameters
- **version** (string) - Required - The FileMaker Data API version requested. Can use `v1`, `v2`, or `vLatest`.
- **database-name** (string) - Required - The name of the hosted database.
- **layout-name** (string) - Required - The name of the layout to use as the context for running the script.
- **script-name** (string) - Required - The script that you want to run.

#### Query Parameters
- **script.param** (string) - Optional - The text string to use as a parameter for the script that was named by script-name.

### Request Example
```
GET /fmi/data/vLatest/databases/customers/layouts/entry/script/UpdateProcessing?script.param=14
```

### Response
#### Success Response (200)
- **scriptError** (string) - The error code from the script execution.
- **messages** (array) - An array of message objects.
  - **code** (string) - The status code.
  - **message** (string) - The status message.

#### Response Example
```
{
  "response": {
    "scriptError": "0"
  },
  "messages": [
    {
      "code": "0",
      "message": "OK"
    }
  ]
}
```

### Notes
- When using FileMaker Data API to run a script, make sure that the script has a unique name. If there are multiple scripts with the same name, FileMaker Data API cannot control which script is called, even if the scripts are in different folders.
```

--------------------------------

### Get a range of records response

Source: https://help.claris.com/en/data-api-guide/content/get-range-of-records.html

Example response body for a successful request to get a range of records. The response contains the record data in JSON format and a messages array with an error code of 0.

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

--------------------------------

### Example request: curl GET for a single record

Source: https://help.claris.com/en/data-api-guide/content/get-single-record.html

A curl command that sends a GET request to the FileMaker Data API to retrieve a record with ID 324 from the specified database and layout. Requires a valid session token in the Authorization header.

```bash
curl --request GET \
  --url https://ServerDomain/fmi/data/vLatest/databases/DatabaseName/layouts/LayoutName/records/324 \
  --header 'Authorization: Bearer c4d2e429122e9cdeda19bb23c55cd2a8f282c3cc50c60943a110'
```

--------------------------------

### Example response: databases array with database names

Source: https://help.claris.com/en/data-api-guide/content/get-database-names.html

Shows the JSON response returned by the databases endpoint. It contains a databases array listing the database names and a messages array with an error code of 0.

```json
{
  "response": {
    "databases": [
      {
        "name": "Customers"
      },  
      {
        "name": "Sales"
      }
    ]
}, 
  "messages": [
    {
      "code": "0",
      "message": "OK"
    }
  ]
}
```

--------------------------------

### POST /fmi/data/version/databases/database-name/sessions

Source: https://help.claris.com/en/data-api-guide/content/log-in-external-data-source.html

Creates a session with the hosted database and logs in to an external data source using the fmDataSource parameter.

```APIDOC
## [POST] /fmi/data/version/databases/database-name/sessions

### Description
Creates a session with the hosted database and logs in to an external data source. The hosted database name is specified in the URL, the account name and password for the hosted database are specified in the Authorization header, and the external data source credentials are provided in the fmDataSource parameter.

### Method
POST

### Endpoint
/fmi/data/version/databases/database-name/sessions

### Parameters
#### Path Parameters
- **version** (string) - Required - The FileMaker Data API version requested. Can use `v1`, `v2`, or `vLatest`.
- **database-name** (string) - Required - The name of the hosted database.

#### HTTP Headers
- **Content-Type** (string) - Required - Must be `application/json`.
- **Authorization** (string) - Required - A base64-encoded string representing the account name and password to use to log in to the hosted database. This base64-encoded string should follow the standard HTTP Basic Authentication Scheme.

#### Request Body
- **fmDataSource** (array) - Required - A JSON array specifying the database name, account name, and password for the external data source.
  - **database** (string) - Required - The name of the external data source (without the .fmp12 extension).
  - **username** (string) - Optional - The account name for the external data source. Required unless using OAuth.
  - **password** (string) - Optional - The password for the external data source. Required unless using OAuth.
  - **oAuthRequestId** (string) - Optional - The X-FMS-Request-ID header value for OAuth authentication.
  - **oAuthIdentifier** (string) - Optional - The URL query value for OAuth authentication.

### Request Example
```json
{
  "fmDataSource": [
    {
      "database": "contacts",
      "username": "admin",
      "password": "admin"
    }
  ]
}
```

### Response
#### Success Response (200)
- **response** (object) - Empty object.
- **messages** (array) - Array of message objects.
  - **code** (string) - Error code. 0 indicates success.
  - **message** (string) - Status message.
- **X-FM-Data-Access-Token** (header) - The session token to be used for subsequent API calls.

#### Response Example
```
X-FM-Data-Access-Token: c13c0f486780f2187bde6f3859dabd4dcf8ea43be420dfeadf34
{
  "response": {},
  "messages": [
    {
      "code": "0",
      "message": "OK"
    }
  ]
}
```

### Notes
- FileMaker databases are the only external data sources supported. Specify the database name without the .fmp12 filename extension.
- Files listed in the `fmDataSource` parameter will be opened as needed, for example, when a script is run or when the context is changed to a layout that requires the external data source. As a result, errors with logging in to the external data source happen when attempting to open the files, not when logging in to the database session.

### Request Example
For standard authentication:
```json
{
  "fmDataSource": [
    {
      "database": "contacts",
      "username": "admin",
      "password": "admin"
    }
  ]
}
```

For OAuth authentication:
```json
{
  "fmDataSource": [
    {
      "database": "contacts",
      "oAuthRequestId": "E65B98BB17429CO643B31119F",
      "oAuthIdentifier": "B164A3459A776E5177445DR223"
    }
  ]
}
```

### Response
#### Success Response (200)
- **X-FM-Data-Access-Token** (string) - The session token to be used for subsequent API calls.
- **response** (object) - Empty response body.
- **messages** (array) - Array of message objects.
  - **code** (string) - Error code. 0 indicates success.
  - **message** (string) - Message description.

#### Response Example
```
X-FM-Data-Access-Token: c13c0f486780f2187bde6f3859dabd4dcf8ea43be420dfeadf34  
{  
  "response": {},  
  "messages": [  
    {  
      "code": "0",  
      "message": "OK"  
    }  
  ]  
}
```
```

--------------------------------

### GET script

Source: https://help.claris.com/en/data-api-guide/content/run-filemaker-scripts.html

Runs a FileMaker script using an HTTP GET request to the `script` API endpoint.

```APIDOC
## [GET] script

### Description
Runs a FileMaker script using an HTTP GET method with the `script` API endpoint.

### Method
GET

### Endpoint
`script`

### Parameters
None explicitly documented.

### Request Example
No request body is used for this endpoint.

### Response
No response schema is explicitly documented.

### Response Example
No response example is provided.
```

--------------------------------

### GET /fmi/data/version/databases/database-name/layouts

Source: https://help.claris.com/en/data-api-guide/content/get-layout-names.html

Retrieves the layout names of all available layouts for a specified database. Use an HTTP GET method with the layouts API endpoint.

```APIDOC
## [GET] /fmi/data/version/databases/database-name/layouts

### Description
Retrieves the layout names of all available layouts for a specified database.

### Method
GET

### Endpoint
/fmi/data/version/databases/database-name/layouts

### Parameters
#### Path Parameters
- **version** (string) - Required - The FileMaker Data API version requested. Can use `v1`, `v2`, or `vLatest`.
- **database-name** (string) - Required - The name of the hosted database.

#### Query Parameters
None

#### Request Body
None

### Request Example
No request body is required.

### Response
#### Success Response (200)
- **messages** (array) - An array of message objects.
  - **message** (string) - The message text.
  - **code** (string) - The error code. A value of "0" indicates success.
- **response** (object) - The response object.
  - **layouts** (array) - An array of layout objects.
    - **name** (string) - The layout name.
    - **isFolder** (boolean) - Indicates if the layout is a folder.
    - **folderLayoutNames** (array) - An array of layout objects within a folder.
      - **name** (string) - The layout name.

#### Response Example
```
{
  "messages": [
    {
      "message": "OK",
      "code": "0"
    }
  ],
  "response": {
    "layouts": [
      {
        "name": "Customers"
      },
      {
        "name": "Details"
      },
      {
        "folderLayoutNames": [
          {
            "name": "Mark as sent"
          },
          {
            "name": "Find Unsent"
          }
        ],
        "isFolder": true,
        "name": "Package Management"
      }
    ]
  }
}
```

### Error Responses
See Error responses.
```

--------------------------------

### POST /fmi/data/version/databases/database-name/sessions

Source: https://help.claris.com/en/data-api-guide/content/log-in-database-session.html

Logs in to a hosted database session by providing account credentials in the Authorization header. Returns an access token for subsequent API calls.

```APIDOC
## [POST] /fmi/data/version/databases/database-name/sessions

### Description
Logs in to a hosted database session using the provided account credentials. Returns an access token that must be used for subsequent API calls.

### Method
POST

### Endpoint
/fmi/data/version/databases/database-name/sessions

### Parameters
#### Path Parameters
- **version** (string) - Required - The FileMaker Data API version. Can use `v1`, `v2`, or `vLatest`.
- **database-name** (string) - Required - The name of the hosted database.

#### Headers
- **Content-Type** (string) - Required - Must be `application/json`.
- **Authorization** (string) - Required - Basic authentication header. Format: `Basic base64(account:password)`. For example, `Basic YWRtaW46YWRtaW4=` for account `admin` and password `admin`.

#### Request Body
- **fmDataSource** (object) - Optional - Used to log in to an external data source. See "Log in to an external data source."

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **response.token** (string) - The access token for the session.
- **messages** (array) - Array of message objects.
- **messages[].message** (string) - Status message, e.g., "OK".
- **messages[].code** (string) - Error code, "0" for success.

#### Response Example
```json
{
  "response": {
    "token": "c4d2e429122e9cdeda19bb23c55cd2a8f282c3cc50c60943a110"
  },
  "messages": [
    {
      "message": "OK",
      "code": "0"
    }
  ]
}
```

### Request Example
```
curl --request POST \
  --url https://ServerDomain/fmi/data/vLatest/databases/DatabaseName/sessions \
  --header 'Authorization: Basic YWRtaW46YWRtaW4=' \
  --header 'Content-Type: application/json'
```

### Response
#### Success Response (200)
- **response.token** (string) - The access token for the session.
- **messages** (array) - Array of message objects.
- **messages[].message** (string) - Status message, e.g., "OK".
- **messages[].code** (string) - Error code, "0" for success.

#### Response Example
{
  "response": {
    "token": "c4d2e429122e9cdeda19bb23c55cd2a8f282c3cc50c60943a110"
  },
  "messages": [
    {
      "message": "OK",
      "code": "0"
    }
  ]
}
```

--------------------------------

### Find request body with offset, limit, and portals

Source: https://help.claris.com/en/data-api-guide/content/perform-find-request.html

Example JSON body for a find request that includes portal restrictions, offset, limit, and a response layout. The offset and limit parameters apply to the found records, while offset.Portal1 and limit.Portal1 restrict related records.

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

--------------------------------

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

Source: https://help.claris.com/en/data-api-guide/content/perform-find-request.html

Performs a find request on a specified layout. Use the query parameter to specify find criteria, and optional parameters for sorting, pagination, and portal control.

```APIDOC
## POST /fmi/data/version/databases/database-name/layouts/layout-name/_find

### Description
Performs a find request on a specified layout. Use the query parameter to specify find criteria, and optional parameters for sorting, pagination, and portal control.

### Method
POST

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

### Parameters
#### Path Parameters
- **version** (string) - Required - The FileMaker Data API version requested. Can use `v1`, `v2`, or `vLatest`.
- **database-name** (string) - Required - The name of the hosted database.
- **layout-name** (string) - Required - The layout to use as the context for the find request.

#### Request Body
- **query** (array) - Required - A JSON array of query objects specifying fields and find criteria. Each query object can include an `omit` field to omit records.
- **sort** (array) - Optional - A JSON array of sort objects with `fieldName` and `sortOrder` (ascend or descend).
- **offset** (string) - Optional - The starting record number for the found set.
- **limit** (string) - Optional - The maximum number of records to return.
- **portal** (array) - Optional - A JSON array of portal names to include related records.
- **offset.portal-name** (string) - Optional - The starting record number for a specific portal.
- **limit.portal-name** (string) - Optional - The maximum number of records to return for a specific portal.
- **layout.response** (string) - Optional - 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.
- **dateformats** (string) - Optional - Specifies the format of date and timestamp fields. Value is 0 for US formats, 1 for the file locale's formats, or 2 for ISO 8601 formats. Default is 0.
- **script.prerequest** (string) - Optional - Runs a FileMaker script before the request.
- **script.presort** (string) - Optional - Runs a FileMaker script after sorting.
- **script** (string) - Optional - Runs a FileMaker script as part of the request.

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

### Response
#### Success Response (200)
- **response** (object) - Contains the record data in JSON format.
- **messages** (array) - An array of message objects with an error code of 0.

#### Response Example
```
{  
  "response": {  
    "data": [  
      ...  
    ]  
  },  
  "messages": [  
    {  
      "code": "0",  
      "message": "OK"  
    }  
  ]  
}
```

```

--------------------------------

### Log in to external data source with account credentials

Source: https://help.claris.com/en/data-api-guide/content/log-in-external-data-source.html

Use this JSON body in the POST request to /fmi/data/version/databases/database-name/sessions to log in to an external data source with an account name and password. The database name must be specified without the .fmp12 filename extension.

```json
{
  "fmDataSource": [
    {
      "database": "contacts",
      "username": "admin",
      "password": "admin"
    }
  ]
}
```
Tokens:
Raw