API Documentation: Media Actions

All requests are done via HTTP POST to https://www.wellcomemat.com/ and will return a JSON response. If you would like the API to do something that is not listed here, visit our Help.

NOTES
1. Authentication parameters are also required for each request.
2. Required fields are marked with an asterisk.

Actions

  1. Upload + Replace
  2. Query
  3. Update
  4. Deactivate
  5. Activate

Upload + Replace: /api/media/upload.php

NOTES
1. You can use media or media_url. For a direct upload, use media. For a file hosted elsewhere, use media_url.

2. To replace a video, specify either customid or hash, along with #1.
At this time, no other fields are accepted when replacing.

3. Global distribution is not enabled for API uploads at this time.

Video details:

Parameter Name Definition Notes
media Media File Must be a properly formatted POST video
media_url Media File Publicly accessible video URL
video_type Video Type Select a video categorization that best describes the video you are uploading. WellcomeMat uses this information for better search engine placement and to better organize videos within your account. Video types also determine the distribution options that are available to you for each kind of video.

Must be a valid type id
title Title Text String: Limit 100 characters
description Description Text String: Limit 1500 characters
keywords Keywords - Text String: Comma separated by keyword or phrase
- Limit 10 keywords or phrases
- Suggested: Limit 63 characters (including commas)
customid Custom/Listing ID A Custom ID is a unique code you can use to more easily identify your video when connecting to WellcomeMat via our API.

Text String: Limit 256 characters
hash Video Hash Only used to specify a video to replace
external_link_url External Link URL Add a link to another location here so viewers can click through to more information about this video.

Text String: Limit 256 characters
external_link_name External Link Name Links themselves are often not descriptive enough to entice people to click through. The words you enter here will instigate viewers to click through to another web location where they can find more information about your video.

Text String: Limit 256 characters
slideshow Slideshow Based on hundreds of thousands of videos in the WellcomeMat database, we know that full motion videos are exactly twice as engaging (on average) as slideshows and animations. Please mark slideshows and animations properly so that we can better inform your content strategies and allow you to correctly integrate different forms of content on your website(s).

- Boolean: 1 or 0
- Indicates that video is a slideshow or animation. We use this for distribution and statistics
bedrooms Bedrooms Number: Integer or floating point
bathrooms Bathrooms Number: Integer or floating point
price Price Text String: Most formats should be accepted
address Address Text String: Limit 100 characters
city City Text String: Limit 50 characters
state State i.e. Colorado, Ohio, etc.

Text String: Limit 50 characters
postal_code Postal Code Text String: Limit 12 characters

Options:

Parameter Name Definition Notes
disable_email Disable Email Notification - Boolean: 1 or 0 (defaults to 0)
- Turns off the email a user receives when a video has finished encoding
distribute Distribute to Service - Distributes to services configured by Connected Services
- Options: youtube, facebook, facebook_page, twitter
- Separate multiple services with a comma
default_photo Default Photo - Set the poster image that shows when your video loads
- Accepts an image upload or publicly accessible image URL
- Will take effect after video has encoded

Callbacks:

Parameter Name Definition Notes
callback_uploaded Uploaded Callback URL The API will redirect the client to this URL upon upload completion. The following GET parameters will be appended to the URL:
  • success
  • error
  • hash
Example Callback: http://yourdomain.com/uploaded-callback.php?success=1&hash=abc123def&error=
callback_processed Processed Callback URL When the video has been processed, this URL will be called. The following GET parameters will be appended to the URL:Example Callback: http://yourdomain.com/processed-callback.php?hash=abc123def&status_code=400

Query: /api/media/query.php

NOTE: If no parameters are specified, query will return ALL medias for this account. This is inadvisable for users with large video libraries.

If querying for a single media, include at least one:

Parameter Name Definition Notes
hash Video Hash
customid Custom/Listing ID A Custom ID is a unique code you can use to more easily identify your video when connecting to WellcomeMat via our API.

Other filters:

Parameter Name Definition Notes
ortitlewords OR Title Words - Comma separated list of title words
- Returned media will have at least one of the title words
andtitlewords AND Title Words - Comma separated list of title words
- Returned media will have all of the title words
orkeywords OR Keywords - Comma separated list of keywords
- Returned media will have at least one of the keywords
andkeywords AND Keywords - Comma separated list of keywords
- Returned media will have all of the keywords
status Media Status Must be a valid status code
playlist Playlist Must be a valid playlist id. To maintain the playlist's video order, do not specify a sort
video_type Video Type Must be a valid type id
start_date Start Date Show videos uploaded after start_date. Format: YYYY-MM-DD hh:mm:ss
end_date End Date Show videos uploaded before end_date. Format: YYYY-MM-DD hh:mm:ss
metadata_updated_start Metadata Updated Start Datetime Show videos with data modified after metadata_updated_start. Format: YYYY-MM-DD hh:mm:ss
metadata_updated_end Metadata Updated End Datetime Show videos with data modified before metadata_updated_end. Format: YYYY-MM-DD hh:mm:ss
limit Limit results Number: Integer

Options:

Parameter Name Definition Notes
sort Sort Order Must be a valid sorting option, either "newest" or "oldest" first
include_playlists Include playlists in results - Boolean: 1 or 0 (defaults to 0)
- Whether to include the playlists that a video is in

Update: /api/media/update.php

NOTES
1. If you specify customid but no hash, the video will be queried based on customid. If you specify both a customid and hash, the video identified by hash will have its customid updated.

2. You must include either hash or customid.

3. To replace a video, use the upload action.
Parameter Name Definition Notes
hash Video Hash
customid Custom/Listing ID A Custom ID is a unique code you can use to more easily identify your video when connecting to WellcomeMat via our API.

Text String: Limit 256 characters
title Title Text String: Limit 100 characters
description Description Text String: Limit 1500 characters
keywords Keywords - Text String: Comma separated by keyword or phrase
- Limit 10 keywords or phrases
- Suggested: Limit 63 characters (including commas)
imagehash Image Hash This needs to refer to an image already assigned to this media
traffic_url Traffic Generation Override - Point all viewers to a webpage where you have embedded your video
- A warning will be returned if the video could not be found
distribute Distribute to Service - Distributes to services configured by Connected Services
- Options: youtube, facebook, facebook_page, twitter
- Separate multiple services with a comma

Deactivate: /api/media/deactivate.php

Include at least one:

Parameter Name Definition Notes
hash Video Hash
customid Custom/Listing ID A Custom ID is a unique code you can use to more easily identify your video when connecting to WellcomeMat via our API.

Activate: /api/media/activate.php

Include at least one:

Parameter Name Definition Notes
hash Video Hash
customid Custom/Listing ID A Custom ID is a unique code you can use to more easily identify your video when connecting to WellcomeMat via our API.

Close