Getting Started with BrightSync API

BrightSync API lets developers manage Aurinko's sync logic between mailboxes and business platforms for seamless two-way calendar, contacts, and tasks sync.

BrightSync API allows developers to configure, activate, and manage Aurinko’s pre-built sync logic, which is a worker process migrating data between mailbox or email marketing providers and one business platform (also called “portal”):

Two-way calendar sync between user mailboxes and a business platform
One-way email logging to a business platform with contact/opportunity matching
Two-way contacts sync between user mailboxes and a business platform
Two-way tasks sync between user mailboxes and the business platform

Prerequisites:

A custom Aurinko connector for your business platform needs to be created by Yoxel. See CRM Connector Requirements.
You need to obtain appId & appSecret from Yoxel.

Please contact us at [email protected] to discuss your integration.

Signing up

BrightSync runs a sync job for every registered user so first step for your integration is to create a sync account for your user: POST user signup details to the /signup endpoint:

{  
    "appId": "{appId}",  
    "compExtId": "c1647588",  
    "companyName": "ABC Co.",  
    "instanceUrl": "https://api.myplatform.com",  
    "userExtId": "u886450",  
    "firstName": "John",  
    "lastName": "Smith",  
    "email": "[email protected]",   
    "admin": true,  
    "timeZoneInfo": "America/Los_Angeles",  
    "apiHash":"B5HIlStgADzu5VkN5/dSaagNgQ4CJa5ynwCvs2E6M59BanOQkvmA9YP4p1TlIhUR",  
    "requestTimestamp": 12234875958   
}

Where:

appId - ID we assign to your integration, together with a secret key
compExtId - Org/Tenant/Company ID that the user is associated with in your platform. BrightSync groups all users by their organizations.
companyName - the name of the Org/Tenant/Company
instanceUrl - API URL associated with the Org/Tenant/Company.
userExtId - your platform’s user ID
apiHash - HMAC signature using your app secret
requestTimestamp - time of the request, is used in the signature calculation

Here is the sample Java code to generate the apiHash:

final Mac mac = Mac.getInstance("HmacSHA256");

mac.init(new SecretKeySpec("{appSecret}".getBytes(), "HmacSHA256")); 

signupRequest.setRequestTimestamp(System.currentTimeMillis());

signupRequest.setApiHash(new String(Base64.encodeBase64(mac.doFinal("OrgId:UserId:".concat(sr.getRequestTimestamp().toString()).getBytes()))));

This call returns an access token for the user which should be used in all other API calls:

{"accessToken":"djIjMjYxMCN2O...jIxNDU5"}

Access token

The access token returned by the signup call should be used to call all other API methods.

You need to use the BASIC HTTP authentication with username={access_token}, password=X.

GET https://api.yoxel.com/v2/me

Response:

{
    "uid": 1,
    "name": "John Smith",
    "firstName": "John",
    "lastName": "Smith",
    "email": "[email protected]",
    "addedBy": 0,
    "extId": "u886450",
    "timeZoneInfo": "America/Los_Angeles",
    "disabled": false,
    "admin": false,
    "templCount": 0
}

If you get the 401 - Unauthorized HTTP status in response that means that the user access token is invalid and you need to repeat the /signup.

Services

BrightSync needs to be able to connect to remote accounts which are called services.

First, check if services already exist for the current user as there are scenarios when some services are auto-populated during signup, i.e. if you’d configured Org wide sync templates (see about sync templates below).

GET https://api.yoxel.com/v2/services

Refer to the /services API refs for more details. Here is an example of the key data returned:

[
  {
    "id": 1,
    "type": "GOOGLE|OFFICE365|EXCHANGE|SFORCE|MYPLATFORM",
    "offline": true,
    "displayName": "My Google",
    "fullName": "John Smith",
    "email": "[email protected]",
    "server": "https://api.google.com",
    "syncData": {...},
    "scanEmail": true,
    "scanEmails": {...configuration options...},
    "fwdEmail": true,
    "fwdEmails": {...configuration options...},

    "importEvents": true,
    "calendar": {...configuration options...},    
    "importContacts": true,
    "contacts": {...configuration options...},
    "importTasks": true,
    "tasks": {...configuration options...},
    "authRedirectUrl": 
    "url if unauthorized",

    "templId": 0,    
    "templLocked": true,
    "authError": "string"
  },
  ...
  
]

Non-null authRedirectUrl means the user has not authorized BrightSync to access this account yet or the access token has been lost. Direct your user to authRedirectUrl in a browser popup window to get a new authorization.

Creating a new service

POST https://api.yoxel.com/v2/services

Updating an existing service

GET https://api.yoxel.com/v2/services/{id}

Sync settings

The /services/syncSettings endpoints allow you to configure a user sync between two services: one business platform (also called portal) and one mailbox (i.e. Google, Office 365,…) or an email marketing account (i.e. Hubspot, Constant Contact,…)

GET https://api.yoxel.com/v2/services/syncSettings

PUT https://api.yoxel.com/v2/services/syncSettings

Here is an example of the key options you control:

{
    "logEmail": true,
    "emailSkipDomains": "string",
    "emailFetchAttachments": true,
    "emailCreateLeads": true,
    "emailCreateContacts": true,
    "emailAutoDetectDeal": true,
    "emailCreateCompany": true,
    ...

    "syncCalendar": true,
    "calSyncDirection": "BOTH|TO_PORTAL|FROM_PORTAL",
    "calSyncPrivate": true,
    "calFetchAttachments": true,
    "calMailboxSyncAll": true,
    "calMailboxSyncTags": "string",
    "calMailboxSyncMeetingsOnly": true,
    "calPastWeeks": 0,
    "calFutureWeeks": 0,
    ...

    "syncContacts": true,
    "contSyncDirection": "BOTH|TO_PORTAL|FROM_PORTAL",
    "contCreateCompany": true,
    "contPortalSyncAll": true,
    "contMailboxSyncAll": true,
    "contPortalSyncMine": true,
    "contPortalSyncTags": "string",
    "contMailboxSyncTags": "string",
    "contMailboxSyncDeleted": true,
    ...
    
    "syncTasks": true,
    "taskSyncDirection": "BOTH|TO_PORTAL|FROM_PORTAL",
    "taskMailboxSyncAll": true,
    "taskMailboxSyncTags": "string"
}

Sync activation

Initially, BrightSync for a new user is in the “review” mode, except when locked templates are in place that auto-provision all user services (see below about the templates).

Call GET /sync to see the sync status:

{
    "userSyncEnabled": true,
    "pkgCheckFailed": true,
    "userLastSynced": "2019-08-24T14:15:22Z",
    "syncState": "IDLE",
    "lastRequest": "2019-08-24T14:15:22Z",
    "needReview": ["CALENDAR", "EMAIL", "CONTACTS", "TASKS"]
}

Non-empty needReview indicates if any of the sync modules are in the review mode.

In this mode, you can run the sync but it will only load data from remote accounts without updating/creating anything:

POST /sync

Payload:

{'initial':'true'}

To check progress:

GET /sync

Check pre-sync reports while in the review mode:

GET /rules/<type>/report

Activate the sync completely by calling /allowSync:

PUT /rules/<type>/allowSync or PUT /allowSync

Payload:

{'CALENDAR', 'TASKS'}

Then run the sync:

POST /sync

Payload:

{'initial':'false'}

To check progress:

GET /sync

Monitoring sync progress

The sync progress can be monitored by polling its current status:

GET /sync

{
    "userSyncEnabled": true,
    "pkgCheckFailed": true,
    "userLastSynced": "2019-08-24T14:15:22Z",
    "syncState": "IDLE",
    "lastRequest": "2019-08-24T14:15:22Z",

    "needReview": null,

    "errors": [],
    "errMessage": "string",
    "errTimestamp": "2019-08-24T14:15:22Z",
    "errSvcId": 0
}

Check syncState:

IDLE - the sync is not currently running
REQUESTED - a request for syncing was received but the sync is not running yet
QUEUED - the sync is in a queue to be run
EXECUTING - the sync is running

Non-empty needsReview indicated that a sync module is not completely activated and the user needs to review the data that the synced prepared for syncing.

Sync templates

Sync templates are team-level configurations that can be assigned to sync users and result in auto-populating services and settings. Using the templates also disables the “review” steps and allows user sync to activate completely right away.

The /templateGroups endpoints all you to manage multiple sync templates and their assignments to users.

GET https://api.yoxel.com/v2/templateGroups

POST https://api.yoxel.com/v2/templateGroups PUT https://api.yoxel.com/v2/templateGroups/{gid}

Template services

GET https://api.yoxel.com/v2/templateGroups/{gid}/services

Refer to the /groupTemplates API refs for more details. Here is an example of the key data returned:

[
  {
    "id": 1,

    "groupId": {gid},    
    "type": "GOOGLE|OFFICE365|EXCHANGE|SFORCE|MYPLATFORM",
    "offline": true,
    "displayName": "My Google",
    "fullName": "John Smith",
    "email": "[email protected]",
    "server": "https://api.google.com",
    "syncData": {...},
    "scanEmail": true,
    "scanEmails": {...configuration options...},
    "fwdEmail": true,
    "fwdEmails": {...configuration options...},
    "importEvents": true,
    "calendar": {...configuration options...},
    "importContacts": true,
    "contacts": {...configuration options...},
    "importTasks": true,
    "tasks": {...configuration options...},
    "authRedirectUrl": "url if unauthorized",
    "lockService": true,
    "authError": "string"
  },
  ...
  
]

BrightSync supports admin/app-level connectivity for Google, Office 365, MS Exchange, and Salesforce accounts which can be configured at the template level.

Non-null authRedirectUrl means the Org admin has not authorized BrightSync to access this Org yet or the access token has been lost. Direct the admin user to authRedirectUrl in a browser popup window to get a new authorization.

Creating a new template service

POST https://api.yoxel.com/v2/templateGroups/{gid}/services

Updating an existing template service

GET https://api.yoxel.com/v2/templateGroups/{gid}services/{id}

Template sync settings

The /templateGroups/{gid}/syncSettings endpoints allow you to prepare a sync configuration between two services: one business platform (also called portal) and one mailbox (i.e. Google, Office 365,…) or an email marketing account (i.e. Hubspot, Constant Contact,…)

GET https://api.yoxel.com/v2/templateGroups/{gid}/syncSettings PUT https://api.yoxel.com/v2/templateGroups/{gid}/syncSettings

Here is an example of the key options you control (very similar to the user-level sync settings):

{
    "templGroupId": {gid},    
    "logEmail": true,
    "emailSkipDomains": "string",
    "emailFetchAttachments": true,
    "emailCreateLeads": true,
    "emailCreateContacts": true,
    "emailAutoDetectDeal": true,
    "emailCreateCompany": true,
    ...
    
    "syncCalendar": true,
    "calSyncDirection": "BOTH|TO_PORTAL|FROM_PORTAL",
    "calSyncPrivate": true,
    "calFetchAttachments": true,
    "calMailboxSyncAll": true,
    "calMailboxSyncTags": "string",
    "calMailboxSyncMeetingsOnly": true,
    "calPastWeeks": 0,
    "calFutureWeeks": 0,
    ...
    
    "syncContacts": true,
    "contSyncDirection": "BOTH|TO_PORTAL|FROM_PORTAL",
    "contCreateCompany": true,
    "contPortalSyncAll": true,
    "contMailboxSyncAll": true,
    "contPortalSyncMine": true,
    "contPortalSyncTags": "string",
    "contMailboxSyncTags": "string",
    "contMailboxSyncDeleted": true,
    ...
    
    "syncTasks": true,
    "taskSyncDirection": "BOTH|TO_PORTAL|FROM_PORTAL",
    "taskMailboxSyncAll": true,
    "taskMailboxSyncTags": "string"
}

User management

With an admin user’s access token, it is possible to manage other users’ syncs.

Additional documentation detailing the /users endpoints i being developed.

PreviousCalendar Sync API Requirements

Last updated 4 months ago

Was this helpful?

hashtagPrerequisites:

hashtagSigning up

hashtagAccess token

hashtagServices

hashtagCreating a new service

hashtagUpdating an existing service

hashtagSync settings

hashtagSync activation

hashtagCall GET /syncarrow-up-right to see the sync status:

hashtagTo check progress:

hashtagCheck pre-sync reports while in the review mode:

hashtagActivate the sync completely by calling /allowSyncarrow-up-right:

hashtagThen run the sync:

hashtagTo check progress:

hashtagMonitoring sync progress

hashtagSync templates

hashtagTemplate services

hashtagCreating a new template service

hashtagUpdating an existing template service

hashtagTemplate sync settings

hashtagUser management

Prerequisites:

Signing up

Access token

Services

Creating a new service

Updating an existing service

Sync settings

Sync activation

Call GET /sync to see the sync status:

To check progress:

Check pre-sync reports while in the review mode:

Activate the sync completely by calling /allowSync:

Then run the sync:

To check progress:

Monitoring sync progress

Sync templates

Template services

Creating a new template service

Updating an existing template service

Template sync settings

User management