Skip to content
Henceforth Docs

Upsert records through the API

Goal

Section titled “Goal”

Create a record if it doesn’t exist, or update it if it does, in a single request, matched on a unique field.

Prerequisites

Section titled “Prerequisites”
  • The object has a field marked unique: true (for example, email on Account). Any unique field works as the match key, whatever its type: text, UUID, integer, decimal, boolean, or a lookup.
  • You know the value to match on. It can’t be null.
  • If you call the API through a surface, the surface declares both runtime.data.record.create and runtime.data.record.update.

Steps

Section titled “Steps”

1. Send the upsert request

Section titled “1. Send the upsert request”

PUT /v1/data/core/Account/email

The {fieldKey} in the URL path must reference a field marked unique: true. The request body must include the match field (email in this example) and all required fields, since the record may be created:

{
  "email": "info@acme.com",
  "name": "Acme Corp",
  "industry": "Technology"
}

2. Check the response status to see what happened

Section titled “2. Check the response status to see what happened”
  • 201 Created if a new record was inserted (the response includes a Location header).
  • 200 OK if an existing record was updated.

The request can also fail:

  • 409 UNIQUE_VIOLATION: a record you can’t change already holds the value. The answer is the same one POST gives for that body, and the other record is left as it was.
  • 403 SURFACE_SCOPE_EXCEEDED: the surface doesn’t declare both create and update.
  • 403 SEED_RECORD_IMMUTABLE: the value matches a seeded record that can’t be changed.
  • 422 VALIDATION_ERROR: the match field is missing from the body or null (field code REQUIRED), or another field fails validation.
  • 400 FIELD_NOT_UNIQUE: the field in the URL isn’t marked unique.

Sending the same PUT again, or several at once, is safe: one creates the record, and the others update it. Another PUT can still answer 409: when the record belongs to someone whose records you can’t change, or when it was deleted while your request was waiting. In that last case, send the PUT again.

Verification

Section titled “Verification”

GET the record using the id from the response (or the Location header) and confirm the fields match what you sent. Run the same PUT request a second time with a changed field and confirm the response status is 200 OK (update), not 201 Created (create), and that the record’s id is unchanged.

See also

Section titled “See also”