evenbooks
Sign inStart for free

Customers & vendors

People and businesses you sell to and buy from.

Paths are relative to https://evenbooks.org/api/v1. How keys, errors, paging and versions work is in the guide; the whole reference is also an OpenAPI 3.1 document.

Administrator key marks endpoints that need a key with the admin role, Write access those a read-only key can’t call, and Idempotent those that accept an idempotency key.

List customers and vendors

get/contacts

By name A–Z unless sort and dir say otherwise. Archived contacts are left out unless includeArchived is set; kind keeps customers or vendors; q searches the name and email.

Parameters

  • limitintegerquery

    1–200 · default 50

  • cursorstring · PageCursorquery
  • sortstringquery

    One of: name createdAt

  • dirstring · SortDirectionquery

    One of: asc desc

  • qstringquery

    up to 200 characters

  • kindstringquery

    One of: customer vendor

  • includeArchivedboolean · QueryBooleanquery

Response 200

A page of ContactDto ({ items, nextCursor, total }, see paging).

Errors 400 · 401 · 403 · 404 · 409 · 429

Add a customer or vendor

post/contacts
Write access

A contact is a customer, a vendor or both (isCustomer defaults to true). Invoices need a customer; expenses can name a vendor.

Request body

CreateContactInput

  • namestringrequired

    1–200 characters

  • isCustomerboolean

    default true

  • isVendorboolean

    default false

  • emailstring (email) or null

    up to 254 characters

  • phonestring or null

    up to 50 characters

  • billingAddressAddressInput
    Show 6 fields
    • line1string

      up to 200 characters

    • line2string

      up to 200 characters

    • citystring

      up to 100 characters

    • regionstring

      up to 100 characters

    • postalCodestring

      up to 20 characters

    • countrystring

      up to 2 characters

  • notesstring or null

    up to 2000 characters

Response 200

ContactDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Get a customer or vendor

get/contacts/{id}

Parameters

  • idstring (uuid)path · required

Response 200

ContactDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Change a customer or vendor

patch/contacts/{id}
Write access

Omitted fields stay as they are. isArchived: true leaves it out of lists and stops new invoices to it (contacts are archived, not deleted). Send version from your last read (409 version_conflict if it changed). Invoices already issued keep the details they were issued with.

Parameters

  • idstring (uuid)path · required

Request body

UpdateContactInput

  • versionintegerrequired
  • namestring

    1–200 characters

  • isCustomerboolean
  • isVendorboolean
  • emailstring (email) or null

    up to 254 characters

  • phonestring or null

    up to 50 characters

  • billingAddressAddressInput
    Show 6 fields
    • line1string

      up to 200 characters

    • line2string

      up to 200 characters

    • citystring

      up to 100 characters

    • regionstring

      up to 100 characters

    • postalCodestring

      up to 20 characters

    • countrystring

      up to 2 characters

  • notesstring or null

    up to 2000 characters

  • isArchivedboolean

Response 200

ContactDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Get what a customer owes

get/contacts/{id}/balance

The customer’s open invoices with their balances, payments with money not yet applied, and credit notes with credit left, plus the totals owed (totalReceivable) and held as credit (totalCredits).

Parameters

  • idstring (uuid)path · required

Response 200

CustomerBalanceDto

Errors 400 · 401 · 403 · 404 · 409 · 429

Archive or restore many contacts

post/contacts/bulk
Write access

Up to 100 contacts, each with the version from your last read. A stale version fails only that contact; the response has one result per contact, with the updated contact (and its new version) when it went through.

Request body

BulkContactsInput

  • actionstringrequired

    One of: archive unarchive

  • itemsarray of objectrequired

    1–100 items

    Show 2 fields of each item
    • idstring · Uuidrequired
    • versionintegerrequired

Response 200

BulkContactsResultDto

  • resultsarray of object
    Show 4 fields of each item
    • idstring
    • okboolean
    • contactContactDtooptional
    • errorobjectoptional
      Show 2 fields
      • codestring
      • messagestring
  • succeededinteger
  • failedinteger

Errors 400 · 401 · 403 · 404 · 409 · 429

Schemas

The types these endpoints take or return, by name. Type names above link here.

Address

  • line1stringoptional

    up to 200 characters

  • line2stringoptional

    up to 200 characters

  • citystringoptional

    up to 100 characters

  • regionstringoptional

    up to 100 characters

  • postalCodestringoptional

    up to 20 characters

  • countrystringoptional

    up to 2 characters

AddressInput

  • line1string

    up to 200 characters

  • line2string

    up to 200 characters

  • citystring

    up to 100 characters

  • regionstring

    up to 100 characters

  • postalCodestring

    up to 20 characters

  • countrystring

    up to 2 characters

ContactDto

  • idstring
  • namestring
  • isCustomerboolean
  • isVendorboolean
  • emailstring or null
  • phonestring or null
  • billingAddressAddress
  • notesstring or null
  • isArchivedboolean
  • versioninteger
  • createdAtstring

DecimalString

decimal string

string

up to 32 characters · pattern ^-?\d+(\.\d+)?$

OpenInvoiceDto

PageCursor

string

up to 2000 characters

PlainDateString

string

pattern ^\d{4}-\d{2}-\d{2}$

QueryBoolean

boolean

SortDirection

string

One of: asc desc

Uuid

string (uuid)