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.

200: OK The availability for the requested catalog items.

{
    "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"
        }
    ]
}

200: OK Some catalogs do not exist, but some do.

{
    "invalidCatalogIds": [999,1800],
    "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"
    }
  ]
}