# Create contact

> **POST** `https://api.us.nylas.com/v3/grants/{grant_id}/contacts`

Source: https://developer.nylas.com/docs/reference/api/contacts/post-contact/

Create a contact in a user's address book.

**Authentication:** NYLAS_API_KEY, ACCESS_TOKEN

## Parameters

### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `select` | string | No | Specify fields that you want Nylas to return, as a comma-separated list (for example, `select=id,updated_at`). This allows you to receive only the portion of object data that you're interested in. You can use `select` to optimize response size and reduce latency by limiting queries to only the information that you need. |

### Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `grant_id` | string | Yes | ID of the grant to access. Use `/me/` to refer to the grant associated with an access token. |

## Request body

Content-Type: application/json

- `birthday` (string) - The contact's birthday in [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates).
- `company_name` (string) - The name of the company that the contact is affiliated with (for example, their workplace).
- `emails` (array)
  - `email` (string) **(required)** - The contact's email address.
  - `type` (string) - (Google, IMAP, and iCloud only) The email address type.
- `given_name` (string) **(required)** - The contact's given name.
- `groups` (array) - A list of IDs for contact groups the contact is included in.
Microsoft, iCloud and IMAP support at most one contact group per contact.
  - `id` (string) **(required)** - A globally unique object identifier for Microsoft accounts. An email address for Google accounts.
- `im_addresses` (array)
  - `im_address` (string) **(required)** - The contact's IM address.
  - `type` (string) - The protocol for the IM address.
- `job_title` (string) - The contact's occupation or job title.
- `manager_name` (string) - The name of the contact's manager.
- `middle_name` (string) - The contact's middle name.
- `nickname` (string) - A custom nickname for the contact.
- `notes` (string) - Notes about with the contact (for example, their favorite food).
- `office_location` (string) - The location of the office where the contact works.
- `phone_numbers` (array)
  - `number` (string) **(required)** - The contact's phone number, including its
[country code](https://www.itu.int/oth/T0202.aspx?parent=T0202).
  - `type` (string) - The phone number type. `mobile` is supported for Google and Microsoft Graph only. `other` is
supported for Google and EWS only.
- `physical_addresses` (array)
  - `city` (string) - The town or city in which the contact is located.
  - `country` (string) - The country in which the contact is located.
  - `postal_code` (string) - The postal code of a location associated with the contact.
  - `state` (string) - The state or province in which the contact is located.
  - `street_address` (string) - The street address of a location associated with the contact (for example, their work).
  - `type` (string) **(required)** - The physical address type.
- `suffix` (string) - (Not supported for EWS) The suffix of a contact's name, if applicable.
- `surname` (string) - The contact's surname.
- `web_pages` (array) - An array of the contact's websites. Different providers may have different limits on the number of web pages.
- IMAP/iCloud/Yahoo: at most one web page per contact.
- Microsoft/EWS: at most one web page per contact. The type must be `work`.
  - `url` (string) **(required)** - A URL that links to the contact's website.
  - `type` (string) - The website type.

## Responses

### 200 - Contact

- `request_id` (string) - The request ID.
- `data` (object)
  - `birthday` (string) - The contact's birthday in [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates).
  - `company_name` (string) - The name of the company that the contact is affiliated with (for example, their workplace).
  - `emails` (array,null) - The contact's email addresses. May be `null` if the contact has no email addresses. Treat `null` the same as an empty array.
  - `given_name` (string) - The contact's given name.
  - `grant_id` (string) - The ID of grant for the connected user.
  - `groups` (array,null) - The contact's group memberships. May be `null` if the contact has no group memberships. Treat `null` the same as an empty array.
  - `id` (string) - A globally unique object identifier for Microsoft accounts. An email address for Google accounts.
  - `im_addresses` (array,null) - The contact's IM addresses. May be `null` if the contact has no IM addresses. Treat `null` the same as an empty array.
  - `job_title` (string) - The contact's occupation or job title.
  - `manager_name` (string) - The name of the contact's manager.
  - `middle_name` (string) - The contact's middle name.
  - `nickname` (string) - A custom nickname for the contact.
  - `notes` (string) - Notes about with the contact (for example, their favorite food).
  - `object` (string) - The response object type.
  - `office_location` (string) - The location of the office where the contact works.
  - `phone_numbers` (array,null) - The contact's phone numbers. May be `null` if the contact has no phone numbers. Treat `null` the same as an empty array.
  - `physical_addresses` (array,null) - The contact's physical addresses. May be `null` if the contact has no physical addresses. Treat `null` the same as an empty array.
  - `picture_url` (string) - A URL that links to the contact's picture.
  - `source` (string) - The source of the contact. For iCloud and IMAP grants, the source is `inbox` if the contact is 
parsed from a message. If the contact is created or updated using the Nylas API, its source is 
`address_book`.
  - `suffix` (string) - (Not supported for EWS) The suffix of a contact's name, if applicable.
  - `surname` (string) - The contact's surname.
  - `web_pages` (array,null) - The contact's web pages. May be `null` if the contact has no web pages. Treat `null` the same as an empty array.

### 400 - Bad Request

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The error from the provider.

### 401 - Unauthorized

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The error from the provider.

### 429 - Rate Limit

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.

### 504 - Provider Failure

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.

## Code samples

### cURL

```bash
curl --compressed --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "birthday": "1960-12-31",
    "company_name": "Nylas",
    "emails": [
      {
        "email": "leyah.miller@example.com",
        "type": "work"
      },
      {
        "email": "leyah@example.com",
        "type": "home"
      }
    ],
    "given_name": "Leyah",
    "groups": [
      {
        "id": "starred"
      },
      {
        "id": "friends"
      }
    ],
    "im_addresses": [
      {
        "type": "jabber",
        "im_address": "leyah_jabber"
      },
      {
        "type": "msn",
        "im_address": "leyah_msn"
      }
    ],
    "job_title": "Software Engineer",
    "manager_name": "Bill",
    "middle_name": "Allison",
    "nickname": "Allie",
    "notes": "Loves Ramen",
    "office_location": "123 Main Street",
    "phone_numbers": [
      {
        "number": "+1-555-555-5555",
        "type": "work"
      },
      {
        "number": "+1-555-555-5556",
        "type": "home"
      }
    ],
    "physical_addresses": [
      {
        "type": "work",
        "street_address": "123 Main Street",
        "postal_code": "94107",
        "state": "CA",
        "country": "USA",
        "city": "San Francisco"
      },
      {
        "type": "home",
        "street_address": "456 Main Street",
        "postal_code": "94107",
        "state": "CA",
        "country": "USA",
        "city": "San Francisco"
      }
    ],
    "source": "address_book",
    "surname": "Miller",
    "web_pages": [
      {
        "type": "work",
        "url": "<WEBPAGE_URL>"
      },
      {
        "type": "home",
        "url": "<WEBPAGE_URL>"
      }
    ]
  }'
```

### Node.js SDK

```javascript
import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});

async function createContact() {
  try {
    const contact = await nylas.contacts.create({
      identifier: "<NYLAS_GRANT_ID>",
      requestBody: {
        givenName: "My",
        middleName: "Nylas",
        surname: "Friend",
        notes: "Make sure to keep in touch!",
        emails: [{ type: "work", email: "swag@example.com" }],
        phoneNumbers: [{ type: "work", number: "(555) 555-5555" }],
        webPages: [{ type: "other", url: "nylas.com" }],
      },
    });

    console.log("Contact:", JSON.stringify(contact));
  } catch (error) {
    console.error("Error to create contact:", error);
  }
}

createContact();

```

### Python SDK

```python
from nylas import Client

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>"
)

grant_id = "<NYLAS_GRANT_ID>"

contact = nylas.contacts.create(
  grant_id,
  request_body={
    "middle_name": "Nylas",
    "surname": "Friend",
    "notes": "Make sure to keep in touch!",
    "emails": [{"type": "work", "email": "swag@example.com"}],
    "phone_numbers": [{"type": "work", "number": "(555) 555-5555"}],
    "web_pages": [{"type": "other", "url": "nylas.com"}]
  }
)

print(contact)
```

### Ruby SDK

```ruby
require 'nylas'	

nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")

request_body = {
  given_name: "My",
  middle_name: "Nylas",
  surname: "Friend",  
  emails: [{email: "nylas-friend@example.com", type: "work"}],
  notes: "Make sure to keep in touch!",
  phone_numbers: [{number: "555 555-5555", type: "business"}],
  web_pages: [{url: "https://www.nylas.com", type: "homepage"}]
}

contact, _ = nylas.contacts.create(identifier: "<NYLAS_GRANT_ID>", request_body: request_body)

puts contact
```

### Java SDK

```java
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.ArrayList;
import java.util.List;

public class CreateAContact {
    public static void main(String[] args) throws
            NylasSdkTimeoutError, NylasApiError {

        NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

        List<ContactEmail> contactEmails = new ArrayList<>();
        contactEmails.add(new ContactEmail("swag@nylas.com", "work"));

        List<WebPage> contactWebpages = new ArrayList<>();
        contactWebpages.add(new WebPage("https://www.nylas.com", "work"));

        CreateContactRequest requestBody = new CreateContactRequest.Builder().
                emails(contactEmails).
                companyName("Nylas").
                givenName("Nylas' Swag").
                notes("This is good swag").
                webPages(contactWebpages).
                build();

        Response<Contact> contact = nylas.contacts().create("<NYLAS_GRANT_ID>", requestBody);

        System.out.println(contact);
    }
}

```

### Kotlin SDK

```kotlin
import com.nylas.NylasClient
import com.nylas.models.ContactEmail
import com.nylas.models.CreateContactRequest
import com.nylas.models.WebPage

fun main(args: Array<String>) {
  val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
  val emails : List<ContactEmail> = listOf(ContactEmail("swag@nylas.com", "work"))
  val webpage : List<WebPage> = listOf(WebPage("https://www.nylas.com", "work"))

  val contactRequest = CreateContactRequest.Builder().
      emails(emails).
      companyName("Nylas").
      givenName("Nylas' Swag").
      notes("This is good swag").
      webPages(webpage).
      build()

  val contact = nylas.contacts().create("<NYLAS_GRANT_ID>", contactRequest)

  print(contact.data)
}

```