Media Actions - WellcomeMat API

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. All parameters should be set in the body, as 'form data'.
3. Required fields are marked with an asterisk.
4. The start and end date cannot exceed a 6 month time interval.

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

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

2. To upload a video to a specific user's account contained under the main account's key, use user_id (recommended) or unqiue_id.

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

4. All parameters besides the key and secret MUST be sent in the request BODY.

5. 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
user_id	User ID	This is WellcomeMat's internal ID for users of our system.
unique_id	Unique ID	This is an ID assigned to users externally from WellcomeMat (Example: agent, member or associate IDs)
default_state	Media activation status	Sets this video to active or inactive when finished encoding, overriding the Default Video State in Global Videos Settings. Videos must be active before they can be seen on your channel or search engines. - Boolean: 1 or 0 - Indicates that video is a active or inactive. - To change a videos state after it is encoded use our activate and deactave api calls -Activate -Deactivate
title	Title	Text String: Limit 100 characters
description	Description	Text String: Limit 1500 characters
keywords	Keywords("Tags")	- Text String: Comma separated by keyword or phrase - Limit 10 keywords("tags") 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_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 that has been URL encoded. - Will take effect after video has encoded

Callbacks:

Parameter Name	Definition	Notes
callback_location	Callback Location URL	When the video file has been recieved, the media object will be pushed to this URL. NOTE: This is the only callback parameter that is usable on the Embedded Uploader Tool and for safety, the callback_location should be URL encoded to ensure success. We expect a 200 response back from the server handshake. The following GET parameters will be appended to the URL: success error media key Example Callback: https://yourdomain.com/uploaded-location.php?success=1&media={MediaObject}&error=&key=yourKey
callback_uploaded	Uploaded Callback URL	The API will redirect the client to this URL upon upload completion. NOTE: If you use `callback_uploaded`, you cannot use `callback_location` as `callback_uploaded` sends a redirect which ends execution. The following GET parameters will be appended to the URL: success error hash key Example Callback: https://yourdomain.com/uploaded-callback.php?success=1&hash=abc123def&error=&key=youKey
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: hash status_code Example Callback: https://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, including shared videos. This is inadvisable for users with large video libraries.

NOTE: If hash or customID are not provided and user_id OR unique_id ARE provided, query will return ALL medias for the user specified account. I.E. If you are the key and secret owner, if you specify your user_id you will only recieve your videos. If you were to specify an account's user_id that shares videos to your account, it will return only those user's videos.

If querying for a single media, include at least the Hash(recommended) or customID:

Parameter Name	Definition	Notes
hash	Video Hash	We highly recommended using the hash to avoid handling duplicates as this is a unique identifier for the video.
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
user_id	User ID	This is WellcomeMat's internal ID for users of our system.
unqiue_id	Unique ID	This is an ID assigned to users externally from WellcomeMat (Example: agent, member or associate IDs)
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("tags") - Returned media will have at least one of the keywords("tags")
andkeywords	AND Keywords	- Comma separated list of keywords("tags") - Returned media will have all of the keywords("tags")
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("Tags")	- Text String: Comma separated by keyword or phrase - Limit 10 keywords("tags") 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_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 that has been URL encoded. - Will take effect after video has encoded

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.