# 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`. | {% tabs %} {% tab title="200: OK The availability for the requested catalog items." %} ```javascript { "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" } ] } ``` {% endtab %} {% tab title="200: OK Some catalogs do not exist, but some do." %} ```json { "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" } ] } ``` {% endtab %} {% endtabs %} ## Request object An API call can be made to this endpoint with a JSON body containing the following parameters:
ParameterTypeDescriptionRequired/Optional
recordIdarray of numbersentity idsRequired
dim1array of numbersDimension ValuesOptional
dim2array of numbersDimension ValuesOptional
dim3array of numbersDimension ValuesOptional
dim4array of numbersDimension ValuesOptional
windowStartstringYYYY-MM-DD Required
windowEndstringYYYY-MM-DDRequired
isExclusivebooleanexclusive title flagOptional ( defaults to true if not specified )
matchTypefixed string values

Valid Values:

CoverEntire

OverlapPart

StartWithin

EndWithin

Required
isExactbooleanexact matchesOptional ( defaults to true if not specified )
isWindowingEnforcedbooleanenforce windowingOptional ( defaults to false if not specified )
showUnavailablebooleanshow unavailable availsOptional ( defaults to false if not specified )
startnumberstart return row ( for pagination )Required
rowsnumbernumber of rows to return ( for pagination )Required
truncateDatesToSearchbooleanIf true, the windowStart and windowEnd in the response will be truncated to the dates in the requestOptional ( defaults to false if not specified )
includeRecalcStatusbooleanIf true, a recalcStatus will be returned with the resultsOptional (defaults to false if not specified )
rightTemplateIdsarray of numbersTemplate IDs of any rights that should be included in the responseOptional, by default no rights are returned
includeUserFriendlyDimensionDisplaybooleanIf 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 ```json { "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:
ParameterTypeDescription
invalidRecordIdsint[]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.
rowCountintnumber of rows returned
rowsarray of availability objects ( see table below)availability data
recalcStatusstringOnly 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.
rightsarray of right objectsDistinct 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
ParameterTypeDescription
templateIdnumberTemplate identifier
templateNamestringTemplate name
processIdnumberProcess identifier
processNamestringProcess name
### **Entity status object**
ParameterTypeDescription
statusIdnumberStatus identifier
statusNamestringStatus 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](/avails/avails-reason-unavailable-list.md). | | 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 ```json { "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" } ] } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://api-docs.rightsline.com/avails/avails-get-availability.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.