Datasets API

Use the Datasets API to keep an Auto Filing dataset in step with another system, such as a CRM, a matter-management system or an HR directory. You can read a dataset, replace all of its rows, or add, change and delete one row at a time.

Before you begin

• Create an API key and note your organization ID. See mxHERO V3 API Key.
• Create the dataset in the dashboard first (Auto Filling › Datasets). The API updates existing datasets; it does not create them.
• Get the dataset ID: open Auto Filling › Datasets, click Edit on the dataset, and copy the ID from the page URL.

How datasets are structured

A dataset is a list of rows. Each row has one key and one or more values. In JSON, rows is an object whose property names are the keys and whose property values are arrays of strings:

{
  "id": "17539a6e-4ccb-447d-b14d-75968bc6a843",
  "organizationId": "{organizationId}",
  "name": "Client folders",
  "rows": {
    "jane.doe@example.com": ["Acme"],
    "john.roe@example.net": ["Globex", "Initech"]
  }
}

How mxHERO uses rows when a rule runs:

• Key lookups are case-insensitive, and spaces at either end of a key are ignored.
• If two keys differ only by case, the first one wins. Avoid such duplicates.
• A variable can read the values as {VALUE} (first value) or {VALUE-n} (the n-th value). See Custom Variables.

Endpoints

All paths are relative to https://api.mxhero.com/v3/organizations/{organizationId}/datasets/{datasetId}. Every request needs the x-api-key header.

URL-encode the key in the query string (for example, @ becomes %40).

Read a dataset

curl -X GET "https://api.mxhero.com/v3/organizations/{organizationId}/datasets/{datasetId}" \
  -H "accept: application/json" \
  -H "x-api-key: {api-key}"

The response is the dataset object shown in How datasets are structured.

Replace all rows

Send the complete dataset. Rows that are not in the body are removed.

curl -X PUT "https://api.mxhero.com/v3/organizations/{organizationId}/datasets/{datasetId}" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: {api-key}" \
  -d '{
    "id": "{datasetId}",
    "organizationId": "{organizationId}",
    "name": "Client folders",
    "rows": {
      "jane.doe@example.com": ["Acme"],
      "john.roe@example.net": ["Globex"]
    }
  }'

Warning: A full PUT overwrites every row. To change one row, use the row endpoint instead.

Add or update one row

The body is a JSON array with the row's values.

curl -X PUT "https://api.mxhero.com/v3/organizations/{organizationId}/datasets/{datasetId}/row?key=jane.doe%40example.com" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: {api-key}" \
  -d '["Acme"]'

If the key exists, its values are replaced. If it doesn't, a new row is added.

Delete one row

curl -X DELETE "https://api.mxhero.com/v3/organizations/{organizationId}/datasets/{datasetId}/row?key=jane.doe%40example.com" \
  -H "accept: application/json" \
  -H "x-api-key: {api-key}"

Datasets that sync from cloud storage

A dataset can also be filled automatically from a storage folder (Dataset Sync). If the sync is set to Replace, each sync run replaces the rows, including rows you added through the API. Use Merge, or don't combine API updates and a Replace sync on the same dataset. See Datasets.

Limits

• A dataset is stored as a single document. Keep datasets well under a few megabytes.
• A key can't be blank or start with a space. Values can't be blank.

Verify

1. Make a change with PUT /row.
2. Read the dataset with GET and confirm the row.
3. In the dashboard, open the dataset under Auto Filling › Datasets and search for the key.
4. Test the variable that uses the dataset with Test variable in Auto Filling › Variables.

Troubleshooting

Related pages

• mxHERO V3 API Key
• Datasets
• Custom Variables
• Regular Expressions