Contacts API

Aurinko's Contacts API offers a RESTful interface for syncing contacts from Google, Office 365, etc., with features like CRUD operations, incremental sync, and detailed access.

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, then follow the guide to Get Your Developer API Keys.

Contacts API Endpoints

---

Contacts

Contacts are objects within an address. Aurinko supports key contacts functionality, making it easy to add address book integrations.

Synchronization

Contacts sync 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 /contacts/sync.

curl -X POST -H 'Authorization: Bearer <account\_access\_token>' \
    -G https:/api.aurinko.io/v1/contacts/sync[?awaitReady=false]

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:

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

If the response shows ready: false call the "sync start" method again. Once the sync is ready you will get delta tokens syncUpdatedToken, syncDeletedToken and can start loading updated and deleted contacts.

Initial full sync

Initial requests /contacts/sync/updated and /contacts/sync/deleted are equivalent to a full sync, plus loading all updated contacts (deleted contacts) since the sync start.

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

Response:

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

Continue loading pages using provided nextPageToken until you find another nextDeltaToken.

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 nextPageToken instead of the nextDeltaToken in the response. Continue loading pages using the provided nextPageToken until you find another nextDeltaToken.

Other examples

---

To create a new contact POST json payload to /contacts endpoint:

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": "[e-mail]", "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 existing contacts. List only those high level fields that are being updated, and specify If-Match header with the ETag value that was received when you loaded the contact.

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"
    }
}'