NAV Navbar
cURL

lexoffice API Documentation

This documentation describes the set-up process, where to start with the API and the currently available endpoints. It moreover provides samples and suggestions on how to get the best out of the API.

Introduction

The lexoffice API is a REST API that allows developers to incorporate lexoffice into their applications by pushing and pulling data from and to lexoffice. Examples for this data are contact information and e.g. scanned images for bookkeeping vouchers (referred to as "files"). The responses of the endpoints are formatted in JSON.

The lexoffice API endpoints are exposed by a gateway located at https://api.lexoffice.io. In the request examples throughout this documentation, we use placeholder variables {appbaseurl} to refer to the lexoffice application url, {resourceurl} to refer to the resource urls of the lexoffice API endpoints and {accessToken} to refer to the API key. We also use access token and API key interchangeably.

Contacts Endpoint

Purpose

This endpoint provides read access to contacts (e.g. customers, vendors). A contact can hold addresses, contact information (e.g. phone numbers, email addresses) and contact persons for company related contacts. It is also possible to use filters on the contacts collection.

Contact Properties

Sample of a contact with roles customer and vendor

{
  "id": "be9475f4-ef80-442b-8ab9-3ab8b1a2aeb9",
  "organizationId": "612f56c7-4e92-4124-9e1f-4ed2b48e3e50",
  "version": 1,
  "roles": {
    "customer": {
      "number": 10307
    },
    "vendor": {
      "number": 70303
    }
  },
  "company": {
    "name": "Testfirma",
    "taxNumber": "12345/12345",
    "vatRegistrationId": "DE123456789",
    "allowTaxFreeInvoices": true,
    "contactPersons": [
      {
        "salutation": "Herr",
        "firstName": "Max",
        "lastName": "Mustermann",
        "emailAddress": "contactpersonmail@lexoffice.de",
        "phoneNumber": "08000/11111"
      }
    ]
  },
  "addresses": {
    "billing": [
      {
        "supplement": "Rechnungsadressenzusatz",
        "street": "Hauptstr. 5",
        "zip": "12345",
        "city": "Musterort",
        "countryCode": "DE"
      }
    ],
    "shipping": [
      {
        "supplement": "Lieferadressenzusatz",
        "street": "Schulstr. 13",
        "zip": "76543",
        "city": "MUsterstadt",
        "countryCode": "DE"
      }
    ]
  },
  "emailAddresses": {
    "business": [
      "business@lexoffice.de"
    ],
    "office": [
      "office@lexoffice.de"
    ],
    "private": [
      "private@lexoffice.de"
    ],
    "other": [
      "other@lexoffice.de"
    ]
  },
  "phoneNumbers": {
    "business": [
      "08000/1231"
    ],
    "office": [
      "08000/1232"
    ],
    "mobile": [
      "08000/1233"
    ],
    "private": [
      "08000/1234"
    ],
    "fax": [
      "08000/1235"
    ],
    "other": [
      "08000/1236"
    ]
  },
  "note": "Notizen",
  "archived": false
}
                    Property Description
id
uuid
Unique id of the contact generated on creation by lexoffice.
organizationId
uuid
Unique id of the organization the contact belongs to.
version
integer
Version (revision) number which will be increased on each change to handle optimistic locking.
Read-only.
roles
object
Defines contact roles and supports further contact information. For object details see below.
company
object
Company related information. For details see below.
person
object
Individual person related information. For details see below.
addresses
object
Addresses (e.g. billing and shipping address(es)) for the contact. Contains a list for each address type. For details see below.
emailAddresses
object
Email addresses for the contact. Contains a list for each EMail type. For details see below.
phoneNumbers
object
Phone numbers for the contact. Contains a list for each PhoneNumber type. For details see below.
note
string
A note to the contact. This is just an additional information.
archived
boolean
Archived flag of the contact.
Read-only.

Roles Details

Contains a customer and/or a vendor object. The presence of a role in the JSON implies that the contact will have this role. For example, if the customer object is present, the contact has the role customer. Please note that each contact must have at least one role.

                    Property Description
customer
object
May be present. If present the created contact has the role customer.
vendor
object
May be present. If present the created contact has the role vendor.

Customer Details

                    Property Description
number
integer
Unique customer number within the current organization. This number is created by lexoffice for contacts with role Customer.

Vendor Details

                    Property Description
number
integer
Unique vendor number within the current organization. This number is created by lexoffice for contacts with role Vendor.



Company Details

Use this object to provide information for a contact of type company.

                    Property Description
allowTaxFreeInvoices
boolean
Possible values are true or false.
name
string
Company name
taxNumber
string
Tax number for this company --> "Steuernummer".
vatRegistrationId
string
Vat registration id for this company. This id has to follow the german rules for the vat registration ids --> "Umsatzsteuer ID".
contactPersons
list
A list of company contact persons. Each entry is an object of company contact person. Details of nested object please see below.

Company Contact Person Details

                    Property Description
salutation
enum
Salutation for the contact person. Possible values are Herr and Frau.
firstName
string
First name of the contact person.
lastName
string
Last name of the contact person.
emailAddress
string
Email address of the contact person.
phoneNumber
string
Phone number of the contact person.



Person Details

Sample json for a contact of type private person

{
  "id": "e9066f04-8cc7-4616-93f8-ac9ecc8479c8",
  "organizationId": "612f56c7-4e92-4124-9e1f-4ed2b48e3e50",
  "version": 0,
  "roles": {
    "customer": {
      "number": 10308
    }
  },
  "person": {
    "salutation": "Frau",
    "firstName": "Inge",
    "lastName": "Musterfrau"
  },
  "archived": false
}

Use this object to provide information for a contact of type private person.

                    Property Description
salutation
enum
Salutation for the individual person. Possible values are Herr and Frau.
firstName
string
First name of the person.
lastName
string
Last name of the person.



Addresses Details

Use this objects to provide billing and shipping information of a contact.

                    Property Description
billing
list
A list of billing addresses. Each entry is an object of address.
shipping
list
A list of shipping addresses. Each entry is an object of address.

Address Details

                    Property Description
supplement
string
Additional address information.
street
string
Street with Street number.
zip
string
Zip code
city
string
City
countryCode
string
Country code in the format of ISO 3166 alpha2 (e.g. DE is used for germany).



E-Mail Addresses Details

                    Property Description
business
list
A list of email addresses. Each entry is of type string and contains an email address.
office
list
A list of email addresses. Each entry is of type string and contains an email address.
private
list
A list of email addresses. Each entry is of type string and contains an email address.
other
list
A list of email addresses. Each entry is of type string and contains an email address.



Phone Numbers Details

                    Property Description
business
list
A list of phone numbers. Each entry is of type string and contains a phone number.
office
list
A list of phone numbers. Each entry is of type string and contains a phone number.
mobile
list
A list of phone numbers. Each entry is of type string and contains a phone number.
private
list
A list of phone numbers. Each entry is of type string and contains a phone number.
fax
list
A list of phone numbers. Each entry is of type string and contains a phone number.
other
list
A list of phone numbers. Each entry is of type string and contains a phone number.

Create a Contact

Sample Request to create a customer

curl https://api.lexoffice.io/v1/contacts
-X POST
-H "Authorization: Bearer {accessToken}"
-H "Content-Type: application/json"
-H "Accept: application/json"
-d '
{
  "version": 0,
  "roles": {
    "customer": {
    }
  },
  "person": {
     "salutation": "Frau",
     "firstName": "Inge",
     "lastName": "Musterfrau"
  },
  "note": "Notizen"
}'

Sample response

{
  "id": "66196c43-baf3-4335-bfee-d610367059db",
  "resourceUri": "https://api.lexoffice.io/v1/contacts/66196c43-bfee-baf3-4335-d610367059db",
  "createdDate": "2016-06-29T15:15:09.447+02:00",
  "updatedDate": "2016-06-29T15:15:09.447+02:00",
  "version": 1
}

POST {resourceurl}/v1/contacts

The contents of the contact are expected in the request’s body as an application/json.

Description of required properties when creating a customer.

                    Property Required Notes
version Yes Set to 0
roles Yes Each customer must have at least one role.
company * If the contact is of type company it must be set.
person * If the contact is of type person it must be set.

Company Details

                    Property Required Notes
name Yes Must not be empty if customer is of type company.

Company Contact Person Details

                    Property Required Notes
salutation Yes Must be set to Herr or Frau if customer is of type company.
lastName Yes Must be not empty if customer is of type company.

Person Details

                    Property Required Notes
salutation Yes Must be set to Herr or Frau if customer is of type person.
lastName Yes Must be not empty if customer is of type person.

Address Details

                    Property Required Notes
countryCode Yes Must be not empty. Must contain the country code in the format of ISO 3166 alpha2 (e.g. DE is used for germany).

Retrieve a Contact

Sample request

curl https://api.lexoffice.io/v1/contacts/e9066f04-8cc7-4616-93f8-ac9ecc8479c8
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample response

{
  "id": "e9066f04-8cc7-4616-93f8-ac9ecc8479c8",
  "organizationId": "612f56c7-4e92-4124-9e1f-4ed2b48e3e50",
  "version": 0,
  "roles": {
    "customer": {
      "number": 10308
    }
  },
  "person": {
    "salutation": "Frau",
    "firstName": "Inge",
    "lastName": "Musterfrau"
  },
  "note": "Notizen",
  "archived": false
}

GET {resourceurl}/v1/contacts/{id}

Returns the contact with id value {id}.

Update a Contact

PUT {resourceurl}/v1/contacts/{id}

Update an existing contact with id {id} with the data given in the payload as JSON. Returns an action result on success.

For information about required fields please see Create a contact.

Filtering Contacts

GET {resourceurl}/v1/contacts?filter_1=value_1&...&filter_n=value_n

Sample request for retrieveng all contacts

curl https://api.lexoffice.io/v1/contacts/?page=0
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample response

{
  "content": [
  {
    "id": "e9066f04-8cc7-4616-93f8-ac9ecc8479c8",
    "organizationId": "612f56c7-4e92-4124-9e1f-4ed2b48e3e50",
    "version": 0,
    "roles": {
      "customer": {
        "number": 10308
      }
    },
    "person": {
      "salutation": "Frau",
      "firstName": "Inge",
      "lastName": "Musterfrau"
    },
    "archived": false
  },
  {
    "id": "313ef116-a432-4823-9dfe-1b1200eb458a",
    "organizationId": "612f56c7-4e92-4124-9e1f-4ed2b48e3e50",
    "version": 0,
    "roles": {
      "customer": {
        "number": 10309
      }
    },
    "person": {
      "salutation": "Herr",
      "firstName": "Max",
      "lastName": "Mustermann"
    },
    "archived": true
  }
],
"totalPages": 1,
"totalElements": 2,
"last": true,
"sort": [
  {
    "direction": "ASC",
    "property": "name",
    "ignoreCase": false,
    "nullHandling": "NATIVE",
    "ascending": true
  }
],
"size": 25,
"number": 0,
"first": true,
"numberOfElements": 2
}

Sample request for a filter with email max@gmx.de and name Mustermann:

curl https://api.lexoffice.io/v1/contacts/?email=max@gmx.de&name=Mustermann
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample call Filter only vendor contacts:

curl https://api.lexoffice.io/v1/contacts/?vendor=true&customer=false
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Returns the contacts that fulfill the criteria given by filters filter_1 to filter_n using a paging mechanism. If more than one filter is given, the logical connector is AND. Filters that are not set are ignored.

Note that a filter should not be present more than once in a request.

The following table describes the possible filter parameters.

Parameter Description
email
string
filters contacts where any of their email addresses inside the emailAddresses JSON object match the given email value. At least 3 characters are necessary to successfully complete the query.
name
string
filters contacts whose name matches the given name value. At least 3 characters are necessary to successfully complete the query.
number
integer
returns the contacts with the specified contact number. Number is either the customer number or the vendor number located in the roles object.
customer
boolean
if set to true filters contacts that have the role customer. If set to false filters contacts that do not have the customer role.
vendor
boolean
if set to true filters contacts that have the role vendor. If set to false filters contacts that do not have the vendor role.

Credit Notes Endpoint

Purpose

With a credit note the partial or full amount of an invoice can be refunded to a customer.

At the moment, credit notes can be created without any reference to an invoice. To refer a credit note to an invoice on the printed document, the invoice number can be included in the header text (introduction).

It is possible to create credit notes of type net, gross, vatfree ("Steuerfrei"), intra-community supply ("Innergemeinschaftliche Lieferung gem. §13b UStG") and constructional services ("Bauleistungen gem. §13b UStG").

Other tax types such as external services ("Fremdleistungen innerhalb der EU gem. §13b UStG"), services to third party countries ("Nichtsteuerbare Dienstleistung an Drittländer") can only be read.

Credit Notes Properties

Sample of a credit note with multiple line items. Fields with no content are displayed with "null" just for demonstration purposes.

{
    "id": "e9066f04-8cc7-4616-93f8-ac9ecc8479c8",
    "organizationId": "a3d94eb4-98bc-429e-b7ad-17f1a8463af9",
    "createdDate": "2019-06-17T18:32:07.480+02:00",
    "updatedDate": "2019-06-17T18:32:07.551+02:00",
    "version": 1,
    "archived": false,
    "voucherStatus": "draft",
    "voucherNumber": "GS0007",
    "voucherDate": "2017-02-22T00:00:00.000+01:00",
    "address": {
        "name": "Bike & Ride GmbH & Co. KG",
        "supplement": "Gebäude 10",
        "street": "Musterstraße 42",
        "city": "Freiburg",
        "zip": "79112",
        "countryCode": "DE"
    },
    "lineItems": [
        {
            "type": "custom",
            "name": "Abus Kabelschloss Primo 590 ",
            "description": "· 9,5 mm starkes, smoke-mattes Spiralkabel mit integrierter Halterlösung zur Befestigung am Sattelklemmbolzen · bewährter Qualitäts-Schließzylinder mit praktischem Wendeschlüssel · KabelØ: 9,5 mm, Länge: 150 cm",
            "quantity": 2,
            "unitName": "Stück",
            "unitPrice": {
                "currency": "EUR",
                "netAmount": 13.4,
                "grossAmount": 15.946,
                "taxRatePercentage": 19
            },
            "lineItemAmount": 26.8
        },
        {
            "type": "custom",
            "name": "Energieriegel Testpaket",
            "quantity": 1,
            "unitName": "Stück",
            "unitPrice": {
                "currency": "EUR",
                "netAmount": 5,
                "grossAmount": 5,
                "taxRatePercentage": 0
            },
            "lineItemAmount": 5
        }
    ],
    "totalPrice": {
        "currency": "EUR",
        "totalNetAmount": 31.8,
        "totalGrossAmount": 36.89,
        "totalTaxAmount": 5.09
    },
    "taxAmounts": [
        {
            "taxRatePercentage": 0,
            "taxAmount": 0,
            "netAmount": 5
        },
        {
            "taxRatePercentage": 19,
            "taxAmount": 5.09,
            "netAmount": 26.8
        }
    ],
    "taxConditions": {
        "taxType": "net"
    },
    "introduction": "Rechnungskorrektur zur Rechnung RE-00020",
    "remark": "Folgende Lieferungen/Leistungen schreiben wir Ihnen gut.",
    "files": {
      "documentFileId": "a79fea19-a892-4ea9-89ad-e879946329a3"
    }
}
                    Property Description
id
uuid
Unique id generated on creation by lexoffice.
Read-only.
organizationId
uuid
Unique id of the organization the credit note belongs to.
Read-only.
createdDate
dateTime
The instant of time when the credit note was created by lexoffice in ISO 8601 format yyyy-MM-dd HH:mm:ss.mmm z (e.g. 2017-02-22T00:00:00.000+01:00).
Read-only.
updatedDate
dateTime
The instant of time when the credit note was updated by lexoffice in ISO 8601 format yyyy-MM-dd HH:mm:ss.mmm z (e.g. 2017-02-22T00:00:00.000+01:00).
Read-only.
version
integer
Version (revision) number which will be increased on each change to handle optimistic locking.
Read-only.
archived
boolean
Specifies if the credit note is only available in the archive in lexoffice.
Read-only.
voucherStatus
enum
Specifies the status of the credit note. Possible values are draft (editable later in lexoffice), open (finished and no longer editable but not yet paid off), paidoff (has been fully paid back to the customer), voided (cancelled)
Read-only.
voucherNumber
string
The specific number a credit note is aware of. This consecutive number is set by lexoffice on creation.
Read-only.
voucherDate
dateTime
The date of credit note in ISO 8601 format yyyy-MM-dd HH:mm:ss.mmm z (e.g. 2017-02-22T00:00:00.000+01:00).
address
object
The address of the credit note recipient. For details see below.
lineItems
list
The items of the credit note. For details see below.
totalPrice
object
The total price of the credit note. For details see below.
taxAmounts
list
The tax amounts for each tax rate. Please note: As done with every read-only element or object all submitted content (POST) will be ignored. For details see below.
Read-only.
taxConditions
object
The tax conditions of the credit note. For details see below.
introduction
string
(Optional) An introductory text / header. Recommended to include the invoice number in the header when the credit note is related to an invoice.
remark
string
(Optional) A closing text note.
files
object
The document id for the PDF version of the credit note. For details see below.
Read-only.

Address Details

There are two main options to address the recipient of a credit note. First, using an existing lexoffice contact or second creating a new address.

For referencing an existing contact it is only necessary to provide the UUID of that contact. Additionally, the referenced address can also be modified for this specific credit note. Therefore all required address fields must be set and the deviated address will not be stored back to the lexoffice contacts.

Otherwise, a new address for the credit note recipient can be created. That type of address is called a "one-time address". A one-time address will not create a new contact in lexoffice. For instance, this could be useful when it is not needed to create a contact in lexoffice for each new credit note.

Please get in touch with us if you are not sure which option fits your use case best.

                    Property Description
contactId
uuid
If the credit note recipient is (optionally) registered as a contact in lexoffice, this field specifies the related id of the contact.
name
string
The name of the credit note recipient. To use an existing contact of an individual person, provide the name in the format {firstname} {lastname}.
supplement
string
(Optional) An address supplement.
street
string
The street (street and street number) of the address.
city
string
The city of the address.
zip
string
The zip code of the address.
countryCode
enum
The ISO 3166 alpha2 country code of the address.

Line Items Details

                    Property Description
id
uuid
The field specifies the related id of the product/service.
Read-only.
type
enum
The type of the item. Possible values are service (the line item is related to a supply of services), material (the line item is related to a physical product), custom (an item without reference in lexoffice and has no id) or text (contains only a name and/or a description for informative purposes).
name
string
The name of the item.
description
string
The description of the item.
quantity
number
The amount of the purchased item. The value can contain up to 4 decimals.
unitName
string
The unit name of the purchased item. If the provided unit name is not known in lexoffice it will be created on the fly.
unitPrice
object
The unit price of the purchased item. For details see below.
lineItemAmount
number
The total price of this line item. Depending by the selected taxType in taxConditions, the amount must be given either as net or gross. The value can contain up to 2 decimals.
Read-only.

Unit Price Details

                    Property Description
currency
enum
The currency of the price. Currently only EUR is supported.
netAmount
number
The net price of the unit price. The value can contain up to 4 decimals.
grossAmount
number
The gross price of the unit price. The value can contain up to 4 decimals.
taxRatePercentage
number
The tax rate of the unit price. Supported tax rates are 0, 7, 19.

Total Price Details

                    Property Description
currency
string
The currency of the total price. Currently only EUR is supported.
totalNetAmount
number
The total net price over all line items. The value can contain up to 2 decimals.
Read-only.
totalGrossAmount
number
The total gross price over all line items. The value can contain up to 2 decimals.
Read-only.
totalTaxAmount
number
The total tax amount over all line items. The value can contain up to 2 decimals.
Read-only.
totalDiscountAbsolute
number
(Optional) A total discount as absolute value. The value can contain up to 2 decimals.
totalDiscountPercentage
number
(Optional) A total discount relative to the gross amount or net amount dependent on the given tax conditions. The value can contain up to 2 decimals.

Tax Amounts Details

                    Property Description
taxRatePercentage
number
The tax rate percentage. Supported tax rates are 0, 7, 19.
taxAmount
number
The total tax amount for this tax rate. The value can contain up to 2 decimals.
netAmount
number
The total net amount for this tax rate. The value can contain up to 2 decimals.

Tax Conditions Details

                    Property Description
taxType
enum
The tax type for the credit note. Possible values are net, gross, vatfree (without value added tax), intraCommunitySupply (Innergemeinschaftliche Lieferung gem. §13b UStG), constructionService13b (Bauleistungen gem. §13b UStG), externalService13b (Fremdleistungen innerhalb der EU gem. §13b UStG), thirdPartyCountryService (Nichtsteuerbare Dienstleistung an Drittländer), and thirdPartyCountryDelivery (Steuerfreie Ausfuhrlieferung)
taxTypeNote
string
When taxType is set to vatfree, intraCommunitySupply, constructionService13b, externalService13b, thirdPartyCountryService, or thirdPartyCountryDelivery, it is possible to add a note regarding the tax type.

Files Details

                    Property Description
documentFileId
uuid
The id of the credit note PDF. The PDF will be created when the credit note turns from draft into status open or paidoff. To download the credit note PDF file please use the files endpoint.

Create a Credit Note

Sample Request to create a credit note

curl https://api.lexoffice.io/v1/credit-notes
-X POST
-H "Authorization: Bearer {accessToken}"
-H "Content-Type: application/json"
-H "Accept: application/json"
-d '
{
  "archived": false,
  "voucherDate": "2017-02-22T00:00:00.000+01:00",
  "address": {
    "name": "Bike & Ride GmbH & Co. KG",
    "supplement": "Gebäude 10",
    "street": "Musterstraße 42",
    "city": "Freiburg",
    "zip": "79112",
    "countryCode": "DE"
  },
  "lineItems": [
    {
      "id": "97b98491-e953-4dc9-97a9-ae437a8052b4",
      "type": "material",
      "name": "Abus Kabelschloss Primo 590 ",
      "description": "· 9,5 mm starkes, smoke-mattes Spiralkabel mit integrierter Halterlösung zur Befestigung am Sattelklemmbolzen · bewährter Qualitäts-Schließzylinder mit praktischem Wendeschlüssel · KabelØ: 9,5 mm, Länge: 150 cm",
      "quantity": 2,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 13.4,
        "taxRatePercentage": 19
      }
    },
    {
      "type": "custom",
      "name": "Energieriegel Testpaket",
      "quantity": 1,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 5,
        "taxRatePercentage": 0
      }
    }
  ],
  "totalPrice": {
    "currency": "EUR"
   },
  "taxConditions": {
    "taxType": "net"
  },
  "introduction": "Rechnungskorrektur zur Rechnung RE-00020",
  "remark": "Folgende Lieferungen/Leistungen schreiben wir Ihnen gut."
}
'

Sample response

{
  "id": "e9066f04-8cc7-4616-93f8-ac9ecc8479c8",
  "resourceUri": "https://api.lexoffice.io/v1/credit-notes/e9066f04-8cc7-4616-93f8-ac9ecc8479c8",
  "createdDate": "2019-06-17T18:32:07.480+02:00",
  "updatedDate": "2019-06-17T18:32:07.551+02:00",
  "version": 1
}

POST {resourceurl}/v1/credit-notes[?finalize=true]

Credit notes transmitted via the API are created in draft mode per default. To create a finalized credit note with status open the optional query parameter finalized has to be set. The status of a credit note cannot be changed via the api.

The created credit note will be shown in the main voucher list in lexoffice: https://app.lexoffice.de/vouchers. To provide your customers access to the created credit note please use our deeplink function.

The contents of the credit note are expected in the request's body as an application/json and must not contain read-only fields.

Description of required properties when creating a credit note.

                    Property Required Notes
voucherDate Yes
address Yes Nested object. Required fields for address please see below.
lineItems Yes List of nested objects. Required fields for lineItems please see below.
totalPrice Yes Nested object. Required fields for totalPrice please see below.
taxConditions Yes Nested object. Required fields for taxConditions see below.

Address Required Properties

Description of required address properties when creating a credit note.

                    Property Required Notes
contactId * Only when referencing an existing lexoffice contact.
name * Only required when no existing contact is referenced.
countryCode * Only required when no existing contact is referenced.

Line Items Required Properties

Description of required lineItem properties when creating a credit note. At this point only line items of type "custom" are supported.

                    Property Required Notes
type Yes Currently the only possible value is custom.
name Yes
quantity Yes
unitName Yes
unitPrice Yes Nested object. Required fields for unitPrice see below.

Unit Price Required Properties

Description of required unitPrice properties when creating a credit note.

                    Property Required Notes
currency Yes
netAmount * Only relevant if taxConditions.taxType != gross is delivered.
grossAmount * Only relevant if taxConditions.taxType == gross is delivered.
taxRatePercentage Yes

Total Price Required Properties

Description of required totalPrice properties when creating a credit note.

                    Property Required Notes
currency Yes

Tax Condition Required Properties

Description of required tax condition properties when creating a credit note.

                    Property Required Notes
taxType Yes Supported values are gross, net, vatfree, intraCommunitySupply and constructionService13b.

Retrieve a Credit Note

Sample request

curl https://api.lexoffice.io/v1/credit-notes/e9066f04-8cc7-4616-93f8-ac9ecc8479c8
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample response


{
    "id": "e9066f04-8cc7-4616-93f8-ac9ecc8479c8",
    "organizationId": "a3d94eb4-98bc-429e-b7ad-17f1a8463af9",
    "createdDate": "2019-06-17T18:32:07.480+02:00",
    "updatedDate": "2019-06-17T18:32:07.551+02:00",
    "version": 1,
    "archived": false,
    "voucherStatus": "draft",
    "voucherNumber": "GS0007",
    "voucherDate": "2017-02-22T00:00:00.000+01:00",
    "address": {
        "name": "Bike & Ride GmbH & Co. KG",
        "supplement": "Gebäude 10",
        "street": "Musterstraße 42",
        "city": "Freiburg",
        "zip": "79112",
        "countryCode": "DE"
    },
    "lineItems": [
        {
            "type": "custom",
            "name": "Abus Kabelschloss Primo 590 ",
            "description": "· 9,5 mm starkes, smoke-mattes Spiralkabel mit integrierter Halterlösung zur Befestigung am Sattelklemmbolzen · bewährter Qualitäts-Schließzylinder mit praktischem Wendeschlüssel · KabelØ: 9,5 mm, Länge: 150 cm",
            "quantity": 2,
            "unitName": "Stück",
            "unitPrice": {
                "currency": "EUR",
                "netAmount": 13.4,
                "grossAmount": 15.946,
                "taxRatePercentage": 19
            },
            "lineItemAmount": 26.8
        },
        {
            "type": "custom",
            "name": "Energieriegel Testpaket",
            "quantity": 1,
            "unitName": "Stück",
            "unitPrice": {
                "currency": "EUR",
                "netAmount": 5,
                "grossAmount": 5,
                "taxRatePercentage": 0
            },
            "lineItemAmount": 5
        }
    ],
    "totalPrice": {
        "currency": "EUR",
        "totalNetAmount": 31.8,
        "totalGrossAmount": 36.89,
        "totalTaxAmount": 5.09
    },
    "taxAmounts": [
        {
            "taxRatePercentage": 0,
            "taxAmount": 0,
            "netAmount": 5
        },
        {
            "taxRatePercentage": 19,
            "taxAmount": 5.09,
            "netAmount": 26.8
        }
    ],
    "taxConditions": {
        "taxType": "net"
    },
    "introduction": "Rechnungskorrektur zur Rechnung RE-00020",
    "remark": "Folgende Lieferungen/Leistungen schreiben wir Ihnen gut."
}

GET {resourceurl}/v1/credit-notes/{id}

Returns the credit note with id value {id}.

Render a Credit Note Document (PDF)

Sample request

curl https://api.lexoffice.io/v1/credit-notes/e9066f04-8cc7-4616-93f8-ac9ecc8479c8/document
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample response

{
  "documentFileId": "b26e1d73-19ff-46b1-8929-09d8d73d4167"
}

GET {resourceurl}/v1/credit-notes/{id}/document

To download the pdf file of a credit note document, you need its documentFileId. This id is usually returned by the credit note resource. However, newly created credit notes in status open via the API have to trigger the pdf document file rendering separately. This can be done with this endpoint.

The returned documentFileId can be used to download the credit note pdf document via the (Files Endpoint).

Credit notes can be directly accessed by permanent HTTPS links to either be viewed or to be edited. If a credit note is not allowed to be edited, a redirection to the view page takes place. In case the given id does not exist, a redirection to the main voucher list takes place.

View URL {appbaseurl}/permalink/credit-notes/view/{id}

Edit URL {appbaseurl}/permalink/credit-notes/edit/{id}

Event Subscriptions Endpoint

Purpose

Using event subscriptions you will be notified about certain events on resources - e.g. you receive a notification every time a contact changes in lexoffice. This will make pull requests superfluous to keep your data synced between lexoffice and your application. The notifications are implemented as webhooks. Subscribing to an event simply requires the event type and your callback url. With the event-subscriptions endpoint you can manage your subscriptions within lexoffice.

Event Subscriptions Properties

Sample of an created event subscription.

{
  "subscriptionId": "4d43ad14-671d-4e0c-fd4b-2fd8cc117eff",
  "organizationId": "612f56c7-4e92-4124-9e1f-4ed2b48e3e50",
  "createdDate": "2018-04-11T12:15:00.000+02:00",
  "eventType": "contact.changed",
  "callbackUrl": "https://example.org/webhook"
}
                    Property Description
subscriptionId
uuid
Unique id of the event subscription generated on creation by lexoffice.
Read-only.
organizationId
uuid
Unique id of the organization the event subscription belongs to.
Read-only.
createdDate
dateTime
The instant of time when the event subscription was created by lexoffice in ISO 8601 format yyyy-MM-dd HH:mm:ss.mmm z (e.g. 2017-02-22T00:00:00.000+01:00).
Read-only.
eventType
string
The event type is a combined key which defines the resource and its event name you are subscribing to. All available events receivable via the API can be taken from the table Event Types.
callbackUrl
string
When a resource entity triggers an event, the callback url is used to notify the subscriber about it. The payload of the callback is described in Webhook Callback Properties.

Event Types

The following table lists all types of events you can subscribe to. The property EventType is the combined key of a resource and a event name. The EventType is handled in lower case.

Resource Event type Description
contacts contact.created A new contact was created in lexoffice.
contacts contact.changed A lexoffice contact has changed. You should get the updated contact details.
contacts contact.deleted A lexoffice contact was deleted. Depending on your application, you should unlink the lexoffice contact on your site or delete it as well.
credit-notes credit-note.created A new credit note was created in lexoffice. Get the new credit note by calling the credit notes endpoint.
credit-notes credit-note.changed A credit note has changed. Get the updated credit note by calling the credit notes endpoint. Please note that the status may also have changed.
credit-notes credit-note.deleted A credit note was deleted in lexoffice.
credit-notes credit-note.status.changed The status of a credit note has changed. Update the credit note by calling the credit notes endpoint to retrieve the new status.
invoices invoice.created A new invoice was created in lexoffice. Get the new invoice by calling the invoices endpoint.
invoices invoice.changed An invoice has changed. Get the updated invoice by calling the invoices endpoint. Please note that the status may also have changed.
invoices invoice.deleted An invoice was deleted in lexoffice.
invoices invoice.status.changed The status of an invoice has changed. Update the invoice by calling the invoices endpoint to retrieve the new status.
revoke token.revoked The refresh token was revoked, hence is invalid. The resourceId in the webhook callback refers to the connectionId you retrieve using the profile endpoint. Please store the refresh token to the connectionId prior to the registration on this event.

Webhook Callback Properties

Sample payload from a webhook callback of an event subscription.

{
  "organizationId": "612f56c7-4e92-4124-9e1f-4ed2b48e3e50",
  "eventType": "contact.changed",
  "resourceId": "4d43ad14-671d-4e0c-fd4b-2fd8cc117eff",
  "eventDate": "2018-04-11T12:30:00.000+02:00"
}

Subscribed events will send a POST request to your given webhook url and contain the following JSON payload.

                    Property Description
organizationId
uuid
The organization for which an event has been triggered.
eventType
string
Describes the occurred event. The eventType describes the resource and the event name.
resourceId
uuid
The resource entity on which the event has occurred. Use the corresponding resource endpoint and the resourceId to get the latest data of the resource entity.
eventDate
dateTime
The instant of time when the event was triggered in ISO 8601 format yyyy-MM-dd HH:mm:ss.mmm z (e.g. 2017-02-22T00:00:00.000+01:00).
Read-only.

Verify Authenticity

For verification that the webhook call was sent from lexoffice, every webhook contains an RSA-SHA512 encrypted signature of the JSON request body (without whitespaces and linebreaks) in a base64 encoded header called X-Lxo-Signature. To verify it, please use this public key.

Example signature verification with OpenSSL

Sample Signature Verification with OpenSSL

openssl dgst -sha512 -verify public_key.pub -signature sample_signature_decoded sample_payload.json

The signature can be verified using openssl. With the public key, a sample payload and the decoded signature, openssl can be used to verify the signature. It should print Verified OK.

Sample decoding of base64 encoded signature

openssl base64 -d -in sample_signature_base64 -out  signature_decoded

The signature from the X-Lxo-Signature header is base64 encoded and needs to be decoded before calling the former command. For this example, this is the sample base64 encoded signature.

Create an Event Subscription

Sample Request to create an event subscription

curl https://api.lexoffice.io/v1/event-subscriptions
-X POST
-H "Authorization: Bearer {accessToken}"
-H "Content-Type: application/json"
-H "Accept: application/json"
-d '
{
    "eventType": "contact.changed",
    "callbackUrl": "https://example.org/webhook"
}'

Sample response

{
    "id": "49aa2f76-c51a-4df3-ae83-3a103d781494",
    "resourceUri": "https://api.lexoffice.io/v1/event-subscriptions/49aa2f76-c51a-4df3-ae83-3a103d781494",
    "createdDate": "2018-04-11T12:20:00.000+02:00",
    "updatedDate": "2018-04-11T12:20:00.000+02:00",
    "version": 0
}

POST {resourceurl}/v1/event-subscriptions

To subscribe to an event, provide the event type and the webhook callback url in the request body. The endpoint returns an action result (HTTP status code 201 Created) on success.

                    Property Required Notes
eventType Yes The name of the event usually a combined key containing the resource and the event name.
callbackUrl Yes Your webhook HTTPS url where you will be notified on events. A HEAD request will be sent to the given URL to determine if SSL certificates are correct. If this fails the endpoint returns a 406 HTTP status code.

Retrieve an Event Subscription

Sample request to retrieve all event subscriptions

curl https://api.lexoffice.io/v1/event-subscriptions/49aa2f76-c51a-4df3-ae83-3a103d781494
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample response

{
    "subscriptionId": "49aa2f76-c51a-4df3-ae83-3a103d781494",
    "organizationId": "612f56c7-4e92-4124-9e1f-4ed2b48e3e50",
    "createdDate": "2018-04-11T12:20:00.000+02:00",
    "eventType": "contact.changed",
    "callbackUrl": "https://example.org/webhook"
}

GET {resourceurl}/v1/event-subscriptions/{subscriptionId}

Returns the event subscription with the id {subscriptionId}.

Retrieve all Event Subscriptions

Sample Request to retrieve all event subscriptions

curl https://api.lexoffice.io/v1/event-subscriptions
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample response

{
    "content": [
        {
            "subscriptionId": "49aa2f76-c51a-4df3-ae83-3a103d781494",
            "organizationId": "612f56c7-4e92-4124-9e1f-4ed2b48e3e50",
            "createdDate": "2018-04-11T12:20:00.000+02:00",
            "eventType": "contact.changed",
            "callbackUrl": "https://example.org/webhook"
        }
    ]
}

GET {resourceurl}/v1/event-subscriptions

Returns all your event subscriptions.

Delete an Event Subscription

Sample Request to delete an event subscription

curl https://api.lexoffice.io/v1/event-subscriptions/49aa2f76-c51a-4df3-ae83-3a103d781494
-X DELETE
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

DELETE {resourceurl}/v1/event-subscriptions/{subscriptionId}

Deletes an event subscription with the id {subscriptionId}. On success, you will receive a status code 204 (No Content).

Files Endpoint

Purpose

Use this endpoint to upload and/or download files, e.g. vouchers or invoices.

Upon a successful upload, the uploaded voucher image will be shown in the image selection dialog.

Response codes and error handling: With the following links you can find further HTTP Status Codes and Error Codes.

Upload a file

POST {resourceurl}/v1/files

Sample Request file upload

curl https://api.lexoffice.io/v1/files
-X POST
-H "Authorization: Bearer {accessToken}"
-H "Content-Type: multipart/form-data"
-H "Accept: application/json"
-F "file=@{PathToImage}" -F "type=voucher"

To upload a file set the type of the upload file. At the moment only the type voucher is supported. This parameter is to be included as a form with name = type and value = voucher.

Allowed file formats for files of type "voucher" are:

Set Content-Type to multipart/form-data.

Sample Response

{
  "id": "8118c402-1c70-4da1-a9f1-a22f480cc623"
}

On success, a HTTP status 202 Accepted is returned with a response containing the id, that is used on the call to the status.

If the upload type type is not provided or is not valid, a HTTP status 400 Bad Request will be returned. If no file is provided, the file upload endpoint returns HTTP status 500.

Download a file

GET {resourceurl}/v1/files/{id}[?renderType={value}]

Sample request file download

curl "https://api.lexoffice.io/v1/files/{id}"
-X GET
-H "Authorization: Bearer {accessToken}"

Returns the binary file with id value {id}. The HTTP header field Content-Type specifies the file type (MIME type), whereas the HTTP header field Content-Length indicates the size of the file in bytes.

Optional Download Parameters

For some file resources different download options are possible via query string parameter.

                 Parameter Name Description
renderType
string
Render Type Only usable if the file is related to an invoice resource.
Enables to download the invoice pdf files with other predefined printing options. Possible values are: factoring (without letter paper and bank details).

Newly uploaded and unassigned files in lexoffice can be accessed via the following deeplink for further processing by the user, e.g. creating a voucher.

View URL {appbaseurl}/permalink/files/view

Invoices Endpoint

Purpose

At the moment, it is possible to create invoices of type net, gross, vatfree (Steuerfrei), intra-community supply (Innergemeinschaftliche Lieferung gem. §13b UStG) and constructional services (Bauleistungen gem. §13b UStG).

The creation of invoices with type external Services (Fremdleistungen innerhalb der EU gem. §13b UStG), services to third party countries (Nichtsteuerbare Dienstleistung an Drittländer) and invoices for down payment (Abschlagsrechnung) are not supported via the API at the moment.

However, it is possible to retrieve such of type net, gross, vatfree, intra-community supply, constructional services, external services, and services to third party countries.

Invoices Properties

Sample of an invoice with multiple line items. Fields with no content are displayed with "null" just for demonstration purposes.

{
  "id": "e9066f04-8cc7-4616-93f8-ac9ecc8479c8",
  "organizationId": "a3d94eb4-98bc-429e-b7ad-17f1a8463af9",
  "createdDate": "2017-04-24T08:20:22.528+02:00",
  "updatedDate": "2017-04-24T08:20:22.528+02:00",
  "version": 0,
  "archived": false,
  "voucherStatus": "draft",
  "voucherNumber": "RE1019",
  "voucherDate": "2017-02-22T00:00:00.000+01:00",
  "address": {
    "contactId": null,
    "name": "Bike & Ride GmbH & Co. KG",
    "supplement": "Gebäude 10",
    "street": "Musterstraße 42",
    "city": "Freiburg",
    "zip": "79112",
    "countryCode": "DE"
  },
  "lineItems": [
    {
      "id": null,
      "type": "material",
      "name": "Abus Kabelschloss Primo 590 ",
      "description": "· 9,5 mm starkes, smoke-mattes Spiralkabel mit integrierter Halterlösung zur Befestigung am Sattelklemmbolzen · bewährter Qualitäts-Schließzylinder mit praktischem Wendeschlüssel · KabelØ: 9,5 mm, Länge: 150 cm",
      "quantity": 2,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 13.4,
        "grossAmount": 15.95,
        "taxRatePercentage": 19
      },
      "discountPercentage": 50,
      "lineItemAmount": 13.4
    },
    {
      "id": null,
      "type": "service",
      "name": "Aufwändige Montage",
      "description": "Aufwand für arbeitsintensive Montagetätigkeit",
      "quantity": 1,
      "unitName": "Stunde",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 8.32,
        "grossAmount": 8.9,
        "taxRatePercentage": 7
      },
      "discountPercentage": 0,
      "lineItemAmount": 8.32
    },
    {
      "id": null,
      "type": "custom",
      "name": "Energieriegel Testpaket",
      "description": null,
      "quantity": 1,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 5,
        "grossAmount": 5,
        "taxRatePercentage": 0
      },
      "discountPercentage": 0,
      "lineItemAmount": 5
    },
    {
      "type": "text",
      "name": "Freitextposition",
      "description": "This item type can contain either a name or a description or both."
    }
  ],
  "totalPrice": {
    "currency": "EUR",
    "totalNetAmount": 26.72,
    "totalGrossAmount": 29.85,
    "totalTaxAmount": 3.13,
    "totalDiscountAbsolute": null,
    "totalDiscountPercentage": null
  },
  "taxAmounts": [
    {
      "taxRatePercentage": 0,
      "taxAmount": 0,
      "netAmount": 5
    },
    {
      "taxRatePercentage": 7,
      "taxAmount": 0.58,
      "netAmount": 8.32
    },
    {
      "taxRatePercentage": 19,
      "taxAmount": 2.55,
      "netAmount": 13.4
    }
  ],
  "taxConditions": {
    "taxType": "net",
    "taxTypeNote": null
  },
  "paymentConditions": {
    "paymentTermLabel": "10 Tage - 3 %, 30 Tage netto",
    "paymentTermDuration": 30,
    "paymentDiscountConditions": {
      "discountPercentage": 3,
      "discountRange": 10
    }
  },
  "shippingConditions": {
    "shippingDate": "2017-04-22T00:00:00.000+02:00",
    "shippingEndDate": null,
    "shippingType": "delivery"
  },
  "introduction": "Ihre bestellten Positionen stellen wir Ihnen hiermit in Rechnung",
  "remark": "Vielen Dank für Ihren Einkauf",
  "files": {
    "documentFileId": "75295db7-7e69-4630-befd-a7f4ddfdaa83"
  }
}
                    Property Description
id
uuid
Unique id generated on creation by lexoffice.
Read-only.
organizationId
uuid
Unique id of the organization the invoice belongs to.
Read-only.
createdDate
dateTime
The instant of time when the invoice was created by lexoffice in ISO 8601 format yyyy-MM-dd HH:mm:ss.mmm z (e.g. 2017-02-22T00:00:00.000+01:00).
Read-only.
updatedDate
dateTime
The instant of time when the invoice was updated by lexoffice in ISO 8601 format yyyy-MM-dd HH:mm:ss.mmm z (e.g. 2017-02-22T00:00:00.000+01:00).
Read-only.
version
integer
Version (revision) number which will be increased on each change to handle optimistic locking.
Read-only.
archived
boolean
Specifies if the invoice is only available in the archive in lexoffice.
Read-only.
voucherStatus
enum
Specifies the status of the invoice. Possible values are draft (editable later in lexoffice), open (finished and no longer editable but yet unpaid or only partially paid), paid (has been fully paid), voided (cancelled)
Read-only.
voucherNumber
string
The specific number an invoice is aware of. This consecutive number is set by lexoffice on creation.
Read-only.
voucherDate
dateTime
The date of invoice in ISO 8601 format yyyy-MM-dd HH:mm:ss.mmm z (e.g. 2017-02-22T00:00:00.000+01:00).
dueDate
dateTime
Sets the date on which the invoice is payable before becoming overdue. ISO 8601 format yyyy-MM-dd HH:mm:ss.mmm z (e.g. 2017-02-22T00:00:00.000+01:00).
Read-only.
address
object
The address of the invoice recipient. For details see below.
lineItems
list
The items of the invoice. For details see below.
totalPrice
object
The total price of the invoice. For details see below.
taxAmounts
list
The tax amounts for each tax rate. Please note: As done with every read-only element or object all submitted content (POST) will be ignored. For details see below.
Read-only.
taxConditions
object
The tax conditions of the invoice. For details see below.
paymentConditions
object
The payment conditions of the invoice. For details see below.
shippingConditions
object
The shipping conditions of the invoice. For details see below.
introduction
string
(Optional) An introductory text / header.
remark
string
(Optional) A closing text note.
files
object
The document id for the PDF version of the invoice. For details see below.
Read-only.

Address Details

There are two main options to address the recipient of an invoice. First, using an existing lexoffice contact or second creating a new address.

For referencing an existing contact it is only necessary to provide the UUID of that contact. Additionally, the referenced address can also be modified for this specific invoice. Therefore all required address fields must be set and the deviated address will not be stored back to the lexoffice contacts.

Otherwise, a new address for the invoice recipient can be created. That type of address is called a "one-time address". A one-time address will not create a new contact in lexoffice. For instance, this could be useful when it is not needed to create a contact in lexoffice for each new invoice.

Please get in touch with us if you are not sure which option fits your use case best.

                    Property Description
contactId
uuid
If the invoice recipient is (optionally) registered as a contact in lexoffice, this field specifies the related id of the contact.
name
string
The name of the invoice recipient. To use an existing contact of an individual person, provide the name in the format {firstname} {lastname}.
supplement
string
(Optional) An address supplement.
street
string
The street (street and street number) of the address.
city
string
The city of the address.
zip
string
The zip code of the address.
countryCode
enum
The ISO 3166 alpha2 country code of the address.

Line Items Details

                    Property Description
id
uuid
The field specifies the related id of the product/service.
Read-only.
type
enum
The type of the item. Possible values are service (the line item is related to a supply of services), material (the line item is related to a physical product), custom (an item without reference in lexoffice and has no id) or text (contains only a name and/or a description for informative purposes).
name
string
The name of the item.
description
string
The description of the item.
quantity
number
The amount of the purchased item. The value can contain up to 4 decimals.
unitName
string
The unit name of the purchased item. If the provided unit name is not known in lexoffice it will be created on the fly.
unitPrice
object
The unit price of the purchased item. For details see below.
discountPercentage
number
The offered discount for the item. The value can contain up to 2 decimals.
lineItemAmount
number
The total price of this line item. Depending by the selected taxType in taxConditions, the amount must be given either as net or gross. The value can contain up to 2 decimals.
Read-only.

Unit Price Details

                    Property Description
currency
enum
The currency of the price. Currently only EUR is supported.
netAmount
number
The net price of the unit price. The value can contain up to 4 decimals.
grossAmount
number
The gross price of the unit price. The value can contain up to 4 decimals.
taxRatePercentage
number
The tax rate of the unit price. Supported tax rates are 0, 7, 19.

Total Price Details

                    Property Description
currency
string
The currency of the total price. Currently only EUR is supported.
totalNetAmount
number
The total net price over all line items. The value can contain up to 2 decimals.
Read-only.
totalGrossAmount
number
The total gross price over all line items. The value can contain up to 2 decimals.
Read-only.
totalTaxAmount
number
The total tax amount over all line items. The value can contain up to 2 decimals.
Read-only.
totalDiscountAbsolute
number
(Optional) A total discount as absolute value. The value can contain up to 2 decimals.
totalDiscountPercentage
number
(Optional) A total discount relative to the gross amount or net amount dependent on the given tax conditions. The value can contain up to 2 decimals.

Tax Amounts Details

                    Property Description
taxRatePercentage
number
The tax rate percentage. Supported tax rates are 0, 7, 19.
taxAmount
number
The total tax amount for this tax rate. The value can contain up to 2 decimals.
netAmount
number
The total net amount for this tax rate. The value can contain up to 2 decimals.

Tax Conditions Details

                    Property Description
taxType
enum
The tax type for the invoice. Possible values are net, gross, vatfree (without value added tax), intraCommunitySupply (Innergemeinschaftliche Lieferung gem. §13b UStG), constructionService13b (Bauleistungen gem. §13b UStG), externalService13b (Fremdleistungen innerhalb der EU gem. §13b UStG), thirdPartyCountryService (Nichtsteuerbare Dienstleistung an Drittländer), and thirdPartyCountryDelivery (Steuerfreie Ausfuhrlieferung)
taxTypeNote
string
When taxType is set to vatfree, intraCommunitySupply, constructionService13b, externalService13b, thirdPartyCountryService, or thirdPartyCountryDelivery, it is possible to add a note regarding the tax type.

Payment Conditions Details

                    Property Description
paymentTermLabel
string
A textual note regarding the payment conditions.
paymentTermDuration
integer
The time left (in days) until the payment must be conducted.
paymentDiscountConditions
list
The payment discount conditions for the invoice.

Payment Discount Conditions Details

                    Property Description
discountPercentage
number
The discount offered in return for payment within the discountRange. The value can contain up to 2 decimals.
discountRange
integer
The time left (in days) the discount is valid.

Shipping Conditions Details

                    Property Description
shippingDate
dateTime
The instant of time when the purchased items have to be shipped. Format yyyy-MM-dd HH:mm:ss.mmm z, example: 2017-02-22T00:00:00.000+01:00.
shippingEndDate
dateTime
An end instant in order to specify a shipping period of time. Format yyyy-MM-dd HH:mm:ss.mmm z, example: 2017-02-22T00:00:00.000+01:00. Must not specify an instant before shippingDate.
shippingType
enum
The type of the shipping. Possible values are service (a service is supplied on shippingDate), serviceperiod (a service is supplied within the period [shippingDate,shippingEndDate] ), delivery (a product is delivered), deliveryperiod (a product is delivered within the period [shippingDate,shippingEndDate]) and none (no shipping date has to be provided)

Files Details

                    Property Description
documentFileId
uuid
The id of the invoice PDF. The PDF will be created when the invoice turns from draft into status open. To download the invoice PDF file please use the files endpoint.

Create an Invoice

Sample Request to create an invoice

curl https://api.lexoffice.io/v1/invoices
-X POST
-H "Authorization: Bearer {accessToken}"
-H "Content-Type: application/json"
-H "Accept: application/json"
-d '
{
 "archived": false,
  "voucherDate": "2017-02-22T00:00:00.000+01:00",
   "address": {
   "name": "Bike & Ride GmbH & Co. KG",
    "supplement": "Gebäude 10",
    "street": "Musterstraße 42",
    "city": "Freiburg",
    "zip": "79112",
    "countryCode": "DE"
  },
  "lineItems": [
    {
      "id": "97b98491-e953-4dc9-97a9-ae437a8052b4",
      "type": "material",
      "name": "Abus Kabelschloss Primo 590 ",
      "description": "· 9,5 mm starkes, smoke-mattes Spiralkabel mit integrierter Halterlösung zur Befestigung am Sattelklemmbolzen · bewährter Qualitäts-Schließzylinder mit praktischem Wendeschlüssel · KabelØ: 9,5 mm, Länge: 150 cm",
      "quantity": 2,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 13.4,
        "taxRatePercentage": 19
      },
      "discountPercentage": 50
    },
    {
      "id": "dc4c805b-7df1-4310-a548-22be4499eb04",
      "type": "service",
      "name": "Aufwändige Montage",
      "description": "Aufwand für arbeitsintensive Montagetätigkeit",
      "quantity": 1,
      "unitName": "Stunde",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 8.32,
        "taxRatePercentage": 7
      },
      "discountPercentage": 0
    },
    {
      "type": "custom",
      "name": "Energieriegel Testpaket",
      "quantity": 1,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 5,
        "taxRatePercentage": 0
      },
      "discountPercentage": 0
    }
  ],
  "totalPrice": {
    "currency": "EUR"
   },
  "taxConditions": {
    "taxType": "net"
  },
  "paymentConditions": {
    "paymentTermLabel": "10 Tage - 3 %, 30 Tage netto",
    "paymentTermDuration": 30,
    "paymentDiscountConditions": {
      "discountPercentage": 3,
      "discountRange": 10
    }
  },
  "shippingConditions": {
    "shippingDate": "2017-04-22T00:00:00.000+02:00",
    "shippingType": "delivery"
  },
  "introduction": "Ihre bestellten Positionen stellen wir Ihnen hiermit in Rechnung",
  "remark": "Vielen Dank für Ihren Einkauf"
}
'

Sample response

{
  "id": "e9066f04-8cc7-4616-93f8-ac9ecc8479c8",
  "resourceUri": "https://api.lexoffice.io/v1/invoices/66196c43-bfee-baf3-4335-d610367059db",
  "createdDate": "2016-06-29T15:15:09.447+02:00",
  "updatedDate": "2016-06-29T15:15:09.447+02:00",
  "version": 1
}

POST {resourceurl}/v1/invoices[?finalize=true]

Invoices transmitted via the API are created in draft mode per default. To create a finalized invoice with status open the optional query parameter finalized has to be set. The status of an invoice cannot be changed via the api.

The created invoice will be shown in the main voucher list in lexoffice: https://app.lexoffice.de/vouchers. To provide your endusers access to the created invoice please use our deeplink function.

The contents of the invoice are expected in the request's body as an application/json and must not contain read-only fields.

Description of required properties when creating an invoice.

                    Property Required Notes
voucherDate Yes
address Yes Nested object. Required fields for address please see below.
lineItems Yes List of nested objects. Required fields for lineItems please see below.
totalPrice Yes Nested object. Required fields for totalPrice please see below.
taxConditions Yes Nested object. Required fields for taxConditions see below.
shippingConditions Yes Nested object. Required fields for shippingConditions please see below.

Address Required Properties

Description of required address properties when creating an invoice.

                    Property Required Notes
contactId * Only when referencing an existing lexoffice contact.
name * Only required when no existing contact is referenced.
countryCode * Only required when no existing contact is referenced.

Line Items Required Properties

Description of required lineItem properties when creating an invoice. At this point only line items of type "custom" are supported.

                    Property Required Notes
type Yes Currently the only possible value is custom.
name Yes
quantity Yes
unitName Yes
unitPrice Yes Nested object. Required fields for unitPrice see below.

Unit Price Required Properties

Description of required unitPrice properties when creating an invoice.

                    Property Required Notes
currency Yes
netAmount * Only relevant if taxConditions.taxType != gross is delivered.
grossAmount * Only relevant if taxConditions.taxType == gross is delivered.
taxRatePercentage Yes

Total Price Required Properties

Description of required totalPrice properties when creating an invoice.

                    Property Required Notes
currency Yes

Tax Condition Required Properties

Description of required tax condition properties when creating an invoice.

                    Property Required Notes
taxType Yes Supported values are gross, net, vatfree, intraCommunitySupply and constructionService13b.

Shipping Condition Required Properties

Description of required shipping condition properties when creating an invoice.

                    Property Required Notes
shippingType Yes
shippingDate * Required for shipping types service, serviceperiod, delivery and deliveryperiod.
shippingEndDate * Required for shipping types serviceperiod and deliveryperiod.

Retrieve an Invoice

Sample request

curl https://api.lexoffice.io/v1/invoices/e9066f04-8cc7-4616-93f8-ac9ecc8479c8
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Content-Type: application/json"
-H "Accept: application/json"

Sample response


{
  "id": "e9066f04-8cc7-4616-93f8-ac9ecc8479c8",
  "organizationId": "a3d94eb4-98bc-429e-b7ad-17f1a8463af9",
  "createdDate": "2017-04-24T08:20:22.528+02:00",
  "updatedDate": "2017-04-24T08:20:22.528+02:00",
  "version": 0,
  "archived": false,
  "voucherStatus": "draft",
  "voucherNumber": "RE1019",
  "voucherDate": "2017-02-22T00:00:00.000+01:00",
  "address": {
    "name": "Bike & Ride GmbH & Co. KG",
    "supplement": "Gebäude 10",
    "street": "Musterstraße 42",
    "city": "Freiburg",
    "zip": "79112",
    "countryCode": "DE"
  },
  "lineItems": [
    {
      "id": "97b98491-e953-4dc9-97a9-ae437a8052b4",
      "type": "material",
      "name": "Abus Kabelschloss Primo 590 ",
      "description": "· 9,5 mm starkes, smoke-mattes Spiralkabel mit integrierter Halterlösung zur Befestigung am Sattelklemmbolzen · bewährter Qualitäts-Schließzylinder mit praktischem Wendeschlüssel · KabelØ: 9,5 mm, Länge: 150 cm",
      "quantity": 2,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 13.4,
        "grossAmount": 15.95,
        "taxRatePercentage": 19
      },
      "discountPercentage": 50,
      "lineItemAmount": 13.4
    },
    {
      "id": "dc4c805b-7df1-4310-a548-22be4499eb04",
      "type": "service",
      "name": "Aufwändige Montage",
      "description": "Aufwand für arbeitsintensive Montagetätigkeit",
      "quantity": 1,
      "unitName": "Stunde",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 8.32,
        "grossAmount": 8.9,
        "taxRatePercentage": 7
      },
      "discountPercentage": 0,
      "lineItemAmount": 8.32
    },
    {
      "type": "custom",
      "name": "Energieriegel Testpaket",
      "quantity": 1,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 5,
        "grossAmount": 5,
        "taxRatePercentage": 0
      },
      "discountPercentage": 0,
      "lineItemAmount": 5
    }
  ],
  "totalPrice": {
    "currency": "EUR",
    "totalNetAmount": 26.72,
    "totalGrossAmount": 29.85,
    "totalTaxAmount": 3.13
  },
  "taxAmounts": [
    {
      "taxRatePercentage": 0,
      "taxAmount": 0,
      "netAmount": 5
    },
    {
      "taxRatePercentage": 7,
      "taxAmount": 0.58,
      "netAmount": 8.32
    },
    {
      "taxRatePercentage": 19,
      "taxAmount": 2.55,
      "netAmount": 13.4
    }
  ],
  "taxConditions": {
    "taxType": "net"
  },
  "paymentConditions": {
    "paymentTermLabel": "10 Tage - 3 %, 30 Tage netto",
    "paymentTermDuration": 30,
    "paymentDiscountConditions": {
      "discountPercentage": 3,
      "discountRange": 10
    }
  },
  "shippingConditions": {
    "shippingDate": "2017-04-22T00:00:00.000+02:00",
    "shippingType": "delivery"
  },
  "introduction": "Ihre bestellten Positionen stellen wir Ihnen hiermit in Rechnung",
  "remark": "Vielen Dank für Ihren Einkauf"
}

GET {resourceurl}/v1/invoices/{id}

Returns the invoice with id value {id}.

Render an Invoice Document (PDF)

Sample request

curl https://api.lexoffice.io/v1/invoices/e9066f04-8cc7-4616-93f8-ac9ecc8479c8/document
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample response

{
  "documentFileId": "b26e1d73-19ff-46b1-8929-09d8d73d4167"
}

GET {resourceurl}/v1/invoices/{id}/document

To download the pdf file of an invoice document, you need its documentFileId. This id is usually returned by the invoice resource. However, newly created invoices in status open via the API have to trigger the pdf document file rendering separately. This can be done with this endpoint.

The returned documentFileId can be used to download the invoice pdf document via the Files Endpoint.

Invoices can be directly accessed by permanent HTTPS links to either be viewed or to be edited. If an invoice is not allowed to be edited, a redirection to the view page takes place. In case the given id does not exist, a redirection to the main voucher list takes place.

View URL {appbaseurl}/permalink/invoices/view/{id}

Edit URL {appbaseurl}/permalink/invoices/edit/{id}

Profile Endpoint

Purpose

The profile endpoint provides read access to basic profile information such as company name, user name and email from your lexoffice account.

Profile Properties

                    Property Description
organizationId
uuid
Unique id of your company.
companyName
string
Name of your company registered at lexoffice.
created
object
Information about the established connection to lexoffice. For specification of object created please see below.
connectionId
uuid
The id of the current API connection.

Object created Details

                    Property Description
userName
string
The user who established the connection to lexoffice.
userEmail
string
The user's email who established the connection to lexoffice.
date
string
The date when the connection was established. Formatted as ISO 8601 format yyyy-MM-dd HH:mm:ss.mmm z (e.g. 2017-02-22T00:00:00.000+01:00).

Retrieve Profile Information

Sample Request

curl https://api.lexoffice.io/v1/profile
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample Response

{
  "organizationId": "42b1fbdd-c4e0-4bb4-8c20-1d3d0b9432e8",
  "companyName": "Testfirma GmbH",
  "created": {
    "userName": "Frau Erika Musterfrau",
    "userEmail": "erika.musterfrau@testfirma.de",
    "date": "2017-01-03T13:15:45+0100"
  },
  "connectionId": "3dea098a-fae5-4458-a85c-f97965966c25",
  "features": [
    "cashbox"
  ],
  "subscriptionStatus": "active"
}

GET {resourceurl}/v1/profile

The following sample shows how to retrieve your basic profile information. It is required to replace the placeholder {accessToken} before sending the request.

Voucherlist Endpoint

Purpose

The voucherlist endpoint provides read access to meta data of invoices and credit notes. For filters that can be applied to the list see below. Details concerning items from the list are accessible by id using the respective endpoint. For more information on the different voucher types refer to the documentation on the respective endpoints.

Voucherlist Properties

This section describes the properties of the meta data object for vouchers returned by this endpoint.

                    Property Description
id
uuid
Unique id of the voucher in lexoffice.
voucherType
enum
Type of the voucher. Possible values are invoice and creditnote.
voucherStatus
enum
Showing the current workflow status of the voucher in lexoffice. Possible values are draft, open, paid, paidoff, voided, transferred and overdue.
voucherNumber
string
Identification/Reference number of the voucher.
voucherDate
dateTime
Date when the voucher was issued. Format is ISO 8601 format yyyy-MM-dd HH:mm:ss.mmm z (e.g. 2017-02-22T00:00:00.000+01:00).
updatedDate
dateTime
Date when the voucher was last changed (or status changed) in lexoffice. Format is ISO 8601 format yyyy-MM-dd HH:mm:ss.mmm z (e.g. 2017-02-22T00:00:00.000+01:00).
dueDate
dateTime
Date when the voucher's payment has to be settled. Format is ISO 8601 format yyyy-MM-dd HH:mm:ss.mmm z (e.g. 2017-02-22T00:00:00.000+01:00).
contactName
string
Name of the recipient or invoicing party. Further information on the contact can be retrieved by using the corresponding voucher endpoint (see below).
totalAmount
number
Total amount of the voucher (may include taxes). Format is ##.00 (119.00).
currency
enum
Currency of the voucher. Only possible value is EUR.
archived
boolean
Indicates if the voucher is marked as archived in lexoffice.

Filter parameter voucherType

This filter parameter is required. It can contain a comma separated list of voucher types.

Full information on any voucher can be retrieved by calling the endpoint related to the meta data object's voucherType. Please refer to this list for information on which endpoint you should call.

                    Voucher Type Endpoint
invoice Invoices endpoint
creditnote Credit Notes endpoint

Filter parameter voucherStatus

This filter parameter is required. It can contain a comma separated list of voucher status.

                    Voucher Status Description
draft Voucher is created but not yet final. It is still editable in lexoffice.
open Voucher is finalized in lexoffice and no longer editable but yet unpaid or only partially paid.
overdue Voucher is open and dueDate is in the past.
paid Invoice is marked as fully paid in lexoffice.
paidoff Credit note is marked as paidoff in lexoffice.
voided Voucher is cancelled.
transferred Voucher is transferred via the lexoffice online banking connector. When the payment is handled by the bank this status changes to paid.

Filter parameter archived

This filter parameter is optional. If absent the result contains archived and non-archived vouchers.

                    Parameter Name Description
archived (optional) Filter vouchers by archived flag. Possible values are true or false.

Paging parameters

The voucherlist is a paged list. This parameter changes the used page size:

                    Parameter Name Description
size (optional) Default page size is 25. Can be set up to a maximum of 250.

For further information see Paging of Resources

Sorting parameters

The voucherlist can be sorted using the following parameter:

                    Parameter Name Description
sort (optional) Property significant to order of the contents. Possible values are voucherDate, voucherNumber, and updatedDate. The sort direction can be added separated by a comma. Possible values for the direction are ASC or DESC.

Retrieve and filter voucherlist

It is possible to filter vouchers by voucherType, voucherStatus and the archived flag.

Sample Request

curl https://api.lexoffice.io/v1/voucherlist?voucherType=invoice&voucherStatus=open
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample Response

{
    "content": [
        {
            "id": "f3d3ae48-30d9-4b56-973a-b3159cbe743c",
            "voucherType": "invoice",
            "voucherStatus": "open",
            "voucherNumber": "RE1012",
            "voucherDate": "2019-02-14T00:00:00.000+01:00",
            "updatedDate": "2019-03-03T16:52:21.000+01:00",
            "dueDate": "2025-11-13T00:00:00.000+01:00",
            "contactName": "Musterfrau, Erika",
            "totalAmount": 99.8,
            "currency": "EUR",
            "archived": false
        },
        {
            "id": "55aa6de8-d32d-47bd-9c3c-d541ab65a8e8",
            "voucherType": "invoice",
            "voucherStatus": "overdue",
            "voucherNumber": "RE1011",
            "voucherDate": "2014-10-07T00:00:00.000+02:00",
            "updatedDate": "2017-05-03T16:52:21.000+02:00",
            "dueDate": "2014-11-06T00:00:00.000+01:00",
            "contactName": "Test GmbH",
            "totalAmount": 498.8,
            "currency": "EUR",
            "archived": false
        }
    ],
    "first": true,
    "last": true,
    "totalPages": 1,
    "totalElements": 2,
    "numberOfElements": 2,
    "size": 25,
    "number": 0,
    "sort": [
        {
            "property": "voucherdate",
            "direction": "DESC",
            "ignoreCase": false,
            "nullHandling": "NATIVE",
            "ascending": false
        }
    ]
}

GET {resourceurl}/v1/voucherlist?{voucherType}&{voucherStatus}&{archived}

Returns a page with meta data on all vouchers of type voucherType, status voucherStatus and marked as archived archived.

Paging of Resources

Sample Request

curl https://api.lexoffice.io/v1/contacts/?page=0
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample Response

{
  "content":[
    ...
  ],
  "totalPages": 1,
  "totalElements": 13,
  "last": true,
  "sort": [
      {
        "direction": "ASC",
        "property": "name",
        "ignoreCase": false,
        "nullHandling": "NATIVE",
        "ascending": true
      }
  ],
  "size": 25,
  "number": 0,
  "first": true,
  "numberOfElements": 13
}

The lexoffice API offers basic paging of some of its resources. This page describes the general concept of the paging mechanism in the API. For further details please refer to the specific endpoints. Each paged resource has it own predefined sorting.

Paging Parameters and their names

                 Parameter Name Description
page
integer
Page Pages are zero indexed, thus providing 0 for page will return the first page.
size
integer
Size Default page size is set to 25 but can be increased up to 100/250 (depends on the used endpoint).

Description of the paging information.

                    Property Description
content
complex
The content of this page as a JSON array.
last
boolean
Whether this page is the last one.
totalPages
integer
The total number of pages.
totalElements
integer
The total amount of elements.
sort
string
Information on how the content is sorted. Attribute is read-only.
size
integer
The size of this page.
number
integer
The number of this page. It is always non-negative.
first
boolean
Whether this page is the first one.
numberOfElements
integer
The number of elements in this page.

Optimistic locking

Resource modification with PUT requests in the lexoffice API requires passing a version property, also known as a revision. This is required to mitigate the risk of overwriting data in a data race condition due to concurrent access of the API.

The lexoffice API implements a paradigm known as optimistic locking. That means: an entity (or resource) is not required to be locked before modification, but passing the correct version is required to make sure that no other request has modified the respective entity in the time between the last GET request and the modifying PUT request.

If, for example, a contact is about to be modified, first GET the respective contact, and then include the version you received in your next PUT request. If the record has been modified by someone else in the meantime, you will receive an HTTP status 409 Conflict (see below).

For versioned resources, in the initial POST request, the version needs to have the value of 0.

HTTP Status Codes

The following list shows a brief description of the available HTTP status codes and their meaning in context of the lexoffice API.

                    Response code Description
200
OK
Standard response for a successful request. Depending on the verb (POST, GET, PUT) the response type will be action-result (POST & PUT) or a single entity or a collection of entities (GET).
201
Created
Returned on successful creation of a new resource via POST requests.
202
Accepted
lexoffice has accepted the request. Further processing has to be done. Depending on the used endpoint you can query the processing status.
204
No Content
The resource was successfully deleted.
400
Bad Request
Malformed syntax or a bad query.
401
Unauthorized
Action requires user authentication.
402
Payment Required
Action not accessible due to a lexoffice contract issue. For details see Error Codes.
403
Forbidden
Authenticated but insufficient scope or insufficient access rights in lexoffice.
404
Not Found
Requested resource does no exist (anymore).
405
Not Allowed
Method not allowed on resource.
406
Not Acceptable
Validation issues due to invalid data.
409
Conflict
Indicates that the request is not allowed due to the current state of the resource. For instance, an outdated version field send with PUT.
415
Unsupported Media Type
Missing Content-Type header for POST and PUT requests. Only application/json is supported besides file uploads where multipart/form-data is expected.
429
Too Many Requests
May occur if the endpoint exceeds the limit of throttling. This request should be called again at a later time.
500
Server Error
Internal server error. Please get in contact with us.
501
Not Implemented
Requested HTTP operation not supported.
503
Service Unavailable
Unable to handle the request temporarily.
504
Gateway Timeout
The proxied request from the gateway to the targeted services has timed out. This error occurs when the server did not answer before the request timeout of 30 seconds. It is possible that your request has been processed successfully.

Error Codes

The lexoffice API provides two types of error objects which provide further information in case an error occurs during an API operation.

While extending functionality to the API we also improve the error handling. This happens on behalf of feedback we get from our users and technical aspects.

Authorization and Connection Error Responses

Status Body Cause
401
Unauthorized
{ "message": "Unauthorized" } No token provided, invalid format of authorization token, invalid token or your API client is disabled.
403
Forbidden
{"message": "'{accessToken}' not a valid key=value pair (missing equal-sign) in Authorization header: 'Bearer {accessToken}'."} Resource not available. Possibly wrong Url or method.
500
Internal Server Error
{ "message": null } lexoffice server not available or internal problem.
503
Service Unavailable
Detail information. May be null. lexoffice server not available.
504
Gateway Timeout
{ "message": "Endpoint request timed out" } Endpoint request timed out. This timeout is set to 30 seconds for all requests.

Legacy error response

Sample for a legacy error response

{
  "IssueList": [
    {
      "i18nKey": "missing_entity",
      "source": "company.name",
      "type": "validation_failure",
      "additionalData": null,
      "args": null
    }
  ]
}

The following REST endpoints are using the legacy error response:

Format of the Error Object

The error object is a JSON object only containing a JSON array named IssueList, which wraps one or more issue objects.

Each issue object contains the attributes i18nKey, source, type, additionalData and args.

Attribute Description
i18nKey error code (human readable)
source Source for this error e.g. the attribute/field that could not be validated. May be null.
type Global type/category
additionalData Detail information. May be null.
args e.g. valid range or locale code. May be null.

Bad Request Errors - Returned with HTTP Status Code 400

i18nKey source type Description
bad_request_error null bad_request_error This error may occur in many cases.
bad_request_error size must be between {MIN_SIZE} and {MAX_SIZE} bad_request_error This error may occur in many cases. In case of the contact filter using email or name, the length of the value is out of range specified by {MIN_SIZE} and {MAX_SIZE}.

Validation Errors - Returned with HTTP Status Code 406

i18nKey source type additionalData args Description
missing_entity attribute name validation_failure null null The value must not be null or empty.

Technical Errors - Returned with HTTP Status Code 500

i18nKey source type additionalData args Description
technical_error error source and contact_vendor_info_not_assigned technical_error null null The contact has a structural failure. Contact support for further investigations.
technical_error error source and contact_is_neither_ customer_nor_vendor technical_error null null The contact has a structural failure. Contact support for further investigations.
technical_error error source and contact_has_no_valid_salutation technical_error null null The contact has a structural failure. Contact support for further investigations.
technical_error error source and contact_has_not_ mappable_email_address technical_error null null The contact has a structural failure. Contact support for further investigations.
technical_error error source and contact_has_not_ mappable_phone_number technical_error null null The contact has a structural failure. Contact support for further investigations.
technical_error error source and contact_has_not_mappable_address technical_error null null The contact has a structural failure. Contact support for further investigations.
technical_error error source and contact_has_not_mappable_country technical_error null null The contact has a structural failure. Contact support for further investigations.

Regular error response

Sample JSON response of type regular error message

{
  "timestamp": "2017-05-11T17:12:31.233+02:00",
  "status": 406,
  "error": "Not Acceptable",
  "path": "/v1/invoices",
  "traceId": "90d78d0777be",
  "message": "Validation failed for request. Please see details list for specific causes.",
  "details": [
    {
      "violation": "NOTNULL",
      "field": "lineItems[0].unitPrice.taxRatePercentage",
      "message": "darf nicht leer sein"
    }
  ]
}

The following REST endpoints are using the regular error response:

Format of the Error Object

The error object is a JSON object.

                    Property Description
timestamp
dateTime
Detailed information about the time when the error has occurred.
status
string
HTTP status code. E.g. 406 in case the payload can´t be accepted because of validation issues. A list of used HTTP status codes can be found here.
error
string
A brief description of the error code.
path
string
Information about the called REST endpoint.
traceId
string
A unique id allowing us to trace the error in our logs.
message
string
Human readable information about the occurred error. This message is not suitable for presenting it to your applications end-users.
details
object
An optional list of additional information about the validation issues.

Description of the Details Object

                    Property Description
violation
string
Information about the type of violation. E.g. NOTNULL indicates a missing data for a mandatory field.
field
string
Name and location of property involved in the validation error.
message
string
Human readable information about the occurred error.
This message is not suitable for presenting it to your application's end-users.

FAQ

Meaning of collective contact (e.g. customer or vendor)

A collective customer / vendor is a concept of a generic contact, against which different bookkeeping actions can be referenced. It can be used, if the user of lexoffice didn't want to create an explicit customer/vendor for each voucher.

In context of the API this means, that an API consumer (Shop-Plugin, App, etc.) can provide a configuration possibility for the user to allow using the collective contact in favor of creating new contacts for each e.g. order.



Getting HTTP Status Code 401

If you retrieve this HTTP status code it is possible, that the lexoffice API is temporarily unavailable which you can verify on the lexoffice status page. Otherwise your request could be missing the authorization header or contain an invalid access token.



URI Components

lexoffice API URI components

The URI components follow the pattern: https://{hostname}/{version}/{resourceUri}{?query}.

Hostname

The host name (base URI) is the first segment of the APIs URI.

{resourceurl}/v1/vouchers

Version

The current API version is v1 and will be changed only if breaking changes are required. See our change log for possible breaking changes.

{resourceurl}/v1/vouchers

Resource URI

The resource URI is the endpoint which provides functionality to create, update and read lexoffice objects.

{resourceurl}/v1/contacts

Query

An optional query string containing key-value pairs separated by a delimiter can used both to filter resources by its property values and control the paging of resources of collections (list of resources).

{resourceurl}/v1/contacts?page=0

Create a lexoffice account

To sign up for a new company, visit https://app.lexoffice.de/signup and click on "Kostenlos registrieren". The signup only requires email and password.

After successful registration check you mailbox for the verification email to confirm the signup.

Gathering organization id

You can get the organization id of your lexoffice account via browser console (open via F12) using the following command:

lxo.organizationId

Gathering contact id(s)

To get the id of an existing contact (e.g. to use it for the invoices endpoint), switch to Kontakte and select the desired contact. When the contact details are shown, the contact's id can be found in the browser's URL field.

https://app.lexoffice.de/master-data/#/contacts/97c5794f-8ab2-43ad-b459-c5980b055e4d

Samples

The samples for the lexoffice API REST endpoints are provided as a generic Postman collection.

Postman is a free app for API development which allows to easily test REST APIs and supports any type of required "infrastructure". E.g. authorization (basic, token, etc.) as well as header-manipulation, body data, etc.

Importing the samples

The lexoffice samples can be directly imported into Postman via the Import button at the left top (Import File -> Choose Files).

Postman Collection Import

Initial setup

To run the samples via the blue Send button, an "environment" needs to be configured within Postman.

The pre-configured lexoffice environment can be directly imported into Postman via the Manage Environments dropdown at the right top and choosing (Import) in the subsequent dialog.

Postman Environment Import

Accessing endpoints with your API Key

As a first step, you can use Postman to familiarize with the lexoffice API.

Tip: As our sample requests contain an environment variable in the authorization header field, you can add your access token to all requests by updating the accessToken field in the Postman environment to contain your access token.

Postman Bearer Auth Header

Ping Endpoint response

{
    "userEmail": "yourEmail@example.org"
}

After clicking "Send" you should receive a JSON response with the email address of your authorized lexoffice account.

Tip: Postman can generate action basic code in several languages from any sample (e.g. PHP, C#, Java, JavaScript, Ruby, Swift, etc.). Just press the Code link which is located just below the send button.

Postman Code Generation

Change Log

Change log of lexoffice API

API Changes