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:

  • Participants

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

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/participants.[xml|json]
  • [GET] /api/v2/media/:medium_id/participants.[xml|json]

Returns a list of all participants.

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 all participants.
[GET] https://service_name.synctv.com/api/v2/participants.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>
  <participants>
    <participant>
      <id>1</id>
      <name>Harrison Ford 6</name>
      <alias nil="true"/>
      <external_id>TMSID_6</external_id>
      <category nil="true"/>
      <gender nil="true"/>
      <birthplace nil="true"/>
      <date_of_birth nil="true"/>
      <date_of_death nil="true"/>
      <biography nil="true"/>
      <external_image_paths/>
    </participant>
    <participant>
      <id>2</id>
      <name>Harrison Ford 7</name>
      <alias nil="true"/>
      <external_id>TMSID_7</external_id>
      <category nil="true"/>
      <gender nil="true"/>
      <birthplace nil="true"/>
      <date_of_birth nil="true"/>
      <date_of_death nil="true"/>
      <biography nil="true"/>
      <external_image_paths/>
    </participant>
    <participant>
      <id>3</id>
      <name>Harrison Ford 8</name>
      <alias nil="true"/>
      <external_id>TMSID_8</external_id>
      <category nil="true"/>
      <gender nil="true"/>
      <birthplace nil="true"/>
      <date_of_birth nil="true"/>
      <date_of_death nil="true"/>
      <biography nil="true"/>
      <external_image_paths/>
    </participant>
  </participants>
</response>
Response Fields:
  • (Integer) participant[id]
    The unique identifier of the participant.
  • (String) participant[name]
    The name of the participant.
  • (String) participant[alias]
    List of alias for the participant.
  • (String) participant[external_id]
    External id for the participant (e.g. TMS id or IDMB)
  • (String) participant[category]
    Category of this participant (e.g. Signer, Actor, Newscaster, etc.)
  • (String) participant[gender]
    Gender of participant.
  • (String) participant[birthplace]
    Birth place participant.
  • (DateTime) participant[date_of_birth]
    Date of brith of the participant.
  • (DateTime) participant[date_of_death]
    Date of death of the participant.
  • (String) participant[birthplace]
    Birthplace of the participant.
  • (String) participant[biography]
    Biography participant.
  • (String) participant[external_image_paths]
    List of external image paths of the participant.

Url:

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

Returns the specified participant.

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 the information for participant 9.
[GET] https://service_name.synctv.com/api/v2/participants/9.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Example Response
XML JSON

<response>
  <participant>
    <id>1</id>
    <name>Harrison Ford 9</name>
    <alias nil="true"/>
    <external_id>TMSID_9</external_id>
    <category nil="true"/>
    <gender nil="true"/>
    <birthplace nil="true"/>
    <date_of_birth nil="true"/>
    <date_of_death nil="true"/>
    <biography nil="true"/>
    <external_image_paths/>
  </participant>
</response>
Response Fields:
  • (Integer) participant[id]
    The unique identifier of the participant.
  • (String) participant[name]
    The name of the participant.
  • (String) participant[alias]
    List of alias for the participant.
  • (String) participant[external_id]
    External id for the participant (e.g. TMS id or IDMB)
  • (String) participant[category]
    Category of this participant (e.g. Signer, Actor, Newscaster, etc.)
  • (String) participant[gender]
    Gender of participant.
  • (String) participant[birthplace]
    Birth place participant.
  • (DateTime) participant[date_of_birth]
    Date of brith of the participant.
  • (DateTime) participant[date_of_death]
    Date of death of the participant.
  • (String) participant[birthplace]
    Birthplace of the participant.
  • (String) participant[biography]
    Biography participant.
  • (String) participant[external_image_paths]
    List of external image paths of the participant.

Url:

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

Create a new participant.

Note:
The associated media_id, role_id, and person_id must already exist.
Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of query parameters.
  • (String) participant[name]
    The name of the participant.
  • (String) participant[alias]
    List of alias for the participant.
  • (String) participant[external_id]
    External id for the participant (e.g. TMS id or I
  • (String) participant[category]
    Category of this participant (e.g. Signer, Actor,
  • (String) participant[gender]
    Gender of participant.
  • (String) participant[birthplace]
    Birth place participant.
  • (DateTime) participant[date_of_birth]
    Date of brith of the participant.
  • (DateTime) participant[date_of_death]
    Date of death of the participant.
  • (String) participant[birthplace]
    Birthplace of the participant.
  • (String) participant[biography]
    Biography participant.
  • (String) participant[external_image_paths]
    List of external image paths of the participant.
Example Request

The following request creates a participant associated to media id 100, participant role id 1, and participant person id 1.
[POST] https://service_name.synctv.com/api/v2/participants.xml?participant[media_id]=100&participant[role_id]=1&participant[person_id]=1&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d

Url:

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

Update the specified participant.

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 modifies participant with id 5 to be associated with media_id 65, participant role_id 1, and participant person_id 3.
[PUT] https://service_name.synctv.com/api/v2/participants/5.xml?participant[media_id]=65&participant[role_id]=1&participant[person_id]=3&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Request Field:
  • (String) participant[name] — The name of the participant.
  • (String) participant[alias] — List of alias for the participant.
  • (String) participant[external_id] — External id for the participant (e.g. TMS id or I
  • (String) participant[category] — Category of this participant (e.g. Signer, Actor,
  • (String) participant[gender] — Gender of participant.
  • (String) participant[birthplace] — Birth place participant.
  • (DateTime) participant[date_of_birth] — Date of brith of the participant.
  • (DateTime) participant[date_of_death] — Date of death of the participant.
  • (String) participant[birthplace] — Birthplace of the participant.
  • (String) participant[biography] — Biography participant.
  • (String) participant[external_image_paths] — List of external image paths of the participant.
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>
    <message>Person record not found</message>
  </messages>
</response>

Url:

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

Delete the specified participant.

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