---
title: "POST /objects/{object_name}/records/upsert"
method: POST
path: "/objects/{object_name}/records/upsert"
tags: ["Object Records"]
---

# POST /objects/{object_name}/records/upsert

`POST /objects/{object_name}/records/upsert`

## Path parameters

- `object_name` string, required

## Query parameters

- `validation_mode` 'strict' | 'ignore_invalid' — Validation mode to use when validating request data. `strict` validation will fail requests if any attribute fails validation, including unrecognized attributes. `ignore_invalid` validation will strip out unknown attributes and replace known, non-required attributes with `undefined` if they fail validation. The request will still fail if the request body does not contain the proper structure or if any required attributes fail validation.

## Request body

- UpsertRecordRequest — Request body for upserting a record. At least one of `create`, `create_or_update` or `create_or_update_if_empty` must be provided, and all required attributes on the object must be included in at least one of these properties. When the same attribute is specified in multiple properties, the values will be applied in a specific order of precedence. If a record is being created, the following order is used: 1. `create` 2. `create_or_update` 3. `create_or_update_if_empty` If an existing record is being updated, the following order is used: 1. `update` 2. `create_or_update` 3. `update_if_empty` 4. `create_or_update_if_empty`
  - `match` object, required — The attribute values to match against to find an existing record. At least one unique attribute must be included to ensure that at most one record is matched. Additional unique or non-unique attributes may also be included to refine the matching criteria.
  - `create` object — The attribute values to use when creating a new record if no match is found.
  - `update` object — The attribute values to use when updating an existing record if a match is found.
  - `update_if_empty` object — The attribute values to update when a matching record is found and the existing attribute value on the record is `null`.
  - `create_or_update` object — The attribute values to apply during both creation and update operations.
  - `create_or_update_if_empty` object — The attribute values to apply during both creation and update-if-empty operations.

## Response `200`

Response for a successful update operation.

- object — Response for a successful update operation.
  - `status` 'success', required
  - `data` object, required
    - `object` string, required — The API name of the object this record is an instance of.
    - `id` string, required — String UUIDv4 value.
    - `created_at` string, date-time, required — Date and time the record was created.
    - `updated_at` string, date-time, required — Date and time the record was last updated.
    - `attributes` object, required — Attribute values for the record. Each key is the API name of the attribute and each value is the corresponding attribute value for the record.

## Other responses

- `400` — Response for any operation that results in a bad request error.
- `401` — Response for any operation that results in an unauthorized error.
- `404` — Response for any operation that results in a not found error.
- `409` — Response for any operation that results in a conflict error.
- `500` — Response for any operation that results in an internal server error.
- `503` — Response for any operation that results in service unavailability.

---

[API](https://skmtc.net/unifygtm/apis/unify-analytics-api.md) · [All operations](https://skmtc.net/unifygtm/apis/unify-analytics-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unifygtm/unify-analytics-api/revisions/2f145e6f6d7e/schema)