Skip to main content
The API uses type for Database and app for Space. See Terminology.
Creates Entity (or Entities) if no existing duplicate is found (based on the Conflict Field); otherwise, it either skips creating or updates the existing duplicate, depending on the Conflict Action.
Setting the fibery/id Field for Entities is mandatory to apply the Conflict Action when a duplicate is found.
The Conflict Field can be of type: fibery/text, fibery/int, or fibery/date
Conflict ActionDescription
skip-createdo not create Entity if a Duplicate was found
update-latestupdates the Duplicate found with all fields from the Entity to be created, excluding platform fields (fibery/id, fibery/public-id, fibery/rank, fibery/creation-date). If more than one Duplicate is found, the Duplicate with the latest fibery/creation-date is selected for updating.
If a batch of Entities is passed to the command and it contains Duplicates, the following action is taken:
  • skip-create: Uses the first found Duplicate in the batch.
  • update-latest: Uses the last found Duplicate in the batch.
Duplicate matching rules:
  • NULL values are not considered equal. An entity with a NULL Conflict Field value is not considered a Duplicate of another entity with a NULL value.
  • Text Field comparisons are case-sensitive.
The result is an array of created Entities or resolved Conflicts, in the order of the Entities. The array contents are determined as follows:
  • Created: If an Entity was created, the array contains the new Entity’s information with create action.
  • Skipped: If an Entity was not created because skip-create was applied to a found Duplicate, the array contains a resolved Conflict with skip-create action.
  • Updated: If an Entity was used to update a found Duplicate due to update-latest, the array contains a resolved Conflict with update-latest action.
  • Batch Duplicate handling: If an Entity was ignored due to a Duplicate found within the same batch of Entities, the array contains a resolved Conflict with prefer-duplicate-found-in-the-batch action. This action uses the Duplicate entity (D) and resolves it by applying the specified Conflict Action later:
  • If no Conflict is found for D, the array contains the created Entity D info with create action.
  • If a Conflict is found for D and resolved with skip-create, the array contains a resolved Conflict with skip-create action.
  • If a Conflict is found for D and resolved with update-latest, the array contains a resolved Conflict with update-latest action.

​
Case 1

  • Batch of Entities contain duplicates
  • There are no existing duplicates in the DB
  • Conflict Action is skip-create
const response = await fetch('https://YOUR_ACCOUNT.fibery.io/api/commands', {
  method: 'POST',
  headers: {
    'Authorization': 'Token YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    command: 'fibery.entity.batch/create-or-update',
    args: {
      type: 'Cricket/Player',
      entities: [
        // Entity 1 (does not exist in the DB)
        {
          'fibery/id': 'd17390c4-98c8-11e9-a2a3-2a2ae2dbcce4',
          'Cricket/Name': 'Curtly Ambrose',
          'Cricket/Shirt Number': 1,
          'Cricket/Height': '2.01',
          'Cricket/Retired': false
        },
        // Entity 2 (does not exist in the DB)
        {
          'fibery/id': '20f9b920-9752-11e9-81b9-4363f716f666',
          'Cricket/Name': 'Brian Lara',
          'Cricket/Shirt Number': 18,
          'Cricket/Height': '1.75',
          'Cricket/Retired': false
        },
        // Entity 3 (duplicate of Entity 1)
        {
          'fibery/id': '79580f9d-fd30-439e-8040-6922d9f0455d',
          'Cricket/Name': 'Curtly Ambrose',
          'Cricket/Shirt Number': 1,
          'Cricket/Height': '2.10',
          'Cricket/Retired': true
        }
      ],
      'conflict-field': 'Cricket/Name',
      'conflict-action': 'skip-create'
    }
  })
});
const data = await response.json();
Result: 
{
  "success": true,
  "result": [
    {
      "action": "create",
      "created": {
        "Cricket/Height": "2.01",
        "fibery/modification-date": "2025-09-02T14:32:25.905Z",
        "fibery/id": "d17390c4-98c8-11e9-a2a3-2a2ae2dbcce4",
        "fibery/created-by": {"fibery/id": "4044090b-7165-4791-ac15-20fb12ae0b64"},
        "fibery/creation-date": "2025-09-02T14:32:25.905Z",
        "Cricket/Name": "Curtly Ambrose",
        "fibery/public-id": "3",
        "Cricket/Retired": false,
        "Cricket/Shirt Number": 1,
        "Cricket/Bio": {"fibery/id": "01990ad7-e855-701f-ae77-6c146f6b9ee7"},
        "fibery/rank": 5674304923033269
      }
    },
    {
      "action": "create",
      "created": {
        "Cricket/Height": "1.75",
        "fibery/modification-date": "2025-09-02T14:32:25.905Z",
        "fibery/id": "20f9b920-9752-11e9-81b9-4363f716f666",
        "fibery/created-by": {"fibery/id": "4044090b-7165-4791-ac15-20fb12ae0b64"},
        "fibery/creation-date": "2025-09-02T14:32:25.905Z",
        "Cricket/Name": "Brian Lara",
        "fibery/public-id": "2",
        "Cricket/Retired": false,
        "Cricket/Shirt Number": 18,
        "Cricket/Bio": {"fibery/id": "01990ad7-e855-701d-a776-0d933166aa86"},
        "fibery/rank": 5674304922933269
      }
    },
    {
      "action": "prefer-duplicate-found-in-the-batch",
      "entity": {
        "fibery/id": "79580f9d-fd30-439e-8040-6922d9f0455d",
        "Cricket/Name": "Curtly Ambrose",
        "Cricket/Shirt Number": 1,
        "Cricket/Height": "2.10",
        "Cricket/Retired": true
      },
      "duplicate": {
        "fibery/id": "d17390c4-98c8-11e9-a2a3-2a2ae2dbcce4",
        "Cricket/Name": "Curtly Ambrose",
        "Cricket/Shirt Number": 1,
        "Cricket/Height": "2.01",
        "Cricket/Retired": false
      }
    }
  ]
}

​
Case 2

  • Batch of Entities contains duplicates
  • There are existing duplicates in the DB
  • Conflict Action is skip-create
const response = await fetch('https://YOUR_ACCOUNT.fibery.io/api/commands', {
  method: 'POST',
  headers: {
    'Authorization': 'Token YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    command: 'fibery.entity.batch/create-or-update',
    args: {
      type: 'Cricket/Player',
      entities: [
        // Entity 1 (already exists in the DB)
        {
          'fibery/id': 'a1185326-afc5-4467-a8f7-825b090a97e1',
          'Cricket/Name': 'Curtly Ambrose',
          'Cricket/Shirt Number': 1,
          'Cricket/Height': '2.01',
          'Cricket/Retired': false
        },
        // Entity 2 (already exists in the DB)
        {
          'fibery/id': 'abe35d9b-4286-49f9-9ecb-0a777dcf98da',
          'Cricket/Name': 'Brian Lara',
          'Cricket/Shirt Number': 18,
          'Cricket/Height': '1.75',
          'Cricket/Retired': false
        },
        // Entity 3 (duplicate of Entity 1)
        {
          'fibery/id': '79580f9d-fd30-439e-8040-6922d9f0455d',
          'Cricket/Name': 'Curtly Ambrose',
          'Cricket/Shirt Number': 1,
          'Cricket/Height': '2.10',
          'Cricket/Retired': true
        }
      ],
      'conflict-field': 'Cricket/Name',
      'conflict-action': 'skip-create'
    }
  })
});
const data = await response.json();
Result: 
{
  "success": true,
  "result": [
    {
      "action": "skip-create",
      "entity": {
        "fibery/id": "a1185326-afc5-4467-a8f7-825b090a97e1",
        "Cricket/Name": "Curtly Ambrose",
        "Cricket/Shirt Number": 1,
        "Cricket/Height": "2.01",
        "Cricket/Retired": false
      },
      "duplicate": {
        "Cricket/Height": "2.01",
        "fibery/modification-date": "2025-09-02T14:32:25.905Z",
        "fibery/id": "d17390c4-98c8-11e9-a2a3-2a2ae2dbcce4",
        "fibery/created-by": {"fibery/id": "4044090b-7165-4791-ac15-20fb12ae0b64"},
        "fibery/creation-date": "2025-09-02T14:32:25.905Z",
        "Cricket/Name": "Curtly Ambrose",
        "fibery/public-id": "3",
        "Cricket/Retired": false,
        "Cricket/Shirt Number": 1,
        "Cricket/Bio": {"fibery/id": "01990ad7-e855-701f-ae77-6c146f6b9ee7"},
        "fibery/rank": 5674304923033269
      }
    },
    {
      "action": "skip-create",
      "entity": {
        "fibery/id": "abe35d9b-4286-49f9-9ecb-0a777dcf98da",
        "Cricket/Name": "Brian Lara",
        "Cricket/Shirt Number": 18,
        "Cricket/Height": "1.75",
        "Cricket/Retired": false
      },
      "duplicate": {
        "Cricket/Height": "1.75",
        "fibery/modification-date": "2025-09-02T14:32:25.905Z",
        "fibery/id": "20f9b920-9752-11e9-81b9-4363f716f666",
        "fibery/created-by": {"fibery/id": "4044090b-7165-4791-ac15-20fb12ae0b64"},
        "fibery/creation-date": "2025-09-02T14:32:25.905Z",
        "Cricket/Name": "Brian Lara",
        "fibery/public-id": "2",
        "Cricket/Retired": false,
        "Cricket/Shirt Number": 18,
        "Cricket/Bio": {"fibery/id": "01990ad7-e855-701d-a776-0d933166aa86"},
        "fibery/rank": 5674304922933269
      }
    },
    {
      "action": "prefer-duplicate-found-in-the-batch",
      "entity": {
        "fibery/id": "79580f9d-fd30-439e-8040-6922d9f0455d",
        "Cricket/Name": "Curtly Ambrose",
        "Cricket/Shirt Number": 1,
        "Cricket/Height": "2.10",
        "Cricket/Retired": true
      },
      "duplicate": {
        "fibery/id": "d17390c4-98c8-11e9-a2a3-2a2ae2dbcce4",
        "Cricket/Name": "Curtly Ambrose",
        "Cricket/Shirt Number": 1,
        "Cricket/Height": "2.01",
        "Cricket/Retired": false
      }
    }
  ]
}

​
Case 3

  • Batch of Entities contains duplicates
  • There are no existing duplicates in the DB
  • Conflict Action is update-latest
const response = await fetch('https://YOUR_ACCOUNT.fibery.io/api/commands', {
  method: 'POST',
  headers: {
    'Authorization': 'Token YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    command: 'fibery.entity.batch/create-or-update',
    args: {
      type: 'Cricket/Player',
      entities: [
        // Entity 1 (duplicate of Entity 3)
        {
          'fibery/id': 'd17390c4-98c8-11e9-a2a3-2a2ae2dbcce4',
          'Cricket/Name': 'Curtly Ambrose',
          'Cricket/Shirt Number': 1,
          'Cricket/Height': '2.01',
          'Cricket/Retired': false
        },
        // Entity 2 (does not exist in the DB)
        {
          'fibery/id': '20f9b920-9752-11e9-81b9-4363f716f666',
          'Cricket/Name': 'Brian Lara',
          'Cricket/Shirt Number': 18,
          'Cricket/Height': '1.75',
          'Cricket/Retired': false
        },
        // Entity 3 (does not exist in the DB)
        {
          'fibery/id': '79580f9d-fd30-439e-8040-6922d9f0455d',
          'Cricket/Name': 'Curtly Ambrose',
          'Cricket/Shirt Number': 1,
          'Cricket/Height': '2.10',
          'Cricket/Retired': true
        }
      ],
      'conflict-field': 'Cricket/Name',
      'conflict-action': 'update-latest'
    }
  })
});
const data = await response.json();
Result: 
{
  "success": true,
  "result": [
    {
      "action": "prefer-duplicate-found-in-the-batch",
      "entity": {
        "fibery/id": "d17390c4-98c8-11e9-a2a3-2a2ae2dbcce4",
        "Cricket/Name": "Curtly Ambrose",
        "Cricket/Shirt Number": 1,
        "Cricket/Height": "2.01",
        "Cricket/Retired": false
      },
      "duplicate": {
        "fibery/id": "79580f9d-fd30-439e-8040-6922d9f0455d",
        "Cricket/Name": "Curtly Ambrose",
        "Cricket/Shirt Number": 1,
        "Cricket/Height": "2.10",
        "Cricket/Retired": true
      }
    },
    {
      "action": "create",
      "created": {
        "Cricket/Height": "1.75",
        "fibery/modification-date": "2025-09-02T14:39:58.586Z",
        "fibery/id": "20f9b920-9752-11e9-81b9-4363f716f666",
        "fibery/created-by": {"fibery/id": "4044090b-7165-4791-ac15-20fb12ae0b64"},
        "fibery/creation-date": "2025-09-02T14:39:58.586Z",
        "Cricket/Name": "Brian Lara",
        "fibery/public-id": "4",
        "Cricket/Retired": false,
        "Cricket/Shirt Number": 18,
        "Cricket/Bio": {"fibery/id": "01990ade-d091-7022-b1c4-7efe12ccd84b"},
        "fibery/rank": 7072311628808326
      }
    },
    {
      "action": "create",
      "created": {
        "Cricket/Height": "2.10",
        "fibery/modification-date": "2025-09-02T14:39:58.586Z",
        "fibery/id": "79580f9d-fd30-439e-8040-6922d9f0455d",
        "fibery/created-by": {"fibery/id": "4044090b-7165-4791-ac15-20fb12ae0b64"},
        "fibery/creation-date": "2025-09-02T14:39:58.586Z",
        "Cricket/Name": "Curtly Ambrose",
        "fibery/public-id": "5",
        "Cricket/Retired": true,
        "Cricket/Shirt Number": 1,
        "Cricket/Bio": {"fibery/id": "01990ade-d091-7024-9fd1-e03f62f5860e"},
        "fibery/rank": 7072311628908326
      }
    }
  ]
}

​
Case 4

  • Batch of Entities contains duplicates
  • There are existing duplicates in the DB
  • Conflict Action is update-latest
const response = await fetch('https://YOUR_ACCOUNT.fibery.io/api/commands', {
  method: 'POST',
  headers: {
    'Authorization': 'Token YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    command: 'fibery.entity.batch/create-or-update',
    args: {
      type: 'Cricket/Player',
      entities: [
        // Entity 1 (duplicate of Entity 3)
        {
          'fibery/id': 'a1185326-afc5-4467-a8f7-825b090a97e1',
          'Cricket/Name': 'Curtly Ambrose',
          'Cricket/Shirt Number': 1,
          'Cricket/Height': '2.01',
          'Cricket/Retired': false
        },
        // Entity 2 (already exists in the DB)
        {
          'fibery/id': 'abe35d9b-4286-49f9-9ecb-0a777dcf98da',
          'Cricket/Name': 'Brian Lara',
          'Cricket/Shirt Number': 18,
          'Cricket/Height': '1.75',
          'Cricket/Retired': false
        },
        // Entity 3 (already exists in the DB)
        {
          'fibery/id': 'c79d09ba-1c2d-40f4-aa3b-cf7bc79ff7a8',
          'Cricket/Name': 'Curtly Ambrose',
          'Cricket/Shirt Number': 1,
          'Cricket/Height': '2.10',
          'Cricket/Retired': true
        }
      ],
      'conflict-field': 'Cricket/Name',
      'conflict-action': 'update-latest'
    }
  })
});
const data = await response.json();
Result: 
{
  "success": true,
  "result": [
    {
      "action": "prefer-duplicate-found-in-the-batch",
      "entity": {
        "fibery/id": "a1185326-afc5-4467-a8f7-825b090a97e1",
        "Cricket/Name": "Curtly Ambrose",
        "Cricket/Shirt Number": 1,
        "Cricket/Height": "2.01",
        "Cricket/Retired": false
      },
      "duplicate": {
        "fibery/id": "79580f9d-fd30-439e-8040-6922d9f0455d",
        "Cricket/Name": "Curtly Ambrose",
        "Cricket/Shirt Number": 1,
        "Cricket/Height": "2.15",
        "Cricket/Retired": true
      }
    },
    {
      "action": "update-latest",
      "entity": {
        "fibery/id": "abe35d9b-4286-49f9-9ecb-0a777dcf98da",
        "Cricket/Name": "Brian Lara",
        "Cricket/Shirt Number": 18,
        "Cricket/Height": "1.75",
        "Cricket/Retired": false
      },
      "duplicate": {
        "Cricket/Height": "1.75",
        "fibery/modification-date": "2025-09-02T14:39:58.586Z",
        "fibery/id": "20f9b920-9752-11e9-81b9-4363f716f666",
        "fibery/created-by": {"fibery/id": "4044090b-7165-4791-ac15-20fb12ae0b64"},
        "fibery/creation-date": "2025-09-02T14:39:58.586Z",
        "Cricket/Name": "Brian Lara",
        "fibery/public-id": "4",
        "Cricket/Retired": false,
        "Cricket/Shirt Number": 18,
        "Cricket/Bio": {"fibery/id": "01990ade-d091-7022-b1c4-7efe12ccd84b"},
        "fibery/rank": 7072311628808326
      },
      "updated": {
        "Cricket/Height": "1.75",
        "fibery/id": "20f9b920-9752-11e9-81b9-4363f716f666",
        "Cricket/Name": "Brian Lara",
        "Cricket/Retired": false,
        "Cricket/Shirt Number": 18
      }
    },
    {
      "action": "update-latest",
      "entity": {
        "fibery/id": "c79d09ba-1c2d-40f4-aa3b-cf7bc79ff7a8",
        "Cricket/Name": "Curtly Ambrose",
        "Cricket/Shirt Number": 1,
        "Cricket/Height": "2.15",
        "Cricket/Retired": true
      },
      "duplicate": {
        "Cricket/Height": "2.10",
        "fibery/modification-date": "2025-09-02T14:39:58.586Z",
        "fibery/id": "79580f9d-fd30-439e-8040-6922d9f0455d",
        "fibery/created-by": {"fibery/id": "4044090b-7165-4791-ac15-20fb12ae0b64"},
        "fibery/creation-date": "2025-09-02T14:39:58.586Z",
        "Cricket/Name": "Curtly Ambrose",
        "fibery/public-id": "5",
        "Cricket/Retired": true,
        "Cricket/Shirt Number": 1,
        "Cricket/Bio": {"fibery/id": "01990ade-d091-7024-9fd1-e03f62f5860e"},
        "fibery/rank": 7072311628908326
      },
      "updated": {
        "Cricket/Height": "2.15",
        "fibery/id": "79580f9d-fd30-439e-8040-6922d9f0455d",
        "Cricket/Name": "Curtly Ambrose",
        "Cricket/Retired": true,
        "Cricket/Shirt Number": 1
      }
    }
  ]
}