EspoCRM is a single page application so the frontend uses REST API to connect with the backend. All operations you perform using the UI, you can implement via API calls using your programing language. You can learn how the API works if you trace what's going in the network tab in your browser console (press F12 key to open the console).
Most of API functions return JSON. POST and PUT requests usually need some data passed in the payload in JSON format. Whenever you send the JSON payload, add the header:
The path to the API in EspoCRM is:
Example of GET API request
In this documentation we omit the site URL and
api/v1/ path when we show examples of API functions. If you utilize any our client implementation, it will prepend these URL parts automatically.
API client implementations (available below) do most of work for you: add needed headers, handle autentication, parameters, etc.
It's recommended to create a separate API user with specific rights (roles) and use this user for API calls.
See in tutorial how to get started.
In this article:
- CRUD operations – create, read, update, delete
- Related records
Authentication by API Key¶
The simplest method of authentication. You need to create an API User (Administration > API Users) with the API Key authentication method. Apply a needed role to the user to grant access to specific scopes.
The most secure method. You need to create an API User (Administration > API Users) with the HMAC authentication method. Apply a needed role to the user to grant access to specific scopes.
"X-Hmac-Authorization: " + base64Encode(apiKey + ':' + hashHmacSha256(method + ' /' + uri , secretKey))
method– GET, POST, PUT, DELETE;
uri– a request path, e.g.
This method is not recommended.
For regular (non-API) users the EspoCRM front-end uses the Basic Authentication. A username and password (or token) are passed through the
Authorization header encoded with Base64.
"Authorization: Basic " + base64Encode(username + ':' + password)
It's better to use an auth token instead of a password. In this case you will need to provide the username and the password/token in the
"Espo-Authorization: " + base64Encode(username + ':' + passwordOrToken)
- Obtain an access token by
GET App/userrequest with the username and password passed in
- Use this token instead of a password in
Espo-Authorizationheader for all further requests.
- If the request returns 401 error that means either that the username/password is wrong or the token is not valid anymore.
Authentication Token / User Specific Data¶
Make this request to retrieve an access token.
token– access token to use
acl– information about user access
preferences– user preferences
user– user record attributes
400 Bad request¶
When you create or update a record, this error can mean that you didn't pass a required field or it has an empty value. Check the response message or see
data/log for more details.
Usually occurs when you don't have access to a specific record or action. See
data/log for more details.
404 Not found¶
Usually occurs when a requested record doesn't exist.