Admin permissions required.

The contact object

Attribute Type Description
id integer Unique ID for the contact.
client object An object containing the contact’s client id and name.
title string The title of the contact.
first_name string The first name of the contact.
last_name string The last name of the contact.
email string The contact’s email address.
phone_office string The contact’s office phone number.
phone_mobile string The contact’s mobile phone number.
fax string The contact’s fax number.
created_at datetime Date and time the contact was created.
updated_at datetime Date and time the contact was last updated.

List all contacts

Returns a list of your contacts. The contacts are returned sorted by creation date, with the most recently created contacts appearing first.

The response contains an object with a contacts property that contains an array of up to per_page contacts. Each entry in the array is a separate contact object. If no more contacts are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your contacts.

GET /v2/contacts
Parameter Type Description
client_id integer Only return contacts belonging to the client with the given ID.
updated_since datetime Only return contacts that have been updated since the given date and time.
page integer The page number to use in pagination. For instance, if you make a list request and receive 100 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer The number of records to return per page. Can range between 1 and 100. (Default: 100)

Example Request:

curl "https://api.harvestapp.com/v2/contacts" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)"

Example Response:

{
"contacts":[
{
"id":4706479,
"title":"Owner",
"first_name":"Jane",
"last_name":"Doe",
"email":"janedoe@example.com",
"phone_office":"(203) 697-8885",
"phone_mobile":"(203) 697-8886",
"fax":"(203) 697-8887",
"created_at":"2017-06-26T21:20:07Z",
"updated_at":"2017-06-26T21:27:07Z",
"client":{
"id":5735774,
"name":"ABC Corp"
}
},
{
"id":4706453,
"title":"Manager",
"first_name":"Richard",
"last_name":"Roe",
"email":"richardroe@example.com",
"phone_office":"(318) 515-5905",
"phone_mobile":"(318) 515-5906",
"fax":"(318) 515-5907",
"created_at":"2017-06-26T21:06:55Z",
"updated_at":"2017-06-26T21:27:20Z",
"client":{
"id":5735776,
"name":"123 Industries"
}
}
],
"per_page":100,
"total_pages":1,
"total_entries":2,
"next_page":null,
"previous_page":null,
"page":1,
"links":{
"first":"https://api.harvestapp.com/v2/contacts?page=1&per_page=100",
"next":null,
"previous":null,
"last":"https://api.harvestapp.com/v2/contacts?page=1&per_page=100"
}
}

Retrieve a contact

Retrieves the contact with the given ID. Returns a contact object and a 200 OK response code if a valid identifier was provided.

GET /v2/contacts/{CONTACT_ID}

Example Request:

curl "https://api.harvestapp.com/v2/contacts/4706479" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)"

Example Response:

{
"id":4706479,
"title":"Owner",
"first_name":"Jane",
"last_name":"Doe",
"email":"janedoe@example.com",
"phone_office":"(203) 697-8885",
"phone_mobile":"(203) 697-8886",
"fax":"(203) 697-8887",
"created_at":"2017-06-26T21:20:07Z",
"updated_at":"2017-06-26T21:27:07Z",
"client":{
"id":5735774,
"name":"ABC Corp"
}
}

Create a contact

Creates a new contact object. Returns a contact object and a 201 Created response code if the call succeeded.

POST /v2/contacts
Parameter Type Required Description
client_id integer required The ID of the client associated with this contact.
title string optional The title of the contact.
first_name string required The first name of the contact.
last_name string optional The last name of the contact.
email string optional The contact’s email address.
phone_office string optional The contact’s office phone number.
phone_mobile string optional The contact’s mobile phone number.
fax string optional The contact’s fax number.

Example Request:

curl "https://api.harvestapp.com/v2/contacts" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"client_id":"5735776","first_name":"George","last_name":"Frank","email":"georgefrank@example.com"}'

Example Response:

{
"id":4706510,
"title":null,
"first_name":"George",
"last_name":"Frank",
"email":"georgefrank@example.com",
"phone_office":"",
"phone_mobile":"",
"fax":"",
"created_at":"2017-06-26T21:44:57Z",
"updated_at":"2017-06-26T21:44:57Z",
"client":{
"id":5735776,
"name":"123 Industries"
}
}

Update a contact

Updates the specific contact by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns a contact object and a 200 OK response code if the call succeeded.

PATCH /v2/contacts/{CONTACT_ID}
Parameter Type Description
client_id integer The ID of the client associated with this contact.
title string The title of the contact.
first_name string The first name of the contact.
last_name string The last name of the contact.
email string The contact’s email address.
phone_office string The contact’s office phone number.
phone_mobile string The contact’s mobile phone number.
fax string The contact’s fax number.

Example Request:

curl "https://api.harvestapp.com/v2/contacts/4706510" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"title":"Owner"}'

Example Response:

{
"id":4706510,
"title":"Owner",
"first_name":"George",
"last_name":"Frank",
"email":"georgefrank@example.com",
"phone_office":"",
"phone_mobile":"",
"fax":"",
"created_at":"2017-06-26T21:44:57Z",
"updated_at":"2017-06-26T21:46:48Z",
"client":{
"id":5735776,
"name":"123 Industries"
}
}

Delete a contact

Delete a contact. Returns a 200 OK response code if the call succeeded.

DELETE /v2/contacts/{CONTACT_ID}

Example Request:

curl "https://api.harvestapp.com/v2/contacts/4706510" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)" \
  -X DELETE