COVERITLIVE API - PIN/CREATE (V. 2.0)

The Request

This method allows for the creation of pin items. The pin item id is returned by this method if the pin item is successfully created, allowing for further interactions through the API.

URL:
https://api.coveritlive.com/remote/2/pin/create
Response Format:
JSON
HTTP Method(s):
POST
API Rate Limited:
false
In addition to the parameters listed in the Request Parameters section, the pin/create method also includes the following parameters:

Parameter Description Required
event_code The event code for the event in which the pin item is being created. Each CiL event that is created is assigned a unique event code that identifies it in the database - The event owner can find this value after creating a new event, by selecting the "altcast_code" which is found in their Viewer Window embed code (e.g. the event code is "46e6cd22b5" in "altcast_code=46e6cd22b5"). This value is also returned by the event/list API method. yes
content The content of the pin item to be created. May include HTML markup. May not be > 5000 characters in length. yes
status The status of the pin item to be created. Must be set to "published" or "unpublished".

Note: If the maximum number of pin items (3) have already been published, attempting to create new published pin items will return an error.

yes
direction Where the newly pin item will display. Valid values are "append" or "prepend". Appended items will appear at the end of the list of pin items, while prepended items will appear at the beginning. Omit this parameter if the status request parameter is set to "unpublished". Defaults to "append". no

The Response

The pin item id of a successfully created pin item is returned in the data field of a general response. This field will consist of a pin_id field, which will contain the pin item id.


Example response to a successful pin/create request:


{
	"result":"success",
	"message":"true",
	"type":"pin",
	"action":"create",
	"version":2,
	"data":{
		"pin_id" : "123456"
	}
}

pin/create Error Responses

A variety of error responses (in addition to the common error responses) to pin/create requests, and instructions on how to rectify them:

result response message response solution
missing_content_param Required parameter empty: content. Ensure the content request parameter is present.
invalid_content_param Exceeded maximum content length of: 5000 Ensure the content request parameter does not exceed 5000 characters in length (including markup).
missing_status_param Required parameter empty: status. Ensure the status request parameter is present.
invalid_direction_param Direction parameter contains an invalid value. Valid values include "append", "prepend". The direction request parameter can only be populated with one of the following values: "append", "prepend".
max_pin_items The maximum number of pin items have been published. If the status request parameter is set to "published", and there are already the maximum number of pin items published (3), then new pin items cannot be published. A currently published item must be unpublished first (can be achieved using the pin/update API request).
invalid_param_combo Direction parameter cannot contain a value when combined with a status parameter with a value of "unpublished". If the status request parameter is set to "unpublished" the direction request parameter should be omitted.