Sync

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.

Authorization: Bearer $ACCESS_TOKEN
X-Basecrm-Device-UUID: $CLIENT_DEVICE_UUID

Start synchronization flow

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.

Action

POST /v2/sync/start

Examples

Start a new synchronization session

POST /v2/sync/start HTTP/1.1

Accept: application/json
X-Basecrm-Device-UUID: $CLIENT_DEVICE_UUID
Authorization: Bearer $ACCESS_TOKEN

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"

require 'restclient'
headers = {
    "Accept" => "application/json",
    "X-Basecrm-Device-UUID" => "$CLIENT_DEVICE_UUID",
    "Authorization" => "Bearer $ACCESS_TOKEN"
}
response = RestClient.execute method: :post, url: "https://api.getbase.com/v2/sync/start", headers: headers

puts response

import requests
import json

response = requests.post(
    url='https://api.getbase.com/v2/sync/start',
    headers={
      'Accept': 'application/json',
      'X-Basecrm-Device-UUID': '$CLIENT_DEVICE_UUID',
      'Authorization': 'Bearer $ACCESS_TOKEN'
    },
    verify=True
  )

print(response.text)

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_sesion"
  }
}

Get data from queue

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}]

Action

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

Examples

Fetch next batch of data

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

Accept: application/json
X-Basecrm-Device-UUID: $CLIENT_DEVICE_UUID
Authorization: Bearer $ACCESS_TOKEN

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"

require 'restclient'
headers = {
    "Accept" => "application/json",
    "X-Basecrm-Device-UUID" => "$CLIENT_DEVICE_UUID",
    "Authorization" => "Bearer $ACCESS_TOKEN"
}
response = RestClient.execute method: :get, url: "https://api.getbase.com/v2/sync/:session_id/queues/main", headers: headers

puts response

import requests
import json

response = requests.get(
    url='https://api.getbase.com/v2/sync/:session_id/queues/main',
    headers={
      'Accept': 'application/json',
      'X-Basecrm-Device-UUID': '$CLIENT_DEVICE_UUID',
      'Authorization': 'Bearer $ACCESS_TOKEN'
    },
    verify=True
  )

print(response.text)

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

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.

Parameters

Attribute	Description
ack_keys array required	A list of acknowledgement keys.

Action

POST /v2/sync/ack

Examples

Acknowledge previously fetched data

POST /v2/sync/ack HTTP/1.1

Content-Type: application/json
X-Basecrm-Device-UUID: $CLIENT_DEVICE_UUID
Authorization: Bearer $ACCESS_TOKEN

{
  "data": {
    "ack_keys": [
      "Source-976368-1375200190",
      "Source-976369-0"
    ]
  }
}

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"
    ]
  }
}'

require 'restclient'
headers = {
    "Content-Type" => "application/json",
    "X-Basecrm-Device-UUID" => "$CLIENT_DEVICE_UUID",
    "Authorization" => "Bearer $ACCESS_TOKEN"
}
body = '{
  "data": {
    "ack_keys": [
      "Source-976368-1375200190",
      "Source-976369-0"
    ]
  }
}

'
response = RestClient.execute method: :post, url: "https://api.getbase.com/v2/sync/ack", payload: body, headers: headers

puts response

import requests
import json

payload = {
  'data': {
    'ack_keys': [
      'Source-976368-1375200190',
      'Source-976369-0'
    ]
  }
}

response = requests.post(
    url='https://api.getbase.com/v2/sync/ack',
    headers={
      'Content-Type': 'application/json',
      'X-Basecrm-Device-UUID': '$CLIENT_DEVICE_UUID',
      'Authorization': 'Bearer $ACCESS_TOKEN'
    },
    data=json.dumps(payload),
    verify=True
  )

print(response.text)

HTTP/1.1 202 Accepted

Sync

Endpoints

Start synchronization flow

Get data from queue

Acknowledge received data

Parameters