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


---

# 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/unified-apis/contacts-api.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.