Responses

The Sell API will always respond with a JSON response, regardless of whether the request succeeds or fails.

Headers

Content Negotiation

Whenever you request data from the Sell API and set your expected format via the Accept header, the Sell API will respond with the Content-Type header set to the requested format. Requests for a format not supported by the server will be rejected with the 406 Not Acceptable status code.

Content-Type: application/json; charset=utf-8

Language Negotiation

All responses include the payload’s language in the Content-Language header. The header utilizes Language Tags, where any two-letter primary-tag is an ISO-639 language abbreviation and any two-letter initial subtag is an ISO-3166 country code.

Vary: Content-Language
Content-Language: en

If your request has no Accept-Language, the Sell API will return a response with all human-readable text in your default language (which can be changed via the dashboard).

If your request has data in the Accept-Language header, Sell API will sort the media types by the q parameter, select the first language in the list that the server can support, and include the Vary: Accept-Language response header.

If any language in the Accept-Language list is unsupported, Sell API will use your default language instead.

Request Unique Id

Every response contains the X-Request-Id header which identifies a specific request. It has a random universally unique identifier (UUID) format: the same uuid as the one returned as the logref in the error envelope.

Whenever you have a problem with a request, please get in touch with our support team to troubleshoot it and attach the unique identifier (UUID), which will help us to diagnose the problem.

X-Request-Id: 05b84162-28aa-45b5-a531-8bf1a69120dc

Body

The Sell API will always respond with a JSON response, regardless of whether the request succeeds or fails.

Date and Time

Date and time formats can cause a lot of confusion and interoperability issues. To overcome this, we use the industry-adopted standard, ISO 8601. Even though we internally store all the timestamps using the UTC timezone, we don’t make any assumptions about the timezone you supply.

The Section 3.7 Mutual agreement of the ISO 8601 standard says that we are free to define our own Date-Time representations, as long as we do not interfere with the representations defined in the standard. As a result, to indicate forever, use the representation 9999-12-31T00:00:00Z.

Envelope

Each API response is wrapped in a standard structure called the envelope, which holds the results of the API call, plus the metadata related to the request.

Name Description Type
items A collection of objects the payload carries. collection
data An object the payload carries. depends on endpoint
errors A collection of error objects. collection
error The error object. error
meta Payload’s metadata information e.g. pagination, type etc. -

Meta

Metadata information is always returned in the response body within the unique meta field. 

In a successful response, the meta object always holds the type attribute and pagination information, if the response includes a collection array. The type might be one of the following values:

Name Example Description
collection - An array of objects.
error - The error object.
resource_name contact Arbitrary resource type the payload carries.

On an error response, the metadata object holds error-related information such as the http_status and logref attributes.

Pagination

The pagination info is included in the meta attribute of the body’s envelope.

It is crucial to follow the links’ values instead of attempting to construct your own URLs.

Meta Attributes

Name Description
type Type of the response.
count The number of items in a result.

Meta’s Links Attributes

Name Description
self The URL of the results.
first_page The URL of the first page of results.
prev_page The URL of the immediate previous page of results.
next_page The URL of the next page of results.
last_page The URL of the last page of results.

The links object will only include pertinent links. So for the first page of results, no first_page or prev_page parameters will be included.

Examples

On the right side of the page, you can find some sample server responses for a single resource, collection of resources and errors.

Single resource response

{
  "data": {
    "id": 2,
    "is_organization": false,
    "private": false,
    "contact_id": 1,
    "name": "Mark Johnson",
    "first_name": "Mark",
    "last_name": "Johnson",
    "customer_status": "none",
    "prospect_status": "none",
    "title": "CEO",
    "description": "I know him via Tom",
    "industry": "Design Services",
    "webiste": "http://www.designservice.com",
    "email": "mark@designservices.com",
    "phone": "508-778-6516",
    "mobile": "508-778-6516",
    "fax": "+44-208-1234567",
    "twitter": "mjohnson",
    "facebook": "mjohnson",
    "linkedin": "mjohnson",
    "skype": "mjohnson",
    "address": {
        "line1": "2726 Smith Street",
        "line2": null,
        "city": "Hyannis",
        "postal_code": "02601",
        "state": "MA",
        "country": "US"
    },
    "tags": ["important"],
    "custom_fields": {
        "known_via": "tom"
    },
    "created_at": "2014-08-27T16:32:56Z",
    "updated_at": "2014-08-27T16:32:56Z"
  },
  "meta": {
    "type": "contact"
  }
}

Collection of resources response

{
  "items": [{
      "data": {
          "id": 1,
          "is_organization": true,
          "private": false,
          "contact_id": null,
          "name": "Design Services Company",
          "first_name": null,
          "last_name": null,
          "customer_status": "none",
          "prospect_status": "none",
          "title": null,
          "description": null,
          "industry": "Design Services",
          "webiste": "http://www.designservice.com",
          "email": null,
          "phone": null,
          "mobile": null,
          "fax": "+44-208-1234567",
          "twitter": null,
          "facebook": null,
          "linkedin": null,
          "skype": null,
          "address": {
              "line1": "2726 Smith Street",
              "line2": null,
              "city": "Hyannis",
              "postal_code": "02601",
              "state": "MA",
              "country": "US"
          },
          "tags": ["important"],
          "custom_fields": {
              "known_via": "tom"
          },
          "created_at": "2014-08-27T16:32:56Z",
          "updated_at": "2014-08-27T16:32:56Z"
      },
      "meta": {
          "type": "contact"
      }
  }, {
      "data": {
          "id": 2,
          "is_organization": false,
          "private": false,
          "contact_id": 1,
          "name": "Mark Johnson",
          "first_name": "Mark",
          "last_name": "Johnson",
          "customer_status": "none",
          "prospect_status": "none",
          "title": "CEO",
          "description": "I know him via Tom",
          "industry": "Design Services",
          "webiste": "http://www.designservice.com",
          "email": "mark@designservices.com",
          "phone": "508-778-6516",
          "mobile": "508-778-6516",
          "fax": "+44-208-1234567",
          "twitter": "mjohnson",
          "facebook": "mjohnson",
          "linkedin": "mjohnson",
          "skype": "mjohnson",
          "address": {
              "line1": "2726 Smith Street",
              "line2": null,
              "city": "Hyannis",
              "postal_code": "02601",
              "state": "MA",
              "country": "US"
          },
          "tags": ["important"],
          "custom_fields": {
              "known_via": "tom"
          },
          "created_at": "2014-08-27T16:32:56Z",
          "updated_at": "2014-08-27T16:32:56Z"
      },
      "meta": {
          "type": "contact"
      }
  }],
  "meta": {
      "type": "collection",
      "count": 2,
      "links": {
          "self": "http://api.getbase.com/v2/contacts"
      }
  }
}

Error response

{
  "errors": [{
    "error": {
      "resource": "contact",
      "field": "/data/last_name",
      "code": "blank",
      "message": "attribute can't be blank",
      "details": "The attribute '/data/last_name' can't be blank (neither null nor empty)."
    },
    "meta": {
      "links": {
        "more_info": "https://developers.getbase.com/docs/rest/articles/errors/blank"
      }
    }
  }],
  "meta": {
    "http_status": "422 Unprocessable Entity",
    "logref": "b4bce554-8df2-48b1-9f68-a88e741463f0",
    "links": {
      "more_info": "https://developers.getbase.com/help"
    }
  }
}