Read paired-value fields

Paired-value fields are used to pair different types of metadata as a single value in a field. For example, suppose all videos require a team of contributors, including an editor, product marketing manager, and voice talent. Each video’s metadata must include each team member and their role. You can create a paired-value field called “Video Team.” The first value would designate the contributor, and the second value would be the production role.

You can create paired-value fields with these sets of metadata:

• Two authority lists (Example: A marketing campaign and a brand spotlight)
• An authority list and a free-text field or vice versa (Example: A production partner and a note describing their involvement in the project)
• An authority list and a linked field or vice versa (Example: A video production role and a contributor’s name linked to their account)

Each paired value is returned as an object with a ValueLeft and a ValueRight property, nested under the field's name in APIResponse.Items:

"Marketing.ProductionStatus": [
    {
        "ValueLeft": "Active",
        "ValueRight": "New York"
    }
]

ValueLeft and ValueRight preserve the left and right sides of the pair exactly as configured on the field. The following table describes the left and right values based on the paired-value field’s configuration.

Additional properties by pairing mode

Depending on the pairing mode, a paired value can include additional properties.

Handle empty values and unresolved linked records

Two edge cases apply to any pairing mode:

• A side can be empty. If the field configuration permits it, either ValueLeft or ValueRight can be an empty string.
• A linked record can fail to resolve. Orange Logic can't always resolve a linked record's display text, for example when the record was deleted or the requesting user lacks permission to access it. When that happens, the corresponding ValueLeft or ValueRight falls back to the record-ID representation instead of the display value.

⚠️

Caution:

A paired-value field can also return a Value property, a single formatted string combining both sides for display (for example, Active (New York)). Value is a display convenience, not a stable data contract. Its format can change with the field's display template. Build integrations against ValueLeft, ValueRight, and the field's configured pairing mode, not against Value.

Example

The following call returns the Marketing.ProductionStatus paired field (an authority-list + free-text pairing) for images with "London" in the title:

curl -X 'GET' \
  'https://mangovations.orangelogic.com/API/Search/v4.0/Search?query=title%3ALondon&fields=Marketing.ProductionStatus&fields=SystemIdentifier&pagenumber=1&format=JSON' \
  -H 'accept: application/json'

This returns:

{
    "APIResponse": {
        "GlobalInfo": {
            "TotalCount": 1
        },
        "Items": [
            {
                "SystemIdentifier": "ZZ13UJ5",
                "Marketing.ProductionStatus": [
                    {
                        "ValueLeft": "Active",
                        "ValueRight": "New York",
                        "LinkedText": "New York",
                        "Value": "Active (New York)"
                    }
                ]
            }
        ]
    }
}