Admin APIs
At its core, SyncTV is an API driven service. The APIs themselves are easy enough for developers to understand, but understanding the ecosystem is a little trickier. We've created the following tutorials to help you get your head around it.

Topics:

  • Bundles

This document describes the API for bundles. A bundle represents a grouping of media items. Each bundle of media can be associated with one or more ownership_policies.

Note:
Each call to the SyncTV V2 API described in this section requires a MD5 hash signature.
See the Authorization (User) API for details on generating the MD5 hash signature.
Actions

Url:

  • [GET] /api/v2/bundles.[xml|json]
  • [GET] /api/v2/media/:medium_id/bundles.[xml|json]

Returns a list of bundles.

Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of alphabetically sorted query parameters.
Example Request

https://service_name.synctv.com/api/v2/bundles.xml
Request Field:
  • (Integer) status — Filters response by status (0 == ENABLED, 1 == ACTIVE, -1 == DELETED, -2 = INACTIVE, -3 = DISABLED).
  • (String) type_id — Filters response based on given set of type_ids (e.g. type_id[]=1&type_id[]=2)
  • (DateTime) created_at_greater — Filters response to include only items with created_at >= specified timestamp (e.g. created_at_greater=2012-02-15T02:06:56Z).
  • (DateTime) created_at_less — Filters response to include only items with created_at <= specified timestamp (e.g. created_at_less=2012-02-15T02:06:56Z).
  • (DateTime) updated_at_greater — Filters response to include only items with updated_at >= specified timestamp (e.g. updated_at_greater=2012-02-15T02:06:56Z).
  • (DateTime) updated_at_less — Filters response to include only items with updated_at <= specified timestamp (e.g. updated_at_less=2012-02-15T02:06:56Z).
  • (DateTime) begin_at_greater — Filters response to include only items with begin_at >= specified timestamp (e.g. begin_at_greater=2012-02-15T02:06:56Z).
  • (DateTime) begin_at_less — Filters response to include only items with begin_at <= specified timestamp (e.g. begin_at_less=2012-02-15T02:06:56Z).
  • (DateTime) end_at_greater — Filters response to include only items with end_at >= specified timestamp (e.g. end_at_greater=2012-02-15T02:06:56Z).
  • (DateTime) end_at_less — Filters response to include only items with end_at <= specified timestamp (e.g. end_at_less=2012-02-15T02:06:56Z).
  • (Integer) medium_id — Filters response to include all bundles associated with the given medium_id (e.g. medium_id=3156).
  • (Array) all_of_media_ids — Filters response to include bundles that only match exactly the supplied media ids (e.g. all_of_media_ids[]=1&all_of_media_ids[]=4).
  • (Array) any_of_media_ids — Filters response to include bundles that match any of the supplied media ids (e.g. any_of_media_ids[]=1&any_of_media_ids[]=4).
  • (Array) none_of_media_ids — Filters response to include bundles that match none of the supplied media ids (e.g. none_of_media_ids[]=1&none_of_media_ids[]=4).
  • (Array) any_of_available_platform_ids — Filters response based on a match of any platforms defined through the associated ownerships platform view rules (e.g. any_of_available_platform_ids[]=1&any_of_available_platform_ids[]=2...).
  • (Array) any_of_available_platform_type_ids — Filters response based on a match of any platform types of the platforms defined through the associated ownerships platform view rules (e.g. any_of_available_platform_type_ids[]=1&any_of_available_platform_type_ids[]=2...).
  • (Array) any_of_bundle_type_ids — Filters response to include bundles that match the given bundle type ids (e.g. any_of_bundle_type_ids[]=1&any_of_bundle_type_ids[]=4).
  • (Array) none_of_bundle_type_ids — Filters response to include bundles that don't match any of the given bundle type ids (e.g. none_of_bundle_type_ids[]=1&none_of_bundle_type_ids[]=4).
  • (Array) fields — Filters response by which fields are rendered for each response object. This can include optional fields, like 'ownership_policies', 'ownership_ids', 'medias', 'container_ids' (e.g. fields[]=id&fields[]=ownership_policies).
  • (Array) add_fields — Filters response by which fields are added in addition to the default fields for each response object (e.g. add_fields[]=medias).
  • (Array) remove_fields — Filters response by which fields are removed from response object (e.g. remove_fields[]=id).
  • (Float) available_price_greater — Filters response to include bundles that have available prices >= specified price (E.g. available_price_greater=1.99)
  • (Float) available_price_less — Filters response to include bundles that have available prices <= specified price (E.g. available_price_less=1.99)
  • (Array) any_of_available_price_currencies — Filters response to include bundles with any of price currencies specified symbols (E.g. any_of_available_price_currencies[]=USD)
  • (Array) all_of_media_type_ids — Filters response for bundles that include the given media type IDs (e.g. all_of_media_type_ids[]=1&all_of_media_type_ids[]=2).
  • (Array) none_of_media_type_ids — Filters response for bundles that don't include any of the given media type IDs (e.g. none_of_media_type_ids[]=1&none_of_media_type_ids[]=2).
Example Response
XML JSON

<response>
  <bundles>
    <bundle>
      <id>1</id>
      <name>Bundle-3</name>
      <status>-3</status>
      <bundle_type>
        <id>1</id>
        <name>BundleType-3</name>
      </bundle_type>
      <begin_at nil="true"/>
      <end_at nil="true"/>
      <updated_at>2014-05-01T21:28:57Z</updated_at>
      <created_at>2014-05-01T21:28:57Z</created_at>
      <ownership_policy_ids/>
      <media_ids/>
    </bundle>
    <bundle>
      <id>2</id>
      <name>Bundle-4</name>
      <status>-3</status>
      <bundle_type>
        <id>2</id>
        <name>BundleType-4</name>
      </bundle_type>
      <begin_at nil="true"/>
      <end_at nil="true"/>
      <updated_at>2014-05-01T21:28:57Z</updated_at>
      <created_at>2014-05-01T21:28:57Z</created_at>
      <ownership_policy_ids/>
      <media_ids/>
    </bundle>
  </bundles>
</response>
Response Fields:
  • (Integer) bundle[id]
    Id of the bundle
  • (String) bundle[name]
    Name of the bundle
  • (Integer) bundle[status]
    Status of the bundle (0 == ENABLED, 1 == ACTIVE, -1 == DELETED, -2 = INACTIVE, -3 = DISABLED)
  • (Integer) bundle[bundle_type][id]
    The id of the bundle's associated bundle_type.
  • (String) bundle[bundle_type][name]
    The name of the associated bundle_type.
  • (DateTime) bundle[begin_at]
    Timestamp (ISO 8601) for when the bundle began to become availiable.
  • (DateTime) bundle[end_at]
    Timestamp (ISO 8601) for when the bundle is suppose to end.
  • (DateTime) bundle[created_at]
    Timestamp of when the bundle was created.
  • (DateTime) bundle[updated_at]
    Timestamp of when the bundle was last updated.

Url:

  • [GET] /api/v2/bundles/:id.[xml|json]
  • [GET] /api/v2/media/:medium_id/bundles/:id.[xml|json]

Returns a specific bundle, including the ownership_policy_ids and media_ids associated with bundle.

Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of alphabetically sorted query parameters.
Example Request

The follow example retrieves a single bundle record.
https://service_name.synctv.com/api/v2/bundles/1.xml
Example Response
XML JSON

<response>
  <bundle>
    <id>1</id>
    <name>Bundle-5</name>
    <status>-3</status>
    <bundle_type>
      <id>1</id>
      <name>BundleType-5</name>
    </bundle_type>
    <begin_at nil="true"/>
    <end_at nil="true"/>
    <updated_at>2014-05-01T21:28:57Z</updated_at>
    <created_at>2014-05-01T21:28:57Z</created_at>
    <ownership_policy_ids/>
    <media_ids/>
  </bundle>
  <ownership_policy_ids>
    <ownership_policy_id>1</ownership_policy_id>
    <ownership_policy_id>2</ownership_policy_id>
  </ownership_policy_ids>
  <media_ids>
    <media_id>1</media_id>
    <media_id>2</media_id>
  </media_ids>
</response>
Response Fields:
  • (Element) bundle
    Contains the fields for the bundle item. See above for description of bundle response fields.
  • (Array) ownership_policy_ids
    Contains the ownership_policy_ids associated with the bundle item.
  • (Array) media_ids
    Contains the media_ids associated with the bundle item.

Url:

  • [POST] /api/v2/bundles.[xml|json]

Create a new bundle.

Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of alphabetically sorted query parameters.
  • (String) bundle[name]
    The bundle name.
  • (Integer) bundle[bundle_type_id]
    ID of the desired bundle type.
Example Request

The following URL creates a bundle with name `Bundee` consisting of media 1 and media 2 and linked to ownership policy 3.
[POST] https://service_name.synctv.com/api/v2/bundles.xml?bundle[name]=Bundee&bundle[media_ids][]=1&bundle[media_ids][]=2&media[ownership_policy_ids]=3&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Request Field:
  • (String) bundle[name] — Name of bundle, preperably describing media of the bundle.
  • (Integer) bundle[bundle_type_id] — ID of the desired bundle type.
  • (Array) bundle[media_ids][] — List of media ids included in the bundle.
  • (Array) bundle[ownership_policy_ids][] — List of ownership policy ids linked to the bundle.
  • (Integer) bundle[status] — The status of the bundle (-1 == DELETED , 0 == INACTIVE, 1 == ACTIVE).
  • (DateTime) bundle[begin_at] — Timestamp (ISO 8601) for when the bundle began to become availiable.
  • (DateTime) bundle[end_at] — Timestamp (ISO 8601) for when the bundle is suppose to end.
Example Response
XML JSON

<response>
  <bundle>
    <id>1</id>
    <name>Bundle-6</name>
    <status>-3</status>
    <bundle_type>
      <id>1</id>
      <name>BundleType-6</name>
    </bundle_type>
    <begin_at nil="true"/>
    <end_at nil="true"/>
    <updated_at>2014-05-01T21:28:58Z</updated_at>
    <created_at>2014-05-01T21:28:58Z</created_at>
    <ownership_policy_ids/>
    <media_ids/>
  </bundle>
</response>
Response Fields:
  • (Element) bundle
    Contains the fields for the bundle item. See above for description of bundle response fields.

Url:

  • [PUT] /api/v2/bundles/1.[xml|json]

Update bundle.

Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of alphabetically sorted query parameters.
Example Request

The following URL updates bundle 100 with name `Specials` consisting of media 1 and media 2 and linked to ownership policy 3.
[PUT] https://service_name.synctv.com/api/v2/bundles/100.xml?bundle[name]=Specials&bundle[media_ids][]=1&bundle[media_ids][]=2&media[ownership_policy_ids]=3&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Example Response
XML JSON

<response>
  <bundle>
    <id>1</id>
    <name>Bundle-7</name>
    <status>-3</status>
    <bundle_type>
      <id>1</id>
      <name>BundleType-7</name>
    </bundle_type>
    <begin_at nil="true"/>
    <end_at nil="true"/>
    <updated_at>2014-05-01T21:28:59Z</updated_at>
    <created_at>2014-05-01T21:28:59Z</created_at>
    <ownership_policy_ids/>
    <media_ids/>
  </bundle>
</response>

On success: HTTP 200
On error:   HTTP 400 with array of errors in message tags
<response>
  <code>-4</code>
  <messages>
    <message>Record not found</message>
  </messages>
</response>

Url:

  • [DELETE] /api/v2/bundles/:id.[xml|json]

Destroy a bundle.

Example Request

The following URL deletes bundle 100
https://service_name.synctv.com/api/v2/bundles/100.xml
Example Response
XML JSON

On success: HTTP 200
On error:   HTTP 400 with array of errors in message tags
<response>
  <code>-4</code>
  <messages>
    <message>Record not found</message>
  </messages>
</response>

Url:

  • [GET] /api/v2/bundles/count.[xml|json]
  • [GET] /api/v2/media/:medium_id/bundles/count.[xml|json]

Counts a list of bundles.

Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of alphabetically sorted query parameters.
Example Request

https://service_name.synctv.com/api/v2/bundles/count.xml
Request Field:
  • (Integer) status — Filters response by status (-1 == DELETED , 0 == INACTIVE, 1 == ACTIVE).
  • (String) type_id — Filters response based on given set of type_ids (e.g. type_id[]=1&type_id[]=2)
  • (DateTime) begin_at_greater — Filters response to include only items with begin_at >= specified timestamp (e.g. begin_at_greater=2012-02-15T02:06:56Z).
  • (DateTime) begin_at_less — Filters response to include only items with begin_at <= specified timestamp (e.g. begin_at_less=2012-02-15T02:06:56Z).
  • (DateTime) end_at_greater — Filters response to include only items with end_at >= specified timestamp (e.g. end_at_greater=2012-02-15T02:06:56Z).
  • (DateTime) end_at_less — Filters response to include only items with end_at <= specified timestamp (e.g. end_at_less=2012-02-15T02:06:56Z).
  • (Integer) medium_id — Filters response to include all bundles associated with the given medium_id (e.g. medium_id=3156).
  • (Array) all_of_media_ids — Filters response to include bundles that only match exactly the supplied media ids (e.g. all_of_media_ids[]=1&all_of_media_ids[]=4).
  • (Array) any_of_media_ids — Filters response to include bundles that match any of the supplied media ids (e.g. any_of_media_ids[]=1&any_of_media_ids[]=4).
  • (Array) none_of_media_ids — Filters response to include bundles that match none of the supplied media ids (e.g. none_of_media_ids[]=1&none_of_media_ids[]=4).
  • (Integer) status — Filters response by status (-1 == DELETED , 0 == INACTIVE, 1 == ACTIVE).
  • (String) type_id — Filters response based on given set of type_ids (e.g. type_id[]=1&type_id[]=2)
  • (DateTime) begin_at_greater — Filters response to include only items with begin_at >= specified timestamp (e.g. begin_at_greater=2012-02-15T02:06:56Z).
  • (DateTime) begin_at_less — Filters response to include only items with begin_at <= specified timestamp (e.g. begin_at_less=2012-02-15T02:06:56Z).
  • (DateTime) end_at_greater — Filters response to include only items with end_at >= specified timestamp (e.g. end_at_greater=2012-02-15T02:06:56Z).
  • (DateTime) end_at_less — Filters response to include only items with end_at <= specified timestamp (e.g. end_at_less=2012-02-15T02:06:56Z).
  • (Array) any_of_available_platform_ids — Filters response based on a match of any platforms defined through the associated ownerships platform view rules (e.g. any_of_available_platform_ids[]=1&any_of_available_platform_ids[]=2...).
  • (Array) any_of_available_platform_type_ids — Filters response based on a match of any platform types of the platforms defined through the associated ownerships platform view rules (e.g. any_of_available_platform_type_ids[]=1&any_of_available_platform_type_ids[]=2...).
  • (Integer) medium_id — Filters response to include all bundles associated with the given medium_id (e.g. medium_id=3156).
  • (Array) all_of_media_ids — Filters response to include bundles that only match exactly the supplied media ids (e.g. all_of_media_ids[]=1&all_of_media_ids[]=4).
  • (Array) any_of_media_ids — Filters response to include bundles that match any of the supplied media ids (e.g. any_of_media_ids[]=1&any_of_media_ids[]=4).
  • (Array) none_of_media_ids — Filters response to include bundles that match none of the supplied media ids (e.g. none_of_media_ids[]=1&none_of_media_ids[]=4).
  • (Array) any_of_bundle_type_ids — Filters response to include bundles that match the given bundle type ids (e.g. any_of_bundle_type_ids[]=1&any_of_bundle_type_ids[]=4).
  • (Array) none_of_bundle_type_ids — Filters response to include bundles that don't match any of the given bundle type ids (e.g. none_of_bundle_type_ids[]=1&none_of_bundle_type_ids[]=4).
Example Response
XML JSON

<response>
  <count>25</count>
  <code>1</code>
  <messages>
    <message>Successfully completed.</message>
  </messages>
</response>