> For the complete documentation index, see [llms.txt](https://docs.aurinko.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aurinko.io/brightsync/getting-started-with-brightsync.md).

# Getting Started with BrightSync API

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](https://docs.aurinko.io/brightsync/crm-connector-requirements).
2. You need to obtain appId & appSecret from Yoxel.

Please contact us at <support@aurinko.io> to discuss your integration.<br>

### Signing up <a href="#h-signing-up-8" id="h-signing-up-8"></a>

***

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](http://my.yoxel.com/testapi/v2/signup) endpoint:

```json
{  
    "appId": "{appId}",  
    "compExtId": "c1647588",  
    "companyName": "ABC Co.",  
    "instanceUrl": "https://api.myplatform.com",  
    "userExtId": "u886450",  
    "firstName": "John",  
    "lastName": "Smith",  
    "email": "jsmith@abc.co",   
    "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
* r**equestTimestamp** - time of the request, is used in the signature calculation

Here is the sample Java code to generate the apiHash:

```java
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:

<mark style="color:red;">`{"accessToken":"djIjMjYxMCN2O...jIxNDU5"}`</mark>

### Access token <a href="#h-access-token-8" id="h-access-token-8"></a>

***

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

You need to use the <mark style="color:red;">`BASIC`</mark> HTTP authentication with <mark style="color:red;">`username={access_token}`</mark>, <mark style="color:red;">`password=X`</mark>.

<mark style="color:red;">`GET https://api.yoxel.com/v2/me`</mark>

*Response:*

```json
{
    "uid": 1,
    "name": "John Smith",
    "firstName": "John",
    "lastName": "Smith",
    "email": "jsmith@abc.co",
    "addedBy": 0,
    "extId": "u886450",
    "timeZoneInfo": "America/Los_Angeles",
    "disabled": false,
    "admin": false,
    "templCount": 0
}
```

{% hint style="warning" %}
If you get the <mark style="color:red;">`401 - Unauthorized`</mark> HTTP status in response that means that the user access token is invalid and you need to repeat the [/signup](http://my.yoxel.com/testapi/v2/signup).
{% endhint %}

### Services <a href="#h-services-8" id="h-services-8"></a>

***

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).

<mark style="color:red;">`GET https://api.yoxel.com/v2/services`</mark>

Refer to the [/services API refs](https://sync-docs.aurinko.io/#tag/Services/operation/getServices) for more details. Here is an example of the key data returned:

```json
[
  {
    "id": 1,
    "type": "GOOGLE|OFFICE365|EXCHANGE|SFORCE|MYPLATFORM",
    "offline": true,
    "displayName": "My Google",
    "fullName": "John Smith",
    "email": "jsmith@abc.com",
    "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"
  },
  ...
  
]
```

{% hint style="warning" %}
Non-null <mark style="color:red;">`authRedirectUrl`</mark> means the user has not authorized BrightSync to access this account yet or the access token has been lost. Direct your user to <mark style="color:red;">`authRedirectUrl`</mark> in a browser popup window to get a new authorization.
{% endhint %}

#### **Creating a new service**

<mark style="color:red;">`POST https://api.yoxel.com/v2/services`</mark>

#### **Updating an existing service**

<mark style="color:red;">`GET https://api.yoxel.com/v2/services/{id}`</mark>

### Sync settings <a href="#h-sync-settings-7" id="h-sync-settings-7"></a>

***

The [/services/syncSettings](https://sync-docs.aurinko.io/#tag/Services/operation/getSyncSettings) 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,…)

<mark style="color:red;">`GET https://api.yoxel.com/v2/services/syncSettings`</mark>

<mark style="color:red;">`PUT https://api.yoxel.com/v2/services/syncSettings`</mark>

Here is an example of the key options you control:

```json
{
    "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 <a href="#h-sync-activation-7" id="h-sync-activation-7"></a>

***

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](https://sync-docs.aurinko.io/#tag/Sync/operation/getSyncInfo) to see the sync status:

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

{% hint style="warning" %}
Non-empty <mark style="color:red;">`needReview`</mark> indicates if any of the sync modules are in the *review* mode.
{% endhint %}

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

<mark style="color:red;">`POST /sync`</mark>

*<mark style="color:blue;">Payload:</mark>*

```json
{'initial':'true'}
```

#### **To check progress:**

<mark style="color:red;">`GET /sync`</mark>

#### Check pre-sync reports while in the review mode:

<mark style="color:red;">`GET /rules/<type>/report`</mark>

#### Activate the sync completely by calling [/allowSync](https://sync-docs.aurinko.io/#tag/Sync/operation/allowRulesSync):

<mark style="color:red;">`PUT /rules/<type>/allowSync`</mark> or <mark style="color:red;">`PUT /allowSync`</mark>

*<mark style="color:blue;">Payload:</mark>*

```
{'CALENDAR', 'TASKS'}
```

#### Then run the sync:

<mark style="color:red;">`POST /sync`</mark>

*<mark style="color:blue;">Payload:</mark>*

```json
{'initial':'false'}
```

#### **To check progress:**

<mark style="color:red;">`GET /sync`</mark>

### Monitoring sync progress <a href="#h-monitoring-sync-progress-6" id="h-monitoring-sync-progress-6"></a>

***

The sync progress can be monitored by polling its [current status](https://sync-docs.aurinko.io/#tag/Sync/operation/getSyncInfo):

<mark style="color:red;">`GET /sync`</mark>

```json
{
    "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 <mark style="color:red;">`syncState`</mark>:

* **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

{% hint style="warning" %}
Non-empty <mark style="color:red;">`needsReview`</mark> indicated that a sync module is not completely activated and the user needs to review the data that the synced prepared for syncing.
{% endhint %}

### Sync templates <a href="#h-sync-templates-5" id="h-sync-templates-5"></a>

***

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](https://sync-docs.aurinko.io/#tag/TemplateGroups/operation/getTemplateGroups) endpoints all you to manage multiple sync templates and their assignments to users.

<mark style="color:red;">`GET https://api.yoxel.com/v2/templateGroups`</mark>

<mark style="color:red;">`POST https://api.yoxel.com/v2/templateGroups`</mark>\ <mark style="color:red;">`PUT https://api.yoxel.com/v2/templateGroups/{gid}`</mark>

#### **Template services**

<mark style="color:red;">`GET https://api.yoxel.com/v2/templateGroups/{gid}/services`</mark>

Refer to the [/groupTemplates API refs](https://sync-docs.aurinko.io/#tag/TemplateGroups/operation/getGroupTemplates) for more details. Here is an example of the key data returned:

```json
[
  {
    "id": 1,

    "groupId": {gid},    
    "type": "GOOGLE|OFFICE365|EXCHANGE|SFORCE|MYPLATFORM",
    "offline": true,
    "displayName": "My Google",
    "fullName": "John Smith",
    "email": "jsmith@abc.com",
    "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.

{% hint style="warning" %}
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 <mark style="color:red;">`authRedirectUrl`</mark> in a browser popup window to get a new authorization.
{% endhint %}

#### **Creating a new template service**

<mark style="color:red;">`POST https://api.yoxel.com/v2/templateGroups/{gid}/services`</mark>

#### **Updating an existing template service**

<mark style="color:red;">`GET https://api.yoxel.com/v2/templateGroups/{gid}services/{id}`</mark>

#### **Template sync settings**

The [/templateGroups/{gid}/syncSettings](https://sync-docs.aurinko.io/#tag/TemplateGroups/operation/getSyncSettings_1) 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,…)

<mark style="color:red;">`GET https://api.yoxel.com/v2/templateGroups/{gid}/syncSettings`</mark>\ <mark style="color:red;">`PUT https://api.yoxel.com/v2/templateGroups/{gid}/syncSettings`</mark>

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

```json
{
    "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 <a href="#h-user-management" id="h-user-management"></a>

***

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

*Additional documentation detailing the* [*/users*](https://sync-docs.aurinko.io/#tag/Users/operation/listUsers) *endpoints i being developed*.