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.

Here's a glimpse of our Date-Time syntax, where timezone-offset set to Z indicates the UTC timezone:

{year}-{month}-{day}T{hour}:{minute}:{second},{nanosecond}{timezone-offset}
2014-12-08T12:35: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.

{
  "items": [
    ...
  ],
  "meta": {
    "type": "collection",
    "count": 25,
    "links": {
      "self": "https://api.getbase.com/v2/contacts?page=1&per_page=25",
      "next_page": "https://api.getbase.com/v2/contacts?page=2&per_page=25"
    }
  }
}

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,
      "creator_id": 5339024,
      "contact_id": 1,
      "created_at": "2014-08-27T16:32:56Z",
      "updated_at": "2014-08-27T16:32:56Z",
      "title": "CEO",
      "name": "Mark Johnson",
      "first_name": "Mark",
      "last_name": "Johnson",
      "description": "I know him via Tom",
      "website": "https://www.designservice.com",
      "email": "[email protected]",
      "phone": "508-778-6516",
      "mobile": "508-778-6516",
      "fax": "[phone]",
      "twitter": "mjohnson",
      "facebook": "mjohnson",
      "linkedin": "mjohnson",
      "skype": "mjohnson",
      "owner_id": 5339024,
      "is_organization": false,
      "address": {
          "city": "Hyannis",
          "line1": "2726 Smith Street",
          "postal_code": "02601",
          "state": "MA",
          "country": "US"
      },
      "shipping_address": {
          "city": "Hyannis",
          "line1": "2726 Smith Street",
          "postal_code": "02601",
          "state": "MA",
          "country": "US"
      },
      "billing_address": {
          "city": "Hyannis",
          "line1": "2726 Smith Street",
          "postal_code": "02601",
          "state": "MA",
          "country": "US"
      },
      "industry": "Design Services",
      "tags": [
        "important"
      ],
      "custom_fields": {
          "known_via": "tom"
      },
      "customer_status": "none",
      "prospect_status": "none",
      "parent_organization_id": null
  },
  "meta": {
      "version": 3,
      "type": "contact"
  }
}

---

Collection of resources response

{
  "items": [{
      "data": {
          "id": 1,
          "creator_id": 5339024,
          "contact_id": null,
          "created_at": "2014-08-27T16:32:56Z",
          "updated_at": "2014-08-27T16:32:56Z",
          "title": null,
          "name": "Design Services Company",
          "first_name": null,
          "last_name": null,
          "description": null,
          "website": "https://www.designservice.com",
          "email": null,
          "phone": null,
          "mobile": null,
          "fax": "[phone]",
          "twitter": null,
          "facebook": null,
          "linkedin": null,
          "skype": null,
          "owner_id": 5339024,
          "is_organization": true,
          "address": {
              "city": "Hyannis",
              "line1": "2726 Smith Street",
              "postal_code": "02601",
              "state": "MA",
              "country": "US"
          },
          "shipping_address": {
              "city": null,
              "line1": null,
              "postal_code": null,
              "state": null,
              "country": null
          },
          "billing_address": {
              "city": null,
              "line1": null,
              "postal_code": null,
              "state": null,
              "country": null
          },
          "industry": "Design Services",
          "tags": [
            "important"
          ],
          "custom_fields": {
            "known_via": "tom"
          },
          "customer_status": "none",
          "prospect_status": "none",
          "parent_organization_id": null
      },
      "meta": {
          "version": 3,
          "type": "contact"
      }
  }, {
      "data": {
          "id": 2,
          "creator_id": 5339024,
          "contact_id": 1,
          "created_at": "2014-08-27T16:32:56Z",
          "updated_at": "2014-08-27T16:32:56Z",
          "title": "CEO",
          "name": "Mark Johnson",
          "first_name": "Mark",
          "last_name": "Johnson",
          "description": "I know him via Tom",
          "website": "https://www.designservice.com",
          "email": "[email protected]",
          "phone": "508-778-6516",
          "mobile": "508-778-6516",
          "fax": "[phone]",
          "twitter": "mjohnson",
          "facebook": "mjohnson",
          "linkedin": "mjohnson",
          "skype": "mjohnson",
          "owner_id": 5339024,
          "is_organization": false,
          "address": {
              "city": "Hyannis",
              "line1": "2726 Smith Street",
              "postal_code": "02601",
              "state": "MA",
              "country": "US"
          },
          "shipping_address": {
              "city": "Hyannis",
              "line1": "2726 Smith Street",
              "postal_code": "02601",
              "state": "MA",
              "country": "US"
          },
          "billing_address": {
              "city": "Hyannis",
              "line1": "2726 Smith Street",
              "postal_code": "02601",
              "state": "MA",
              "country": "US"
          },
          "industry": "Design Services",
          "tags": [
            "important"
          ],
          "custom_fields": {
              "known_via": "tom"
          },
          "customer_status": "none",
          "prospect_status": "none",
          "parent_organization_id": null
      },
      "meta": {
          "version": 3,
          "type": "contact"
      }
  }],
  "meta": {
      "type": "collection",
      "count": 2,
      "links": {
          "self": "https://api.getbase.com/v2/contacts?page=1&per_page=25"
      }
  }
}

---

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": {
      "type": "error",
      "links": {
        "more_info": "https://developers.getbase.com/docs/rest/articles/errors"
      }
    }
  }],
  "meta": {
    "type": "errors",
    "http_status": "422 Unprocessable Entity",
    "logref": "b4bce554-8df2-48b1-9f68-a88e741463f0",
    "links": {
      "more_info": "https://developers.getbase.com/docs/rest/articles/errors"
    }
  }
}