---
title: "Assert a deal record"
method: PUT
path: "/v2/objects/deals/records"
tags: ["Deals"]
---

# Assert a deal record

`PUT /v2/objects/deals/records`

Use this endpoint to create or update deal records, using a unique attribute to search for existing deals. By default, deals do not have a unique attribute, so you should add your own attribute with a unique constraint to use this API. If a deal is found with the same value for the matching attribute, that deal will be updated, otherwise a new deal will be created instead. If the matching attribute is a multiselect attribute, new values will be added and existing values will not be deleted. For any other multiselect attribute, all values will be either created or deleted as necessary to match the list of supplied values.

Required scopes: `record_permission:read-write`, `object_configuration:read`.

## Query parameters

- `matching_attribute` string, required — The ID or slug of the attribute to use to check if a deal already exists. The attribute must be unique. There is no unique attribute on deals by default, so you should add your own.

## Request body

- object
  - `data` object, required
    - `values` object, required — This object's keys should be the slugs or IDs of the attributes you wish to update. Below, you'll find documentation for the value types of each standard deal attribute. For information on potential custom attributes, refer to our [attribute type docs](/docs/attribute-types).
      - `name` object[]
        - `value` string, required — A raw text field. Values are limited to 10MB.
      - `stage` object[]
        - `status` string, required — The UUID or status title identifying the selected status.
      - `owner` union[]
        - union
          - object
            - `referenced_actor_type` 'workspace-member', required — The type of the referenced actor. Currently, only workspace members can be written into actor reference attributes. [Read more information on actor types here](/docs/actors).
            - `referenced_actor_id` string, uuid, required — The ID of the referenced Actor.
          - object
            - `workspace_member_email_address` string, required — Workspace member actors can be referenced by email address as well as actor ID.
      - `value` object[]
        - `currency_value` number, required — A numerical representation of the currency value. A decimal with a max of 4 decimal places.
      - `associated_people` union[]
        - union
          - object
            - `target_object` string, required — A UUID or slug to identify the object that the referenced record belongs to.
            - `target_record_id` string, uuid, required — A UUID to identify the referenced record.
          - object
            - `target_object` string, required — A UUID or slug to identify the object that the referenced record belongs to.
            - `[slug_or_id_of_matching_attribute]` union[], required — In addition to referencing records directly by record ID, you may also reference by a matching attribute of your choice. For example, if you want to add a reference to the person record with email "alice@website.com", you should pass a value with `target_object` set to `"people"` and `email_addresses` set to `[{email_address:"alice@website.com"}]`. The key should be the slug or ID of the matching attribute you would like to use and the value should be an array containing a single value of the appropriate attribute type (as specified below). Matching on multiple values is not currently supported. Matching attributes must be unique. This process is similar to how you use the `matching_attribute` query param in Attio's [assert endpoints](/rest-api/endpoint-reference/records/assert-a-record).
              - …
      - `associated_company` union[]
        - union
          - object
            - `target_object` string, required — A UUID or slug to identify the object that the referenced record belongs to.
            - `target_record_id` string, uuid, required — A UUID to identify the referenced record.
          - object
            - `target_object` string, required — A UUID or slug to identify the object that the referenced record belongs to.
            - `[slug_or_id_of_matching_attribute]` union[], required — In addition to referencing records directly by record ID, you may also reference by a matching attribute of your choice. For example, if you want to add a reference to the person record with email "alice@website.com", you should pass a value with `target_object` set to `"people"` and `email_addresses` set to `[{email_address:"alice@website.com"}]`. The key should be the slug or ID of the matching attribute you would like to use and the value should be an array containing a single value of the appropriate attribute type (as specified below). Matching on multiple values is not currently supported. Matching attributes must be unique. This process is similar to how you use the `matching_attribute` query param in Attio's [assert endpoints](/rest-api/endpoint-reference/records/assert-a-record).
              - …

## Response `200`

Success

- object — Success
  - `data` object, required
    - `id` object, required
      - `workspace_id` string, uuid, required — A UUID identifying the workspace this record belongs to.
      - `object_id` string, uuid, required — A UUID identifying the object this record belongs to.
      - `record_id` string, uuid, required — A UUID identifying this record.
    - `created_at` string, required — When this record was created.
    - `web_url` string, uri, required — A URL that links directly to the record page in the Attio web application.
    - `values` object, required — An object with `attribute_slug` keys, and an array of value objects as the values. Attributes slugs (for example `name` or `stage`) can be used, including custom attribute slugs.
      - `name` object[]
        - `active_from` string, date-time, required — The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`.
        - `active_until` string, date-time, nullable, required — The point in time at which this value was deactivated. If `null`, the value is active.
        - `created_by_actor` object, required — The actor that created this value.
          - `id` string, nullable — An ID to identify the actor.
          - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors).
        - `value` string, required — A raw text field. Values are limited to 10MB.
        - `attribute_type` 'text', required — The attribute type of the value.
      - `stage` object[]
        - `active_from` string, date-time, required — The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`.
        - `active_until` string, date-time, nullable, required — The point in time at which this value was deactivated. If `null`, the value is active.
        - `created_by_actor` object, required — The actor that created this value.
          - `id` string, nullable — An ID to identify the actor.
          - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors).
        - `status` Status, required
          - `id` object, required
            - `workspace_id` string, uuid, required — The ID of the workspace
            - `object_id` string, uuid, required — The ID of the object
            - `attribute_id` string, uuid, required — The ID of the attribute
            - `status_id` string, uuid, required — The ID of the status
          - `title` string, required — The title of the status
          - `is_archived` boolean, required — Whether or not to archive the status. See our [archiving guide](/docs/archiving-vs-deleting) for more information on archiving.
          - `celebration_enabled` boolean, required — Whether arriving at this status triggers a celebration effect in the UI
          - `target_time_in_status` string, nullable, required — Target time for a record to spend in given status expressed as a ISO-8601 duration string
        - `attribute_type` 'status', required — The attribute type of the value.
      - `owner` object[]
        - `active_from` string, date-time, required — The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`.
        - `active_until` string, date-time, nullable, required — The point in time at which this value was deactivated. If `null`, the value is active.
        - `created_by_actor` object, required — The actor that created this value.
          - `id` string, nullable — An ID to identify the actor.
          - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors).
        - `referenced_actor_type` 'api-token' | 'workspace-member' | 'system' | 'app', required — The type of the referenced actor. [Read more information on actor types here](/docs/actors).
        - `referenced_actor_id` string, uuid, nullable, required — The ID of the referenced actor.
        - `attribute_type` 'actor-reference', required — The attribute type of the value.
      - `value` object[]
        - `active_from` string, date-time, required — The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`.
        - `active_until` string, date-time, nullable, required — The point in time at which this value was deactivated. If `null`, the value is active.
        - `created_by_actor` object, required — The actor that created this value.
          - `id` string, nullable — An ID to identify the actor.
          - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors).
        - `currency_value` number, required — A numerical representation of the currency value. A decimal with a max of 4 decimal places.
        - `currency_code` 'AUD' | 'BRL' | 'BEL' | 'CAD' | 'CNY' | 'COP' | 'CZK' | 'DKK' | 'EUR' | 'HKD' | 'ISK' | 'INR' | 'ILS' | 'JPY' | 'KRW' | 'MYR' | 'MXN' | 'NTD' | 'NZD' | 'NGN' | 'NOK' | 'XPF' | 'PEN' | 'PHP' | 'PLN' | 'GBP' | 'SAR' | 'SGD' | 'ZAR' | 'SEK' | 'CHF' | 'AED' | 'USD', nullable — The ISO4217 currency code representing the currency that the value is stored in.
        - `attribute_type` 'currency', required — The attribute type of the value.
      - `associated_people` object[]
        - `active_from` string, date-time, required — The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`.
        - `active_until` string, date-time, nullable, required — The point in time at which this value was deactivated. If `null`, the value is active.
        - `created_by_actor` object, required — The actor that created this value.
          - `id` string, nullable — An ID to identify the actor.
          - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors).
        - `target_object` string, required — A slug identifying the object that the referenced record belongs to.
        - `target_record_id` string, uuid, required — A UUID to identify the referenced record.
        - `attribute_type` 'record-reference', required — The attribute type of the value.
      - `associated_company` object[]
        - `active_from` string, date-time, required — The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`.
        - `active_until` string, date-time, nullable, required — The point in time at which this value was deactivated. If `null`, the value is active.
        - `created_by_actor` object, required — The actor that created this value.
          - `id` string, nullable — An ID to identify the actor.
          - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors).
        - `target_object` string, required — A slug identifying the object that the referenced record belongs to.
        - `target_record_id` string, uuid, required — A UUID to identify the referenced record.
        - `attribute_type` 'record-reference', required — The attribute type of the value.

## Other responses

- `400` — Bad Request
- `404` — Not Found

---

[API](https://skmtc.dev/attio/apis/attio-standard-objects.md) · [All operations](https://skmtc.dev/attio/apis/attio-standard-objects/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/attio/attio-standard-objects/revisions/d6d3cac7a275/schema)