/v1/contacts

Time	Status	User Agent
Retrieving recent requests…

Create or update contacts in Apptoto.

To update existing contacts, be sure to provide either an external_id or id, otherwise a new contact will be created. For the contact properties, this API acts like a patch... meaning that only the events fields you specify will be updated.

However, if you provide a value for the "phone_numbers", "email_addresses", or "custom_data" field, then provide all of the data. Meaning, it does not act as a patch for custom_data or individual endpoints.

Also, please note that we do not support moving a contact from one address book to another.

The PUT Request BODY should look like the following:

{
  "contacts": [
    CONTACTS TO CREATE OR UPDATE
  ]
}

Each Contact object should have the following properties:

Field	Type	Description
id	Integer	The unique identifier of the contact to be updated.
external_id	String	The "external_id" provided by you when you created the contact through the API. Or it could also be the "external_id" on the source address book. For example the Google Address Book's id.
address_book_id	Integer	The id of the address book to scope the external_id to.
name	String (Required)	The full name of the contact. E.g. Fred Smith NOTE: you can provide either "name" or you can provide "first_name" and "last_name". "name" will take precedence.
first_name	String (Required)	The first name of the contact. E.g. Fred
last_name	String (Required)	The last name of the contact. E.g. Fred
add_phone	String	A new phone number for the contact . E.g. 650-555-1212.
add_email	String	An email address for the contact. E.g. [email protected] .
phone_numbers	Array	An array of phone numbers to add to the contact. See below for phone number fields
email_addresses	Array	An array of email addresses to add to the contact. See below for the email address fields.
external_id	String	An optional unique identifier (should be unique across all calendars in user's account). Can be used to fetch updates and update events.

Each Phone number object should include the following properties

Field	Type	Description
number	String	The number of the contact. E.g. 650-555-1212
is_mobile	Boolean	Sets the phone type as "mobile" for the address book specified.
type	String	The type of the phone number to be added. Each address book type has a different set of phone types. List of phone types can be fetched from the /v1/address_books endpoint.
is_primary	Boolean	True if this should be the primary phone number to use when sending email to this contact.

Each email address object should include the following properties

Field	Type	Description
address	String	The email address of the contact. E.g. [email protected]
type	String	The type of email address. Each address book type has a different set of phone types. List of email address types can be fetched from the /v1/address_books endpoint.
is_primary	Boolean	True if this should be the primary email address to use when sending email to this contact.

Example Result:

{ 
  contacts: [ CONTACTS CREATED ]
}

OAuth scope

Calls authenticated with an OAuth 2.0 bearer token must include the contacts:write scope. A token without it receives a 403 insufficient_scope response. HTTP Basic auth is not scope-gated.