Get availability

Get availability request

POST https://ris.rightsline.com/v4/avails/availability

This endpoint returns the availability for the specified catalog-items for the given dimensions.

Headers

Name
Type
Description

x-api-key

string

Your company's API key.

Authentication

string

Authentication token.

Request Body

Name
Type
Description

recordId

array

Array of type INTEGER of desired catalog items

dim1

array

Array of type INTEGER of desired dim1 values

dim2

array

Array of type INTEGER of desired dim2 values

dim3

array

Array of type INTEGER of desired dim3 values

dim4

array

Array of type INTEGER of desired dim4 values

windowStart

string

yyyy-mm-dd format

windowEnd

string

yyyy-mm-dd format

matchType

string

CoverEntire, OverlapPart, StartWithin, EndWithin

isExact

boolean

True for if the window dates should match exactly, False for flexible

isExclusive

boolean

True for Exclusive, False for Non-Exclusive, null for no value

start

string

Record count start (0-based index)

rows

integer

Page result count (25 recommended)

isWindowingEnforced

boolean

Enforce windowing

showUnavailable

boolean

Show unavailable avails

includeUserFriendlyDimensionDisplay

boolean

List out all 4 dimension fields using Excluding format if applicable.

templateIds

array

(Optional) - If recordId parameter is not included in request, you can specify specific template IDs of the catalog items instead. Array of type INTEGER.

statusIds

array

(Optional) - If recordId parameter is not included in request, you can specify specific status IDs of the catalog items instead. Array of type INTEGER.

minWindowDays

integer

(Optional) - The minimum availability window in days.

rollupDimId

integer

(Optional) - The rights dimension to rollup.

scopeExclusivity

boolean

(Optional) - Scope the results to Exclusivity.

scopeDimensions

array

(Optional) - Scope the results to specific rights dimensions. Array of type INTEGER.

rightsActions

array

(Optional) - Return the rights IDs based on these rights action rules. Array of type RightsAction.

{
    "invalidCatalogIds": [],
    "rowCount": 1,
    "rows": [
        {
            "dim1": [
                {
                    "id": 1,
                    "value": "All Media",
                    "xref": null
                }
            ],
            "dim2": [
                {
                    "id": 1,
                    "value": "World",
                    "xref": null
                }
            ],
            "dim3": [
                {
                    "id": 1,
                    "value": "All Languages",
                    "xref": null
                }
            ],
            "dim4": null,
            "id": 111,
            "isExclusive": true,
            "lastUpdatedDate": "2018-09-20T11:20:20.260Z",
            "status": {
                "statusId": 1,
                "statusName": "Approved"
            },
            "template": {
                "fields": [],
                "processId": 0,
                "processName": null,
                "templateId": 1,
                "templateName": "Series"
            },
            "title": "Title 111",
            "windowEnd": "2018-09-24",
            "windowStart": "2018-09-01"
        }
    ]
}

Request object

An API call can be made to this endpoint with a JSON body containing the following parameters:

Parameter
Type
Description
Required/Optional

recordId

array of numbers

entity ids

Required

dim1

array of numbers

Dimension Values

Optional

dim2

array of numbers

Dimension Values

Optional

dim3

array of numbers

Dimension Values

Optional

dim4

array of numbers

Dimension Values

Optional

windowStart

string

YYYY-MM-DD

Required

windowEnd

string

YYYY-MM-DD

Required

isExclusive

boolean

exclusive title flag

Optional ( defaults to true if not specified )

matchType

fixed string values

Valid Values:

CoverEntire

OverlapPart

StartWithin

EndWithin

Required

isExact

boolean

exact matches

Optional ( defaults to true if not specified )

isWindowingEnforced

boolean

enforce windowing

Optional ( defaults to false if not specified )

showUnavailable

boolean

show unavailable avails

Optional ( defaults to false if not specified )

start

number

start return row ( for pagination )

Required

rows

number

number of rows to return ( for pagination )

Required

truncateDatesToSearch

boolean

If true, the windowStart and windowEnd in the response will be truncated to the dates in the request

Optional ( defaults to false if not specified )

includeRecalcStatus

boolean

If true, a recalcStatus will be returned with the results

Optional (defaults to false if not specified )

rightTemplateIds

array of numbers

Template IDs of any rights that should be included in the response

Optional, by default no rights are returned

includeUserFriendlyDimensionDisplay

boolean

If true, a list of each dimension fields will be returned using excluding format if applicable.

Optional (defaults to false if not specified )

'IncludeUserFriendlyDimensionDisplay': Setting this parameter to true will return additional properties for the dimension data in a general string that will use exclusion logic if that string is shorter than just displaying the list of included items.

  • Media example: “All Media Excluding: SVOD”

  • Territory example: “Worldwide Excluding: France | Italy | Spain ”

  • Language example: “English (US)”

  • 4th Dimension, if hierarchical (Channel):“Amazon | Apple TV | Google Play | VUDU”

Example API request

{
"recordId": [
      36816
  ], 
  "dim1": [],
  "dim2": [],
  "dim3": [],
  "dim4": [], 
  "windowStart": "2021-10-01", 
  "windowEnd": "2021-10-31",   
  "isExclusive": false,
  "matchType": "CoverEntire",
  "isExact": false,
  "start": 0,   
  "rows": 25,
  "includeUserFriendlyDimensionDisplay": true,
  "rightsActions":[
    {
        "reasonUnavailable": "RightsOutExist",
        "rightsActionsTemplateIds":[2],
        "showDimensionLimitation": true,
        "showTermLimitation": true
    }
  ]
}

Response object

On a successful API call ( HTTP Status 200 ) the following information will be returned:

Parameter
Type
Description

invalidRecordIds

int[]

A list of catalog item IDs from the request that are invalid. The catalog either does not exist or the API user does not have access to it.

rowCount

int

number of rows returned

rows

array of availability objects ( see table below)

availability data

recalcStatus

string

Only returned if includeRecalc = true in the request. Returns 'calculating' If a recalculation of availabilities is currently underway, 'paused' if that recalculation has been paused, and 'calculated' if availability calculations are up to date.

rights

array of right objects

Distinct list of all rights involved in the availabilities returned. Only returned if rightTemplateIDs were provided in the request.

Availability object

Parameter
Type
Description

LastUpdatedDate

string

Last update date / time

Template

template data ( see table below )

Template data structure

Status

status data ( see table below )

Status data structure

WindowStart

YYYY-MM-DD

Start window date

WindowEnd

YYYY-MM-DD

End window date

Dim1

array of char data data ( see table below )

Dimension 1 data

Dim2

array of char data ( see table below )

Dimension 2 data

Dim3

array of char data ( see table below )

Dimension 3 data

Dim4

array of char data ( see table below )

Dimension 4 data

IsExclusive

bool

Flag for exclusivity

IsExact

bool

Flag for exact match

Available

string

Available status

ReasonUnavailable

string

Reason if unavailable

associatedRightIds

int[]

Specific rights involved in this availability result. Only returned if rightTemplateIDs were provided in the request.

dim1Display

string

Dimension 1 data using excluding format if applicable.

dim2Display

string

Dimension 2 data using excluding format if applicable.

dim3Display

string

Dimension 3 data using excluding format if applicable.

dim4Display

string

Dimension 4 data using excluding format if applicable.

Entity template object

Parameter
Type
Description

templateId

number

Template identifier

templateName

string

Template name

processId

number

Process identifier

processName

string

Process name

Entity status object

Parameter
Type
Description

statusId

number

Status identifier

statusName

string

Status name

Dimension data object

Parameter
Type
Description

id

number

Identifier

value

string

Dimension Value

xref

string

Dimension Cross Reference Value

Rights action object

Parameter
Type
Description

reasonUnavailable

string

The reason unavailable. Possible values can be found here.

rightsActionsTemplateIds

array

Array of type INTEGER to filter results by right template ID.

showDimensionLimitation

boolean

Show the dimension limitation in the result.

showTermLimitation

boolean

Show the term limitation in the result.

Example API response

{
  "invalidRecordIds": [],
  "rowCount": 1,
  "rows": [
    {
      "lastUpdatedDate": "2021-10-05T22:41:58.467Z",
      "template": {
        "templateId": 19,
        "templateName": "Movie",
        "processId": 0,
        "processName": null
      },
      "status": {
        "statusId": 11,
        "statusName": "Approved"
      },
      "windowStart": "2021-10-01",
      "windowEnd": "2021-10-15",
      "dim1": [
        {
           "id": 7,
           "value": "Free TV"
           "xref": null
        },
        {
            "id": 10,
            "value": "Theatrical"
            "xref": null
        },
        {
            "id": 18,
            "value": "Hotels"
            "xref": null
        },
        {
            "id": 51,
            "value": "Non-Theatrical / Public Video"
            "xref": null
        },
        {
            "id": 52,
            "value": "Pay Per View"
            "xref": null
        },
        {
            "id": 53,
            "value": "Pay TV"
            "xref": null
        },
        {
            "id": 54,
            "value": "VOD"
            "xref": null
        },
        {
            "id": 59,
            "value": "Derivative/Ancillary"
            "xref": null
       },
       {
            "id": 60,
            "value": "Other"
            "xref": null
        }
      ],
      "dim2": [
        {
          "id": 43,
          "value": "North America",
          "xref": null
        }
      ],
      "dim3": [
        {
          "id": 29,
          "value": "English",
          "xref": "en"
        }
      ],
      "dim4": null,
      "dim1Display": "All Media Excluding: Broadcast TV|Transportation|VOD 1",
      "dim2Display": "North America",
      "dim3Display": "English",
      "dim4Display": "",
      "isExclusive": false,
      "isExact": false,
      "matchType": "CoverEntire",
      "available": "Partially",
      "rightsActions": [125],
      "reasonUnavailable": "Limited (Term)",
      "id": 36816,
      "title": "title"
    }
  ]
}

PreviousGet reason unavailable listNextAvailability request vs Rights Explorer

Last updated