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:

1. A custom Aurinko connector for your business platform needs to be created by Yoxel. See CRM Connector Requirements.

2. You need to obtain appId & appSecret from Yoxel.

Please contact us at [e-mail] 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": "[e-mail]",   
    "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": "[e-mail]",
    "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": "[e-mail]",
    "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": "[e-mail]",
    "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.