evenbooks
Sign inStart for free

Company

Business details and settings.

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.

Get the company

get/company

Business details and settings of the company the credential belongs to.

Response 200

CompanyDto (fields under Schemas)

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

Change company details and settings

patch/company
Administrator keyWrite access

Omitted fields stay as they are. Send version from your last read (409 version_conflict if it changed). nextInvoiceNumber can only go up, and fiscalYearStartMonth can only change while no accounting period is closed (409 invalid_state). Changing invoiceFooter also updates the invoice branding’s default footer.

Request body

UpdateCompanyInput

  • versionintegerrequired
  • namestring

    1–200 characters

  • legalNamestring or null

    up to 200 characters

  • emailstring (email) or null

    up to 254 characters

  • phonestring or null

    up to 50 characters

  • addressAddressInput
    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

  • timeZonestring

    1–64 characters

  • fiscalYearStartMonthinteger

    1–12

  • invoicePrefixstring

    up to 12 characters

  • nextInvoiceNumberinteger

    at most 2147483647 · greater than 0

  • creditNotePrefixstring

    up to 12 characters

  • defaultTermsDaysinteger

    0–365

  • invoiceFooterstring or null

    up to 2000 characters

  • transactionDeletionEnabledboolean
  • businessTypestring · BusinessType or null

    One of: sole_proprietor single_member_llc partnership s_corp c_corp nonprofit other

  • taxBasisstring · TaxBasis or null

    One of: cash accrual

  • booksStartDatestring · PlainDateString or null
  • setupDismissedboolean

Response 200

CompanyDto (fields under Schemas)

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

List email sender domains

get/company/email-senders
Administrator key

Domains set up to send invoice emails from the company’s own address, with their verification status and the DNS records to add. active marks the one in use; when none is active, emails come from Evenbooks.

Response 200

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

Set up an email sender domain

post/company/email-senders
Administrator keyWrite access

Starts verification of a domain the company controls, so invoice emails can come from fromEmail (an address on that domain; personal mailbox providers are refused). Add the returned DNS records, then call POST /company/email-senders/{id}/verify, then select it with POST /company/email-senders/select.

Request body

SenderSetupInput

  • domainstringrequired

    up to 253 characters · pattern ^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$

  • fromEmailstring (email)required

    up to 254 characters

  • fromNamestringrequired

    1–100 characters

Response 200

SenderIdentityDto (fields under Schemas)

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

Cancel an email sender setup

post/company/email-senders/{id}/cancel
Administrator keyWrite access

Drops a domain that is not verified yet. A verified domain cannot be cancelled (409 invalid_state); select the Evenbooks sender instead. Returns the remaining domains.

Parameters

  • idstring (uuid)path · required

Response 200

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

Check an email sender domain

post/company/email-senders/{id}/verify
Administrator keyWrite access

Checks the domain’s DNS records now and returns its updated status: verified once the authorization TXT record and the DKIM records are in place, otherwise pending (or failed if it was verified before) with the reason in lastError.

Parameters

  • idstring (uuid)path · required

Response 200

SenderIdentityDto (fields under Schemas)

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

Choose the invoice email sender

post/company/email-senders/select
Administrator keyWrite access

Sends invoice emails from the domain id, which is checked again first and must be verified (409 invalid_state), or from the Evenbooks address when id is null. Returns all domains with the new active flags.

Request body

PostCompanyEmailSendersSelectBody

  • idstring (uuid) or nullrequired

Response 200

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

Get invoice branding and email template

get/company/invoice-presentation

The layout, colors, logo and default notes of invoice PDFs, and the subject, message and signature of invoice emails. version 0 means the defaults were never changed.

Response 200

InvoicePresentationDto (fields under Schemas)

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

Change invoice branding and email template

patch/company/invoice-presentation
Administrator keyWrite access

Replaces the whole branding and email template; send version from your last read (409 version_conflict if it changed). Applies to invoices issued from now on: issued invoices keep the design they were issued with. The logo must be a PNG or JPEG data URL.

Request body

UpdateInvoicePresentationInput

  • brandingInvoiceBrandingInputrequired
    Show 10 fields
    • layoutstringrequired

      One of: classic modern

    • accentColorstringrequired

      pattern ^#[0-9a-fA-F]{6}$

    • paperSizestringrequired

      One of: LETTER A4

    • showQuantityboolean

      default true

    • showUnitPriceboolean

      default true

    • showLineTaxboolean

      default true

    • logostring or nullrequired

      up to 350000 characters · pattern ^data:image\/(png|jpeg);base64,[A-Za-z0-9+/]+=*$

    • defaultFooterstring or nullrequired

      up to 2000 characters

    • defaultNotesstring or nullrequired

      up to 2000 characters

    • paymentInstructionsstring or nullrequired

      up to 2000 characters

  • emailInvoiceEmailTemplateInputrequired
    Show 4 fields
    • subjectstringrequired

      up to 250 characters

    • messagestringrequired

      up to 5000 characters

    • signaturestringrequired

      up to 2000 characters

    • replyTostring (email) or nullrequired

      up to 254 characters

  • versionintegerrequired

    at least 0

Response 200

InvoicePresentationDto (fields under Schemas)

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

Preview an invoice email

post/company/invoice-presentation/preview
Write access

Renders the email without sending it: for invoiceId, or a sample invoice when omitted, with the saved template or the unsaved presentation you pass. Returns the sender, subject, and text and HTML bodies.

Request body

InvoiceEmailPreviewInput

Response 200

InvoiceEmailPreviewDto

  • fromstring
  • replyTostring or null
  • subjectstring
  • messagestring
  • textstring
  • htmlstring
  • templateVersioninteger

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

Make a sample invoice PDF

post/company/invoice-presentation/sample-pdf

Renders a sample invoice with the branding you pass, saved or not, and returns the PDF. Nothing is stored.

Request body

InvoicePresentationInput (fields under Schemas)

Response 200

Returns PDF file (application/pdf).

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

Send a test invoice email

post/company/invoice-presentation/test-email
Administrator keyWrite accessIdempotent

Queues a sample invoice email to to, using the branding and template you pass (saved or not). Counts toward the company’s email limits (429 rate_limited); an address on the suppression list is refused (409 invalid_state). idempotencyKey (or the Idempotency-Key header) is required.

Request body

TestInvoiceEmailInput

  • brandingInvoiceBrandingInputrequired
    Show 10 fields
    • layoutstringrequired

      One of: classic modern

    • accentColorstringrequired

      pattern ^#[0-9a-fA-F]{6}$

    • paperSizestringrequired

      One of: LETTER A4

    • showQuantityboolean

      default true

    • showUnitPriceboolean

      default true

    • showLineTaxboolean

      default true

    • logostring or nullrequired

      up to 350000 characters · pattern ^data:image\/(png|jpeg);base64,[A-Za-z0-9+/]+=*$

    • defaultFooterstring or nullrequired

      up to 2000 characters

    • defaultNotesstring or nullrequired

      up to 2000 characters

    • paymentInstructionsstring or nullrequired

      up to 2000 characters

  • emailInvoiceEmailTemplateInputrequired
    Show 4 fields
    • subjectstringrequired

      up to 250 characters

    • messagestringrequired

      up to 5000 characters

    • signaturestringrequired

      up to 2000 characters

    • replyTostring (email) or nullrequired

      up to 254 characters

  • tostring (email)required

    up to 254 characters

  • idempotencyKeystringrequired

    1–200 characters

Response 200

EmailMessageDto (fields under Schemas)

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

BusinessType

string

One of: sole_proprietor single_member_llc partnership s_corp c_corp nonprofit other

CompanyDto

  • idstring
  • clerkOrgIdstring
  • namestring
  • legalNamestring or null
  • emailstring or null
  • phonestring or null
  • addressAddress
  • baseCurrencystring · CurrencyCode
  • timeZonestring
  • fiscalYearStartMonthinteger
  • invoicePrefixstring
  • nextInvoiceNumberinteger
  • creditNotePrefixstring
  • defaultTermsDaysinteger
  • invoiceFooterstring or null
  • hasPostedEntriesboolean
  • planstring

    One of: free paid

  • transactionDeletionEnabledboolean
  • businessTypestring · BusinessType or null

    One of: sole_proprietor single_member_llc partnership s_corp c_corp nonprofit other

  • taxBasisstring · TaxBasis or null

    One of: cash accrual

  • booksStartDatestring or null
  • setupDismissedAtstring or null
  • versioninteger

CurrencyCode

string

pattern ^[A-Z]{3}$

EmailMessageDto

  • idstring
  • kindstring
  • invoiceIdstring or null
  • toEmailstring
  • fromEmailstring or nulloptional
  • replyTostring or nulloptional
  • templateVersionnumber or nulloptional
  • subjectstring
  • statusstring · EmailStatus

    One of: queued sending sent delivered bounced complained failed uncertain suppressed

  • providerMessageIdstring or null
  • attemptsinteger
  • lastErrorstring or null
  • isResendboolean
  • requestedBystring
  • queuedAtstring
  • sentAtstring or null
  • deliveredAtstring or null
  • failedAtstring or null

EmailStatus

string

One of: queued sending sent delivered bounced complained failed uncertain suppressed

InvoiceBrandingInput

  • layoutstringrequired

    One of: classic modern

  • accentColorstringrequired

    pattern ^#[0-9a-fA-F]{6}$

  • paperSizestringrequired

    One of: LETTER A4

  • showQuantityboolean

    default true

  • showUnitPriceboolean

    default true

  • showLineTaxboolean

    default true

  • logostring or nullrequired

    up to 350000 characters · pattern ^data:image\/(png|jpeg);base64,[A-Za-z0-9+/]+=*$

  • defaultFooterstring or nullrequired

    up to 2000 characters

  • defaultNotesstring or nullrequired

    up to 2000 characters

  • paymentInstructionsstring or nullrequired

    up to 2000 characters

InvoiceBrandingInputOutput

  • layoutstring

    One of: classic modern

  • accentColorstring

    pattern ^#[0-9a-fA-F]{6}$

  • paperSizestring

    One of: LETTER A4

  • showQuantityboolean

    default true

  • showUnitPriceboolean

    default true

  • showLineTaxboolean

    default true

  • logostring or null

    up to 350000 characters · pattern ^data:image\/(png|jpeg);base64,[A-Za-z0-9+/]+=*$

  • defaultFooterstring or null

    up to 2000 characters

  • defaultNotesstring or null

    up to 2000 characters

  • paymentInstructionsstring or null

    up to 2000 characters

InvoiceEmailTemplateInput

  • subjectstringrequired

    up to 250 characters

  • messagestringrequired

    up to 5000 characters

  • signaturestringrequired

    up to 2000 characters

  • replyTostring (email) or nullrequired

    up to 254 characters

InvoiceEmailTemplateInputOutput

  • subjectstring

    up to 250 characters

  • messagestring

    up to 5000 characters

  • signaturestring

    up to 2000 characters

  • replyTostring (email) or null

    up to 254 characters

InvoicePresentationDto

InvoicePresentationInput

PlainDateString

string

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

SenderIdentityDto

  • idstring
  • domainstring
  • fromEmailstring
  • fromNamestring
  • statusstring

    One of: pending verified failed disabled

  • activeboolean
  • checkedAtstring or null
  • lastErrorstring or null
  • recordsarray of object
    Show 4 fields of each item
    • namestring
    • typestring

      One of: TXT CNAME

    • valuestring
    • purposestring

TaxBasis

string

One of: cash accrual