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) |
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 ([email protected])"
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 ([email protected])"
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 ([email protected])" \
-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 ([email protected])" \
-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 ([email protected])" \
-X DELETE