API Reference

Update paired-value fields

Call template

https://{OrangeLogicURL}/API/v2.2/DataTable/Documents.[type].[subtype]:CreateOrUpdate?CoreField.Identifier=[unique identifier]&[paired-value field’s API name][+ or ++]=[Authority list value]{“Linked[Keyword, Text, or Field]”:”[Value in the second authority list, free text, or the linked field’s record ID]”}

All DataTable calls can be POST or GET.

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.

"Video production" paired value field. The first value links to a user's account, and the second value is a value in the production role authority list.

"Video production" paired value field. The first value links to a user's account, and the second value is a value in the production role authority list.

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)

The syntax for the call varies depending on the field’s pairing mode. Refer to the sections below for each pairing mode’s syntax and an example.

The plus sign operators (+= or ++=) indicate whether you want to create a new value in the field’s authority list:

  • Use += if the value already exists in the authority list.
  • Use ++= if the value does not exist and you want to create a new one.

To add multiple paired values to the field, separate each pair with a pipe (|). The second example in the "Pair an authority list with another authority list" section provides sample syntax to add multiple pairs to a field.

ℹ️

Note

The paired-value field must have the Allow creation of new tag values setting activated if you want users to use the ++= operator to add new values to authority lists.

Additional resource: Paired-value fields

Pair an authority list with another authority list

Syntax: /API/v2.2/DataTable/Documents.[type].[subtype]:CreateOrUpdate?CoreField.Identifier=[asset’s Unique Identifier]&[paired-value field’s API Name][+ or ++]=[Value in first authority list]{"LinkedKeyword":"[Value in second authority list]"}

Example 1: Add a single paired value to the field

Let’s say you have a paired-value field called “Marketing campaign” for product photos. Each marketing campaign is paired with a brand in parentheses. The campaign and brand values each belong to separate authority lists.

The following call updates the “Marketing campaign” paired value field for the product photo with a unique ID of ZZ1428I. The new field value will be “Create Your Dream Home (Mango Atelier).” Neither tag exists in the corresponding authority list, so the ++= operator is used to create the new values.

/API/v2.2/DataTable/Documents.Image.Product-Photo:CreateOrUpdate?CoreField.Identifier=ZZ1428I&products.Marketing-campaign++=Create Your Dream Home{“LinkedKeyword”:”Mango Atelier”}

Example call 
curl --location 'https://university1.orangelogic.com/API/v2.2/DataTable/Documents.Image.Product-Photo:CreateOrUpdate' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer ...' \
--header 'Cookie: ...' \
--data-urlencode 'CoreField.Identifier=ZZ1428I' \
--data-urlencode '%26products.Marketing-campaign%2B%2B%3D=Create%20Your%20Dream%20Home{%22LinkedKeyword%22%3A%22Mango%20Atelier%22}'
Response 
<Result>
    <APIRequestInfo>
        <ProviderVersion>MILAN.R4.2162P.218145</ProviderVersion>
        <ProviderIdentity>OLU-T-USW2-APP</ProviderIdentity>
        <ProviderID>44ddde3ac27a33c394335f249d4007d4</ProviderID>
        <Module>DataTable</Module>
        <APIVersion>v2.2</APIVersion>
        <Resource>Documents.Image.Product-Photo:CreateOrUpdate</Resource>
        <IsLoggedIn type="Boolean">True</IsLoggedIn>
        <Status>LoggedIn</Status>
        <UserLogin></UserLogin>
        <Session>No session (production configuration)</Session>
        <TimeoutPeriodMinutes type="Numeric">30</TimeoutPeriodMinutes>
    </APIRequestInfo>
    <RequestInterpretation>
        <Filters type="List">
            <Filter>
                <Field>CoreField.Identifier</Field>
                <Operator>=</Operator>
                <OperatorDescription>Field must be equal to value</OperatorDescription>
                <Value>ZZ1428I</Value>
            </Filter>
        </Filters>
        <Updates type="List" />
        <IgnoredParameters type="List">
            <Parameter>
                <Field>products.Marketing-campaign++=</Field>
                <Value>Create Your Dream Home{"LinkedKeyword":"Mango Atelier"}</Value>
            </Parameter>
        </IgnoredParameters>
    </RequestInterpretation>
    <ResponseSummary>
        <NumberOfRecordsAffected type="Numeric">1</NumberOfRecordsAffected>
    </ResponseSummary>
    <Response>
        <RecordsAffected type="List">
            <Result>
                <RecordID>2QDTWA7D6A5</RecordID>
                <Code>SUCCESS</Code>
            </Result>
        </RecordsAffected>
    </Response>
</Result>

Example 2: Add multiple paired values to the field

Let’s say you have a paired-value field called “Marketing campaign” for product photos. Each marketing campaign is paired with a brand in parentheses. The campaign and brand values each belong to separate authority lists.

The following call adds three pairs to the “Marketing campaign” field for the product photo with a unique ID of ZZ1428I.

New field values:

  • Backyard Renovations (Coral Designs)
  • Create Your Dream Home (Mango Atelier)
  • Home Makeover (Coral Designs)

Each tag exists in the corresponding authority list, so the += operator is used.

/API/v2.2/DataTable/Documents.Image.Product-Photo:CreateOrUpdate?CoreField.Identifier=ZZ1428I&products.Marketing-campaign+=Backyard Renovations{"LinkedKeyword":"Coral Designs"}|Create Your Dream Home{"LinkedKeyword":"Mango Atelier"}|Home Makeover{"LinkedKeyword":"Coral Designs"}

Example call 
curl --location 'https://university1.orangelogic.com/API/v2.2/DataTable/Documents.Image.Product-Photo:CreateOrUpdate' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer ...' \
--header 'Cookie: ...' \
--data-urlencode 'CoreField.Identifier=ZZ1428I' \
--data-urlencode 'products.Marketing-campaign%2B%3D=Backyard Renovations{"LinkedKeyword":"Coral Designs"}|Create Your Dream Home{"LinkedKeyword":"Mango Atelier"}|Home Makeover{"LinkedKeyword":"Coral Designs"}
Response 
<Result>
    <APIRequestInfo>
        <ProviderVersion>MILAN.R4.2162P.218145</ProviderVersion>
        <ProviderIdentity>OLU-T-USW2-APP</ProviderIdentity>
        <ProviderID>44ddde3ac27a33c394335f249d4007d4</ProviderID>
        <Module>DataTable</Module>
        <APIVersion>v2.2</APIVersion>
        <Resource>Documents.Image.Product-Photo:CreateOrUpdate</Resource>
        <IsLoggedIn type="Boolean">True</IsLoggedIn>
        <Status>LoggedIn</Status>
        <UserLogin></UserLogin>
        <Session>No session (production configuration)</Session>
        <TimeoutPeriodMinutes type="Numeric">120</TimeoutPeriodMinutes>
    </APIRequestInfo>
    <RequestInterpretation>
        <Filters type="List">
            <Filter>
                <Field>CoreField.Identifier</Field>
                <Operator>=</Operator>
                <OperatorDescription>Field must be equal to value</OperatorDescription>
                <Value>ZZ1428I</Value>
            </Filter>
        </Filters>
        <Updates type="List" />
        <IgnoredParameters type="List">
            <Parameter>
                <Field>products.Marketing-campaign+=</Field>
                <Value>Backyard Renovations{"LinkedKeyword":"Coral Designs"}|Create Your Dream Home{"LinkedKeyword":"Mango Atelier"}|Home Makeover{"LinkedKeyword":"Coral Designs"}</Value>
            </Parameter>
        </IgnoredParameters>
    </RequestInterpretation>
    <ResponseSummary>
        <NumberOfRecordsAffected type="Numeric">1</NumberOfRecordsAffected>
    </ResponseSummary>
    <Response>
        <RecordsAffected type="List">
            <Result>
                <RecordID>2QDTWA7D6A5</RecordID>
                <Code>SUCCESS</Code>
            </Result>
        </RecordsAffected>
    </Response>
</Result>

Pair an authority list with free text

Syntax: /API/v2.2/DataTable/Documents.[type].[subtype]:CreateOrUpdate?CoreField.Identifier=[asset’s Unique Identifier]&[field’s API Name][+ or ++]=[Value in authority list]{"LinkedText":"[Free text]"}

This syntax works when the authority list precedes the free text field and vice versa.

Example

Let’s say you have a “Production partner” paired-value field that pairs production partners with a free text field for users to note the partner’s level of involvement. The following call updates the “Production partner” paired value field in the marketing video with a unique ID of ZZ11AKZ to “Clementine Studios (Secondary sponsor).” “Clementine Studios” is an existing value in the authority list, so the += operator is used. The “Secondary sponsor” text is free text.

/API/v2.2/DataTable/Documents.Video.Marketing-Video:CreateOrUpdate?CoreField.Identifier=ZZ11AKZ'&media.Production-partner+=Clementine Studios{"LinkedText":"Secondary sponsor"}

Example call 
curl --location 'https://university1.orangelogic.com/API/v2.2/DataTable/Documents.Video.Marketing-Video:CreateOrUpdate' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer ...' \
--header 'Cookie: ...' \
--data-urlencode 'CoreField.Identifier=ZZ11AKZ' \
--data-urlencode 'media.Production-partner%2B%3D=Clementine%20Studios{%22LinkedText%22%3A%22Secondary%20sponsor%22}'
Response 
<Result>
    <APIRequestInfo>
        <ProviderVersion>MILAN.R4.2162P.218145</ProviderVersion>
        <ProviderIdentity>OLU-T-USW2-APP</ProviderIdentity>
        <ProviderID>44ddde3ac27a33c394335f249d4007d4</ProviderID>
        <Module>DataTable</Module>
        <APIVersion>v2.2</APIVersion>
        <Resource>Documents.Video.Marketing-Video:CreateOrUpdate</Resource>
        <IsLoggedIn type="Boolean">True</IsLoggedIn>
        <Status>LoggedIn</Status>
        <UserLogin></UserLogin>
        <Session>No session (production configuration)</Session>
        <TimeoutPeriodMinutes type="Numeric">120</TimeoutPeriodMinutes>
    </APIRequestInfo>
    <RequestInterpretation>
        <Filters type="List">
            <Filter>
                <Field>CoreField.Identifier</Field>
                <Operator>=</Operator>
                <OperatorDescription>Field must be equal to value</OperatorDescription>
                <Value>ZZ11AKZ</Value>
            </Filter>
        </Filters>
        <Updates type="List" />
        <IgnoredParameters type="List">
            <Parameter>
                <Field>media.Production-partner+=</Field>
                <Value>Clementine%20Studios{%22LinkedText%22%3A%22Secondary%20sponsor%22}</Value>
            </Parameter>
        </IgnoredParameters>
    </RequestInterpretation>
    <ResponseSummary>
        <NumberOfRecordsAffected type="Numeric">1</NumberOfRecordsAffected>
    </ResponseSummary>
    <Response>
        <RecordsAffected type="List">
            <Result>
                <RecordID>2QDTWAGH27Z</RecordID>
                <Code>SUCCESS</Code>
            </Result>
        </RecordsAffected>
    </Response>
</Result>

Pair an authority list with a linked field

Syntax: /API/v2.2/DataTable/Documents.Image.Default:CreateOrUpdate?CoreField.Identifier=[asset’s Unique Identifier]&[field’s API Name][+ or ++]=[Value in authority list]{"LinkedField":"[linked asset’s record ID"}

To link an asset or contact to a paired-value field, you must first obtain the asset or contact’s record ID.
This syntax works when the authority list precedes the link and vice versa.

Example

Let’s say you have a paired-value field called “Video Team” that pairs a user account (linked field) with that person’s role on the video production team (authority list).

The following call updates the “Video team” paired value field in the promo video with a unique ID of ZZ11AKZ to “Will Hudson (Voice talent).” Will Hudson’s account record ID is K8OEC0XK0H, and “Voice talent” is an existing value in the corresponding authority list, so the += operator is used.

/API/v2.2/DataTable/Documents.Video.Promo:CreateOrUpdate?CoreField.Identifier=ZZ11AKZ'&media.Video-team+=Voice talent{"LinkedField":"K8OEC0XK0H"}

Example call 
curl --location 'https://university1.orangelogic.com/API/v2.2/DataTable/Documents.Video.Promo:CreateOrUpdate' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer ...' \
--header 'Cookie: ...' \
--data-urlencode 'CoreField.Identifier=ZZ11AKZ' \
--data-urlencode 'media.Video-team%2B%3D=Voice talent{"LinkedField":"K8OEC0XK0H"}'
Response 
<Result>
    <APIRequestInfo>
        <ProviderVersion>MILAN.R4.2162P.218145</ProviderVersion>
        <ProviderIdentity>OLU-T-USW2-APP</ProviderIdentity>
        <ProviderID>44ddde3ac27a33c394335f249d4007d4</ProviderID>
        <Module>DataTable</Module>
        <APIVersion>v2.2</APIVersion>
        <Resource>Documents.Video.Promo:CreateOrUpdate</Resource>
        <IsLoggedIn type="Boolean">True</IsLoggedIn>
        <Status>LoggedIn</Status>
        <UserLogin></UserLogin>
        <Session>No session (production configuration)</Session>
        <TimeoutPeriodMinutes type="Numeric">120</TimeoutPeriodMinutes>
    </APIRequestInfo>
    <RequestInterpretation>
        <Filters type="List">
            <Filter>
                <Field>CoreField.Identifier</Field>
                <Operator>=</Operator>
                <OperatorDescription>Field must be equal to value</OperatorDescription>
                <Value>ZZ11AKZ</Value>
            </Filter>
        </Filters>
        <Updates type="List" />
        <IgnoredParameters type="List">
            <Parameter>
                <Field>media.Video-team+=</Field>
                <Value>Voice talent{"LinkedField":"K8OEC0XK0H"}</Value>
            </Parameter>
        </IgnoredParameters>
    </RequestInterpretation>
    <ResponseSummary>
        <NumberOfRecordsAffected type="Numeric">1</NumberOfRecordsAffected>
    </ResponseSummary>
    <Response>
        <RecordsAffected type="List">
            <Result>
                <RecordID>2QDTWAGH27Z</RecordID>
                <Code>SUCCESS</Code>
            </Result>
        </RecordsAffected>
    </Response>
</Result>