FreeCRM API

This is a live document

We're currently documenting our API here; this is a live document that will continue to change and evolve as we progress.

Standard response format

All responses that return a listing will contain the array of objects within a results key, while all requests that return a single object will contain it within a result key.

There are a few exceptions to this, most notably the /templates/ calls, which return an object where each key is a model type, and the value is an array of fields. Responses also contain a success flag, which should be true , and a process_time property showing how long it took the API to complete compiling the response.

Authentication

Authentication is performed by sending an Authorization header with a value of Token {ACCESS_TOKEN} with each request.
The access token is retrieved by calling the /auth/ endpoint with the user's email and password.

Note that a Successful authentication also returns a URLs object which describes which environment this account belongs to. For example, if your account is part of the eu environment, the API URLs for the EU API will be returned, and those should be used for subsequent requests.
Authentication is normally done against the master environment (.com).

Data models

Most data models in FreeCRM are made of a few basic fixed fields and any number of dynamic fields defined by the template your account is using.

Dynamic fields can be managed, new fields added, existing fields modified, etc. The models described in the API include the fixed fields of each data model; however, your return objects will contain any additional fields defined for your records.

For example, a Deal record will contain a title and description , but using the default unmodified template, it will also contain fields for next_steps and status
You can use the /templates/ endpoint to retrieve your account's templates in advance. The templates fully describe the structure of each data model, including labels, constraints, options, etc.
When fetching records, the result may contain only a subset of the record's fields. For example, when fetching a list of contacts, the contact records are not expanded to load each contact's cases or phone calls. However, when loading a single record, all related records are fetched as well. So when a single full contact record is fetched, it will contain references to all cases, calls, events, documents, etc.

Note that the templates allow you to label fields in your own language.

Filtering

Most listing GET requests allow a filter, alongside start and limit parameters.
start and limit define the range of records to return in a query set.
filter is a URL-encoded JSON object describing how to filter the data returned.

Using the API playground

In order to use the API calls using the Swagger UI, you will need to perform an authentication first, retrieve your token, and use it to authorize all future calls to the API. Click the Authorize button to input your token after you fetch it via the /auth/ call. Remember that the value is Token {ACCESS_TOKEN} and not just the token by itself.