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:

  • People

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

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

Returns a list of all people.

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 a list of contributor people
[GET] https://service_name.synctv.com/api/v2/contributors/people.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=Eastwood)
Example Response
XML JSON

<response>
  <people>
    <person>
      <id>1</id>
      <name>person name 12</name>
      <website_url nil="true"/>
      <date_of_birth nil="true"/>
      <biography nil="true"/>
      <created_at>2014-05-01T21:33:29Z</created_at>
      <updated_at>2014-05-01T21:33:29Z</updated_at>
    </person>
    <person>
      <id>2</id>
      <name>person name 13</name>
      <website_url nil="true"/>
      <date_of_birth nil="true"/>
      <biography nil="true"/>
      <created_at>2014-05-01T21:33:29Z</created_at>
      <updated_at>2014-05-01T21:33:29Z</updated_at>
    </person>
  </people>
</response>
Response Fields:
  • (Integer) id
    The unique identifier of the person's record.
  • (String) name
    The name of the person.
  • (String) website_url
    The website url of the person.
  • (String) date_of_birth
    The date of birth of the person.
  • (String) biography
    The biography of the person.
  • (String) created_at
    The timestamp of when the person's record was create.
  • (String) updated_at
    The timestamp of when the person's record was last updated.

Url:

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

Returns information for the specified person.

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 follow example retrieves a single person record.
[GET] https://service_name.synctv.com/api/v2/contributors/people/1.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Example Response
XML JSON

<response>
  <person>
    <id>1</id>
    <name>person name 14</name>
    <website_url nil="true"/>
    <date_of_birth nil="true"/>
    <biography nil="true"/>
    <created_at>2014-05-01T21:33:30Z</created_at>
    <updated_at>2014-05-01T21:33:30Z</updated_at>
  </person>
</response>
Response Fields:
  • (Integer) id
    The unique identifier of the person's record.
  • (String) name
    The name of the person.
  • (String) website_url
    The website url of the person.
  • (String) date_of_birth
    The date of birth of the person.
  • (String) biography
    The biography of the person.
  • (String) created_at
    The timestamp of when the person's record was create.
  • (String) updated_at
    The timestamp of when the person's record was last updated.

Url:

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

Creates a new person.

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

The following request create a contributor person with name "Rambo 3" and biography "Action Hero."
[POST] https://service_name.synctv.com/api/v2/contributors/people.xml?person[name]=Rambo 3&person[biography]=Action Hero&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Request Field:
  • (String) person[website_url] — The website url of the person.
  • (String) person[date_of_birth] — The date of birth of the person.
  • (String) person[biography] — The biography of the person.
Example Response
XML JSON

<response>
  <person>
    <id>1</id>
    <name>person name 15</name>
    <website_url nil="true"/>
    <date_of_birth nil="true"/>
    <biography nil="true"/>
    <created_at>2014-05-01T21:33:32Z</created_at>
    <updated_at>2014-05-01T21:33:32Z</updated_at>
  </person>
</response>
Response Fields:
  • (Integer) id
    The unique identifier of the person's record.
  • (String) name
    The name of the person.
  • (String) website_url
    The website url of the person.
  • (String) date_of_birth
    The date of birth of the person.
  • (String) biography
    The biography of the person.
  • (String) created_at
    The timestamp of when the person's record was create.
  • (String) updated_at
    The timestamp of when the person's record was last updated.

Url:

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

Updates the specified person's record.

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 modified contributor person with id 1 to have a name of "Tom Hanks."
[PUT] https://service_name.synctv.com/api/v2/contributors/people/1.xml?person[name]=Tom Hanks&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Request Field:
  • (String) person[name] — The name of the person.
  • (String) person[website_url] — The website url of the person.
  • (String) person[date_of_birth] — The date of birth of the person.
  • (String) person[biography] — The biography of the person.
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/people/:id.[xml|json]

Deletes the specified person's record.

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 person 100
[DELETE] https://service_name.synctv.com/api/v2/contributors/people/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>