email Contact Us
  1. Harvest API V2 Documentation
  2. Clients API
  3. Client Contacts

Client Contacts

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.

Required permissions

You must be an Administrator or Manager with permission to create and edit clients in order to interact with the /v2/contacts endpoint. Insufficient permissions will result in a 403 Forbidden status code.

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 DEPRECATED The page number to use in pagination. For instance, if you make a list request and receive 2000 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 2000. (Default: 2000)
This endpoint supports cursor-based pagination and therefore deprecates the page parameter. For more information, visit the pagination guide.

Example requests

We have a collection of API requests in Postman that makes it easy to try this out. Click here to learn more!


curl "https://api.harvestapp.com/v2/contacts" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp ([email protected])"

Example responses

<?xml version="1.0" encoding="UTF-8"?>
<contacts type="array">
    <contact>
        <id type="integer">4706479</id>
        <client-id type="integer">5735774</client-id>
        <title>Owner</title>
        <first-name>Jane</first-name>
        <last-name>Doe</last-name>
        <email>[email protected]</email>
        <phone-office>(203) 697-8885</phone-office>
        <phone-mobile>(203) 697-8886</phone-mobile>
        <fax>(203) 697-8887</fax>
        <created-at type="dateTime">2013-08-12T15:30:14Z</created-at>
        <updated-at type="dateTime">2015-04-16T18:07:28Z</updated-at>
    </contact>
    <contact>
        <id type="integer">4706453</id>
        <client-id type="integer">5735776</client-id>
        <title>Manager</title>
        <first-name>Richard</first-name>
        <last-name>Roe</last-name>
        <email>[email protected]</email>
        <phone-office>(318) 515-5905</phone-office>
        <phone-mobile>(318) 515-5906</phone-mobile>
        <fax>(318) 515-5907</fax>
        <created-at type="dateTime"></created-at>
        <updated-at type="dateTime"></updated-at>
    </contact>
</contacts>
{
  "contacts":[
    {
      "id":4706479,
      "title":"Owner",
      "first_name":"Jane",
      "last_name":"Doe",
      "email":"[email protected]",
      "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":"[email protected]",
      "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":2000,
  "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=2000",
    "next":null,
    "previous":null,
    "last":"https://api.harvestapp.com/v2/contacts?page=1&per_page=2000"
  }
}

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 requests

We have a collection of API requests in Postman that makes it easy to try this out. Click here to learn more!


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

Example responses

<?xml version="1.0" encoding="UTF-8"?>
<contacts type="array">
    <contact>
        <id type="integer">4706479</id>
        <client-id type="integer">5735774</client-id>
        <title>Owner</title>
        <first-name>Jane</first-name>
        <last-name>Doe</last-name>
        <email>[email protected]</email>
        <phone-office>(203) 697-8885</phone-office>
        <phone-mobile>(203) 697-8886</phone-mobile>
        <fax>(203) 697-8887</fax>
        <created-at type="dateTime">2013-08-12T15:30:14Z</created-at>
        <updated-at type="dateTime">2015-04-16T18:07:28Z</updated-at>
    </contact>
</contacts>
{
  "id":4706479,
  "title":"Owner",
  "first_name":"Jane",
  "last_name":"Doe",
  "email":"[email protected]",
  "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 requests

We have a collection of API requests in Postman that makes it easy to try this out. Click here to learn more!


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

Example responses

<?xml version="1.0" encoding="UTF-8"?>
<contacts type="array">
    <contact>
        <id type="integer">4706510</id>
        <client-id type="integer">5735776</client-id>
        <title>null</title>
        <first-name>George</first-name>
        <last-name>Frank</last-name>
        <email>[email protected]</email>
        <phone-office></phone-office>
        <phone-mobile></phone-mobile>
        <fax></fax>
        <created-at type="dateTime">2019-06-26T21:44:57Z</created-at>
        <updated-at type="dateTime">2019-06-26T21:44:57Z</updated-at>
    </contact>
</contacts>
{
  "id":4706510,
  "title":null,
  "first_name":"George",
  "last_name":"Frank",
  "email":"[email protected]",
  "phone_office":"",
  "phone_mobile":"",
  "fax":"",
  "created_at":"2019-06-26T21:44:57Z",
  "updated_at":"2019-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 requests

We have a collection of API requests in Postman that makes it easy to try this out. Click here to learn more!


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

Example responses

<contacts type="array">
    <contact>
        <id type="integer">4706510</id>
        <client-id type="integer">5735776</client-id>
        <title>Owner</title>
        <first-name>George</first-name>
        <last-name>Frank</last-name>
        <email>[email protected]</email>
        <phone-office></phone-office>
        <phone-mobile></phone-mobile>
        <fax></fax>
        <created-at type="dateTime">2019-06-26T21:44:57Z</created-at>
        <updated-at type="dateTime">2019-06-26T21:44:57Z</updated-at>
    </contact>
</contacts>
{
  "id":4706510,
  "title":"Owner",
  "first_name":"George",
  "last_name":"Frank",
  "email":"[email protected]",
  "phone_office":"",
  "phone_mobile":"",
  "fax":"",
  "created_at":"2019-06-26T21:44:57Z",
  "updated_at":"2019-06-26T21:44:57Z",
  "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 requests

We have a collection of API requests in Postman that makes it easy to try this out. Click here to learn more!


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

Still have questions? We’re happy to help!

Contact Us