Record References

record_reference values point from one record to another. They live in attributes, not relationships, when the pointer is one-sided.

Reading values

{
  "value_type": "record_reference",
  "value": {
    "related_record_type": "user",
    "related_record_id": "18c7c2d2-4d66-47f4-9f68-2d5c6b7d2a31"
  }
}

If no record is set, value is null.

Writing by ID

Most reference fields accept a bare UUID:

{
  "attributes": {
    "owner_user_id": "18c7c2d2-4d66-47f4-9f68-2d5c6b7d2a31"
  }
}

Some request bodies also accept the explicit form:

{
  "attributes": {
    "owner_user_id": {
      "related_record_id": "18c7c2d2-4d66-47f4-9f68-2d5c6b7d2a31"
    }
  }
}

Writing by match

Use related_record_match when you know a unique field on the target record but not the target ID.

{
  "attributes": {
    "owner_user_id": {
      "related_record_match": {
        "email": "owner@acme.com"
      }
    }
  }
}

The match key must be unique for the target record type.

Filtering

Use equality operators for reference fields.

{
  "filters": [
    {
      "field": "owner_user_id",
      "operator": "eq",
      "value": "18c7c2d2-4d66-47f4-9f68-2d5c6b7d2a31"
    }
  ]
}

Common errors

Error code	Usually means
`invalid_matching_field`	Match field is not a valid unique field for the target
`target_record_not_found`	Target ID or match value did not resolve
`ambiguous_match`	Match value resolved to multiple records
`field_not_updatable`	Reference field is read-only

Value Types Selects and Stages

⌘I

​Record References

​Reading values

​Writing by ID

​Writing by match

​Filtering

​Common errors