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:

  • Roles

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

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

Returns a list of all roles.

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

This following example returns a list of contributor roles.
[GET] https://service_name.synctv.com/contributors/roles.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) named_like — Filters response to include items that contain the specified value in the name field (e.g. named_like=Actor)
Example Response
XML JSON

<response>
  <roles>
    <role>
      <id>1</id>
      <name>role 12</name>
      <created_at>2014-05-01T21:33:24Z</created_at>
      <updated_at>2014-05-01T21:33:24Z</updated_at>
    </role>
    <role>
      <id>2</id>
      <name>role 13</name>
      <created_at>2014-05-01T21:33:24Z</created_at>
      <updated_at>2014-05-01T21:33:24Z</updated_at>
    </role>
  </roles>
</response>
Response Fields:
  • (Integer) id
    The unique identifier of the role.
  • (String) name
    The name/title of the role.
  • (String) created_at
    The timestamp of when the role record was created.
  • (String) updated_at
    The timestamp of when the role record was last updated.

Url:

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

Returns a role.

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

The follow example retrieves a single role record.
[GET] https://service_name.synctv.com/api/v2/contributors/roles/1.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Example Response
XML JSON

<response>
  <role>
    <id>1</id>
    <name>role 14</name>
    <created_at>2014-05-01T21:33:25Z</created_at>
    <updated_at>2014-05-01T21:33:25Z</updated_at>
  </role>
</response>
Response Fields:
  • (Integer) id
    The unique identifier of the role.
  • (String) name
    The name/title of the role.
  • (String) created_at
    The timestamp of when the role record was created.
  • (String) updated_at
    The timestamp of when the role record was last updated.

Url:

  • [POST] /api/v2/contributors/roles.[xml|json]

Create a new role.

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

The following request creates a new contributor role with name "Art Director"
[POST] https://service_name.synctv.com/api/v2/contributors/roles.xml?role[name]=Art Director&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Request Field:
  • (String) name — (required)(unique) The name/title of the role
Example Response
XML JSON

<response>
  <role>
    <id>1</id>
    <name>role 15</name>
    <created_at>2014-05-01T21:33:26Z</created_at>
    <updated_at>2014-05-01T21:33:26Z</updated_at>
  </role>
</response>
Response Fields:
  • (Integer) id
    The unique identifier of the role.
  • (String) name
    The name/title of the role.
  • (String) created_at
    The timestamp of when the role record was created.
  • (String) updated_at
    The timestamp of when the role record was last updated.

Url:

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

Updates the specified role. This will return only success or failure, no content.

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

The following request updates the name of contributor role id 1 to "Stage Director"
[PUT] https://service_name.synctv.com/api/v2/contributors/roles/1.xml?role[name]=Stage Director&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Request Field:
  • (String) name — (unique) The name/title of the role
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:

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

Deletes the specified role. This will return only success or failure, no content.

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

The following URL deletes role 100
[DELETE] https://service_name.synctv.com/api/v2/contributors/roles/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>