Introduction
Welcome to the ZipBooks API!
We format our responses according to JSON API. You can get more info here: http://jsonapi.org
Authentication
To authorize, use this code:
curl -X POST \
https://api.zipbooks.com/v2/auth/login \
-H 'Content-Type: application/json' \
-d '{
"email": "test@example.com",
"password": "password"
}'
Example Response:
{
"tokens": [
{
"user_id": 1,
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYWxsZXIiOm51bGwsInN1YiI6MSwiaXNzIjoiaHR0cHM6XC9cL2FwcC56aXBib29rcy5jb21cL3YyXC9hdXRoXC9sb2dpbiIsImlhdCI6MTUzOTExMTI1NSwiZXhwIjoxNTU0NjYzMjU1LCJuYmYiOjE1MzkxMTEyNTUsImp0aSI6IjEwNzA2ZDdiLTQzNTMtNDdhNC05NTY1LTMwNDU1ZDQ4NzhlYSIsInN0ZWFsdGgiOiJmYWxzZSIsInVwZGF0ZWRfYXQiOiIyMDE4LTEwLTA5IDE4OjU0OjAwLjAwMDAwMFoifQ.eyTgZ0na9eRSTOQ9RzTukBa9z5QdhIQpz1ztzIHbBGg",
"account_name": "ZipBooks"
}
]
}
The ZipBooks API uses JSON web tokens (JWT) for authentication. When you "log in" a user, you will be sent back a three-part, period-delimited string called "token" (see example response).
You must send this token with all subsequent API requests.
Contacts
List All Contacts
curl -X GET \
https://api.zipbooks.com/v2/contacts \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYWxsZXIiOm51bGwsInN1YiI6MSwiaXNzIjoiaHR0cHM6XC9cL2FwcC56aXBib29rcy5jb21cL3YyXC9hdXRoXC9sb2dpbiIsImlhdCI6MTUzOTExMTI1NSwiZXhwIjoxNTU0NjYzMjU1LCJuYmYiOjE1MzkxMTEyNTUsImp0aSI6IjEwNzA2ZDdiLTQzNTMtNDdhNC05NTY1LTMwNDU1ZDQ4NzhlYSIsInN0ZWFsdGgiOiJmYWxzZSIsInVwZGF0ZWRfYXQiOiIyMDE4LTEwLTA5IDE4OjU0OjAwLjAwMDAwMFoifQ.eyTgZ0na9eRSTOQ9RzTukBa9z5QdhIQpz1ztzIHbBGg' \
-H 'Content-Type: application/json'
Example Response:
{
"jsonapi": {
"version": "1.0"
},
"links": {
"last": "/v2/contacts?page[page]=2&page[page-size]=100",
"next": "/v2/contacts?page[page]=2&page[page-size]=100",
"self": "/v2/contacts?page[page]=1&page[page-size]=100"
},
"meta": {
"from": 1,
"to": 1,
"total": 120,
"unfiltered-total": 120
},
"data": [
{
"attributes": {
"address-1": "4383 Torphy Mountains",
"address-2": null,
"archived-at": null,
"city": "Jonesville",
"country": "PL",
"created-at": "2018-10-03T15:23:21.000000Z",
"department": null,
"email": "dickens.sarina@example.net",
"expenses": "4668.95",
"external-source": null,
"first-name": "Mercedes",
"industry": null,
"is-1099-required": false,
"last-name": "Greenholt",
"name": "Little-Dibbert",
"notes": null,
"phone": "+1-285-877-7471",
"postal-code": "95027-8264",
"revenue": "28198.30",
"state": "MN",
"suggested-next-estimate-number": "36",
"suggested-next-invoice-number": "LITTLE-0002",
"unbilled-journal-entry-lines": true,
"unbilled-time-entries": false,
"updated-at": "2018-10-08T22:52:49.000000Z",
"website": "miller.info"
},
"id": "1",
"relationships": {
"account": {
"data": {
"id": "1",
"type": "account"
}
},
"estimates": {},
"integration-object": {
"data": null
},
"invoices": {},
"people": {},
"projects": {},
"public-profile": {
"data": {
"id": "ZGlja2Vucy5zYXJpbmFAZXhhbXBsZS5uZXQ",
"type": "public-profile"
}
},
"recurring-profiles": {},
"time-entries": {}
},
"type": "contact"
},
...
],
"included": [
{
"attributes": {
...
},
"id": "ZGlja2Vucy5zYXJpbmFAZXhhbXBsZS5uZXQ",
"type": "public-profile"
}
]
}
This endpoint retrieves all contacts.
HTTP Request
GET https://api.zipbooks.com/v2/contacts
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| page[page] | 1 | Pagination page number. |
| page[page-size] | 100 | Pagination page size. |
Estimates
List All Estimates
curl -X GET \
https://api.zipbooks.com/v2/estimates \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYWxsZXIiOm51bGwsInN1YiI6MSwiaXNzIjoiaHR0cHM6XC9cL2FwcC56aXBib29rcy5jb21cL3YyXC9hdXRoXC9sb2dpbiIsImlhdCI6MTUzOTExMTI1NSwiZXhwIjoxNTU0NjYzMjU1LCJuYmYiOjE1MzkxMTEyNTUsImp0aSI6IjEwNzA2ZDdiLTQzNTMtNDdhNC05NTY1LTMwNDU1ZDQ4NzhlYSIsInN0ZWFsdGgiOiJmYWxzZSIsInVwZGF0ZWRfYXQiOiIyMDE4LTEwLTA5IDE4OjU0OjAwLjAwMDAwMFoifQ.eyTgZ0na9eRSTOQ9RzTukBa9z5QdhIQpz1ztzIHbBGg' \
-H 'Content-Type: application/json'
Example Response:
{
"jsonapi": {
"version": "1.0"
},
"links": {
"last": "/v2/estimates?page[page]=3&page[page-size]=100",
"next": "/v2/estimates?page[page]=2&page[page-size]=100",
"self": "/v2/estimates?page[page]=1&page[page-size]=100"
},
"meta": {
"from": 1,
"to": 1,
"total": 250,
"unfiltered-total": 250
},
"data": [
{
"attributes": {
"archived-at": null,
"created-at": "2018-10-03T15:23:25.000000Z",
"currency-code": "USD",
"date": "2017-10-04",
"days-out": 29,
"discount": "",
"external-id": "uEQsw1nO7FNUnNrCjg8BymL4RdAR8Ql0POvseWK8",
"history": [
{
"action": "updated",
"created_at": "2018-10-09T19:37:42.000000Z"
},
{
"action": "accepted",
"created_at": "2017-11-02T00:00:00.000000Z"
},
{
"action": "sent",
"created_at": "2017-10-04T00:00:00.000000Z"
}
],
"notes": "a note",
"number": "34",
"po-number": null,
"sent-date": "2017-10-04T00:00:00.000000Z",
"status": "Accepted",
"subtotal": null,
"terms": "some terms",
"title": "Johanna Mann III",
"total": "108.65",
"updated-at": "2018-10-09T19:37:42.000000Z"
},
"id": "8",
"relationships": {
"account": {
"data": {
"id": "1",
"type": "account"
}
},
"contact": {
"data": {
"id": "2",
"type": "contact"
}
},
"line-items": {
"data": [
{
"id": "403",
"type": "line-item"
}
]
},
"logo-cloud-file": {
"data": {
"id": "80",
"type": "cloud-file"
}
}
},
"type": "estimate"
},
...
],
"included": [
{
"attributes": {
...
},
"id": "2",
"relationships": {
"account": {
"data": {
"id": "1",
"type": "account"
}
},
"estimates": {},
"integration-object": {},
"invoices": {},
"people": {},
"projects": {},
"public-profile": {},
"recurring-profiles": {},
"time-entries": {}
},
"type": "contact"
},
{
"attributes": {
...
},
"id": "80",
"type": "cloud-file"
},
{
"attributes": {
"created-at": "2018-10-03T15:23:25.000000Z",
"discount": null,
"end-date": null,
"name": "Upgradable attitude-oriented task-force",
"notes": "Similique ut adipisci explicabo dolore. Quae quas voluptates sapiente et amet est ipsam. Ut aut ullam fugiat.",
"order": 1,
"quantity": "4.5100",
"rate": "21.9000",
"start-date": null,
"taxes": [
{
"id": "6",
"name": "Sales",
"rate": "5"
}
],
"type": "time-entry",
"updated-at": "2018-10-09T19:37:42.000000Z"
},
"id": "403",
"relationships": {
"chart-account": {
"data": null
},
"line-itemable": {
"data": {
"id": "8",
"type": "estimate"
}
}
},
"type": "line-item"
}
]
}
This endpoint retrieves all estimates.
HTTP Request
GET https://api.zipbooks.com/v2/estimates
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| page[page] | 1 | Pagination page number. |
| page[page-size] | 100 | Pagination page size. |
Invoices
List All Invoices
curl -X GET \
https://api.zipbooks.com/v2/invoices \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYWxsZXIiOm51bGwsInN1YiI6MSwiaXNzIjoiaHR0cHM6XC9cL2FwcC56aXBib29rcy5jb21cL3YyXC9hdXRoXC9sb2dpbiIsImlhdCI6MTUzOTExMTI1NSwiZXhwIjoxNTU0NjYzMjU1LCJuYmYiOjE1MzkxMTEyNTUsImp0aSI6IjEwNzA2ZDdiLTQzNTMtNDdhNC05NTY1LTMwNDU1ZDQ4NzhlYSIsInN0ZWFsdGgiOiJmYWxzZSIsInVwZGF0ZWRfYXQiOiIyMDE4LTEwLTA5IDE4OjU0OjAwLjAwMDAwMFoifQ.eyTgZ0na9eRSTOQ9RzTukBa9z5QdhIQpz1ztzIHbBGg' \
-H 'Content-Type: application/json'
Example Response:
{
"jsonapi": {
"version": "1.0"
},
"links": {
"last": "/v2/invoices?page[page]=3&page[page-size]=50",
"next": "/v2/invoices?page[page]=2&page[page-size]=50",
"self": "/v2/invoices?page[page]=1&page[page-size]=50"
},
"meta": {
"from": 1,
"to": 50,
"total": 150,
"unfiltered-total": 150
},
"data": [
{
"attributes": {
"accept-credit-cards": true,
"accept-paypal": false,
"archived-at": null,
"created-at": "2018-10-09T19:23:49.000000Z",
"currency-code": "USD",
"date": "2018-10-09",
"days-outstanding": null,
"due-date": "2018-11-08",
"external-id": "26dca2ff-3228-452f-b68e-069dcc4b9243",
"google-drive-id": null,
"history": [
{
"action": "updated",
"date": "2018-10-09T19:24:04.000000Z"
},
{
"action": "invoice_created",
"date": "2018-10-09T19:23:49.000000Z"
}
],
"notes": null,
"number": "LITTLE-0001",
"paid-total": "0.00",
"po-number": null,
"sent-date": null,
"status": "Draft",
"terms": "Net 30",
"title": null,
"total": "189.22",
"updated-at": "2018-10-09T19:24:04.000000Z"
},
"id": "187",
"relationships": {
"account": {
"data": {
"id": "1",
"type": "account"
}
},
"contact": {
"data": {
"id": "1",
"type": "contact"
}
},
"estimate": {
"data": null
},
"line-items": {
"data": [
{
"id": "1350",
"type": "line-item"
}
]
},
"logo-cloud-file": {
"data": {
"id": "257",
"type": "cloud-file"
}
},
"recurring-profile": {
"data": null
}
},
"type": "invoice"
},
...
],
"included": [
{
"attributes": {
...
},
"id": "1",
"relationships": {
"account": {
"data": {
"id": "1",
"type": "account"
}
},
"estimates": {},
"integration-object": {},
"invoices": {},
"people": {},
"projects": {},
"public-profile": {},
"recurring-profiles": {},
"time-entries": {}
},
"type": "contact"
},
{
"attributes": {
...
},
"id": "257",
"type": "cloud-file"
},
{
"attributes": {
"created-at": "2018-10-09T19:23:49.000000Z",
"discount": "10.00",
"end-date": null,
"name": "Accounting",
"notes": null,
"order": 1,
"quantity": "4.0000",
"rate": "50.0000",
"start-date": null,
"taxes": [
{
"id": "1",
"name": "Sales",
"rate": "5.123457"
}
],
"type": "time-entry",
"updated-at": "2018-10-09T19:24:04.000000Z"
},
"id": "1350",
"relationships": {
"chart-account": {
"data": null
},
"line-itemable": {
"data": {
"id": "187",
"type": "invoice"
}
}
},
"type": "line-item"
}
],
}
This endpoint retrieves all invoices.
HTTP Request
GET https://api.zipbooks.com/v2/invoices
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| page[page] | 1 | Pagination page number. |
| page[page-size] | 50 | Pagination page size. |