API Headers
Using headers we can tell the server what information we are sending to it and what we expect in return. The CORE REST APIs supports the following common HTTP request and response headers.
Accept: The Accept request header specifies the desired media type of the response. CORE uses application/json for most API interactions.
Accept-Encoding: This represents the desired content-coding in the response. This is usually set by the request library in use if that library supports HTTP compression. This can significantly improve the performance of your app when interacting with CORE APIs, due to the reduced size of the response data.
Authorization: The HTTP Authorization request header contains the credentials to authenticate a user agent with a server. This header is required for all the requests
Connection: The Connection general header controls whether or not the network connection stays open after the current transaction finishes. If the value sent is keep-alive, the connection is persistent and not closed, allowing for subsequent requests to the same server to be done.
Date: The date header specifies the date/time at which the message originated
Host: The Host header specifies the host and port number of requested resource
X-UTC-Offset: The offset is the number of hours or minutes a certain time zone is ahead of or behind GMT. A time zone’s offset can change throughout the year because of Daylight Saving Time.
Referrer: The Referer request header field allows the client to specify the address URI of the resource from which the URL has been requested
User-Agent: The User-Agent header specifies the identifier string for a Web browser or user agent
Allow: The Allow entity header field lists the set of methods supported by the resource identified by the Request-URI
Content-Language: The Content-Language entity header field describes the natural languages of the intended audience for the enclosed entity
Content-Type: The Content-Type entity header field indicates the media type of the entity-body sent to the recipient. CORE API objects are returned as application/json
Content-Length: The Content-Length entity header field indicates the size of the entity-body. This header is used for POST APIs
Date: The date header specifies the date/time at which the message originated
Rate Limiting
As a security measure and to improve availability and quality of service, CORE APIs impose a limit on the number of requests your applications can make in a given amount of time. If they exceed that limit, the API endpoints respond with the 429: Too Many Requests status code to the requests until the limit time interval is over. The 429 response contains a Retry-After header that lets you know the amount of time in seconds your applications need to wait before sending the requests again.
How it works?
As of now, there are two types of rate limits applicable to CORE APIs:
- Per Minute Limit: A fixed number of requests per app
- Per Minute Limit: A fixed number of requests per app per user
Check out this article to know which of these limits are applicable to your application. In the first case, an application can only make a fixed number of requests to the CORE API endpoints in a minute. If the application is making requests for multiple CORE users, the rate limit is shared across them. In the second case, an application can make a fixed number of requests to the endpoints in a minute for each user. The rate limit is not shared by the users in this case and each user gets a separate quota of requests. Also, the endpoints listed below are exempt from rate limiting:
- {base_url}/version
- {base_url}/health
Before your application exceeds the rate limit, the HTTP response for the API requests includes the headers below, which give you an indication of the type of the limit and the number of requests remaining before the limit is imposed.
X-Rate-Limit-Limit: This is the time interval for which the limit is imposed. For CORE APIs, it always has the value 1m indicating the limit is on a per-minute basis.
X-Rate-Limit-Remaining: This indicates the number of API requests remaining before the rate limit is imposed. The value is reset at the end of the one-minute interval.
X-Rate-Limit-Reset: This is the exact time in ISO-8601 date-time format when the rate limit is reset. It represents the time when the one-minute interval for the rate limit is over and the next interval starts.
When your application exceeds the rate limit, all subsequent requests are responded with the 429: Too Many Requests response code until the time interval for the limit is over. This response also contains the Retry-After header, which lets you know the time in seconds your application should wait before making the next API request in order to comply with the rate limit.
Handling the rate limit
We highly recommend that you handle the rate limit for CORE APIs in your applications using the Retry-After header sent in the 429 responses. It ensures that your applications make the API requests in compliance with the rate limit while not getting burdened unnecessarily and wasting resources. You can also use the X-Rate-Limit headers for this purpose because they give you the specifics of the rate limit even before you exceed it. We also recommend that you optimize your applications in a way that makes the most of our APIs without exceeding the request limit. Reducing the number of API calls that your applications make in a given amount of time while achieving similar end results is the key. For example, instead of continuously polling for changes in data, you can use webhooks where possible.
Custom Fields
Custom fields in CORE give you the ability to add additional data that is not included in your records or profile by default. Every employee, client, and project record can have custom fields.
How to Use Custom Fields
- Create a custom field, say, "Phone". To see how to create a custom field, click here. A successful request returns the custom field in the response with a status code 201. Example RequestResponse
- Assign it to a module, say, "Client". To see how to assign a custom field, click here. A successful request returns no content with a status code 200. Example Request
- Get the list of assigned custom fields using the list endpoint with the following query string: where="module=6 AND id='2385d222-721f-4f67-80a0-b66b1bb47f4a'". Example RequestResponse
- Set the value of a custom field. In the API request below, you are adding the field value while creating a client. You can also directly set or retrieve custom field values using the Custom Field Value endpoints. Example RequestResponse
Learn more about how to
Date Time Format
Some requests that create new data allow you to provide time zone information when specifying or generating timestamps. We apply the following rules to determine timezone information for API calls. ISO 8601 provides a standard cross-national approach.
ISO 8601 Date Time Format
When dates are represented with numbers they can be interpreted in different ways. For example, 01/05/12 could mean January 5, 2012, or May 1, 2012. On an individual level this uncertainty can be very frustrating, in a business context it can be very expensive or serious.
ISO 8601 tackles this uncertainty by setting out an internationally agreed way to represent dates: YYYY-MM-DDThh-mm-ss
where:
YYYY = four-digit year
MM = two-digit month (eg 03=March)
DD = two-digit day of the month (01 through 31)
T = a set character indicating the start of time element
hh = two digits of an hour (00 through 23, AM/PM not included)
mm = two digits of a minute (00 through 59)
ss = two digits of a second (00 through 59)
mmm = three digits of a millisecond (000 through 999)
Example: An API call to retrieve a time entry, where the created on date is greater than 2019-01-01T21:00:00
Subscriptions and Security Permissions
When a CORE user grants API access to your application, the user's subscriptions and security permissions limit your application's access to the APIs just like they limit the user's access in CORE. The subscription packages assigned to the user in CORE determine the screens that the user has access to, which in turn determines the APIs that your application can access. Similarly, a user's security permissions apply on top of subscriptions and determine the actions that a user can perform within the subscribed features. This means the user's security permissions restrict the actions that your application can perform using the API endpoints. Check out the relevant articles in CORE Help Center to know more about subscriptions and security permissions.