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:

  • Account ownerships

This document describes the API for creating, reading, and deleting account ownerships.

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

Url:

  • [GET] /api/v2/accounts/ownerships.[xml|json]

Returns a list of ownerships associated with the account.

Note:
Status can be -1(Deleted), 0(Inactive), 1(Active), 2(Expired) and 3(Cancelled).
Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of query parameters.
Example Request

The following example returns a listing of all ownerships associated with the currently authorized account.
[GET] https://service_name.synctv.com/api/v2/accounts/ownerships.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Request Field:
  • (Integer) offset — Used for pagination of response data (default: 25 items per response). Specifies the offset of the next block of data to receive.
  • (Array) status — Filter by status. (e.g. status[]=1&status[]=2&status[]=3).
  • (String) sort_order — Orders response by fields. (e.g. sort_order=created_at).
  • (String) id — The unique identifier of the ownership.
  • (String) begin_at — Timestamp (ISO 8601) for when the associated account's use of this ownership began.
  • (String) end_at — Timestamp (ISO 8601) for when the associated account's ownership is supposed to end.
  • (String) created_at — Timestamp (ISO 8601) for when the ownership itself was created.
  • (Boolean) sort_descending — Reverse order of sort_order sorting, make it descending.
  • (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) platform_id — Filters response to include only items with the provided platform_id (e.g. platform_id=1).
  • (Integer) bundle_id — Filters response to include only items with the provided bundle_id (e.g. bundle_id=1).
  • (Integer) ownership_policy_id — Filters response to include only items with the provided ownership_policy_id (e.g. ownership_policy_id=1).
Example Response
XML JSON

<response>
  <ownerships>
    <ownership>
      <id>1</id>
      <bundle_id>1</bundle_id>
      <ownership_policy_id>1</ownership_policy_id>
      <account_id>1</account_id>
      <status>0</status>
      <begin_at>2012-02-24T10:04:18Z</begin_at>
      <end_at>2012-02-24T10:04:18Z</end_at>
      <platform_id>1</platform_id>
      <device_uid nil="true"/>
      <device_user_uid nil="true"/>
      <playback_begin_at nil="true"/>
      <playback_end_at nil="true"/>
      <created_at>2014-05-01T21:33:39Z</created_at>
      <activated_at nil="true"/>
      <expired_at nil="true"/>
    </ownership>
    <ownership>
      <id>2</id>
      <bundle_id>2</bundle_id>
      <ownership_policy_id>2</ownership_policy_id>
      <account_id>2</account_id>
      <status>0</status>
      <begin_at>2012-02-24T10:04:18Z</begin_at>
      <end_at>2012-02-24T10:04:18Z</end_at>
      <platform_id>2</platform_id>
      <device_uid nil="true"/>
      <device_user_uid nil="true"/>
      <playback_begin_at nil="true"/>
      <playback_end_at nil="true"/>
      <created_at>2014-05-01T21:33:39Z</created_at>
      <activated_at nil="true"/>
      <expired_at nil="true"/>
    </ownership>
  </ownerships>
</response>
Response Fields:
  • (Integer) ownership[id]
    The unique identifier of the ownership.
  • (Integer) ownership[bundle_id]
    The media that the ownership is applied to.
  • (Date) ownership[begin_at]
    Timestamp (ISO 8601) for when the associated account's use of this ownership began.
  • (Date) ownership[end_at]
    Timestamp (ISO 8601) for when the associated account's ownership is supposed to end.
  • (Integer) ownership[ownership_policy_id]
    The ownership policy by which this ownership is governed.
  • (Integer) ownership[account_id]
    The account associated with this ownership.
  • (Integer) ownership[status]
    The status of the ownership (-1 - Deleted, 0 - Inactive, 1 - Active, 2 - Expired, 3 - Cancelled).
  • (Integer) ownership[platform_id]
    Platform with which this ownership was created

Url:

  • [GET] /api/v2/accounts/ownerships/:id.[xml|json]

Returns information for the specified ownership.

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

The following URL returns the ownership information for ownership 100.
[GET] https://service_name.synctv.com/api/v2/accounts/ownerships/100.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Example Response
XML JSON

<response>
  <ownership>
    <id>1</id>
    <bundle_id>1</bundle_id>
    <ownership_policy_id>1</ownership_policy_id>
    <account_id>1</account_id>
    <status>0</status>
    <begin_at>2012-02-24T10:04:18Z</begin_at>
    <end_at>2012-02-24T10:04:18Z</end_at>
    <platform_id>1</platform_id>
    <device_uid nil="true"/>
    <device_user_uid nil="true"/>
    <playback_begin_at nil="true"/>
    <playback_end_at nil="true"/>
    <created_at>2014-05-01T21:33:41Z</created_at>
    <activated_at nil="true"/>
    <expired_at nil="true"/>
  </ownership>
</response>
Response Fields:
  • (Integer) ownership[id]
    The unique identifier of the ownership.
  • (Integer) ownership[bundle_id]
    The media that the ownership is applied to.
  • (Date) ownership[begin_at]
    Timestamp (ISO 8601) for when the associated account's use of this ownership began.
  • (Date) ownership[end_at]
    Timestamp (ISO 8601) for when the associated account's ownership is supposed to end.
  • (Integer) ownership[ownership_policy_id]
    The ownership policy by which this ownership is governed.
  • (Integer) ownership[account_id]
    The account associated with this ownership.
  • (Integer) ownership[status]
    The status of the ownership (-1 - Deleted, 0 - Inactive, 1 - Active, 2 - Expired, 3 - Cancelled).
  • (Integer) ownership[platform_id]
    Platform with which this ownership was created

Url:

  • [POST] /api/v2/accounts/ownerships.[xml|json]

Creates a new ownership with the specified media and currently authorized account.

Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of query parameters.
  • (Integer) ownership[bundle_id]
    The bundle that the ownership policy is to be applied to.
  • (Integer) ownership[media_id]
    (DEPRECATED) (required if bundle_id is not supplied) The media that the ownership policy is to be applied to.
  • (Integer) ownership[ownership_policy_id]
    The policy that this new ownership is to be governed by.
Example Request

The following URL creates an ownership between account 1 and media 2. The ownership is governed by ownership_policy 3.
[POST] https://service_name.synctv.com/api/v2/accounts/ownerships.xml?ownership[bundle_id]=2&ownership[ownership_policy_id]=3&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Example Response
XML JSON

<response>
  <ownership>
    <id>1</id>
    <bundle_id>1</bundle_id>
    <ownership_policy_id>1</ownership_policy_id>
    <account_id>1</account_id>
    <status>0</status>
    <begin_at>2012-02-24T10:04:18Z</begin_at>
    <end_at>2012-02-24T10:04:18Z</end_at>
    <platform_id>1</platform_id>
    <device_uid nil="true"/>
    <device_user_uid nil="true"/>
    <playback_begin_at nil="true"/>
    <playback_end_at nil="true"/>
    <created_at>2014-05-01T21:33:44Z</created_at>
    <activated_at nil="true"/>
    <expired_at nil="true"/>
  </ownership>
</response>
Response Fields:
  • (Integer) ownership[id]
    The unique identifier of the ownership.
  • (Integer) ownership[bundle_id]
    The bundle that the ownership is applied to.
  • (Date) ownership[begin_at]
    Timestamp (ISO 8601) for when the associated account's use of this ownership began.
  • (Date) ownership[end_at]
    Timestamp (ISO 8601) for when the associated account's ownership is supposed to end.
  • (Integer) ownership[ownership_policy_id]
    The ownership policy by which this ownership is governed.
  • (Integer) ownership[account_id]
    The account associated with this ownership.
  • (Integer) ownership[status]
    The status of the ownership (-1 - Deleted, 0 - Inactive, 1 - Active, 2 - Expired, 3 - Cancelled).
  • (Integer) ownership[platform_id]
    Platform with which this ownership was created

Url:

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

Ownerships cannot be truly deleted, this will set the specified ownership's status to -1 (Deleted).

Note:
This will return only success or failure, no content.
Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of query parameters.
Example Request

The following URL deletes ownership 100.
[DELETE] https://service_name.synctv.com/api/v2/accounts/ownerships/100.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
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>