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.

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 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
- 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. 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: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

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