Upsert Record

Create or update a record based on unique value(s).

PUT /objects/{object_name}/records

cURL

cURL

curl --request PUT \
  --url https://api.unifygtm.com/data/v1/objects/{object_name}/records \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "match": {},
  "create": {},
  "update": {},
  "defaults": {}
}
'

200

{
  "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:

Property	Behavior
match	Values to match against existing records. At least one of these values must be a unique attribute to avoid matching more than one record. Any number of additional attribute values (unique or non-unique) can also be specified.
create	Values to fill in if a new record is created. All required attributes on the object must be specified here or the request will fail.
update	Values to overwrite if an existing match is found. These values will replace any existing values on the record.
defaults	Values to fill in if there is not already an existing value for them. When creating a record, these will be populated in addition to any create values. When updating a record, these will never overwrite existing values but will be used for attributes that are curently empty.

You must specify match in the request which defines the value(s) that will be used to find a matching record. In addition, you must specify either create or defaults. Otherwise, all 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

Upsert a company

This creates or updates a company record:

Request

PUT /objects/company/records

{
  "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.

Upsert a person

This creates or updates a person record as well as their associated company and then links them together:

Request

PUT /objects/person/records

{
  "match": {
    "email": "[e-mail]"
  },
  "create": {
    "first_name": "Austin",
    "last_name": "Hughes",
    "email": "[e-mail]",
    "title": "CEO",
    "company": {
      "match": {
        "domain": "unifygtm.com"
      },
      "defaults": {
        "name": "Unify",
        "domain": "unifygtm.com"
      }
    }
  },
  "defaults": {
    "lead_source": "LinkedIn"
  }
}

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.

The use of defaults for the company upsert means that we will fill in the name and domain of the company, but if the company already exists, we won’t overwrite its existing values.

Likewise, the use of defaults for the person upsert means that we will only fill in the lead_source of this person record if it is currently empty or if we end up creating a new record.

Upsert a custom record

This creates or updates a record in a custom object called product_user:

Request

PUT /objects/product_user/records

{
  "match": {
    "user_id": "6b2a2761-3cbe-481f-8a1e-b24859c674f8"
  },
  "defaults": {
    "user_id": "6b2a2761-3cbe-481f-8a1e-b24859c674f8",
    "full_name": "Bob Smith",
    "email_address": "[e-mail]",
    "plan": "free_tier"
  }
}

This is a custom object, so all of these attributes are custom attributes defined for the object. Since this request uses defaults, these values will be filled in if the record is created or if the existing record doesn’t already have values for them.

Usage

Authorizations

x-api-key · string · header · required

Path Parameters

object_name · string · required

Body

application/json

Request body for upserting a record.

match · object · required

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

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.

defaults · object

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

Response

200

application/json

Response for a successful update operation.

Response for a successful update operation.

status · enum<string> · required

Available options: success

data · object · required

Show child attributes