Sync Reference

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_TOKEN
X-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