All requests to the Sync API endpoints must be authenticated. You can easily reuse access tokens you might have used during the calls to the REST API. Just make sure they’re tagged with the sync permission scope.

In addition to the Authorization header, you must provide the UUID for the device for which you want to perform synchronization, within the X-Basecrm-Device-UUID. The UUID must not change between synchronization sessions. There is a limit of 100 active synchronization sessions.

Authorization: Bearer $ACCESS_TOKENX-Basecrm-Device-UUID: $CLIENT_DEVICE_UUID

Start Synchronization Flow

POST /v2/sync/start

This is the first endpoint to call, in order to start a new synchronization session.

If you get a 204 response, there is nothing new to download and you can safely stop the flow. If there is data to synchronize, you will get a 201 response.

The response is the synchronization session object with an embedded array of queues.

The sync_session object will include the following fields:

Parameter Description
id Unique identifier of the synchronization session.
queues An array of queues to synchronize. At this moment the array will include only a single item - the main queue.

The sync_queue fields:

Parameter Description
name Name of the queue.
pages Number of pages to request.
total_count Total number of items in the queue to synchronize.

Allowed for

  • Agents
  • Admins

Using curl

curl -v -X POST https://api.getbase.com/v2/sync/start \-H "Accept: application/json" \-H "X-Basecrm-Device-UUID: $CLIENT_DEVICE_UUID" \-H "Authorization: Bearer $ACCESS_TOKEN"

Example Response

HTTP/1.1 201 Created
Content-Type: application/json
{  "data": {    "id": "$SESSION_ID",    "queues": [      {        "data": {          "name": "main",          "pages": 1,          "total_count": 2        },        "meta": {          "type": "sync_queue",          "links": {            "self": "https://api.getbase.com/v2/sync/$SESSION_ID/queues/main"          }        }      }    ]  },  "meta": {    "type": "sync_session"  }}

Get data from queue

GET /v2/sync/:session_id/queues/main

Fetch fresh data from the main queue.

The queue holds only the freshest data, there are no historical data stored. Only to make a point, imagine a case when, between synchronization sessions, someone creates a lead and then updates its representation. You will get only the freshest data for the lead.

Deleted resources will include only ids, and you should treat it as an instruction to perform local delete.

Once there is no more data to synchronize you will get a 204 response, otherwise you get 200.

A successfull response will include an array of resources, you are already fimiliar with, and additional Sync related attributes within meta/sync object.

The sync meta object fields:

Parameter Description
event_type An eventy type. Treat it as a hint. Possible values: created, updated, deleted.
ack_key An acknowledgement key.
revision Data revision.

The top level meta attribute includes a few attributes that may hint your syncing process.

Parameter Description
type "collection"
count Number of objects returned in current request.
count_left Number of objects left to sync.
failed_objects Items that failed te be fetched in current request.

failed_objects is a list of items which should have been included but for some reasons weren’t. Every item has these attributes attached:

Parameter Description
id Numeric id value
type Text representing type of the failed object, like lead

Example failed_objects might look like:

[{"type": "deal", "id": 1}, {"type": "lead", "id": 2}]

Allowed for

  • Agents
  • Admins

Using curl

curl -v -X GET https://api.getbase.com/v2/sync/:session_id/queues/main \-H "Accept: application/json" \-H "X-Basecrm-Device-UUID: $CLIENT_DEVICE_UUID" \-H "Authorization: Bearer $ACCESS_TOKEN"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
{  "items": [    {      "data": {        "id": 1,        "creator_id": 1,        "name": "Our website",        "updated_at": "2015-05-07T11:44:01Z",        "created_at": "2014-08-27T16:32:57Z"      },      "meta": {        "type": "source",        "sync": {          "event_type": "updated",          "ack_key": "Source-976368-1375200190",          "revision": 1375200190        }      }    },    {      "data": {        "id": 3      },      "meta": {        "type": "source",        "sync": {          "event_type": "deleted",          "ack_key": "Source-976369-0",          "revision": 0        }      }    }  ],  "meta": {    "type": "collection",    "count": 2,    "count_left": 0,    "failed_objects": [
    ]  }}

Acknowledge received data

POST /v2/sync/ack

Send acknowledgement keys, to let the Sync service know which data you have.

Sent acknowledgement keys are processed in a background, so if some acks are left out for processing and you start another synchronization flow you might get data from a previous session.

Attribute Type Mandatory Description
ack_keys array true A list of acknowledgement keys.

Allowed for

  • Agents
  • Admins

Using curl

curl -v -X POST https://api.getbase.com/v2/sync/ack \-H "Content-Type: application/json" \-H "X-Basecrm-Device-UUID: $CLIENT_DEVICE_UUID" \-H "Authorization: Bearer $ACCESS_TOKEN" \-d '{  "data": {    "ack_keys": [      "Source-976368-1375200190",      "Source-976369-0"    ]  }}'

Example Response

HTTP/1.1 202 Accepted