API v2
Contents
General information
For general rules of the example code organisation see CoreData API | Example-API-requests-&-responses.
Authentication
For API v2 authentication details see CoreData API | API-v2-authentication.
Endpoints
Available API v2 endpoints can be represented within the following groups:
Filtering
In addition to limit and offset, a filtering can be added and combined with limit and offset.
Filtering by title
For Contacts, Files, Projects and Tasks it's possible to filter down to entities that have a given title:
?title=$some_title or ?title__startswith=$prefix_of_the_title.
Example:
curl -v \
-H "Authorization: apikey $API_USER:$API_KEY" \
$COREDATA_BASE_URL/api/v2/projects/?title__startswith=BoardFiltering by parent
For Files it is possible to filter based on the File parent (folder):
?parent=$uuid_of_a_folder
Example:
curl -v \
-H "Authorization: apikey $API_USER:$API_KEY" \
$COREDATA_BASE_URL/api/v2/files/?parent=$some_uuidWhere:
some_uuid– ID of aFolder, a parent of targetFiles.
Filtering by Contact
In order to get a list of Projects associated to a given Contact, first get the ID of the Contact. E.g. given a Contact with SSN=60001019906 and SSN_PREFIX=600010199 respectively. Then getting the Contact's ID using their SSN looks like this:
# [1] Using Contact's full SSN
curl -v \
-H "Authorization: apikey $API_USER:$API_KEY" \
$COREDATA_BASE_URL/api/v2/contacts/?identifier=$SSN
# [2] Or using Contact's SSN prefix
curl -v \
-H "Authorization: apikey $API_USER:$API_KEY" \
$COREDATA_BASE_URL/api/v2/contacts/?identifier__startswith=$SSN_PREFIXThis will return a list of matching Contacts containing amongst other fields is the Contact's ID that can be used elsewhere. Here is an example excerpt:
{
"meta": {
"limit": 20,
"next": null,
"offset": 0,
"previous": null,
"total_count": 1
},
"objects": [
{
"id": "2f2672e8-71cf-11ee-848e-47ba9faefc74",
"snapshot_id": "2f268170-71cf-11ee-848e-77ab977f6f41",
"identifier": "60001019906",
"dynatype": {
"caption_plural": "dynatypes_labels:Person_plural:",
"caption_singular": "dynatypes_labels:Person_singular:",
"id": "d2114cf4-71ce-11ee-a1c1-93a2e894b852",
"title": "Person"
},
"emails": [
{
"email": "signer@example.is",
"label": "email_label:Work:"
}
],
"phones": [
{
"label": "phone_label:Mobile:",
"number": "+37200000766"
}
],
"role": "contact_role:customer:",
"status": "contact_status:Active:",
"title": "Signer Signer",
"type": "Contact",
// ... More fields
}
]
}The Contact’s ID from the example above is the following CONTACT_ID=2f2672e8-71cf-11ee-848e-47ba9faefc74.
To get list of the Contact's Projects use either of the following examples:
# [1]
curl -v \
-H "Authorization: apikey $API_USER:$API_KEY" \
$COREDATA_BASE_URL/api/v2/projects/?associated_contacts_id=$CONTACT_ID
# [2]
curl -v \
-H "Authorization: apikey $API_USER:$API_KEY" \
$COREDATA_BASE_URL/api/v2/contacts/$CONTACT_ID/projects/Same goes for Files and Tasks that are associated with that Contact:
# [1]
curl -v \
-H "Authorization: apikey $API_USER:$API_KEY" \
$COREDATA_BASE_URL/api/v2/files/?associated_contacts_id=$CONTACT_ID
# [2]
curl -v \
-H "Authorization: apikey $API_USER:$API_KEY" \
$COREDATA_BASE_URL/api/v2/tasks/?associated_contacts_id=$CONTACT_ID
# [3]
curl -v \
-H "Authorization: apikey $API_USER:$API_KEY" \
$COREDATA_BASE_URL/api/v2/contacts/$CONTACT_ID/files/
# [4]
curl -v \
-H "Authorization: apikey $API_USER:$API_KEY" \
$COREDATA_BASE_URL/api/v2/contacts/$CONTACT_ID/tasks/Filtering by creation or modification date
It is possible to filter by creation and modification date fields using these operations:
Operation | Shortcut |
|---|---|
|
|
|
|
|
|
|
|
|
|
The parameter name passed to API endpoint is constructed using the field name a shortcut from the table joined with two underscored __. For range operation its parameters should be separated by the comma in the URL.
The date format used in requests and responses is the ISO 8601. Here is an example 2019-09-02T15:38:32Z, where the T serves as a date and time separator, and the Z stands for the UTC timezone.
Here are some examples.
Example [1] – Files modified after timestamp (excluding):
curl -v \
-H "Authorization: apikey $API_USER:$API_KEY" \
$COREDATA_BASE_URL/api/v2/files/?modified__gt=2019-09-02T15:38:32ZExample [2] – Projects created before timestamp (including):
curl -v \
-H "Authorization: apikey $API_USER:$API_KEY" \
$COREDATA_BASE_URL/api/v2/projects/?created__lte=2019-09-02T15:38:32ZExample [3] – Contacts modified between timestamps (excluding):
curl -v \
-H "Authorization: apikey $API_USER:$API_KEY" \
$COREDATA_BASE_URL/api/v2/contacts/?modified__range=2019-08-02T15:38:32Z,2019-09-02T15:38:32ZThis filtering works for /api/v2/projects, /api/v2/files, /api/v2/contacts and /api/v2/tasks endpoints.
Endpoint response format
The responses of endpoints returning a list of objects are JSON objects and structured like this:
{
"meta": {
"limit": 20,
"next": null,
"offset": 0,
"previous": null,
"total_count": 1
},
"objects": [
{
"id": "2f2672e8-71cf-11ee-848e-47ba9faefc74",
"snapshot_id": "2f268170-71cf-11ee-848e-77ab977f6f41",
// ... More object type specific fields
}
]
}Where:
meta– contains overall information on the currently returned list of objects, where:limit– maximum number of objects to return;next– ?offset– the offset used in query performed to get the result objects;previous– ?total_count– total number of objects actually returned.
objects– the list of objects returned by endpoint, each object contains:id(which is always the same for an object);snapshot_id(which changes every time the object gets changed);more fields depending on the object’s type.
Limit and offset
Results pagination fields
For list endpoints, such as Spaces, Projects, Files, and others, the Response Body contains a JSON meta field. This field always has the following attributes:
limit– number of results returned, default is20;offset– starting point, default is0;next– URL to subsequent batch ornull;previous– URL to the previous batch ornull;total_count– total number of entities found.
These fields are provided to allow pagination of results.
To control the number of results fetched in each GET request, the request query can be augmented with a limit by appending e.g. ?limit=5 (this would return 5 objects).
To fetch the next batch, the request query can be augmented with an offset by appending e.g. ?offset=5 (this would get objects starting from the 6th object).
These can be combined to ?limit=5&offset=5.
Pagination request example
Here is an example of a request for the second pages of spaces having the limit set to 1:
curl -v \
-H "Authorization: apikey $API_USER:$API_KEY" \
"$COREDATA_BASE_URL/api/v2/spaces/?limit=1&offset=1"The response example looks like this:
{
"meta": {
"limit": 1,
"next": "/api/v2/spaces/?limit=1&offset=2",
"offset": 1,
"previous": "/api/v2/spaces/?limit=1&offset=0",
"total_count": 6
},
"objects": [
{
"aspects": {},
"created": "2024-02-26T12:17:21",
"created_by": "Administrator Administrator",
"description": "",
"dynatype": {},
"id": "fdafd53a-d4a0-11ee-afc8-cbda05af010e",
"is_hidden": false,
"modified": "2024-02-26T12:17:21",
"modified_by": "Administrator Administrator",
"path": "/domain/spaces/Space folder title/Space title",
"resource_uri": "/api/v2/spaces/fdafd53a-d4a0-11ee-afc8-cbda05af010e/",
"snapshot_id": "fdafddc8-d4a0-11ee-afc8-5ba20d934ce2",
"status": "",
"tags": [],
"template": null,
"title": "Space title",
"type": "Space",
"version": "0.1"
}
]
}One can notice the meta.next field contains link for the next page of spaces /api/v2/spaces/?limit=1&offset=2, when the meta.previous field contains link for the previous page of spaces /api/v2/spaces/?limit=1&offset=0.