Upsert a custom object record

POST 
/objects/:schemaKey/records/upsert

Upsert a custom object record. If a record with the same unique field values exists, it will be updated; otherwise, a new record will be created. Use operationMode query parameter to control how fields with multiple values are updated: "append" (default) adds new values to existing arrays, while "replace" overwrites existing values with the new ones.

Request

Version stringrequired

API Version

Available options2021-04-15

schemaKey stringrequired

The key of the Custom Object / Standard Object Schema. For custom objects, the key must include the “custom_objects.” prefix, while standard objects use their respective object keys. This information is available on the Custom Objects Details page under Settings.

operationMode string

Controls how fields with multiple values are updated

Available optionsappendreplace

application/json

application/json

Body

Bodyrequired

locationIdstringrequired

Location Id

propertiesobjectrequired

Properties of the custom object record. Keys are the object field names; values are the field values (string, number, or a monetary { currency, value } object).

configobject

Configuration for different object types

Example (auto)

{
  "locationId": "ve9EPM428h8vShlRW1KT",
  "properties": {
    "pet_name": "Cat",
    "pet_age": 10
  },
  "config": {
    "recurringTask": {
      "frequency": "weekly",
      "interval": 1
    }
  }
}

application/json

Record created or updated successfully

application/json

Schema

Schema

recordobject

The record matching the requested id

Example (auto)

{
  "record": {
    "id": "661c06b4ffde146bdb469442",
    "owner": [
      "sx6wyHhbFdRXh302Lunr"
    ],
    "followers": [
      "v5cEPM428h8vShlRW1KT"
    ],
    "properties": {
      "pet_name": "Cat",
      "pet_age": 10
    },
    "dateAdded": "2025-01-02T09:35:39.032Z",
    "dateUpdated": "2025-01-02T09:35:39.032Z"
  }
}