NAV Navbar
shell

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.