Admin permissions required.

The client object

Attribute Type Description
id integer Unique ID for the client.
name string A textual description of the client.
is_active boolean Whether the client is active or archived.
address string The physical address for the client.
currency string The currency code associated with this client.
created_at datetime Date and time the client was created.
updated_at datetime Date and time the client was last updated.

List all clients

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

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

GET /v2/clients
Parameter Type Description
updated_since datetime Only return clients 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 retreive 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/clients" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)"

Example Response:

{
  "clients":[
    {
      "id":5735776,
      "name":"123 Industries",
      "is_active":true,
      "address":"123 Main St.\r\nAnytown, LA 71223",
      "created_at":"2017-06-26T21:02:12Z",
      "updated_at":"2017-06-26T21:34:11Z",
      "currency":"EUR"
    },
    {
      "id":5735774,
      "name":"ABC Corp",
      "is_active":true,
      "address":"456 Main St.\r\nAnytown, CT 06467",
      "created_at":"2017-06-26T21:01:52Z",
      "updated_at":"2017-06-26T21:27:07Z",
      "currency":"USD"
    }
  ],
  "per_page":100,
  "total_pages":1,
  "total_entries":2,
  "next_page":null,
  "previous_page":null,
  "page":1,
  "links":{
    "first":"https://api.harvestapp.com/v2/clients?page=1&per_page=100",
    "next":null,
    "previous":null,
    "last":"https://api.harvestapp.com/v2/clients?page=1&per_page=100"
  }
}

Retreive a client

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

GET /v2/clients/{CLIENT_ID}

Example Request:

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

Example Response:

{
  "id":5735776,
  "name":"123 Industries",
  "is_active":true,
  "address":"123 Main St.\r\nAnytown, LA 71223",
  "created_at":"2017-06-26T21:02:12Z",
  "updated_at":"2017-06-26T21:34:11Z",
  "currency":"EUR"
}

Create a client

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

POST /v2/clients
Parameter Type Required Description
name string required A textual description of the client.
is_active boolean optional Whether the client is active, or archived. Defaults to true.
address string optional A textual representation of the client’s physical address. May include new line characters.
currency string optional The currency used by the client. If not provided, the company’s currency will be used. See a list of supported currencies

Example Request:

curl "https://api.harvestapp.com/v2/clients" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)" \
  -X POST \
  -d name="Your New Client" \
  -d currency="EUR"

Example Response:

{
  "id":5737336,
  "name":"Your New Client",
  "is_active":true,
  "address":null,
  "created_at":"2017-06-26T21:39:35Z",
  "updated_at":"2017-06-26T21:39:35Z",
  "currency":"EUR"
  }

Update a client

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

PATCH /v2/clients/{CLIENT_ID}
Parameter Type Description
name string A textual description of the client.
is_active boolean Whether the client is active, or archived.
address string A textual representation of the client’s physical address. May include new line characters.
currency string The currency used by the client. If not provided, the company’s currency will be used. See a list of supported currencies

Example Request:

curl "https://api.harvestapp.com/v2/clients/5737336" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp (yourname@example.com)" \
  -X PATCH \
  -d is_active=false

Example Response:

{
  "id":5737336,
  "name":"Your New Client",
  "is_active":false,
  "address":null,
  "created_at":"2017-06-26T21:39:35Z",
  "updated_at":"2017-06-26T21:41:18Z",
  "currency":"EUR"
}

Delete a client

Delete a client. Deleting a client is only possible if it has no projects or invoices associated with it. Returns a 200 OK response code if the call succeeded.

DELETE /v2/clients/{CLIENT_ID}

Example Request:

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