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

apiKey & businessId & userId

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

application/json

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:

or

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:

or

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

HTTPcURLJavaScriptPython

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

{
  "lookup_value": "[email protected]",
  "fields": [
    {
      "name": "first_name",
      "value": "John"
    },
    {
      "name": "last_name",
      "value": "Doe"
    }
  ],
  "oncreate_unarchive": "prompt",
  "onupdate_archived_conflict": "overwrite"
}

Upsert contactUpsert custom record (rename example)

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

Related Topics

• Add Records API

• Manage Records by ID API

• Lookup Record API

• Search Records API