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

Clients

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.
statement_key string Used to build a URL to your client’s invoice dashboard:
https://{ACCOUNT_SUBDOMAIN}.harvestapp.com/client/statements/{STATEMENT_KEY}
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.

Required permissions

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

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
is_active boolean Pass true to only return active clients and false to return inactive clients.
updated_since datetime Only return clients 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 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",
      "statement_key":"0a39d3e33c8058cf7c3f8097d854c64e",
      "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",
      "statement_key":"e42aa2cb60e85925ffe5d13ee7ee8706",
      "created_at":"2017-06-26T21:01:52Z",
      "updated_at":"2017-06-26T21:27:07Z",
      "currency":"USD"
    }
  ],
  "per_page":2000,
  "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=2000",
    "next":null,
    "previous":null,
    "last":"https://api.harvestapp.com/v2/clients?page=1&per_page=2000"
  }
}

Retrieve 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",
  "statement_key":"0a39d3e33c8058cf7c3f8097d854c64e",
  "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 \
  -H "Content-Type: application/json" \
  -d '{"name":"Your New Client","currency":"EUR"}'

Example Response:

{
  "id":5737336,
  "name":"Your New Client",
  "is_active":true,
  "address":null,
  "statement_key":"82455699ad085d8cffc3e9a4e43ff7b8",
  "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. 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 \
  -H "Content-Type: application/json" \
  -d '{"is_active":false}'

Example Response:

{
  "id":5737336,
  "name":"Your New Client",
  "is_active":false,
  "address":null,
  "statement_key":"82455699ad085d8cffc3e9a4e43ff7b8",
  "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, invoices, or estimates 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

Still have questions? We’re happy to help!

Contact Us