On Demand documentation on Vimeo Developer API

Add a genre to an On Demand page

PUT https://api.vimeo.com/ondemand/pages/{ondemand_id}/genres/{genre_id} Playground

This method requires a token with the "edit" scope.

HTTP Status Code	Explanation
201 Created
404 Not Found	If the On Demand page cannot be found.
403 Forbidden	If you are attempting to modify an On Demand page you do not own.
400 Bad Request	If you attempt to add more than 2 genres to an On Demand page.

Add a poster to an On Demand page

POST https://api.vimeo.com/ondemand/pages/{ondemand_id}/pictures Playground

This method requires a token with the "upload" scope.

HTTP Status Code	Explanation
201 Created
403 Forbidden	If you are modifying another users On Demand page.

Add a promotion to an On Demand page

POST https://api.vimeo.com/ondemand/pages/{ondemand_id}/promotions Playground

This method requires a token with the "promo_codes" scope.

Name	Type	Required	Description
access_type	string default vip	No	Promotion access type a purchase option that is not available on the container. "vip" promotions will always make the content free, and must be further defined with the download or stream_period fields.
code	string	Yes	If you are only creating a single promotion code, you can provide the value here. This field will be rejected for batch promotions.
discount_type	string free percent	No	Describes the type of discount offered by this promo code. Note: When providing an accesstype of "vip", this field only accepts the "free" discounttype.
download	boolean	Yes	Whether this promotion grants download access to vod content. This is only necessary when not defined on the On Demand Container, and creating promotions with the "vip" accesstype and "buy" producttype
end_time	timestamp	No	The latest time this promotion is valid. If end_time is not specified, the promotion will never expire.
label	string	Yes	If you are creating a batch promotion, you can describe it here. This field will be rejected for single promotions.
percent_off	integer	Yes	The percentage saved by using this promo code. This field is required, and only applicable if the field discount_type is set to percent.
product_type	string any buy buy_episode rent rent_episode subscribe	No	Restricts the promotion to a particular type of transaction. Defaults to "any" when accesstype is "default", and to "rent" if the accesstype is "vip". Only "buy" and "rent" are valid if the access_type is "vip".
start_time	timestamp	No	The earliest time this promotion is valid. If start_time is not specified, it will default to the time the promotion was created.
stream_period	string 1_week 1_year 24_hour 30_day 3_month 48_hour 6_month 72_hour	Yes	The amount of time a user will have access to the vod content upon redeeming a promo code. This is only necessary when not defined on the On Demand Container, and creating promotions with the "vip" accesstype and "rent" producttype.
total	integer	Yes	Number of promotions to generate if type is batch. The amount of uses for the promotion if type is single.
type	string batch single	Yes	Type of promotions to use. If the access type is "vip", the only possible value for this field is batch.

HTTP Status Code	Explanation
200 OK
404 Not Found	If the On Demand page cannot be found.
403 Forbidden	If you are attempting to create promotions for an On Demand page you do not own.
400 Bad Request	If errors exist in the request.
400 Bad Request	If that promo code already exists.

Add a region to an On Demand page

PUT https://api.vimeo.com/ondemand/pages/{ondemand_id}/regions/{country} Playground

This method requires a token with the "edit" scope.

HTTP Status Code	Explanation
201 Created
404 Not Found	If the On Demand page cannot be found.
404 Not Found	If the On Demand region cannot be found.
403 Forbidden	If you are attempting to modify an On Demand page you do not own.

Add a video to an On Demand page

PUT https://api.vimeo.com/ondemand/pages/{ondemand_id}/videos/{video_id} Playground

This method requires a token with the "edit" scope.

Name	Type	Required	Description
buy.price.AUD	float	No	The purchase price of this video in AUD.
buy.price.CAD	float	No	The purchase price of this video in CAD.
buy.price.CHF	float	No	The purchase price of this video in CHF.
buy.price.DKK	float	No	The purchase price of this video in DKK.
buy.price.EUR	float	No	The purchase price of this video in EUR.
buy.price.GBP	float	No	The purchase price of this video in GBP.
buy.price.JPY	float	No	The purchase price of this video in JPY.
buy.price.KRW	float	No	The purchase price of this video in KRW.
buy.price.NOK	float	No	The purchase price of this video in NOK.
buy.price.PLN	float	No	The purchase price of this video in PLN.
buy.price.SEK	float	No	The purchase price of this video in SEK.
buy.price.USD	float	No	The purchase price of this video. Required if buy.active is true.
position	number	No	The position this video will appear in this On Demand's video collection.
release_year	integer	No	The video release year.
rent.price.AUD	float	No	The rental price of this video in AUD.
rent.price.CAD	float	No	The rental price of this video in CAD.
rent.price.CHF	float	No	The rental price of this video in CHF.
rent.price.DKK	float	No	The rental price of this video in DKK.
rent.price.EUR	float	No	The rental price of this video in EUR.
rent.price.GBP	float	No	The rental price of this video in GBP.
rent.price.JPY	float	No	The rental price of this video in JPY.
rent.price.KRW	float	No	The rental price of this video in KRW.
rent.price.NOK	float	No	The rental price of this video in NOK.
rent.price.PLN	float	No	The rental price of this video in PLN.
rent.price.SEK	float	No	The rental price of this video in SEK.
rent.price.USD	float	No	The rental price of this video in USD. Required if rent.active is true.
type	string extra main trailer	Yes	The type of video you are associating with the On Demand page.

HTTP Status Code	Explanation
200 OK
403 Forbidden	If you are not modifying your own On Demand page.
400 Bad Request	If you are unable to add the video to this On Demand page for any reason.

Check if you have purchased an On Demand page

GET https://api.vimeo.com/me/ondemand/purchases/{ondemand_id} Playground

GET https://api.vimeo.com/users/{user_id}/ondemand/purchases Playground

This method requires a token with the "purchased" scope.

HTTP Status Code	Explanation
200 OK
404 Not Found	If the user cannot be found.
404 Not Found	If the On Demand page cannot be found in the purchases.
403 Forbidden	If the requested user is not the same as the authenticated user.

Create a new background for an On Demand page

POST https://api.vimeo.com/ondemand/pages/{ondemand_id}/backgrounds Playground

This method requires a token with the "upload" scope.

HTTP Status Code	Explanation
200 OK
404 Not Found	If the On Demand page cannot be found.
403 Forbidden	If you are modifying another users On Demand page.

Create an On Demand page

POST https://api.vimeo.com/me/ondemand/pages Playground

POST https://api.vimeo.com/users/{user_id}/ondemand/pages Playground

Name	Type	Required	Description
accepted_currencies	string	No	List of accepted currencies.
buy.active	boolean	No	Required if rent.active is false.
buy.download	boolean	No	If download is available to purchasers who buy the film.
buy.price.AUD	float	No	The purchase price of this video in AUD.
buy.price.CAD	float	No	The purchase price of this video in CAD.
buy.price.CHF	float	No	The purchase price of this video in CHF.
buy.price.DKK	float	No	The purchase price of this video in DKK.
buy.price.EUR	float	No	The purchase price of this video in EUR.
buy.price.GBP	float	No	The purchase price of this video in GBP.
buy.price.JPY	float	No	The purchase price of this video in JPY.
buy.price.KRW	float	No	The purchase price of this video in KRW.
buy.price.NOK	float	No	The purchase price of this video in NOK.
buy.price.PLN	float	No	The purchase price of this video in PLN.
buy.price.SEK	float	No	The purchase price of this video in SEK.
buy.price.USD	float	No	Required if buy.active is true. If this On Demand page is a `film`, this is the price to purchase the film. If `series`, this is the price to purchase the entire collection.
content_rating	string drugs language nudity safe unrated violence	Yes	One or more ratings, comma separated or JSON array depending on your request format.
description	string	Yes	The On Demand page description.
domain_link	string	No	The On Demand page's custom domain.
episodes.buy.active	boolean	No	Whether episodes can be bought
episodes.buy.download	boolean	No	If download is available to purchasers who buy the episode.
episodes.buy.price.USD	float	No	Required if episodes.buy.active is true.
episodes.rent.active	boolean	No	Whether episodes can be rented
episodes.rent.period	string	No	Required if episodes.rent.active is true.
episodes.rent.price.USD	float	No	Required if episodes.rent.active is true. Only applicable if this On Demand page is a series. This is the default price for each individual episode.
link	string	No	The custom string to use in this On Demand page's Vimeo URL.
name	string	Yes	The On Demand page name.
rent.active	boolean	No	Required if buy.active is false.
rent.period	string	No	Required if rent.active is true.
rent.price.AUD	float	No	The rental price of this video in AUD.
rent.price.CAD	float	No	The rental price of this video in CAD.
rent.price.CHF	float	No	The rental price of this video in CHF.
rent.price.DKK	float	No	The rental price of this video in DKK.
rent.price.EUR	float	No	The rental price of this video in EUR.
rent.price.GBP	float	No	The rental price of this video in GBP.
rent.price.JPY	float	No	The rental price of this video in JPY.
rent.price.KRW	float	No	The rental price of this video in KRW.
rent.price.NOK	float	No	The rental price of this video in NOK.
rent.price.PLN	float	No	The rental price of this video in PLN.
rent.price.SEK	float	No	The rental price of this video in SEK.
rent.price.USD	float	No	Required if rent.active is true. If this On Demand page is a `film`, this is the price to rent the film. If `series`, this is the price to rent the entire collection.
subscription.monthly.active	boolean	No	Required if rent.active and buy.active are false.
subscription.monthly.price.USD	float	No	Required if subscription.active is true.
type	string film series	Yes	The On Demand page type.

HTTP Status Code	Explanation
200 OK

Delete a genre from an On Demand page

DELETE https://api.vimeo.com/ondemand/pages/{ondemand_id}/genres/{genre_id} Playground

This method requires a token with the "edit" scope.

HTTP Status Code	Explanation
204 No Content
404 Not Found	If the On Demand page cannot be found.
404 Not Found	If the On Demand genre cannot be found.
403 Forbidden	If you are attempting to modify an On Demand page you do not own.
400 Bad Request	If you are attempting to remove the final On Demand genre from a page.

Delete a list of regions from an On Demand page

DELETE https://api.vimeo.com/ondemand/pages/{ondemand_id}/regions Playground

This method requires a token with the "edit" scope.

HTTP Status Code	Explanation
200 OK
404 Not Found	If the On Demand page cannot be found.
404 Not Found	If the On Demand region cannot be found.
403 Forbidden	If you are attempting to modify an On Demand page you do not own.

Delete a region from an On Demand page

DELETE https://api.vimeo.com/ondemand/pages/{ondemand_id}/regions/{country} Playground

This method requires a token with the "edit" scope.

HTTP Status Code	Explanation
204 No Content
404 Not Found	If the On Demand page cannot be found.
404 Not Found	If the On Demand region cannot be found.
403 Forbidden	If you are attempting to modify an On Demand page you do not own.

Delete a video from an On Demand page

DELETE https://api.vimeo.com/ondemand/pages/{ondemand_id}/videos/{video_id} Playground

This method requires a token with the "edit" scope.

HTTP Status Code	Explanation
204 No Content
403 Forbidden	If you are not modifying your own On Demand page.

Delete an On Demand page

DELETE https://api.vimeo.com/ondemand/pages/{ondemand_id} Playground

This method requires a token with the "delete" scope.

HTTP Status Code	Explanation
204 No Content
404 Not Found	If the On Demand page cannot be found.
403 Forbidden	If you are attempting to modify an On Demand page you do not own.
400 Bad Request	If you are attempting to remove the final On Demand genre from a page.

Delete an On Demand pages' background

DELETE https://api.vimeo.com/ondemand/pages/{ondemand_id}/backgrounds/{background_id} Playground

This method requires a token with the "edit" scope.

HTTP Status Code	Explanation
200 OK
404 Not Found	If the On Demand page cannot be found.
404 Not Found	If the On Demand image cannot be found.
403 Forbidden	If you are attempting to modify an On Demand page you do not own.

Delete an On Demand pages' promotion

DELETE https://api.vimeo.com/ondemand/pages/{ondemand_id}/promotions/{promotion_id} Playground

This method requires a token with the "promo_codes" scope.

HTTP Status Code	Explanation
204 No Content
404 Not Found	If the On Demand page cannot be found.
404 Not Found	If the promotion cannot be found.
403 Forbidden	If you are attempting to delete a promotion for an On Demand page you do not own.

Edit an On Demand page

PATCH https://api.vimeo.com/ondemand/pages/{ondemand_id} Playground

This method requires a token with the "edit" scope.

Name	Type	Required	Description
link	string	No	The custom string to use in this On Demand page's Vimeo URL.
preorder.active	boolean	No	If set to true, you will enable pre-orders on the On Demand page.
preorder.publish_time	boolean	No	Required if "preorder.active" is true. The time that the On Demand page will be published.
publish.active	boolean	No	If set to true, you will publish the On Demand page.
publish_when_ready	boolean	No	This On Demand page will be automatically published when all videos are finished transcoding.

HTTP Status Code	Explanation
200 OK
404 Not Found	If the On Demand page cannot be found.
403 Forbidden	If the authenticated user does not have permission to edit the On Demand page.

Edit an On Demand pages' background

PATCH https://api.vimeo.com/ondemand/pages/{ondemand_id}/backgrounds/{background_id} Playground

This method requires a token with the "edit" scope.

Name	Type	Required	Description
active	boolean	No	Set this background as the active background.

Name

Type

Required

Description

active

boolean

No

Set this background as the active background.

HTTP Status Code	Explanation
200 OK
404 Not Found	If the On Demand page cannot be found.
404 Not Found	If the On Demand image cannot be found.
403 Forbidden	If you are attempting to modify an On Demand page you do not own.

Edit an On Demand pages' poster

PATCH https://api.vimeo.com/ondemand/pages/{ondemand_id}/pictures/{poster_id} Playground

This method requires a token with the "edit" scope.

Name	Type	Required	Description
active	boolean	No	Set this picture as the active picture.

Name

Type

Required

Description

active

boolean

No

Set this picture as the active picture.

HTTP Status Code	Explanation
200 OK

Get a season of an On Demand page

GET https://api.vimeo.com/ondemand/pages/{ondemand_id}/seasons/{season_id} Playground

HTTP Status Code	Explanation
200 OK
404 Not Found	If the On Demand page cannot be found.
404 Not Found	If the On Demand season cannot be found in the On Demand page.

Get a users' On Demand pages

GET https://api.vimeo.com/me/ondemand/pages Playground

GET https://api.vimeo.com/users/{user_id}/ondemand/pages Playground

Name	Type	Required	Description
filter	string film series	No	Filter to apply to the results. Type of On Demand pages to display
page	integer	No	The page number to show. Page for paging
per_page	integer	No	Number of items to show on each page. Max 100. How many On Demand pages to display at a time
sort	string added modified_time name publish.time rating	No	Technique used to sort the results.

HTTP Status Code	Explanation
200 OK
404 Not Found	If the user cannot be found.

Get a video in an On Demand page

GET https://api.vimeo.com/ondemand/pages/{ondemand_id}/videos/{video_id} Playground

HTTP Status Code	Explanation
200 OK	If you're pulling the On Demand video object.
200 OK

Get all On Demand genres

GET https://api.vimeo.com/ondemand/genres Playground

HTTP Status Code	Explanation
200 OK

Get all On Demand pages within a genre

GET https://api.vimeo.com/ondemand/genres/{genre_id}/pages Playground

Name	Type	Required	Description
filter	string country my_region	No	Filter to apply to the results.
sort	string name publish.time videos	No	Technique used to sort the results.

Name

Type

Required

Description

filter

string

country
my_region

No

Filter to apply to the results.

sort

string

name
publish.time
videos

No

Technique used to sort the results.

HTTP Status Code	Explanation
200 OK

Get all On Demand regions

GET https://api.vimeo.com/ondemand/regions Playground

HTTP Status Code	Explanation
200 OK

Get all codes for an On Demand pages' promotion

GET https://api.vimeo.com/ondemand/pages/{ondemand_id}/promotions/{promotion_id}/codes Playground

This method requires a token with the "promo_codes" scope.

Name	Type	Required	Description
page	integer	No	The page number to show.
per_page	integer	No	Number of items to show on each page. Max 100.

Name

Type

Required

Description

page

integer

No

The page number to show.

per_page

integer

No

Number of items to show on each page. Max 100.

HTTP Status Code	Explanation
200 OK
404 Not Found	If the On Demand page cannot be found.
403 Forbidden	If you are attempting to create promotions for an On Demand page you do not own.

Get all posters for an On Demand page

GET https://api.vimeo.com/ondemand/pages/{ondemand_id}/pictures Playground

HTTP Status Code	Explanation
200 OK
404 Not Found	If the On Demand page cannot be found.

Get all videos in a season of an On Demand page

GET https://api.vimeo.com/ondemand/pages/{ondemand_id}/seasons/{season_id}/videos Playground

Name	Type	Required	Description
filter	string viewable	No	Filter to apply to the results.
sort	string date default manual name purchase_time release_date	No	Technique used to sort the results.

Name

Type

Required

Description

filter

string

viewable

No

Filter to apply to the results.

sort

string

date
default
manual
name
purchase_time
release_date

No

Technique used to sort the results.

HTTP Status Code	Explanation
200 OK

Get all videos in an On Demand page

GET https://api.vimeo.com/ondemand/pages/{ondemand_id}/videos Playground

Name	Type	Required	Description
filter	string all buy expiring_soon extra main main.viewable rent trailer unwatched viewable watched	No	Filter to apply to the results.
sort	string date default episode manual name purchase_time release_date	No	Technique used to sort the results.

Name

Type

Required

Description

filter

string

all
buy
expiring_soon
extra
main
main.viewable
rent
trailer
unwatched
viewable
watched

No

Filter to apply to the results.

sort

string

date
default
episode
manual
name
purchase_time
release_date

No

Technique used to sort the results.

HTTP Status Code	Explanation
200 OK	If you're pulling the On Demand video object.
200 OK

Get an On Demand genre

GET https://api.vimeo.com/ondemand/genres/{genre_id} Playground

HTTP Status Code	Explanation
200 OK
404 Not Found	If the On Demand genre cannot be found.

Get an On Demand page

GET https://api.vimeo.com/ondemand/pages/{ondemand_id} Playground

HTTP Status Code	Explanation
200 OK
404 Not Found	If the On Demand page cannot be found.

Get an On Demand page background

GET https://api.vimeo.com/ondemand/pages/{ondemand_id}/backgrounds/{background_id} Playground

HTTP Status Code	Explanation
200 OK
404 Not Found	If the On Demand page cannot be found.
404 Not Found	If the On Demand image cannot be found.
403 Forbidden	If you are viewing another users On Demand page background.

Get an On Demand page in a genre

GET https://api.vimeo.com/ondemand/genres/{genre_id}/pages/{ondemand_id} Playground

HTTP Status Code	Explanation
200 OK
404 Not Found	If the On Demand page cannot be found in the On Demand genre.

Get an On Demand pages' backgrounds

GET https://api.vimeo.com/ondemand/pages/{ondemand_id}/backgrounds Playground

HTTP Status Code	Explanation
200 OK
404 Not Found	If the On Demand page cannot be found.

Get an On Demand pages' genre

GET https://api.vimeo.com/ondemand/pages/{ondemand_id}/genres/{genre_id} Playground

HTTP Status Code	Explanation
200 OK
404 Not Found	If the On Demand page cannot be found.
404 Not Found	If the On Demand genre cannot be found in the On Demand page.

Get an On Demand pages' poster

GET https://api.vimeo.com/ondemand/pages/{ondemand_id}/pictures/{poster_id} Playground

HTTP Status Code	Explanation
200 OK

Get an On Demand pages' promotion

GET https://api.vimeo.com/ondemand/pages/{ondemand_id}/promotions/{promotion_id} Playground

This method requires a token with the "promo_codes" scope.

HTTP Status Code	Explanation
200 OK
404 Not Found	If the On Demand page cannot be found.
404 Not Found	If the promotion cannot be found.
403 Forbidden	If you are attempting to view a promotion for an On Demand page you do not own.

Get an On Demand pages' promotions

GET https://api.vimeo.com/ondemand/pages/{ondemand_id}/promotions Playground

This method requires a token with the "promo_codes" scope.

Name	Type	Required	Description
filter	string batch default single vip	No	Filter to apply to the results.

Name

Type

Required

Description

filter

string

batch
default
single
vip

No

Filter to apply to the results.

HTTP Status Code	Explanation
200 OK
404 Not Found	If the On Demand page cannot be found.
403 Forbidden	If you are attempting to view promotions for an On Demand page you do not own.
400 Bad Request	If an invalid filter was supplied.

Get an On Demand pages' region

GET https://api.vimeo.com/ondemand/pages/{ondemand_id}/regions/{country} Playground

HTTP Status Code	Explanation
200 OK
404 Not Found	If the On Demand page cannot be found.
404 Not Found	If the On Demand region cannot be found.

Get an On Demand region

GET https://api.vimeo.com/ondemand/regions/{country} Playground

HTTP Status Code	Explanation
200 OK
404 Not Found	If the On Demand region cannot be found.

Get genres of an On Demand page

GET https://api.vimeo.com/ondemand/pages/{ondemand_id}/genres Playground

HTTP Status Code	Explanation
200 OK
404 Not Found	If the On Demand page cannot be found.

Get regions for an On Demand page

GET https://api.vimeo.com/ondemand/pages/{ondemand_id}/regions Playground

HTTP Status Code	Explanation
200 OK
404 Not Found	If the On Demand page cannot be found.

Get seasons in an On Demand page

GET https://api.vimeo.com/ondemand/pages/{ondemand_id}/seasons Playground

Name	Type	Required	Description
direction	string asc desc	No	The direction that the results are sorted.
filter	string viewable	No	Filter to apply to the results.
page	integer	No	The page number to show.
per_page	integer	No	Number of items to show on each page. Max 100.
query	string	No	Search query.
sort	string date manual	No	Technique used to sort the results.

HTTP Status Code	Explanation
200 OK
404 Not Found	If the On Demand page cannot be found.

Get users' On Demand purchases and rentals

GET https://api.vimeo.com/me/ondemand/purchases Playground

This method requires a token with the "purchased" scope.

Name

Type

Required

Description

filter

string

all
expiring_soon
film
important
purchased
rented
series
subscription
unwatched
watched

Yes

Which type of On Demand videos to show.

sort

string

added
alphabetical
date
name
purchase_time
rating
release_date

No

Technique used to sort the results.

HTTP Status Code	Explanation
200 OK
400 Bad Request	If you have not provided a filter.
403 Forbidden	If the requested user is not the same as the authenticated user.

Set a list of regions to an On Demand page

PUT https://api.vimeo.com/ondemand/pages/{ondemand_id}/regions Playground

This method requires a token with the "edit" scope.

HTTP Status Code	Explanation
200 OK
404 Not Found	If the On Demand page cannot be found.
404 Not Found	If the On Demand region cannot be found.
403 Forbidden	If you are attempting to modify an On Demand page you do not own.