Skip to main content
POST
/
objects
/
{object_name}
/
records
/
upsert
cURL
curl --request POST \
  --url https://api.unifygtm.com/data/v1/objects/{object_name}/records/upsert \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "match": {},
  "create": {},
  "update": {},
  "update_if_empty": {},
  "create_or_update": {},
  "create_or_update_if_empty": {}
}
'
{
  "status": "success",
  "data": {
    "object": "<string>",
    "id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "attributes": {}
  }
}

​
Overview

The upsert method creates or updates a record depending on whether it already exists or not. If a matching record exists, it will be updated. Otherwise, a new record will be created. The request body accepts the following properties which specify how to create or update the record:
PropertyBehavior
matchValues to match against existing records. At least one of these values must be a unique attribute to avoid matching more than one record.
createValues to use when creating a new record.
updateValues to use when updating an existing record. These values will replace any existing values on the record.
update_if_emptyValues to use when updating an existing record. These values will only be used if the attribute is currently empty.
create_or_updateValues to use when creating a new record or updating an existing record. When updating, these values will replace any existing values on the record.
create_or_update_if_emptyValues to use when creating a new record or updating an existing record. When updating, these values will only be used if the attribute is currently empty.
You must specify match and one of create, create_or_update, or create_or_update_if_empty. All other properties are optional. The upsert method is the most reliable way of sending data into Unify, so if you’re not sure what method to use, this is the one we recommend.

​
Examples

This creates or updates a company record:
POST /objects/company/records/upsert

{
  "match": {
    "domain": "unifygtm.com"
  },
  "create": {
    "name": "Unify",
    "domain": "unifygtm.com",
    "description": "A nice company with a top-notch API.",
    "status": "Active"
  },
  "update": {
    "status": "Active"
  }
}
If there’s already a company record in Unify with the domain unifygtm.com, it will be updated with a status of “Active”. Otherwise, a new record will be created with the specified values.
This creates or updates a person record as well as their associated company and then links them together:
POST /objects/company/records/upsert

{
  "match": {
    "email": "austinhughes@unifygtm.com"
  },
  "create_or_update_if_empty": {
    "first_name": "Austin",
    "last_name": "Hughes",
    "email": "austinhughes@unifygtm.com",
    "title": "CEO",
    "company": {
      "match": {
        "domain": "unifygtm.com"
      },
      "create_or_update_if_empty": {
        "name": "Unify",
        "domain": "unifygtm.com"
      }
    }
  }
}
This works because company is the name of a reference attribute on the person object which references a company object record. This request will create a new company if it doesn’t already exist, update it if it does, and then link this person to that company.
This creates or updates a record in a custom object called product_user:
POST /objects/company/records/upsert

{
  "match": {
    "user_id": "6b2a2761-3cbe-481f-8a1e-b24859c674f8"
  },
  "create_or_update": {
    "user_id": "6b2a2761-3cbe-481f-8a1e-b24859c674f8",
    "full_name": "Bob Smith",
    "email_address": "bob.smith@gmail.com",
    "plan": "free_tier"
  }
}
This is a custom object, so all of these attributes are custom attributes defined for the object. Since this request uses create_or_update, these values will be filled in if the record is created or overridden if an existing record is found.

​
Usage

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
object_name
string
required

Query Parameters

​
validation_mode
enum<string>

Validation mode to use when validating request data.

strict validation will fail requests if any attribute fails validation, including unrecognized attributes.

ignore_invalid validation will strip out unknown attributes and replace known, non-required attributes with undefined if they fail validation. The request will still fail if the request body does not contain the proper structure or if any required attributes fail validation.

Available options:
strict,
ignore_invalid

Body

application/json

Request body for upserting a record.

At least one of create, create_or_update or create_or_update_if_empty must be provided, and all required attributes on the object must be included in at least one of these properties.

When the same attribute is specified in multiple properties, the values will be applied in a specific order of precedence. If a record is being created, the following order is used:

  1. create
  2. create_or_update
  3. create_or_update_if_empty

If an existing record is being updated, the following order is used:

  1. update
  2. create_or_update
  3. update_if_empty
  4. create_or_update_if_empty
​
match
object
required

The attribute values to match against to find an existing record.

At least one unique attribute must be included to ensure that at most one record is matched. Additional unique or non-unique attributes may also be included to refine the matching criteria.

​
create
object

The attribute values to use when creating a new record if no match is found.

​
update
object

The attribute values to use when updating an existing record if a match is found.

​
update_if_empty
object

The attribute values to update when a matching record is found and the existing attribute value on the record is null.

​
create_or_update
object

The attribute values to apply during both creation and update operations.

​
create_or_update_if_empty
object

The attribute values to apply during both creation and update-if-empty operations.

Response

Response for a successful update operation.

Response for a successful update operation.

​
status
enum<string>
required
Available options:
success
​
data
object
required