This use case describes the requirements for uploading content (an ad copy) from a URL with the Broadsign Control Content Import Service API.
POST using the following method: /import.
When posting to the /import endpoint, Broadsign Server performs the request asynchronously. In other words, if the request is valid, Broadsign returns a Content ID# in the JSON response and begins to import the content in the background. Depending on the file size and available bandwidth, the content may take several minutes or more to import completely and be available in Broadsign Control Administrator.
The following table lists the possible attributes for ad copies/content. Include this information in the attributes parameter.
Note: You must use newline separators in the string.
| Mime Type | Possible Attributes |
|---|---|
| avi |
duration audio_codec video_codec height width keep_aspect_ratio |
| bmp |
duration keep_aspect_ratio |
| divx |
duration audio_codec video_codec height width keep_aspect_ratio |
| exe | duration |
| f4v |
duration keep_aspect_ratio |
| fla | duration |
| flv |
duration audio_codec video_codec height width volume_modifier keep_aspect_ratio |
| gif |
duration height width |
| htm | duration |
| html |
direct_url show_scrollbars |
| jpeg |
height width |
| jpg |
height width |
| m2t |
duration height width audio_codec video_codec |
| m2v |
duration height width video_codec |
| m4a |
duration audio_codec volume_modifier |
| m4v |
duration keep_aspect_ratio |
| mht | duration |
| mkv |
duration keep_aspect_ratio video_codec |
| mov |
duration height width audio_codec video_codec keep_aspect_ratio |
| mp3 |
duration audio_codec |
| mp4 |
duration height width audio_codec video_codec keep_aspect_ratio |
| mpeg |
duration height width audio_codec video_codec |
| mpg |
duration height width audio_codec video_codec keep_aspect_ratio |
| pls |
duration volume_modifier |
| png |
duration height width keep_aspect_ratio |
| tif |
duration keep_aspect_ratio |
| vob |
duration height width audio_codec video_codec keep_aspect_ratio |
| webm |
duration height width audio_codec video_codec keep_aspect_ratio |
| wma |
duration audio_codec |
| wmv |
duration width height audio_codec video_codec |
| xap |
duration volume_modifier |
| x-creator |
duration volume_modifier |
| x-digital-tv | duration |
| x-html-package |
duration main_html_file_path |
| xml | duration |
| x-ticker | duration |
| zip |
duration command_line_parameters environment_variables executable_path run_as_admin run_only_once |
These request samples illustrate how to import external content into Broadsign Server.
Note: The ID#s we use in these samples are for illustration purposes. They are invalid. Be sure to use your own ID#s for your integrations. Also, in our examples, we use the content.control-prod endpoint and HTTP token. For testing purposes, you can use the content.control-beta endpoint.
curl -X POST \
https://content.control-prod.broadsign.com/import \
Header: Authorization: Bearer YourAPIKeyHere
{
"name": "My Content",
"container_id": "123",
"attributes": { "height": "720", "width": "1280" },
"url": "https://bucket.s3.ca-central-1.amazonaws.com/key.png"
}Request Parameters
|
Name |
Type |
Description |
|---|---|---|
|
name |
string |
The name of the Content that will be created. |
|
domain_id |
string (int64) |
Optional. The ID of the Domain where to create the Content. By default, this is the Domain ID of the user making the request. |
|
customer_id |
string (int64) |
Optional. The ID of the Customer where to create the Content. By default, the Content will not belong to a Customer. |
|
container_id |
string (int64) |
Optional. The ID of the Container where to create the Content. By default, the Content will not be in a Container. |
|
attributes |
JSON string map |
Information on the file, which will vary according to the mime type. See Mime Types and Attributes. This is a simple key-value map where values must always be strings. |
|
url |
string |
The URL to be retrieved by Broadsign Control that will be made available as Content. The mime of the Content will be deduced based on the extension of the URL (for example: mp4, png, x-html-package, zip). |
Seeing as the import happens asynchronously, there is no direct feedback on the progress of the download taking place server-side. Some client applications may need to periodically check on the import to see if it has completed. This can be achieved by using the GET /import method, using the Content ID# returned from the /import method.
GET https://content.control-prod.broadsign.com/import/123456789
Header: Authorization: Bearer YourAPIKeyHereRequest Parameters
| Name | Type | Description |
|---|---|---|
| contentId | int64 (string) | The ID of the Content for which progress is requested. |
200 - OK
{
"status": "FAILED",
"error": "Failed to download the content at 'https://bucket.s3.ca-central-1.amazonaws.com/key.png'. The request failed with a 403 Forbidden error."
}Response Parameters
| Name | Type | Description |
|---|---|---|
| status | enum (string) |
One of the following status values:
|
| error | string (optional) | Included if the content download request has failed. Descriptive, human-readable string describing why the content failed. |