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
x-api-key
string
Your company's API key.
Authentication
string
Authentication token.
Request Body
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:
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:
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
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
templateId
number
Template identifier
templateName
string
Template name
processId
number
Process identifier
processName
string
Process name
Entity status object
statusId
number
Status identifier
statusName
string
Status name
Dimension data object
id
number
Identifier
value
string
Dimension Value
xref
string
Dimension Cross Reference Value
Rights action object
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"
}
]
}Last updated
Was this helpful?