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

  • Profiles

This document describes the API for reading and updating account profiles. Every account has a profile and profiles cannot be deleted independently of the account.

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/accounts/profiles.[xml|json]

Returns a list of all profiles for the current account.

Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of query parameters.
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) any_of_name — Filters response by profile name or a list of profile names.
Example Response
XML JSON

<response>
  <profiles>
    <profile>
      <id>1</id>
      <name>ABCDEFG</name>
      <properties>
      </properties>
      <master>false</master>
      <created_at>2014-05-01T21:25:47Z</created_at>
      <updated_at>2014-05-01T21:25:47Z</updated_at>
    </profile>
    <profile>
      <id>2</id>
      <name>HIJKLMNOP</name>
      <properties>
      </properties>
      <master>false</master>
      <created_at>2014-05-01T21:25:47Z</created_at>
      <updated_at>2014-05-01T21:25:47Z</updated_at>
    </profile>
  </profiles>
</response>
Response Fields:
  • (Integer) profile[id]
    Id of the profile
  • (String) profile
    [name] Name of the profile
  • (Hash) profile[properties]
    List of key-value pairs for this profile.
  • (Boolean) profile[master]
    Are we creating a master profile.
  • (DateTime) profile[created_at]
    Timestamp of when the profile was created.
  • (DateTime) profile[updated_at]
    Timestamp of when the profile was last updated.

Url:

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

Returns profile information for the current account.

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 request returns the profile with the id of 1 for the current account for the current account.
https://service_name.synctv.com/api/v2/accounts/profiles/1.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.
Example Response
XML JSON

<response>
  <profile>
    <id>1</id>
    <name>John Doe</name>
    <properties>
    </properties>
    <master>false</master>
    <created_at>2014-05-01T21:25:49Z</created_at>
    <updated_at>2014-05-01T21:25:49Z</updated_at>
  </profile>
</response>
Response Fields:
  • (Integer) profile[id]
    Id of the profile
  • (String) profile
    [name] Name of the profile
  • (Hash) profile[properties]
    List of key-value pairs for this profile.
  • (Boolean) profile[master]
    Is this a master profile.
  • (DateTime) profile[created_at]
    Timestamp of when the profile was created.
  • (DateTime) profile[updated_at]
    Timestamp of when the profile was last updated.

Url:

  • [GET] /api/v2/profiles/count.[xml|json]

Returns a count of profiles for the current account.

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 count of all media.
[GET] https://service_name.synctv.com/api/v2/accounts/profiles/count.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Example Response
XML JSON

<response>
  <count>30</count>
  <code>1</code>
  <message>Successfully completed.</message>
</response>
Response Fields:
  • (Integer) count
    The count of account profiles

Url:

  • [PUT] /api/v2/accounts/profiles/:id.[xml|json]

Updates the profile of the currently authorized account.

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 request updates the current account's profile with id of 1 with name JoeSmith.
https://service_name.synctv.com/api/v2/accounts/profiles/1.xml?profile[name]=JoeSmith&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Request Field:
  • (String) profile[name] — Desired profile name.
  • (String) profile[properties][key_name] — Profile settings data, where key_name is the key for the key-value pair being set
Example Response
XML JSON

On success: HTTP 200
On error:   HTTP 400 with array of errors in message tags
<response>
  <code>-3</code>
  <messages>
    <message>Name can't be empty.</message>
  </messages>
</response>

Url:

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

Creates a new profile between the currently authorized account and the specified media object.

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 creates a new account profile that links the current account.
[POST] https://service_name.synctv.com/api/v2/accounts/profiles.xml?profile&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Request Field:
  • (String) profile[name] — Desired profile name.
  • (String) profile[properties][key_name] — Profile settings data, where key_name is the key for the key-value pair being set
Example Response
XML JSON

<response>
  <profile>
    <id>1</id>
    <name>John Doe</name>
    <properties>
    </properties>
    <master>false</master>
    <created_at>2014-05-01T21:25:54Z</created_at>
    <updated_at>2014-05-01T21:25:54Z</updated_at>
  </profile>
</response>
Response Fields:
  • (Integer) profile[id]
    Id of the profile
  • (String) profile
    [name] Name of the profile
  • (Hash) profile[properties]
    List of key-value pairs for this profile.
  • (Boolean) profile[master]
    Are we creating a master profile.
  • (DateTime) profile[created_at]
    Timestamp of when the profile was created.
  • (DateTime) profile[updated_at]
    Timestamp of when the profile was last updated.

Url:

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

Deletes the specified profile.

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 the profile with id = 100
[DELETE] https://service_name.synctv.com/api/v2/accounts/profiles/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>

Url:

  • [PUT] /api/v2/accounts/profiles/:id/set_current_profile.[xml|json]

Sets the specified profile as the current profile.

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 the profile with id = 100
[PUT] https://service_name.synctv.com/api/v2/accounts/profiles/100/set_current_profile.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>

Url:

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

Gets the currently set profile.

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 the profile with id = 100
[GET] https://service_name.synctv.com/api/v2/accounts/profiles/100/set_current_profile.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Example Response
XML JSON

<response>
  <profile>
    <id>1</id>
    <name>John Doe</name>
    <properties>
    </properties>
    <master>false</master>
    <created_at>2014-05-01T21:25:59Z</created_at>
    <updated_at>2014-05-01T21:25:59Z</updated_at>
  </profile>
</response>
Response Fields:
  • (Integer) profile[id]
    Id of the profile
  • (String) profile
    [name] Name of the profile
  • (Hash) profile[properties]
    List of key-value pairs for this profile.
  • (Boolean) profile[master]
    Are we creating a master profile.
  • (DateTime) profile[created_at]
    Timestamp of when the profile was created.
  • (DateTime) profile[updated_at]
    Timestamp of when the profile was last updated.