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:

  • Accounts

This document describes the API for creating, reading, updating and deleting accounts.

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

Returns a list of user accounts.

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 user accounts.
[GET] https://service_name.synctv.com/api/v2/accounts.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.
  • (String) by_email — Filters account listing by email address (e.g. by_email=example@synctv.com).
  • (String) with_role — Filters account listing by roles (e.g. with_role=admin).
  • (String) key — Filters response based on the meta_data key.
  • (String) value — Filters response based on the meta_data value.
  • (Array) any_of_account_type_ids — Filter accounts by account type ids (E.g. any_of_account_type_ids[]=1&any_of_account_type_ids[]=3)
  • (Array) none_of_account_type_ids — Filter accounts by none of account type ids (E.g. none_of_account_type_ids[]=1&none_of_account_type_ids[]=3)
  • (Array) sort_order — Defines the sort order of the response. (e.g. sort_order=created_at). Or can be multi-sort (e.g. sort_order[]=created_at&sort_order[]=id. When multi-sorting the order of the sort attributes in the url determines the hierarchy of which sort filter is applied first). Available sort attributes: id, email, created_at, updated_at.
  • (Boolean) sort_descending — Reverse order of sort_order sorting, make it descending.
Example Response
XML JSON

<response>
  <accounts>
    <account>
      <id>1</id>
      <email>test-account-13@synctv.com</email>
      <status>1</status>
      <roles>
        <role>user</role>
      </roles>
      <properties>
      </properties>
      <created_at>2014-05-01T21:29:07Z</created_at>
      <updated_at>2014-05-01T21:29:07Z</updated_at>
    </account>
    <account>
      <id>2</id>
      <email>test-account-14@synctv.com</email>
      <status>1</status>
      <roles>
        <role>user</role>
      </roles>
      <properties>
      </properties>
      <created_at>2014-05-01T21:29:07Z</created_at>
      <updated_at>2014-05-01T21:29:07Z</updated_at>
    </account>
  </accounts>
</response>
Response Fields:
  • (Response) accounts
    A list of accounts. See below for a description of the account response fields.

Url:

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

Returns information for the specified user 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 URL returns the account information for account with id == 100.
[GET] https://service_name.synctv.com/api/v2/accounts/100.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Example Response
XML JSON

<response>
  <accounts>
    <id>100</id>
    <email>test-account-15@synctv.com</email>
    <status>1</status>
    <roles>
      <role>user</role>
    </roles>
    <properties>
    </properties>
    <created_at>2014-05-01T21:29:08Z</created_at>
    <updated_at>2014-05-01T21:29:08Z</updated_at>
  </accounts>
</response>
Response Fields:
  • (Integer) account[id]
    The unique id of the account.
  • (String) account[email]
    The email address of the user.
  • (Integer) account[status]
    The status of the account [0 == inactive, 1 == active].
  • (Element) account[roles]
    A list of roles associated with the account used to determine access permissions.

Url:

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

Creates a new user account.

Example Request

The following URL creates an account with email "john_smith@synctv.com" and password "12345".
[POST] https://service_name.synctv.com/api/v2/accounts.xml?account[email]=john_smith@synctv.com&account[password]=12345&account[password_confirmation]=12345&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Request Field:
  • (Integer) access_id — Access id returned from Authorization (User) client_authorize.
  • (String) signature — MD5 hash encoded string of query parameters.
  • (String) account[email] — The email address of the user [e.g. john_smith@synctv.com].
  • (String) account[password] — The password for the account.
  • (String) account[password_confirmation] — The password confirmation.
  • (String) account[meta_data_attributes][][key] — Used to set the meta data key value.
  • (String) account[meta_data_attributes][][value] — Used to set the meta data value value.
  • (String) account[account_type_id] — Used to set the account type.
  • (Array) account[roles][] — Sets an account's role as "admin", "backend" or "user" (creator must have the correct permissions).
Example Response
XML JSON

<response>
  <account>
    <id>1</id>
    <email>test-account-16@synctv.com</email>
    <status>1</status>
    <roles>
      <role>user</role>
    </roles>
    <properties>
    </properties>
    <created_at>2014-05-01T21:29:08Z</created_at>
    <updated_at>2014-05-01T21:29:08Z</updated_at>
  </account>
</response>
Response Fields:
  • (Integer) account[id]
    The unique id of the account.
  • (String) account[email]
    The email address of the user.
  • (Integer) account[status]
    The status of the account [0 == inactive, 1 == active].
  • (Element) account[roles]
    A list of roles associated with the account used to determine access permissions.

Url:

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

Updates the specified account.

Note:
This will return only success or failure, no content.
Example Request

The following URL updates account 100 to have email "john_smith@synctv.com"
[PUT] https://service_name.synctv.com/api/v2/accounts/100.xml?account[email]=john_smith@synctv.com&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d

The following example creates a new meta_data.
[PUT] https://service_name.synctv.com/api/v2/account/1.xml?account[meta_data_attributes][][key]=meta_data_key&account[meta_data_attributes][][value]=some value&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d

The following example updates a meta data.
[PUT] https://service_name.synctv.com/api/v2/account/1.xml?account[meta_data_attributes][][id]=1&account[meta_data_attributes][][key]=meta_data_key&account[meta_data_attributes][][value]=something to change&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d

The following example deletes a meta data.
[PUT] https://service_name.synctv.com/api/v2/account/1.xml?account[meta_data_attributes][][id]=1&account[meta_data_attributes][][_destroy]=1&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Request Field:
  • (Integer) access_id — Access id returned from Authorization (User) client_authorize.
  • (String) signature — MD5 hash encoded string of query parameters.

Url:

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

Delete the specified 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 URL deletes account 100
[DELETE] https://service_name.synctv.com/api/v2/accounts/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:

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

Returns information for the current user 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 URL returns the account information of the current user account
[GET] https://service_name.synctv.com/api/v2/accounts/current.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Example Response
XML JSON

<response>
  <account>
    <id>1</id>
    <email>test-account-17@synctv.com</email>
    <status>1</status>
    <roles>
      <role>user</role>
    </roles>
    <properties>
    </properties>
    <created_at>2014-05-01T21:29:11Z</created_at>
    <updated_at>2014-05-01T21:29:11Z</updated_at>
  </account>
</response>
Response Fields:
  • (Integer) account[id]
    The unique id of the account.
  • (String) account[email]
    The email address of the user.
  • (Integer) account[status]
    The status of the account [0 == inactive, 1 == active].
  • (Element) account[roles]
    The list of roles associated with the account used to determine access permissions.

Url:

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

Returns a count of all accounts.

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 accounts.
[GET] https://service_name.synctv.com/api/v2/accounts/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 accounts

Url:

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

Activates the specified 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 activates account 100.
https://service_name.synctv.com/api/v2/accounts/100/activate.xml?access_id=4321&signature=129d2ad3a23826bfd77bd9da23768f02
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/:id/deactivate.[xml|json]

Dectivates the specified 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 deactivates account 101.
https://service_name.synctv.com/api/v2/accounts/101/deactivate.xml?access_id=4321&signature=129d2ad3a23826bfd77bd9da23768f02
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>