Batch

Description #

The batch endpoint effectively allows up to 50 requests to be sent at once.

The following requests are supported by the batch endpoint:

• Create or Update Event
• Delete Event
• Edit External Event
• Delete External Event
• Create or Update Available Period
• Delete Available Period

Note: whilst the Batch endpoint is available on Starter plans, requests like “Create or Update Available Period” still require that you have subscribed to an Emerging plan or higher.

URL format #

{data_center_url}/v1/batch

Example Request #

POST /v1/batch HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "batch": [
    {
      "method": "DELETE",
      "relative_url": "/v1/calendars/cal_123_abc/events",
      "data": {
        "event_id": "456"
      }
    },
    {
      "method": "POST",
      "relative_url": "/v1/calendars/cal_123_abc/events",
      "data": {
        "event_id": "qTtZdczOccgaPncGJaCiLg",
        "description": "Discuss plans for the next quarter.",
        "start": "2014-08-05T15:30:00Z",
        "end": "2014-08-05T17:00:00Z",
        "location": {
          "description": "Board room"
        }
      }
    }
  ]
}

Example Response #

HTTP/1.1 207 Multi-Status
Content-Type: application/json; charset=utf-8

{
"batch": [
  { "status": 202 },
  {
    "status": 422,
    "data": {
      "errors": {
        "summary": [
          { "key": "errors.required", "description": "summary must be specified" }
        ]
      }
    }
  }
]
}

Request parameters #

batch required  #

An array of up to 50 requests that form part of the batch.

batch.method required  #

A String for the HTTP method of the individual request. Maps directly from its main documentation.

batch.relative_url required  #

A String for the relative URL (sometimes referred to as the path and query string) of the individual request. Maps directly from its main documentation.

batch.data required  #

An object containing the body parameters of the request. Maps directly from its main documentation.

Note that this is an object, not a JSON-encoded string.

Response parameters #

batch required  #

An array of responses corresponding directly to each request.

batch.status required  #

An Integer for the HTTP response code to the individual request.

Note that a 404 Not Found response code may also indicate that the request is not supported by the batch endpoint.

batch.headers optional  #

An object containing the headers of the individual response.

batch.data optional  #

An object containing the body of the individual response.

Error responses #

401 Unauthorized #

The request was refused as the provided authentication credentials were not recognized.

When an OAuth refresh_token is available then it should be used to request a replacement auth_token before the request is retried.