> ## Documentation Index > Fetch the complete documentation index at: https://docs.unifygtm.com/llms.txt > Use this file to discover all available pages before exploring further. # Upsert record > Create or update a record based on unique values. ## Overview The *upsert* method creates or updates a record depending on whether it already exists or not. If a matching record exists, it will be updated. Otherwise, a new record will be created. The request body accepts the following properties which specify how to create or update the record: | Property | Behavior | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `match` | Values to match against existing records. At least one of these values must be a unique attribute to avoid matching more than one record. | | `create` | Values to use when creating a new record. | | `update` | Values to use when updating an existing record. These values will replace any existing values on the record. | | `update_if_empty` | Values to use when updating an existing record. These values will only be used if the attribute is currently empty. | | `create_or_update` | Values to use when creating a new record or updating an existing record. When updating, these values will replace any existing values on the record. | | `create_or_update_if_empty` | Values to use when creating a new record or updating an existing record. When updating, these values will only be used if the attribute is currently empty. | You must specify `match` and one of `create`, `create_or_update`, or `create_or_update_if_empty`. All other properties are optional. The upsert method is the most reliable way of sending data into Unify, so if you're not sure what method to use, this is the one we recommend. ## Examples This creates or updates a company record: ```http Request theme={null} POST /objects/company/records/upsert { "match": { "domain": "unifygtm.com" }, "create": { "name": "Unify", "domain": "unifygtm.com", "description": "A nice company with a top-notch API.", "status": "Active" }, "update": { "status": "Active" } } ``` ```json Response theme={null} { "status": "success", "data": { "object": "company", "id": "73fcb798-9ccd-4138-8f6a-9a801123783c", "created_at": "2025-09-04T01:23:45Z", "updated_at": "2025-09-04T01:23:45Z", "attributes": { "name": "Unify", "domain": "unifygtm.com", "description": "A nice company with a top-notch API.", "status": "Active" // ... } } } ``` If there's already a company record in Unify with the domain [unifygtm.com](https://unifygtm.com), it will be updated with a status of "Active". Otherwise, a new record will be created with the specified values. This creates or updates a person record as well as their associated company and then links them together: ```http Request theme={null} POST /objects/company/records/upsert { "match": { "email": "austinhughes@unifygtm.com" }, "create_or_update_if_empty": { "first_name": "Austin", "last_name": "Hughes", "email": "austinhughes@unifygtm.com", "title": "CEO", "company": { "match": { "domain": "unifygtm.com" }, "create_or_update_if_empty": { "name": "Unify", "domain": "unifygtm.com" } } } } ``` ```json Response theme={null} { "status": "success", "data": { "object": "person", "id": "bf3f4d5e-c995-496f-8774-5a1c58d05197", "created_at": "2025-09-04T01:23:45Z", "updated_at": "2025-09-04T01:23:45Z", "attributes": { "first_name": "Austin", "last_name": "Hughes", "email": "austinhughes@unifygtm.com", "title": "CEO", "company": "73fcb798-9ccd-4138-8f6a-9a801123783c", "lead_source": "LinkedIn" // ... } } } ``` This works because `company` is the name of a *reference attribute* on the person object which references a company object record. This request will create a new company if it doesn't already exist, update it if it does, and then link this person to that company. This creates or updates a record in a custom object called `product_user`: ```http Request theme={null} POST /objects/company/records/upsert { "match": { "user_id": "6b2a2761-3cbe-481f-8a1e-b24859c674f8" }, "create_or_update": { "user_id": "6b2a2761-3cbe-481f-8a1e-b24859c674f8", "full_name": "Bob Smith", "email_address": "bob.smith@gmail.com", "plan": "free_tier" } } ``` ```json Response theme={null} { "status": "success", "data": { "object": "product_user", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "created_at": "2025-09-04T01:23:45Z", "updated_at": "2025-09-04T01:23:45Z", "attributes": { "user_id": "6b2a2761-3cbe-481f-8a1e-b24859c674f8", "full_name": "Bob Smith", "email_address": "bob.smith@gmail.com", "plan": "free_tier" // ... } } } ``` This is a custom object, so all of these attributes are custom attributes defined for the object. Since this request uses `create_or_update`, these values will be filled in if the record is created or overridden if an existing record is found. ## Usage ## OpenAPI ````yaml POST /objects/{object_name}/records/upsert openapi: 3.1.0 info: title: Unify Data API summary: Interact with objects, attributes, and records within the Unify platform. version: '1' termsOfService: https://www.unifygtm.com/legal/terms-and-conditions contact: name: Unify Support url: https://www.unifygtm.com/support email: support@unifygtm.com servers: - url: https://api.unifygtm.com/data/v1 variables: {} security: - ApiKeyAuth: [] tags: - name: Objects - name: Object Attributes - name: Object Attribute Options - name: Object Records paths: /objects/{object_name}/records/upsert: post: tags: - Object Records operationId: upsert_object_record parameters: - name: object_name in: path required: true schema: $ref: '#/components/schemas/UObjects.UObjectName' - name: validation_mode in: query required: false schema: $ref: '#/components/schemas/ValidationMode' explode: false requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpsertRecordRequest' responses: '200': description: Response for a successful update operation. content: application/json: schema: type: object required: - status - data properties: status: type: string enum: - success data: type: object required: - object - id - created_at - updated_at - attributes properties: object: type: string description: >- The API name of the object this record is an instance of. readOnly: true id: allOf: - $ref: '#/components/schemas/UValues.UUuid' description: Unique UUID identifier for the record. readOnly: true created_at: type: string format: date-time description: Date and time the record was created. readOnly: true updated_at: type: string format: date-time description: Date and time the record was last updated. readOnly: true attributes: type: object unevaluatedProperties: anyOf: - $ref: '#/components/schemas/UValues.UValue' - type: 'null' description: >- 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. description: Response for a successful update operation. '400': description: Response for any operation that results in a bad request error. content: application/json: schema: type: object required: - status properties: status: type: string enum: - bad_request - record_missing_required_field - referenced_record_not_found errors: type: array items: $ref: '#/components/schemas/UResponses.BadRequestError' message: type: string description: >- Response for any operation that results in a bad request error. '401': description: Response for any operation that results in an unauthorized error. content: application/json: schema: type: object required: - status - message properties: status: type: string enum: - unauthorized message: type: string description: >- Response for any operation that results in an unauthorized error. '404': description: Response for any operation that results in a not found error. content: application/json: schema: type: object required: - status - message properties: status: type: string enum: - object_not_found message: type: string description: Response for any operation that results in a not found error. '409': description: Response for any operation that results in a conflict error. content: application/json: schema: type: object required: - status - message properties: status: type: string enum: - record_conflict message: type: string description: Response for any operation that results in a conflict error. '500': description: Response for any operation that results in an internal server error. content: application/json: schema: type: object required: - status - message properties: status: type: string enum: - error message: type: string description: >- Response for any operation that results in an internal server error. '503': description: Response for any operation that results in service unavailability. content: application/json: schema: type: object required: - status - message properties: status: type: string enum: - service_unavailable message: type: string description: >- Response for any operation that results in service unavailability. components: schemas: UObjects.UObjectName: type: string ValidationMode: type: string enum: - strict - ignore_invalid description: >- 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. UpsertRecordRequest: type: object required: - match properties: match: type: object unevaluatedProperties: anyOf: - $ref: '#/components/schemas/UValues.UValue' - type: 'null' description: >- 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: type: object unevaluatedProperties: $ref: '#/components/schemas/UValues.UValue' description: >- The attribute values to use when creating a new record if no match is found. update: type: object unevaluatedProperties: $ref: '#/components/schemas/UValues.UValue' description: >- The attribute values to use when updating an existing record if a match is found. update_if_empty: type: object unevaluatedProperties: $ref: '#/components/schemas/UValues.UValue' description: >- The attribute values to update when a matching record is found and the existing attribute value on the record is `null`. create_or_update: type: object unevaluatedProperties: $ref: '#/components/schemas/UValues.UValue' description: >- The attribute values to apply during both creation and update operations. create_or_update_if_empty: type: object unevaluatedProperties: $ref: '#/components/schemas/UValues.UValue' description: >- The attribute values to apply during both creation and update-if-empty operations. description: >- 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` UValues.UUuid: type: string description: String UUIDv4 value. title: UUuid UResponses.BadRequestError: type: object required: - code properties: code: type: string path: type: array items: anyOf: - type: string - type: integer object_api_name: type: string attribute_api_name: type: string allOf: - type: object unevaluatedProperties: {} description: Validation error detail returned for bad request responses. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ````