Introduction

Depends on your web server, Concord CRM API is exposed as an HTTP/1 and HTTP/2 service over SSL (recommended). All endpoints live under the URL crm.example.com/api and then generally follow the REST architecture.

Content Type

All requests must be encoded as JSON with the Content-Type: application/json header. Most responses, including errors, are encoded exclusively as JSON as well.

Authentication

Provide your API token as part of the Authorization header Authorization: Bearer {token}.

If the authentication is unsuccessful, the status code 401 is returned.

Each user that has access to API enabled, can generate an API token to be used for authorization, making API requests will work the same as an action is performed via the Dashboard.

To generate an API token, login into the Concord CRM dashboard and click the sidebar profile dropdown then click Personal Access Tokens.

Headers

With each API request, the following headers must be included:

Accept: application/json
Content-Type: application/json
Authorization: Bearer [API-TOKEN]

Please note that some services/plugins automatically include the referer or the origin header when making an API request, you should ensure that these headers are not included as they are conflicting with the Laraval Sanctum package Concord CRM is using.

Laravel Sanctum checks the referer and the origin header to determine whether the request is made from the frontend in order to validate the CSRF token, if the request includes any of the referer or origin headers, you will receive the CSRF token mismatch error.

Common HTTP Verbs

Verb Description
Used for retrieving resources.
Used for creating resources.
Used for updating resources.
Used for deleting resources.

Pagination

Requests that return multiple items will be paginated to 15 items by default. You can specify further pages with the ?page query string parameter. For some resources, you can also set a custom page size up to 100 with the ?per_page parameter. Note that for technical reasons not all endpoints respect the ?per_page parameter.

Rate Limiting

We limit the number of calls you can make over a certain period of time. Rate limits vary and are specified by the following header in all responses:

Header Name Description
X-RateLimit-Limit The maximum number of requests you're permitted to make per minute.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.

If you exceed the rate limit, an error response returns with the status 429 Too Many Requests.

Custom Fields

The section below explains on how to use and provide the custom fields via Concord CRM API. Usually when you will create custom fields in Concord CRM and you plan to use the API, you will want to fill those custom fields with data via HTTP and requests.

When saving on custom fields on resources, you will need to use the custom field ID you provided during custom field creation. The ID should be added in the HTTP request payload with the appropriate value based on the custom field type.

Find the list below to see examples of custom field key and their values when providing in request.

Type Value Type Sample Payload
Boolean boolean [ ...payload, "field_id" => true ]
ColorSwatch string [ ...payload, "field_id" => '#333333' ]
Checkbox array [ ...payload, "field_id" => [5] // options id's ]
Date date [ ...payload, "field_id" => "2020-11-26" ]
DateTime date UTC [ ...payload, "field_id" => "2020-11-26 06:00:00" ]
Email string [ ...payload, 'field_id' => "john@example.com" ]
MultiSelect array [ ...payload, "field_id" => [5] // options id's ]
Number integer [ ...payload, "field_id" => 200 ]
Numeric decimal(15, 3) [ ...payload, "field_id" => 1250.330 ]

[ ...payload, "field_id" => 1300 ]
Radio integer [ ...payload, "field_id" => 5 // option id ]
URL string [ ...payload, "field_id" => 'https://www.concordcrm.com' ]
Select integer [ ...payload, "field_id" => 10 // option id ]
Text string [ ...payload, "field_id" => "Sample Text" ]
Textarea string [ ...payload, "field_id" => "Sample Text" ]
Timezone string [ ...payload, "field_id" => "America/Toronto" ]

Troubleshoot

CSRF token mismatch

If you are encountering the CSRF token mismatch error when an API request is made, make sure the following:

  • Ensure that the Accept header is sent with the request.
  • Ensure that the Authorization header is sent with the request.
  • Ensure that the referer and origin headers are NOT sent with the request.