Upsert record

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

Upsert a record to keep data from another system current in Unify. A matching record is updated. If no record matches, a new record is 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.

Examples

Set UNIFY_API_KEY to your API key.

Keep company data current

This request creates Northstar Labs if its domain is missing, or updates its name and description if it already exists:

curl --request POST \
  --url "https://api.unifygtm.com/data/v1/objects/company/records/upsert" \
  --header "X-Api-Key: $UNIFY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "match": {
    "domain": "northstar.example"
  },
  "create_or_update": {
    "name": "Northstar Labs",
    "domain": "northstar.example",
    "description": "Software for managing laboratory operations."
  }
}'

Fill missing person and company details

Use create_or_update_if_empty to preserve populated attributes. In this example, both the person and the referenced company are created if needed:

curl --request POST \
  --url "https://api.unifygtm.com/data/v1/objects/person/records/upsert" \
  --header "X-Api-Key: $UNIFY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "match": {
    "email": "alex@northstar.example"
  },
  "create_or_update_if_empty": {
    "first_name": "Alex",
    "last_name": "Morgan",
    "email": "alex@northstar.example",
    "title": "Operations director",
    "company": {
      "match": {
        "domain": "northstar.example"
      },
      "create_or_update_if_empty": {
        "name": "Northstar Labs",
        "domain": "northstar.example"
      }
    }
  }
}'

“Empty” means the current value is null. The response returns the resulting record in data.

Sync a custom record

For a product_user object with a unique user_id, use the external user’s ID as the match key:

curl --request POST \
  --url "https://api.unifygtm.com/data/v1/objects/product_user/records/upsert" \
  --header "X-Api-Key: $UNIFY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "match": {
    "user_id": "trial-user-1042"
  },
  "create_or_update": {
    "user_id": "trial-user-1042",
    "full_name": "Alex Morgan",
    "email_address": "alex@northstar.example",
    "plan": "free_tier"
  }
}'

Create the custom object and attributes before sending this request. The attribute values must match their configured types and select options.

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

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

Unify platform

MCP

Developer guides

API reference

SDKs

Upsert record

Overview

Examples

Authorizations

Path Parameters

Query Parameters

Body

Response