My Apps

    Types & Formats

    Types & Formats

    The following sections explain some basic concepts about the types and formats that can be encountered within the Box APIs.

    Requests

    The Box APIs use JSON in the requests bodies. There are a few notable exceptions to this rule:

    • The POST /oauth2/token is used to request access tokens and as per the OAuth 2.0 specification it accepts the body to be sent with a content type of application/x-www-form-urlencoded.
    • Most of the APIs that are used to upload binary data, like the POST /files/content endpoint, expect data to be sent as form data with a content type of multipart/form-data.

    Although not required, we highly recommend passing a header with each API request to define the content type of the data sent, for example Content-Type: application/json.

    GZip compression

    By default data sent from Box is not compressed. To improve bandwidth and response times it's possible to compress the API responses by including a Accept-Encoding: gzip, deflate request header.

    Date and times

    The Box APIs support RFC 3339 timestamps. The preferred way to format a date in a request is to convert the time to UTC, for example 2013-04-17T09:12:36-00:00.

    In those cases where timestamps are rounded to a given day, the time component can be omitted. In this case, 2013-04-17T13:35:01+00:00 would become 2013-04-17. In those cases where timestamps support millisecond precision the expected request format should be as followed 2013-04-17T09:12:36.123-00:00.

    When making requests, when a timezone is omitted and a time has been provided the Pacific timezone is assumed. In responses, the timezone is based on your enterprise settings.

    Timestamps are restricted to dates after the start of the Unix epoch, 00:00:00 UTC on January 1, 1970.

    Responses

    The Box APIs generally returns JSON in the response body. There are a few notable exceptions to this rule as well.

    • APIs that delete items return an empty body with a 204 No Content HTTP status code.
    • APIs used to request binary data either return a 200 OK status code with the binary data attached, or a 202 Accepted, or 302 Found status code with no body and a Location header pointing to the actual binary file.

    The Content-Type response header can be used to understand the type of content returned in the API. Additionally, every API endpoint has it's response type documented in our API reference documentation.

    Resources

    Most standard API responses where only one resource is returned follow the following format.

    {
      "id": "12345",
      "type": "folder",
      ...
    }

    Every one of these resources will always return an ID and the type of the resource.

    Collections

    Where an API response returns multiple items a collection is returned. Although the exact format of these collections can change from endpoint to endpoint they generally are formatted as follows.

    {
      "total_count": 5000,
      "limit": 1000,
      "offset": 2000,
      "order": [
        {
          "by": "type",
          "direction": "ASC"
        }
      ],
      "entries": [
        {
          "id": 12345,
          "etag": 1,
          "type": "file",
          "sequence_id": 3,
          "name": "Contract.pdf"
        }
      ]
    }
    FieldAlways present?
    entriesYesA list of entries in the collection
    total_countNoThe total numbers in the collection that can be requested. This can be larger than this page of results
    limitNoFor endpoints that support offset-based pagination, this specifies the limit to the number of results returned
    offsetNoFor endpoints that support offset-based pagination, this specifies the offset of results returned
    orderNoFor endpoints that support sorting, this specifies the order the results are returned in
    next_markerNoFor endpoints that support marker-based pagination, this specifies the marker for the next page that can be returned
    prev_markerNoFor endpoints that support marker-based pagination, this specifies the marker for the previous page that can be returned

    Request IDs

    When your API call returns in an error, our API will return an error object with a request_id field.

    {
      "type": "error",
      "status": 400,
      "code": "item_name_invalid",
      "help_url": "http://developers.box.com/docs/#errors",
      "message": "Method Not Allowed",
      "request_id": "abcdef123456"
    }

    When reaching out to support about specific error, please provide the full API response including the request_id to help our support team to quickly find your request.

    MostAPI calls also return a BOX-REQUEST-ID response header. The value of this header should not be confused with the request_id value in the body of an error response.

    Large numbers

    In some cases the API can return extremely large numbers for a field. For example, a folder's size might have grown to many terabytes of data and as a result the size field of the folder might have grown to a very large number.

    In these cases these numbers are returned in IEEE754 format for example 1.2318237429383e+31.