Create or Update Records (Upsert) API

Audience: Developers and Solution Architects

Purpose: Explains how to use the Create or Update Record Upsert API to create or update Records based on lookup identifiers while enforcing uniqueness, permissions, and archive conflict handling.

Overview

Use the Create or Update Records (Upsert) endpoint to conditionally create a new Record or update an existing one based on a lookup identifier. Lookup identifiers are governed by Object-level uniqueness rules and differ by Record type.

This endpoint is designed for integration workflows that require duplicate prevention and dynamic create-or-update behavior.

The material on this page builds on information covered in Records Core Concepts and the Records Data Model.

Why Use This API?

Use the Upsert API when you need to create or update a Record in a single request using a defined identifier.

Common scenarios include:

Synchronizing data between external systems and the platform
Preventing duplicate Records during integration workflows
Updating Records when only a name or email is available
Supporting incremental or bidirectional synchronization

Upsert achieves the same outcome as performing a Lookup followed by a Create or Update request, but combines matching and modification into a single API call.

Compared to separate lookup and write operations, Upsert:

Reduces round trips between systems
Simplifies integration logic
Minimizes race conditions
Supports reliable synchronization patterns

Upsert requires a clearly defined identifier strategy to ensure consistent matching behavior.

Create or Update Records (Upsert) API Behavior

Use this endpoint to create or update a Record by providing a lookup identifier. It:

Evaluates the lookup identifier within the specified Object
Creates a new Record if no matching Record exists
Updates the existing Record if a match is found
Returns a response indicating whether a create or update action occurred
Enforces Object-level uniqueness constraints
Uses Record name for most Objects and email for Contact Records
Applies validation rules and required field enforcement
Respects permission constraints
Applies archive conflict handling when a matching Record exists in an archived state

Unarchiving Using Entity Create or Upsert

When a lookup identifier matches a record that exists in an archived state, the Upsert endpoint may trigger archive collision behavior.

Depending on the archive conflict mode configured in the request:

The archived record may be restored
A new record may be created
A conflict response may be returned

Archived conflict handling must be explicitly defined in the request. Upsert does not implicitly overwrite or restore archived records without intentional configuration. Developers implementing synchronization workflows should account for archived record scenarios to prevent unintended duplication or data resurrection.

Create or Update Records (Upsert) Endpoint

Want to try the API out? Visit our Swagger docs.

post

Create or update entity record based on lookup criteria

Authorizations

X-API-KEYstringRequired

X-BUSINESS-IDstringRequired

X-USER-IDstringRequired

Path parameters

object_identifierstringRequired

Query parameters

return_all_fieldsbooleanOptional

If true, return all fields even if not updated

Body

lookup_valuestring · min: 1Required

Value to match the entity record (name for custom objects, email for contacts).

oncreate_unarchiveone of · nullableOptional

Behavior when creating and a matching archived record exists.

prompt - prompt
unarchive - unarchive
overwrite - overwrite

string · enumOptional

prompt - prompt
unarchive - unarchive
overwrite - overwrite

Possible values:

undefined · enumOptionalPossible values:

onupdate_archived_conflictone of · nullableOptional

Updates the identifier of matching archived record to not raise a conflict during update.

overwrite - overwrite

string · enumOptional

overwrite - overwrite

Possible values:

undefined · enumOptionalPossible values:

Responses

200Success

application/json

object_typestringRequired

num_upcoming_activitiesintegerRequired

idstring · uuidRequired

num_associated_team_membersintegerRequired

actionstring · enumRequired

created - created
updated - updated
unarchived - unarchived

Possible values:

201Success

application/json

400Error

application/json

post/api/records/{object_identifier}/upsert

POST /api/records/{object_identifier}/upsert HTTP/1.1
X-API-KEY: YOUR_API_KEY
X-BUSINESS-ID: YOUR_BUSINESS_ID
X-USER-ID: YOUR_USER_ID
Content-Type: application/json
Accept: */*
Content-Length: 189

{
  "lookup_value": "user@example.com",
  "fields": [
    {
      "name": "first_name",
      "value": "John"
    },
    {
      "name": "last_name",
      "value": "Doe"
    }
  ],
  "oncreate_unarchive": "prompt",
  "onupdate_archived_conflict": "overwrite"
}

{
  "id": "<entity_record_id>",
  "action": "updated",
  "display_name": "Record Name",
  "fields": {
    "<field_id>": {
      "name": "field_name",
      "value": "field_value"
    }
  },
  "access": {
    "view": true,
    "edit": true,
    "remove": true
  }
}

Create or Update Records (Upsert) Schema

What’s Next

After implementing Create or Update Records (Upsert) workflows, you can:

Retrieve a Record by name or email to confirm matching behavior
Use ID-based endpoints to perform targeted updates or lifecycle actions
Add new Records explicitly when guaranteed creation is required
Search Records for multi-record filtering and validation
Incorporate Upsert workflows into schema-aware integrations

For more information on Record operations, see the related Records API topics below:

PreviousSearch Records API

NextTeam Interactions in Records

Last updated 6 months ago

Was this helpful?