Request

The Base API is accessed from the https://api.getbase.com domain. All data is sent and received in the JSON format and all API requests require authentication.


HTTP Verbs

Verb Description
HEAD Query HTTP headers
GET Retrieve resources
POST Creates resources or execute custom actions
PUT Partial update of resources
DELETE Delete resources

Query Parameters

Expanding

There are many cases where you need to load data related to the resource being requested. Rather than requiring you to hit the API repeatedly, we allow related data to be returned and loaded alongside the original resource on demand, which improves performance.

One or more resources can be included by using our standard includes parameter. The ?includes query parameter will take a comma-separated list of one or more resources related to the primary resource and return those resources as well.

Consult an endpoint’s parameter description in order to verify which related resources are supported.


Filtering

Record relationships in Base can be complex. It’s not uncommon to see URLs 5 or 6 levels deep. Usually, we don’t need to include the levels above once we have the primary key for the level we are interested in.

We made it as simple as possible for you to use the API by putting optional states and attributes behind the HTTP question mark. For more information, see the example below.

Consult an endpoint’s parameters description to check which properties are filterable for that endpoint.

IDs filter

You can control which individual resources that are returned during the request by appending the standard ids query parameter to the collection URL. The ?ids query parameter takes a comma-separated list of unique identifiers.

Custom Fields filter

In addition to standard attributes, we support custom fields filtering. In order to use it, you need set the custom field to as Filterable in the custom field settings. Keep in mind, only of the following custom field types are supported: Single Line Text, Number, Dropdown or Multi Select.


Pagination

You can control the maximum number of records that are returned using the standard per_page query parameter. To choose a page, use the standard page query parameter.

The default page is always the first one. Page numbering is 1-based and omitting the ?page parameter will return the first page.

The default limit is 25 and maximum number that can be returned is 100.


Sorting

You can control in what order, according to one criteria, how to sort resource collections using the standard query parameter sort_by.

The ?sort_by query parameter takes a field name to sort by.

The default sort order is ascending. If you want to change the sort order to ascending, append an :asc to the field (or append a :desc to explicitly specify descending).

Consult an endpoint’s parameters description in order to check what properties are sortable.

Custom Fields sort option

In addition to standard attributes, we support custom fields soring. In order to use it, you need set the custom field to as Filterable in the custom field settings. Keep in mind, only of the following custom field types are supported: Single Line Text, Number or Dropdown.

The following query shows how to sort by a custom field sku: ?sort_by=custom_fields:sku:desc.

Breaking down the query in more detail, sort_by operator instructs to use sorting, the custom_fields:sku part tells us to sort by a custom field sku, and the remaining element desc specify that we want to sort in descending order.


Headers

Content Negotiation

When you want a response in JSON, you will need to specify this. This is done via the Accept header, and setting the header’s value to application/json.

Accept: application/json

When you use the JSON format, you should specify that you are sending a JSON request in the header. This is done by setting the Content-Type header to application/json. This ensures that your request is interpreted correctly by our servers.

Content-Type: application/json

Language Negotiation

HTTP has built-in support for language negotiation through the standard Accept-Language header. Accept-Language works in the same way content negotiation works: by utilising the Accept pattern. 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.

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


User Agent

All API requests must include a valid User-Agent header. Requests with no User-Agent header will be rejected with 400 Bad Request and the error code invalid_user_agent will be included in the response payload.


Body

All JSON requests must specify the object type that the payload is carrying within the data field. In addition, you can include an object’s type within the meta/type attribute. The type field is mandatory unless the documentation for a given endpoint says otherwise.

Use an envelope to include additional fields in your request, such as metadata, pagination information, etc. Another reason for the envelope is that some clients don’t allow easy access to HTTP headers, and JSONP requests have no access to HTTP headers at all.


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.

Section 3.7 Mutual agreement of the ISO 8601 standard states that we are free to define our own representations as long as we do not interfere with the representations defined in the standard. On occasion you may want to specify an expiration time and set it to forever. Thanks to the loose standard we can mutually agree upon 9999-12-31T00:00:00Z to indicate forever.


Custom Fields

You can assign any number of custom fields to any single Lead, Contact or Deal. Each custom field is a key-value pair assigned to the custom_fields object field.

Custom fields must be defined via Settings before they can be assigned.

Most custom field values are strings, with the following exceptions:

  • Address values are nested objects, as defined in the Address documentation.
  • List values must match exactly the drop-down choice in Settings. Any other values will be ignored.
  • Multi Select values are arrays. Their elements must match exactly the drop-down choice in Settings. Any other values will be ignored.

Any custom fields not defined in Settings will be silently ignored, without an error response.


Tags

You can assign any number of tags to any single Lead, Contact or Deal. Tags are listed within the tags array field.

Tags don’t need to exist to be assigned - they can be created while creating a record. You can check them later via Tags API.

In order to modify tags on an object, you need to supply the entire set. tags are replaced every time they are used in a request which modifies a resource.