# Contacts API

## Aurinko Contacts API

***

The Aurinko Contacts API abstracts away differences between popular contacts APIs (Google, Office 365, Outlook.com, MS Exchange) to make it easy to develop calendar integrations.

### Functionality

***

The Aurinko Contacts API provides a REST interface that focuses on accessing and address books in a uniform manner.

* Access data for contacts, such as event titles, location, description, dates, ...
* Full CRUD (create, read, update, delete) capabilities.
* Incremental synchronization
* Read data for a user’s contacts including name, email, phone number, notes, and more.
* Create new contacts and modify existing contacts.

### Aurinko account setup

***

First, create your account in the [Aurinko portal](https://app.aurinko.io/), then follow the guide to [get Your Developer API Keys](https://docs.aurinko.io/getting-started/get-your-developer-api-keys).

### Contacts API Endpoints

***

#### **Contacts**

[Contacts](https://apirefs.aurinko.io/#tag/Contacts) are objects within an address. Aurinko supports key contacts functionality, making it easy to add address book integrations.

#### **Synchronization**

[Contacts sync](https://apirefs.aurinko.io/#tag/ContSync) methods allow developers to implement incremental synchronization of contacts data in a uniform manner across different address providers. Aurinko supports requesting updated as well as deleted calendar events, reporting series master and exceptions, auto expanding a sync range.

### Contacts sync quickstart

***

#### **Start a new sync**

A new sync needs to be provisioned by calling the "sync start" method <mark style="color:red;">`/contacts/sync`</mark>.

<pre class="language-bash"><code class="lang-bash">curl -X POST -H 'Authorization: Bearer &#x3C;account\_access\_token>'
<strong>    -G https:/api.aurinko.io/v1/contacts/sync[?awaitReady=false]
</strong></code></pre>

The Aurinko platform will initialize all necessary internal resources and let you know when it's ready to serve data. The response should look like this:

```json
{
    "syncUpdatedToken": "asdfghjklpoiuytrew",
    "syncDeletedToken": "zxcvbnmlkjhgfdsaq",
    "ready": true
}
```

If the response shows <mark style="color:red;">`ready: false`</mark> call the "sync start" method again. Once the sync is ready you will get delta tokens <mark style="color:red;">`syncUpdatedToken`</mark>, <mark style="color:red;">`syncDeletedToken`</mark> and can start loading updated and deleted contacts.

#### **Initial full sync**

Initial requests <mark style="color:red;">`/contacts/sync/update`</mark>`d` and <mark style="color:red;">`/contacts/sync/deleted`</mark> are equivalent to a full sync, plus loading all updated contacts (deleted contacts) since the sync start.

```bash
curl -X GET -H 'Authorization: Bearer <access token>'
    -G https:/api.aurinko.io/v1/contacts/sync/updated
    -d deltaToken='{syncUpdatedToken}'
```

*Response:*

```json
{
    "nextPageToken": "string",
    "nextDeltaToken": "string",
    "records":  [{...}]
}
```

Continue loading pages using provided <mark style="color:red;">`nextPageToken`</mark> until you find another <mark style="color:red;">`nextDeltaToken`</mark>.

```bash
curl -X GET -H 'Authorization: Bearer <access token>'
    -G https:/api.aurinko.io/v1/contacts/sync/updated
    -d pageToken='{nextPageToken}'
```

#### **Incremental sync**

A new deltaToken (nextDeltaToken in a response) is provided for loading contacts that have been modified/deleted since the last sync-updated/sync-deleted request. In cases where a large number of contacts have changed since the last incremental sync request, you may find a <mark style="color:red;">`nextPageToken`</mark> instead of the <mark style="color:red;">`nextDeltaToken`</mark> in the response. Continue loading pages using the provided <mark style="color:red;">`nextPageToken`</mark> until you find another <mark style="color:red;">`nextDeltaToken`</mark>.

### Other examples

***

To create a new contact POST json payload to <mark style="color:red;">`/contacts`</mark> endpoint:

```bash
curl -H 'Authorization: Bearer <access token>'
    -X POST https:/api.aurinko.io/v1/contacts
    -d '{
    "name": {
        "givenName": "John",
        "familyName": "Smith"
    },
    "company": {
        "companyName": "ABC Corp",
        "officeLocation": "Florida",
        "department": "R&D",
        "jobTitle": "Manager"
    },
    "notes": "some background",
    "birthday": "2000-09-01",
    "keywords": ["Blue"],
    "emailAddresses": [
        {"address": "john@abccorp.co", "type": "work"}
    ],
    "phoneNumbers": [
        {"number": "1234567", "type": "work"},
        {"number": "7654321", "type": "mobile"}
    ],
    "addresses": [
        {
            "street": "300 Lemon Ave #100",
            "city": "Walnut",
            "state": "CA",
            "postalCode": '91789',
            "country": "USA",
            "type": "work"
        }
    ],
    "urls": [
       {
           "value": "[www.abccorp.co](http://www.abccorp.co)", 
           "type": "work"
       }
    ]
}'
```

Use PATCH request to [update](https://apirefs.aurinko.io/#operation/updateContact) existing contacts. List only those high level fields that are being updated, and specify <mark style="color:red;">`If-Match`</mark> header with the <mark style="color:red;">`Etag`</mark> value that was received when you loaded the contact.

```bash
curl -X PATCH -H 'Authorization: Bearer <access token>' -H 'If-Match: <etag>'
    https:/api.aurinko.io/v1/contacts/{contId}
    -d '{
    "name": {
        "givenName": "John",
        "middleName": "Peter",
        "familyName": "Smith"
    }
}'
```