Aurinko
Aurinko websiteAurinko blogAPI ReferenceContact Support
Aurinko API
Aurinko API
  • Getting started
    • What is Unified Mailbox API?
    • Getting started with Aurinko
    • Get your developer API keys
    • Adding Aurinko to Google Workspace allowlist
    • Bubble.io plugin
    • Team members and roles in applications
  • Unified APIs
    • Email API
    • Calendar API
    • Contacts API
    • Tasks API
    • Webhooks API
      • Configuring Pub/Sub for Gmail API Webhooks
    • Direct API
  • Authentication
    • OAuth Flow
      • Account OAuth Flow
      • User ОАuth Flow
      • Service Account OAuth Flow
    • Authentication scopes
    • Authorized return URLs
    • Google OAuth setup
    • Office 365 OAuth setup
    • ZOHO OAuth setup
    • Service accounts
      • Setting up G Suite service account
      • Setting up Office 365 daemon app registration
  • Scheduling
    • Create your first appointment booking page
    • Calendar Booking Page
    • Booking API
    • Group Booking API
  • Workspace Addons
    • Outlook addins
      • Create your first Outlook addin
      • Office 365: Installing Outlook addin
    • Microsoft Teams apps
      • Microsoft Teams bot setup
      • Create your first MS Teams app
      • Installing MS Teams app
    • Chrome Extensions with Google authentication
    • Google Workspace Add-Ons
  • Dynamic API
    • What is Dynamic (Virtual) API?
    • Getting Started with Dynamic API
Powered by GitBook
On this page
  • Aurinko Contacts API
  • Functionality
  • Aurinko account setup
  • Contacts API Endpoints
  • Contacts sync quickstart
  • Other examples
  1. Unified APIs

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.

PreviousCalendar APINextTasks API

Last updated 3 months ago

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 , then follow the guide to .

Contacts API Endpoints


Contacts

Synchronization

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

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

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.

Use PATCH request to 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.

Aurinko portal
get Your Developer API Keys
Contacts
Contacts sync
update