Upsert records through the API

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

• The object has a field marked unique: true (for example, email on Account).
• You know the value to match on.

Steps

1. Send the upsert request

PUT /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

• 201 Created if a new record was inserted (the response includes a Location header).
• 200 OK if an existing record was updated.

If the specified field is not marked unique, the API returns a FIELD_NOT_UNIQUE error (400).

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

• Objects, Records, and Fields – what an object, record, and field are, and how a create-or-update request becomes rows in the database
• Create records through the API – the full validation rules and error code table, which apply to upserts as well
• Read, update, and delete records through the API
• FieldDefinition – full field type and validation reference