Upsert record

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

import requests

url = "https://api.unifygtm.com/data/v1/objects/{object_name}/records/upsert"

payload = {
    "match": {},
    "create": {},
    "update": {},
    "update_if_empty": {},
    "create_or_update": {},
    "create_or_update_if_empty": {}
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    match: {},
    create: {},
    update: {},
    update_if_empty: {},
    create_or_update: {},
    create_or_update_if_empty: {}
  })
};

fetch('https://api.unifygtm.com/data/v1/objects/{object_name}/records/upsert', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unifygtm.com/data/v1/objects/{object_name}/records/upsert",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'match' => [
        
    ],
    'create' => [
        
    ],
    'update' => [
        
    ],
    'update_if_empty' => [
        
    ],
    'create_or_update' => [
        
    ],
    'create_or_update_if_empty' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.unifygtm.com/data/v1/objects/{object_name}/records/upsert"

	payload := strings.NewReader("{\n  \"match\": {},\n  \"create\": {},\n  \"update\": {},\n  \"update_if_empty\": {},\n  \"create_or_update\": {},\n  \"create_or_update_if_empty\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.unifygtm.com/data/v1/objects/{object_name}/records/upsert")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"match\": {},\n  \"create\": {},\n  \"update\": {},\n  \"update_if_empty\": {},\n  \"create_or_update\": {},\n  \"create_or_update_if_empty\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unifygtm.com/data/v1/objects/{object_name}/records/upsert")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"match\": {},\n  \"create\": {},\n  \"update\": {},\n  \"update_if_empty\": {},\n  \"create_or_update\": {},\n  \"create_or_update_if_empty\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "data": {
    "object": "<string>",
    "id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "attributes": {}
  }
}

{
  "status": "bad_request",
  "errors": [
    {
      "code": "<string>",
      "path": [
        "<string>"
      ],
      "object_api_name": "<string>",
      "attribute_api_name": "<string>"
    }
  ],
  "message": "<string>"
}

{
  "status": "unauthorized",
  "message": "<string>"
}

{
  "status": "object_not_found",
  "message": "<string>"
}

{
  "status": "record_conflict",
  "message": "<string>"
}

{
  "status": "error",
  "message": "<string>"
}

{
  "status": "service_unavailable",
  "message": "<string>"
}

POST

data

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

import requests

url = "https://api.unifygtm.com/data/v1/objects/{object_name}/records/upsert"

payload = {
    "match": {},
    "create": {},
    "update": {},
    "update_if_empty": {},
    "create_or_update": {},
    "create_or_update_if_empty": {}
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    match: {},
    create: {},
    update: {},
    update_if_empty: {},
    create_or_update: {},
    create_or_update_if_empty: {}
  })
};

fetch('https://api.unifygtm.com/data/v1/objects/{object_name}/records/upsert', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unifygtm.com/data/v1/objects/{object_name}/records/upsert",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'match' => [
        
    ],
    'create' => [
        
    ],
    'update' => [
        
    ],
    'update_if_empty' => [
        
    ],
    'create_or_update' => [
        
    ],
    'create_or_update_if_empty' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.unifygtm.com/data/v1/objects/{object_name}/records/upsert"

	payload := strings.NewReader("{\n  \"match\": {},\n  \"create\": {},\n  \"update\": {},\n  \"update_if_empty\": {},\n  \"create_or_update\": {},\n  \"create_or_update_if_empty\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.unifygtm.com/data/v1/objects/{object_name}/records/upsert")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"match\": {},\n  \"create\": {},\n  \"update\": {},\n  \"update_if_empty\": {},\n  \"create_or_update\": {},\n  \"create_or_update_if_empty\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unifygtm.com/data/v1/objects/{object_name}/records/upsert")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"match\": {},\n  \"create\": {},\n  \"update\": {},\n  \"update_if_empty\": {},\n  \"create_or_update\": {},\n  \"create_or_update_if_empty\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "data": {
    "object": "<string>",
    "id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "attributes": {}
  }
}

{
  "status": "bad_request",
  "errors": [
    {
      "code": "<string>",
      "path": [
        "<string>"
      ],
      "object_api_name": "<string>",
      "attribute_api_name": "<string>"
    }
  ],
  "message": "<string>"
}

{
  "status": "unauthorized",
  "message": "<string>"
}

{
  "status": "object_not_found",
  "message": "<string>"
}

{
  "status": "record_conflict",
  "message": "<string>"
}

{
  "status": "error",
  "message": "<string>"
}

{
  "status": "service_unavailable",
  "message": "<string>"
}

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.
`create`	Values to use when creating a new record.
`update`	Values to use when updating an existing record. These values will replace any existing values on the record.
`update_if_empty`	Values to use when updating an existing record. These values will only be used if the attribute is currently empty.
`create_or_update`	Values 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_empty`	Values 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

Upsert a company

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"
  }
}

{
  "status": "success",
  "data": {
    "object": "company",
    "id": "73fcb798-9ccd-4138-8f6a-9a801123783c",
    "created_at": "2025-09-04T01:23:45Z",
    "updated_at": "2025-09-04T01:23:45Z",
    "attributes": {
      "name": "Unify",
      "domain": "unifygtm.com",
      "description": "A nice company with a top-notch API.",
      "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:

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"
      }
    }
  }
}

{
  "status": "success",
  "data": {
    "object": "person",
    "id": "bf3f4d5e-c995-496f-8774-5a1c58d05197",
    "created_at": "2025-09-04T01:23:45Z",
    "updated_at": "2025-09-04T01:23:45Z",
    "attributes": {
      "first_name": "Austin",
      "last_name": "Hughes",
      "email": "austinhughes@unifygtm.com",
      "title": "CEO",
      "company": "73fcb798-9ccd-4138-8f6a-9a801123783c",
      "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.

Upsert a custom record

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"
  }
}

{
  "status": "success",
  "data": {
    "object": "product_user",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2025-09-04T01:23:45Z",
    "updated_at": "2025-09-04T01:23:45Z",
    "attributes": {
      "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

The API name of an object, e.g. company, person, opportunity, or a custom object's API name.

Query Parameters

validation_mode

enum<string>

Validation mode for request data.

strict: Reject requests if any attribute is invalid or unrecognized.
ignore_invalid: Ignore unknown attributes and omit invalid values for optional attributes. Reject requests with an invalid body structure or invalid required attributes.

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. Together, these properties must include all required attributes.

match

object

required

Attribute values used to find an existing record. Include at least one unique attribute. Additional attributes narrow the match.

create

object

Attribute values used when no record matches. These take precedence over other creation values.

update

object

Attribute values used when a record matches. These take precedence over other update values.

update_if_empty

object

Attribute values applied to a matching record only where the existing value is null. Values in update and create_or_update take precedence.

create_or_update

object

Attribute values used for both creation and updates. Values in create or update take precedence.

create_or_update_if_empty

object

Attribute values used for creation, or for updates where the existing value is null. Values in all other properties take precedence.

Response

Response for a successful update operation.

status

enum<string>

required

Available options:

success

data

object

required

Show child attributes

⌘I

Unify Platform

MCP

Developer Guides

API Reference

SDKs

Upsert record

Overview

Examples

Usage

Authorizations

Path Parameters

Query Parameters

Body

Response

​Overview

​Examples

​Usage

Authorizations

Path Parameters

Query Parameters

Body

Response

Overview

Examples

Usage