Upsert a record

v1.0.0

Use this endpoint to create or update people, companies and other records. A matching attribute is used to search for existing records. If a record is found with the same value for the matching attribute, that record will be updated. If no record with the same value for the matching attribute is found, a new record will be created instead. If you would like to avoid matching, please use the Create record action.

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.

Input

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "required": [
        "values"
      ],
      "properties": {
        "values": {
          "type": "object",
          "description": "An object with an attribute `api_slug` or `attribute_id` as the key, and a single value (for single-select attributes), or an array of values (for single or multi-select attributes) as the values. For complete documentation on values for all attribute types, please see our [attribute type docs](/docs/attribute-types)."
        }
      }
    },
    "matching_attribute": {
      "type": "string",
      "description": "The ID or slug of the attribute to use to check if a record already exists. The attribute must be unique."
    },
    "object": {
      "type": "string",
      "description": "The UUID or slug identifying the object the record should belong to."
    }
  },
  "required": [
    "data",
    "matching_attribute",
    "object"
  ],
  "additionalProperties": false
}

Output

{
  "type": "object",
  "description": "Success",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "type": "object",
      "required": [
        "created_at",
        "id",
        "values",
        "web_url"
      ],
      "properties": {
        "created_at": {
          "type": "string",
          "description": "When this record was created."
        },
        "id": {
          "type": "object",
          "required": [
            "object_id",
            "record_id",
            "workspace_id"
          ],
          "properties": {
            "object_id": {
              "type": "string",
              "format": "uuid",
              "description": "A UUID identifying the object this record belongs to."
            },
            "record_id": {
              "type": "string",
              "format": "uuid",
              "description": "A UUID identifying this record."
            },
            "workspace_id": {
              "type": "string",
              "format": "uuid",
              "description": "A UUID identifying the workspace this record belongs to."
            }
          }
        },
        "values": {
          "type": "object",
          "description": "A record type with an attribute `api_slug` as the key, and an array of value objects as the values."
        },
        "web_url": {
          "type": "string",
          "format": "uri",
          "description": "A URL that links directly to the record page in the Attio web application."
        }
      }
    }
  }
}