---
title: "Create contact"
method: POST
path: "/v3/grants/{grant_id}/contacts"
tags: ["Contacts"]
---

# Create contact

`POST /v3/grants/{grant_id}/contacts`

Create a contact in a user's address book. New contacts use `source=address_book`. See
[Contact sources](/docs/v3/email/contacts/#contact-sources) for provider-specific behavior.

You can attach Nylas-managed metadata to the Contact object. Nylas stores metadata separately
from the provider contact, so the provider write and metadata write are not atomic.

## Query parameters

- `select` string

## Request body

- 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` ContactEmail[]
    - `email` string, required — The contact's email address.
    - `type` 'work' | 'home' | 'other' — (Google, IMAP, iCloud, and Yahoo only) The email address type.
  - `given_name` string, required — The contact's given name.
  - `groups` ContactGroupId[] — The IDs of existing explicit provider-backed groups that the contact should belong to. Address-book containers and aggregate views such as iCloud All Contacts are not groups.
    - `id` string, required — A globally unique object identifier for Microsoft accounts. An email address for Google accounts.
  - `im_addresses` ContactImAddress[]
    - `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. Native iCloud and Yahoo CardDAV contacts don't support this field. See [Contacts limitations](/docs/v3/email/contacts/#contacts-limitations) for more information.
  - `metadata` Metadata — The metadata associated with the object. For more information, see [Metadata](/docs/reference/api/#metadata).
  - `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. Native iCloud and Yahoo CardDAV contacts don't support this field. See [Contacts limitations](/docs/v3/email/contacts/#contacts-limitations) for more information.
  - `phone_numbers` ContactPhoneNumber[]
    - `number` string, required — The contact's phone number, including its [country code](https://www.itu.int/oth/T0202.aspx?parent=T0202).
    - `type` 'work' | 'home' | 'mobile' | 'other' — The phone number type. `mobile` is supported for Google, Microsoft Graph, iCloud, and Yahoo. `other` is supported for Google, EWS, iCloud, and Yahoo.
  - `physical_addresses` ContactPhysicalAddress[]
    - `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` 'work' | 'home' | 'other', required — The physical address type.
  - `suffix` string — (Not supported for EWS) The suffix of a contact's name, if applicable.
  - `source` 'address_book' — Contacts created through the API are saved to the provider address book.
  - `surname` string — The contact's surname.
  - `web_pages` ContactWebPage[] — An array of the contact's websites. Different providers may have different limits on the number of web pages. - Google/iCloud/Yahoo: multiple web pages per contact. - IMAP: 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` 'work' | 'home' | 'other' — The website type.

## Response `200`

Contact

- object
  - `request_id` string — The request ID.
  - `data` object — The response 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` ContactEmail[], nullable — The contact's email addresses. May be `null` if the contact has no email addresses. Treat `null` the same as an empty array.
      - `email` string, required — The contact's email address.
      - `type` 'work' | 'home' | 'other' — (Google, IMAP, iCloud, and Yahoo only) The email address type.
    - `given_name` string — The contact's given name.
    - `grant_id` string — The ID of grant for the connected user.
    - `groups` ContactGroupId[], nullable — The contact's explicit provider-backed group memberships. Address-book containers and aggregate views such as iCloud All Contacts are not groups. May be `null` if the contact has no group memberships. Treat `null` the same as an empty array.
      - `id` string, required — A globally unique object identifier for Microsoft accounts. An email address for Google accounts.
    - `id` string — A globally unique object identifier for Microsoft accounts. An email address for Google accounts.
    - `im_addresses` ContactImAddress[], nullable — The contact's IM addresses. May be `null` if the contact has no IM addresses. Treat `null` the same as an empty 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. Native iCloud and Yahoo CardDAV contacts don't support this field. See [Contacts limitations](/docs/v3/email/contacts/#contacts-limitations) for more information.
    - `metadata` Metadata — The metadata associated with the object. For more information, see [Metadata](/docs/reference/api/#metadata).
    - `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. Native iCloud and Yahoo CardDAV contacts don't support this field. See [Contacts limitations](/docs/v3/email/contacts/#contacts-limitations) for more information.
    - `phone_numbers` ContactPhoneNumber[], nullable — The contact's phone numbers. May be `null` if the contact has no phone numbers. Treat `null` the same as an empty array.
      - `number` string, required — The contact's phone number, including its [country code](https://www.itu.int/oth/T0202.aspx?parent=T0202).
      - `type` 'work' | 'home' | 'mobile' | 'other' — The phone number type. `mobile` is supported for Google, Microsoft Graph, iCloud, and Yahoo. `other` is supported for Google, EWS, iCloud, and Yahoo.
    - `physical_addresses` ContactPhysicalAddress[], nullable — The contact's physical addresses. May be `null` if the contact has no physical addresses. Treat `null` the same as an empty 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` 'work' | 'home' | 'other', required — The physical address type.
    - `picture_url` string — A URL that links to the contact's picture. Native iCloud and Yahoo CardDAV contacts don't support profile pictures. See [Contacts limitations](/docs/v3/email/contacts/#contacts-limitations) for more information.
    - `source` 'address_book' | 'domain' | 'inbox' — The source of the contact. See [Contact sources](/docs/v3/email/contacts/#contact-sources) for provider-specific availability and behavior.
    - `suffix` string — (Not supported for EWS) The suffix of a contact's name, if applicable.
    - `surname` string — The contact's surname.
    - `web_pages` ContactWebPage[], nullable — The contact's web pages. May be `null` if the contact has no web pages. Treat `null` the same as an empty array.
      - `url` string, required — A URL that links to the contact's website.
      - `type` 'work' | 'home' | 'other' — The website type.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Unauthorized
- `409` — Conflict
- `429` — Rate Limit
- `504` — Provider Failure

---

[API](https://skmtc.dev/nylas/apis/nylas-api.md) · [All operations](https://skmtc.dev/nylas/apis/nylas-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nylas/nylas-api/revisions/51c2c1b4ecff/schema)