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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aurinko.io/brightsync/getting-started-with-brightsync.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.