bexio API (3.0.0)

Stay up-to-date

Subscribe to our status page to get informed about short term issues with the API. Subscribe to our API developer newsletter to get the latest news and updates around our API platform.

Overview

The bexio API uses HTTPS methods and RESTful endpoints to create, edit, and manage documents in the bexio system. JSON is used as the data interchange format.

First steps

In order to use the bexio API, you need to follow the following steps in order:

  1. Create a bexio account by signing up for a trial account at https://www.bexio.com and complete the onboarding process. If you already have a bexio account, you can skip this step.
  2. Go to the developer portal at https://developer.bexio.com and log in using your bexio credentials.
  3. Read and accept the terms and conditions
  4. Create a new app and make sure that you define a valid site for the "Allowed redirect URL" field(s)
  5. By clicking on the section "App Details" you can reveal the Client ID and Client Secret
  6. Initiate the Authorization Code Flow to obtain an access token.
  7. Use the access token to create a request to the bexio API. The example below fetches a list of contacts (make sure to request the scope contact_show in the authorization code flow)
curl -X GET \
      https://api.bexio.com/2.0/contact \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer {access-token}'

Make sure to replace {access-token} with the token you received in Step 6.

Reporting a problem

If you've encountered a bug, we're here to help. Before you begin, ensure you can reproduce the issue using a tool for testing APIs, such as Postman. To report the problem, please use the form provided below. Be sure to include detailed steps allowing us to reproduce the issue. However, do not include any credentials in your report.

Report a problem

Please do note that the API is provided as is based on this very documentation, there is no guided implementation or code support available.

Changelog

We will list any changes to the current version of the API here.

Date Details of changes
2024-10-22
2024-10-01
2024-08-06
  • Added the field base_currency_id to the journal endpoint. This field is read only and can not be changed through the API.
  • Added the field currency_factor to the journal endpoint. This field is read only and can not be changed through the API.
  • Added the field base_currency_amount to the journal endpoint. This field is read only and can not be changed through the API.
2024-07-15
2024-07-15
2024-06-14
2024-05-29
2024-02-14
  • Removed legacy API documentation.
2023-12-11
  • receiver_house_no marked as required for IBAN and QR payments on purchase outgoing payment endpoint.
2023-10-25
  • New optional payment street and payment house number fields added to purchase bill endpoints to allow storing of structured payment address.
2023-10-09
  • Change in create Purchase Order endpoint - contact_id has to be an integer.
2023-08-28
2023-08-02
  • Purchase scopes have been added to the API Scopes section
  • Required scopes have been updated for all relevant purchase endpoints (there is no change in the required scopes - only the documentation is updated with missing information).
2023-05-16
  • Updated guide to migrate clients away from the legacy API to cover all possible scenarios.
  • Announce 30.11.2023 as the shutdown date of the legacy API.
2023-04-25
2023-04-13
  • bill_id has been removed from the documentation for creating and updating QR and IBAN payments as it is unused
2023-01-31
  • Draft QR payments can be added to purchase bills in EUR currency
  • Outgoing QR payments can be created for purchase bills in EUR currency
2022-10-10
2022-09-21
  • Bill status update endpoint - validation rules for booking account updated.
  • Expense status update endpoint - validation rules for booking account updated.
2022-08-26
  • IS payment endpoints have been removed as only QR payments are valid after 30.09.2022
  • ISR payment endpoints have been removed as only QR payments are valid after 30.09.2022
  • ISR fields in bank account endpoints have been deprecated as only QR payments are valid after 30.09.2022
  • IS/ISR payment types have been removed from bill and outgoing payments endpoints as only QR payments are valid after 30.09.2022
2022-04-19
  • Fixed the language of the recipient’s country field in the sales documents.
2022-03-22
2022-03-08
  • Added new restore endpoint which allows to restore archived contacts.
  • Added new query parameter to show archived contacts for contact search, list and fetch.
2021-12-02
2021-10-18
  • Corrected the limit for all API endpoints (max limit is enforced to 2000).
  • Changed the default limit of GET requests to 500 (instead of 1000).
2021-07-23
  • Added the field ref_uuid to the report endpoint. This field is read only and can not be changed through the API.
2021-01-08
  • Added the field uuid to the project endpoints. This field is read only and can not be changed through the API.
2020-12-16
  • Adjusted the timesheet endpoints so that it includes the stopwatch information in the attribute tracking
2020-12-08
  • Added the section purchase that contains bills, expenses and purchase orders. Please note that Purchase APIs for Bills, Expenses and Outgoing Payments are available only for users already using the new purchase module https://www.bexio.com/en-CH/purchase.
  • Updated the files endpoints to include all attributes in the response
  • Added all search parameters to the Search files endpoint
  • Significantly improved the response time of all API endpoints. For some endpoints the average response time is reduced by up to 40%.
2020-11-02
  • The documentation for creating a purchase order was updated because the sample payload and response of the request were wrong
2020-09-24
2020-09-21
  • Added new endpoint List document templates to retrieve the list of document templates
  • Added the field template_slug to the Quotes, Orders and Invoices endpoints
  • The field logopaper_id used in above mentioned endpoints has been deprecated in favor of the new field template_slug
2020-09-09
2020-07-07
2020-07-07
2020-06-30
2020-06-25
2020-06-10
2020-06-04
2020-05-28
2020-04-20
  • Added 201 response for the endpoint Create IS payment to the documentation.
  • Changed the name of the parameter unique_id to instruction_id in the documentation for all IS payment endpoints (was always returned as instruction_id through the API).
2020-04-16
  • Added the section API Tokens that details how server-to-server connections without the consent flow can be established.
2020-03-31
  • A more detailed description explaining how to retrieve all valid sales taxes from the API has been added to the tax_id parameter for line items on quotes, orders and invoices.
2020-02-20
  • Fixed 404 access errors for the Accounts and Account Groups endpoints
  • Fixed 404 access errors on a handful of POST requests (e.g. edit contact, edit invoice, edit project, etc.)
  • Fixed issue within the creation of projects when the value of the field pr_budget_type_amount was not saved when the field pr_budget_type_id was set to the value of 1
2020-02-05
  • Fixed access issues to PDF endpoints for quotes, orders and invoices
  • Added the info that the field bill_id can not be used for all create payment endpoints
2019-12-16 First version published

Authentication

OpenID Connect

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.

Key Value
Issuer https://auth.bexio.com/realms/bexio
OpenID Configuration URL https://auth.bexio.com/realms/bexio/.well-known/openid-configuration
Authorization endpoint https://auth.bexio.com/realms/bexio/protocol/openid-connect/auth
Token endpoint https://auth.bexio.com/realms/bexio/protocol/openid-connect/token
Userinfo endpoint https://auth.bexio.com/realms/bexio/protocol/openid-connect/userinfo
JWK endpoint https://auth.bexio.com/realms/bexio/protocol/openid-connect/certs

Migration from idp.bexio.com to auth.bexio.com

The IdP, currently available at idp.bexio.com, is about to be replaced by a new IdP available on auth.bexio.com. Like the idp.bexio.com, the new solution will implement the OAuth2 protocol with the OpenID connect extension which ensures compatibility for API clients.

During the migration period of six months, both idp.bexio.com and auth.bexio.com will be available for API clients to initiate the OAuth2 authorization code flow and to issue API access tokens. This will allow API clients to migrate to the new IdP at their own pace.

idp.bexio.com will be decommissioned on 31.03.2025.

How to migrate an API client to the new IdP?

Most client applications can migrate to the new IdP by just reconfiguring the URLs to initialize the authorization flow and to issue tokens. Depending on the framework in use, the URLs to change might differ but usually includes one or more of the following URLs:

Endpoint Old URL New URL
Issuer https://idp.bexio.com https://auth.bexio.com/realms/bexio
OpenID Configuration URL https://idp.bexio.com/.well-known/openid-configuration https://auth.bexio.com/realms/bexio/.well-known/openid-configuration
Authorization endpoint https://idp.bexio.com/authorize https://auth.bexio.com/realms/bexio/protocol/openid-connect/auth
Token endpoint https://idp.bexio.com/token https://auth.bexio.com/realms/bexio/protocol/openid-connect/token
Userinfo endpoint https://idp.bexio.com/userinfo https://auth.bexio.com/realms/bexio/protocol/openid-connect/userinfo
JWK endpoint https://idp.bexio.com/jwk https://auth.bexio.com/realms/bexio/protocol/openid-connect/certs

Other configuration options like client_id, client_secret or scope do not need to be changed.

Are there any new features for client applications?

From a client perspective, there are some minor improvements that simplify the correct use of id and access tokens:

  • Claims in id tokens are aligned with the /userinfo endpoint. Id tokens will contain the following claims if the according scope is requested:
    • scope: profile, claims: given_name, family_name, gender, locale
    • scope: email, claims: email, email_verified
  • In addition, the following scope has been added to request access to company information in id tokens and the /userinfo endpoint:
    • scope: company_profile, claims: company_id, company_name, company_user_id

Are there breaking changes?

The new IdP differs in some of the claims provided by the access and id tokens returned by the /token endpoint and in some of the properties provided by the /userinfo endpoint. The breaking changes affect the following claims:

  • iss - This claim identifies the issuer of the token and is currently "https://idp.bexio.com". With the switch to the new IdP the value will change to "https://auth.bexio.com/realms/bexio".
  • sub - This claim identifies the user who granted the creation of the token. Currently, the claim equals to the user’s email address. The new IdP will instead return a UUID identifying the user within bexio equal to the login_id claim.
    • If you’re using the sub claim to identify the user, consider switching to the login_id claim before migrating to auth.bexio.com. login_id will be identical on both the old and the new IdP for a given user.
    • If you’re using the sub claim to get access to the user’s email address, consider to use the email claim instead. Please note that the claim is only available if the email scope has been granted to your client. Alternatively, you can use the /3.0/users/me endpoint (docs).
  • locale - Contains the user’s default locale if the user grants access to the openid profile scope and is provided by the /userinfo endpoint. idp.bexio.com currently uses the non-compliant underscore to separate language code from country code (as in de_CH). auth.bexio.com will provide the locale in the OIDC compliant format using a hyphen (e.g. de-CH).
  • shard_id - This claim will no longer be available.

Additionally, the following will change with the switch to the new IdP:

  • Offline sessions will have an idle timeout of 1 year. An offline session is created if tokens are requested with the offline_access scope. The returned refresh token will be valid indefinitely but the associated offline session will be closed if not renewed within 1 year. This effectively means that tokens must be refreshed within 1 year.
  • idp.bexio.com supports accepting some parameters to the /token endpoint as query parameters in the URL. This behavior is no longer supported in the new IdP and all parameters must be passed in the request body.
  • In some cases, you may run into more strict CORS policies after switching to the new IdP. These issues can be mitigated by adding your web origin as a valid redirect URL for your app on https://developer.bexio.com. Redirect URLs will be accepted as valid web origins for requests from the according client.

Do users have to re-authorize my application after the switch?

To answer this question we have to distinguish between two cases:

  • Applications using refresh tokens can migrate refresh tokens issued by idp.bexio.com to the new IdP by passing the tokens to the refresh token grant type on https://auth.bexio.com/realms/bexio. When the new IdP receives a refresh token issued by idp.bexio.com, the according user consent will be imported. This means that users wont be required to re-authorize your application in this case. Keep in mind though that this requires that applications replace refresh tokens with the new refresh tokens provided during the token refresh instead of reusing the refresh token received with the initial call to the token endpoint. Also, tokens have to be refreshed at least once before idp.bexio.com is decommissioned on 31.03.2025.
  • If refresh tokens are not used, users will be required to give consent to the scope requested by your application again after switching to the new IdP.

API Scopes

Scope is a mechanism in OAuth 2.0 / OpenID Connect to limit an application's access to a user's account. An application can request one or more scopes, this information is then presented to the user in the consent screen, and the access token issued to the application will be limited to the scopes granted.

Please only request the scopes that you need for your application. You are allowed to request multiple scopes per request. Multiple scopes have to be separated by a whitespace. As an example, write access to quotes and invoices can be requested with the following scopes: kb_offer_edit kb_invoice_edit.

Read access is granted automatically when a write scope is requested for a resource. This means that by requesting the scope contact_edit the scope contact_show is not needed in order to get read access to contacts.

Scope Description
accounting Write access to accounting data
article_show Read access to items / products
article_edit Write access to items / products
bank_account_show Show bank accounts
bank_payment_show Show bank payments
bank_payment_edit Show and edit bank payments
contact_show Read access to contacts
contact_edit Write access to contacts
file Read and write access to the inbox (file upload)
kb_invoice_show Read access to invoices
kb_invoice_edit Write access to invoices
kb_offer_show Read access to quotes
kb_offer_edit Write access to quotes
kb_order_show Read access to orders
kb_order_edit Write access to orders
kb_delivery_show Read access to deliveries
kb_delivery_edit Write access to deliveries
monitoring_show Read access to timesheets
monitoring_edit Write access to timesheets
note_show Read access to contact notes
note_edit Write access to contact notes
kb_article_order_show Read access to purchase orders
kb_article_order_edit Write access to purchase orders
project_show Read access to projects
project_edit Write access to projects
stock_edit Write access to item stock
task_show Read access to tasks
task_edit Write access to tasks
kb_bill_show Read access to supplier bills
kb_expense_show Read access to Purchase Expenses

OpenID Connect Scopes

In addition to scopes controlling API access, the following OpenID Connect Scopes can be used to configure the token response:
Scope Description
company_profile Adds company specific claims to the id token like company_id and company_name describing the company the user is signed in to.
email Adds claims containing email address of the signed in user.
offline_access Ensures that tokens can be refreshed also after the current user session has been closed.
openid Standard OpenID Connect (OIDC) scope. Required to indicate that the application intends to use OIDC to verify the user's identity. If requested, an ID token is provided within the token response.
profile Adds user specific claims to the id token like given_name, family_name, locale and gender.

Authorization Code Flow

bexio supports the "Authorization Code Grant" as defined in OAuth 2.0 RFC 6749, section 4.1 to obtain an Access Token. Your app must be server-side because during this exchange, you must also pass along your application's Client Secret, which must always be kept secure, and you will have to store it in your client.

How it works

UserWeb Appbexio OpenID Connectbexio API1. Click on "connect with bexio" link2. Authorization Code Request to / authorize3. Redirect to login screen4. Sign in and give consent5. Return authorization code6. Token request7. Validate  token request8. Return Access & ID token9. Access bexio API with Access Token10. Response

  1. The user clicks Login within the regular web application.
  2. The web application redirects the user to the /authorize endpoint of the bexio OpenID Connect service.
  3. The bexio OpenID Connect Service displays the login page.
  4. The user authenticates and sees a consent page listing the permissions bexio will give to the web application.
  5. The user is redirected back to the web application with an Authorization Code.
  6. The web application sends this code to the bexio OpenID Connect service (/token endpoint) along with the application's Client ID and Client Secret.
  7. bexio verifies the code, Client ID, and Client Secret.
  8. An ID Token and Access Token (and optionally, a Refresh Token) is returned to the web application.
  9. The web application uses the Access Token to call the bexio API.
  10. The bexio API responds with requested data.

Code example (PHP)

The following example showcases the usage of OpenID Connect (PHP example uses the OpenID-Connect-PHP library). The library uses OpenID Connect Discovery to automatically configure the application.

<?php
require __DIR__ . '/vendor/autoload.php';
use Jumbojett\OpenIDConnectClient;

$oidc = new OpenIDConnectClient("https://auth.bexio.com/realms/bexio", "client_id", "client_secret");
$oidc->setRedirectURL("https://www.example.com/oidc_callback");
$oidc->addScope(array("openid", "profile", "contact_show", "offline_access"));
$oidc->authenticate();

echo $oidc->getAccessToken();

The consent screen shown to the user will look like this:

Refresh Token Flow

Web Appbexio OpenID Connectbexio API1. Exchange Refresh Token for Access Token2. New Access Token3. API Request with the new Access Token4. Response

The scope offline_access is required to obtain a refresh token to keep the api connection alive.

  1. POST a request to the endpoint “/token”. Make sure you use the grant type “refresh_token”. This is implemented according to the standards of OAuth 2.0 RFC 6749
  2. The response contains a new access token. Please note that the requested scopes do not change when refreshing a token. Acquiring new scopes is only possible by going through the initial authorization process again.
  3. The new access token can be used to authorize requests and execute API requests
  4. The bexio API responds with the requested data.

Redirect URL(s)

Redirect URLs are a critical part of the OAuth flow. After a user successfully authorizes an application, the authorization server will redirect the user back to the application with either an authorization code or access token in the URL. Because the redirect URL will contain sensitive information, it is critical that the service doesn’t redirect the user to arbitrary locations.

The best way to ensure the user will only be directed to appropriate locations is to require the developer to register one or more redirect URLs when they create the application.

Source https://www.oauth.com/oauth2-servers/redirect-uris/

The new bexio API platform requires to define redirect URLs during the app registration in the developer portal. Unknown URLs will not be accepted during the Authorization and the user will receive an error message.

Up to 10 different redirect URLs can be defined for an app, e.g. to support multiple test environments and mobile apps with custom schemes

Personal Access Tokens (PAT)

Personal Access Tokens (PAT) can be managed on https://developer.bexio.com/pat and are convenient way to issue API access tokens for personal use:

  • A PAT has all default scopes granted and therefore has full access to your company's data.
  • A PAT is valid for six months after creation.
  • A PAT can be revoked by deleting it on developer.bexio.com. After deletion, a PAT can no longer be used to access the API. In the worst case, it might take up to 1 hour until the revocation takes full effect. Subsystems might still be accessible by the token during this period.

If you have other requirements, like restricting the scope granted to a token, please use the Authorization Code Flow instead.

To use a PAT to authorise a request, it can be used as a bearer token in the Authorization header of a request:

Authorization: Bearer eyJraWQiOiI2ZGM2YmJlOC1iMjZjLTExZTgtOGUwZC0w...

API basics

API routes

Each API endpoint is available on our API host https://api.bexio.com.

Endpoints are usually defined with a relative path, as seen in the following example:

Each relative path must be combined with the API platform URL. For the example this would result in the endpoint https://api.bexio.com/2.0/contact

HTTP Verbs

Where possible, bexio tries to use the appropriate HTTP verb for its operations

Verb Description
GET Used for retrieving resources
POST Used for creating resources
PATCH Used for updating resources with partial data
PUT Used for updating resources with full data
DELETE Used for deleting resources. Please note that delete actions permanently delete resources. It cannot be undone.

HTTP Headers

HTTP headers let the client and the server pass additional information with an HTTP request or response. An HTTP header consists of its case-insensitive name followed by a colon (:), then by its value.

Request Headers

The following headers must be used for every request:

  • Accept: application/json
  • Authorization: Bearer <token>

Additionally, the header Content-Length: <length> must be specified for requests with a payload.

Response Headers

The API will always indicate the return type with a Content-Type header. Normally the header value is set to application/json, but can vary (e.g. for PDF exports).

Response Codes Actions and errors yield different HTTP response codes. Please have a look at the expected response codes in the following list:

Code Description
200 Request OK
201 New resource created
304 The resource has not been changed
400 The request parameters are invalid
401 The bearer token or the provided api key is invalid
403 You do not possess the required rights to access this resource
404 The resource could not be found / is unknown
411 Length Required
415 The data could not be processed or the accept header is invalid
422 Could not save the entity
429 Too many requests
500 An unexpected condition was encountered
503 The server is not available (maintenance work)

Errors

Error responses contain an HTTP status code and a JSON response body that is structured as follows:

{
    "error_code": 404,
    "message": "Page not found"
}

Search

Some older endpoints implement search methods. Searching for these endpoint works by sending a POST request to the resource (e.g.: POST /contact/search or POST /country/search). The search parameters must be provided in the body of the POST request.

Please have a look at the resource documentation to see a list of available search parameters.

Criterias

You can use different criterias for the search. The criteria “like” will be used by default if you do not define a criteria.

Criteria Description
= Exact match
equal Exact match (synonyme for =)
!= Not equal
not_equal Not equal (synonyme for !=)
> Greather than
greater_than Greather than (synonyme for >)
< Less than
less_than Less than (synonyme for <)
>= Greater or equal then
greater_equal Greater or equal then (synonyme for >=)
<= Lesser or equal then
less_equal Lesser or equal then (synonyme for <=)
like Partial match
not_like Does not partial match
is_null Value is NULL
not_null Value is not NULL
in Having multiple results which matche, value must be an array e.g. [1, 2]
not_in Having multiple results which do not match, value must be an array e.g. [1, 2]

Code example (PHP)

The following example shows how the search for the contacts API can be used. The last name of the contact must be “Meyer” and the contact number must be greater than 10.

Define the search array

$data = array(
  array(
    'field' => 'name_1',
    'value' => 'Meyer',
    'criteria' => '=',
  ),
  array(
    'field' => 'nr',
    'value' => 10,
    'criteria' => '>',
  ),
);

Transform the array to JSON

json_encode($data);

POST-Body for the search

[
  {
    "field" : "name_1",
    "value" : "Meyer",
    "criteria" : "="
  },
  {
    "field" : "nr",
    "value" : 10,
    "criteria" : ">"
  }
]

Rate Limiting

The bexio API enforces a rate limit that limits the number of requests a company can make per minute.

If this limit is reached, the API will return a 429 status code to the client.

HTTP Headers

The table below describes the relevant headers regarding the API rate-limit.

Header Description
RateLimit-Limit The current limit for this time period.
RateLimit-Remaining The remaining amount of requests allowed for this time period.
RateLimit-Reset The remaining time until the next time period starts (seconds).

FAQ

Is an OpenAPI (Swagger) definition available?

No, we currently do not provide an OpenAPI definition but we have plans to put it online.

Why is “insert business process here” not available as an API endpoint?

We are continously working on a product that makes our customers more successful. Unfortunately we are not able to support every use case via API yet.

Are Credit Notes available?

No, currently Credit Notes are not available but we have plans to put it online.

Contacts

Fetch a list of contacts

This action fetches a list of all contacts

Authorizations:
bearerAuth
query Parameters
order_by
string
Default: "id"
Enum: "id" "nr" "name_1" "updated_at"
Example: order_by=name_1

Defines the order of the results. Multiple sort parameters can be combined by using a comma separator. _asc and _desc can be appended to any parameter to either sort ascending (default) or descending.

limit
integer <int32>
Default: 500
Example: limit=20

Limit the number of results (max is 2000)

offset
integer <int32>
Default: 0
Example: offset=0

Skip over a number of elements by specifying an offset value for the query

show_archived
boolean
Default: false
Example: show_archived=true

Show archived elements only

header Parameters
Accept
required
string
Example: application/json

Responses

Request samples

curl -X GET \
  https://api.bexio.com/2.0/contact \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
application/json
[
  • {
    }
]

Create contact

This action creates a new contact

Authorizations:
bearerAuth
header Parameters
Accept
required
string
Example: application/json
Request Body schema: application/json
required
nr
string or null

If set to null, the number will be assigned automatically. Must be a number, can also be used as integer

contact_type_id
required
integer

Please use the value 1 for companies or 2 for persons

name_1
required
string

This field is used as the company name if the field contact_type_id is set to 1. Otherwise, the field is used as the last name of the person

name_2
string or null

This field is used as the company addition if the field contact_type_id is set to 1. Otherwise, the field is used as the first name of the person

salutation_id
integer or null

References a salutation object

salutation_form
integer or null
titel_id
integer or null

References a title object

birthday
string or null <date>
address
string or null
postcode
string or null
city
string or null
country_id
integer or null

References a country object

mail
string or null <email>
mail_second
string or null <email>
phone_fixed
string or null
phone_fixed_second
string or null
phone_mobile
string or null
fax
string or null
url
string or null
skype_name
string or null
remarks
string or null
language_id
integer or null

References a language object

contact_group_ids
string or null

References one ore multiple contact group objects

contact_branch_ids
string or null

References one ore multiple contact sector objects

user_id
required
integer

References a user object

owner_id
required
integer

Responses

Request samples

Content type
application/json
{
  • "nr": null,
  • "contact_type_id": 1,
  • "name_1": "Example Company",
  • "name_2": null,
  • "salutation_id": 2,
  • "salutation_form": null,
  • "titel_id": null,
  • "birthday": null,
  • "address": "Smith Street 22",
  • "postcode": 8004,
  • "city": "Zurich",
  • "country_id": 1,
  • "mail": "contact@example.org",
  • "mail_second": "",
  • "phone_fixed": "",
  • "phone_fixed_second": "",
  • "phone_mobile": "",
  • "fax": "",
  • "url": "",
  • "skype_name": "",
  • "remarks": "",
  • "language_id": null,
  • "contact_group_ids": "1,2",
  • "contact_branch_ids": null,
  • "user_id": 1,
  • "owner_id": 1
}

Response samples

Content type
application/json
{
  • "id": 4,
  • "nr": null,
  • "contact_type_id": 1,
  • "name_1": "Example Company",
  • "name_2": null,
  • "salutation_id": 2,
  • "salutation_form": null,
  • "title_id": null,
  • "birthday": null,
  • "address": "Smith Street 22",
  • "postcode": 8004,
  • "city": "Zurich",
  • "country_id": 1,
  • "mail": "contact@example.org",
  • "mail_second": "",
  • "phone_fixed": "",
  • "phone_fixed_second": "",
  • "phone_mobile": "",
  • "fax": "",
  • "url": "",
  • "skype_name": "",
  • "remarks": "",
  • "language_id": null,
  • "is_lead": false,
  • "contact_group_ids": "1,2",
  • "contact_branch_ids": null,
  • "user_id": 1,
  • "owner_id": 1,
  • "updated_at": "2019-04-08 13:17:32",
  • "profile_image": "R0lGODlhAQABAIAAAAUEBAAAACwAAAAAAQABAAACAkQBADs="
}

Search contacts

Search contacts via query. Please refer to the Search section for detailed instructions.
The following search fields are supported:

  • id
  • name_1
  • name_2
  • nr
  • address
  • mail
  • mail_second
  • postcode
  • city
  • country_id
  • contact_group_ids
  • contact_type_id
  • updated_at
  • user_id
  • phone_fixed
  • phone_mobile
  • fax
Authorizations:
bearerAuth
query Parameters
order_by
string
Default: "id"
Enum: "id" "nr" "name_1" "updated_at"
Example: order_by=name_1

Defines the order of the results. Multiple sort parameters can be combined by using a comma separator. _asc and _desc can be appended to any parameter to either sort ascending (default) or descending.

limit
integer <int32>
Default: 500
Example: limit=20

Limit the number of results (max is 2000)

offset
integer <int32>
Default: 0
Example: offset=0

Skip over a number of elements by specifying an offset value for the query

show_archived
boolean
Default: false
Example: show_archived=true

Show archived elements only

header Parameters
Accept
required
string
Example: application/json
Request Body schema: application/json
required
Array
field
required
string <= 255 characters

Field which should be search over

value
required
string <= 255 characters

Value to search for

criteria
string (v2SearchCriteria)
Default: "like"
Enum: "=" "equal" "!=" "not_equal" ">" "greater_than" ">=" "greater_equal" "<" "less_than" "<=" "less_equal" "like" "not_like" "is_null" "not_null" "in" "not_in"

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Fetch a contact

This action fetches a single contact

Authorizations:
bearerAuth
path Parameters
contact_id
required
integer <int32>
Example: 1

the id of the contact

query Parameters
show_archived
boolean
Default: false
Example: show_archived=true

Show archived elements only

header Parameters
Accept
required
string
Example: application/json

Responses

Request samples

curl -X GET \
  https://api.bexio.com/2.0/contact/{contact_id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
application/json
{
  • "id": 4,
  • "nr": null,
  • "contact_type_id": 1,
  • "name_1": "Example Company",
  • "name_2": null,
  • "salutation_id": 2,
  • "salutation_form": null,
  • "title_id": null,
  • "birthday": null,
  • "address": "Smith Street 22",
  • "postcode": 8004,
  • "city": "Zurich",
  • "country_id": 1,
  • "mail": "contact@example.org",
  • "mail_second": "",
  • "phone_fixed": "",
  • "phone_fixed_second": "",
  • "phone_mobile": "",
  • "fax": "",
  • "url": "",
  • "skype_name": "",
  • "remarks": "",
  • "language_id": null,
  • "is_lead": false,
  • "contact_group_ids": "1,2",
  • "contact_branch_ids": null,
  • "user_id": 1,
  • "owner_id": 1,
  • "updated_at": "2019-04-08 13:17:32",
  • "profile_image": "R0lGODlhAQABAIAAAAUEBAAAACwAAAAAAQABAAACAkQBADs="
}

Edit a contact

This action edits a single contact

Authorizations:
bearerAuth
path Parameters
contact_id
required
integer <int32>
Example: 1

the id of the contact

header Parameters
Accept
required
string
Example: application/json
Request Body schema: application/json
nr
string or null

If set to null, the number will be assigned automatically. Must be a number, can also be used as integer

contact_type_id
required
integer

Please use the value 1 for companies or 2 for persons

name_1
required
string

This field is used as the company name if the field contact_type_id is set to 1. Otherwise, the field is used as the last name of the person

name_2
string or null

This field is used as the company addition if the field contact_type_id is set to 1. Otherwise, the field is used as the first name of the person

salutation_id
integer or null

References a salutation object

salutation_form
integer or null
titel_id
integer or null

References a title object

birthday
string or null <date>
address
string or null
postcode
string or null
city
string or null
country_id
integer or null

References a country object

mail
string or null <email>
mail_second
string or null <email>
phone_fixed
string or null
phone_fixed_second
string or null
phone_mobile
string or null
fax
string or null
url
string or null
skype_name
string or null
remarks
string or null
language_id
integer or null

References a language object

contact_group_ids
string or null

References one ore multiple contact group objects

contact_branch_ids
string or null

References one ore multiple contact sector objects

user_id
required
integer

References a user object

owner_id
required
integer

Responses

Request samples

Content type
application/json
{
  • "nr": null,
  • "contact_type_id": 1,
  • "name_1": "Example Company",
  • "name_2": null,
  • "salutation_id": 2,
  • "salutation_form": null,
  • "titel_id": null,
  • "birthday": null,
  • "address": "Smith Street 22",
  • "postcode": 8004,
  • "city": "Zurich",
  • "country_id": 1,
  • "mail": "contact@example.org",
  • "mail_second": "",
  • "phone_fixed": "",
  • "phone_fixed_second": "",
  • "phone_mobile": "",
  • "fax": "",
  • "url": "",
  • "skype_name": "",
  • "remarks": "",
  • "language_id": null,
  • "contact_group_ids": "1,2",
  • "contact_branch_ids": null,
  • "user_id": 1,
  • "owner_id": 1
}

Response samples

Content type
application/json
{
  • "id": 4,
  • "nr": null,
  • "contact_type_id": 1,
  • "name_1": "Example Company",
  • "name_2": null,
  • "salutation_id": 2,
  • "salutation_form": null,
  • "title_id": null,
  • "birthday": null,
  • "address": "Smith Street 22",
  • "postcode": 8004,
  • "city": "Zurich",
  • "country_id": 1,
  • "mail": "contact@example.org",
  • "mail_second": "",
  • "phone_fixed": "",
  • "phone_fixed_second": "",
  • "phone_mobile": "",
  • "fax": "",
  • "url": "",
  • "skype_name": "",
  • "remarks": "",
  • "language_id": null,
  • "is_lead": false,
  • "contact_group_ids": "1,2",
  • "contact_branch_ids": null,
  • "user_id": 1,
  • "owner_id": 1,
  • "updated_at": "2019-04-08 13:17:32",
  • "profile_image": "R0lGODlhAQABAIAAAAUEBAAAACwAAAAAAQABAAACAkQBADs="
}

Delete a contact

This action deletes a contact. Please note that a contact is marked as deleted and can still be accessed by using the "show deleted contacts" filter.

Authorizations:
bearerAuth
path Parameters
contact_id
required
integer <int32>
Example: 1

the id of the contact

header Parameters
Accept
required
string
Example: application/json

Responses

Request samples

curl -X DELETE \
  https://api.bexio.com/2.0/contact/{contact_id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
application/json
{
  • "success": true
}

Bulk create contacts

This action creates multiple contacts in one request

Authorizations:
bearerAuth
header Parameters
Accept
required
string
Example: application/json
Request Body schema: application/json
Array
nr
string or null

If set to null, the number will be assigned automatically. Must be a number, can also be used as integer

contact_type_id
required
integer

Please use the value 1 for companies or 2 for persons

name_1
required
string

This field is used as the company name if the field contact_type_id is set to 1. Otherwise, the field is used as the last name of the person

name_2
string or null

This field is used as the company addition if the field contact_type_id is set to 1. Otherwise, the field is used as the first name of the person

salutation_id
integer or null

References a salutation object

salutation_form
integer or null
titel_id
integer or null

References a title object

birthday
string or null <date>
address
string or null
postcode
string or null
city
string or null
country_id
integer or null

References a country object

mail
string or null <email>
mail_second
string or null <email>
phone_fixed
string or null
phone_fixed_second
string or null
phone_mobile
string or null
fax
string or null
url
string or null
skype_name
string or null
remarks
string or null
language_id
integer or null

References a language object

contact_group_ids
string or null

References one ore multiple contact group objects

contact_branch_ids
string or null

References one ore multiple contact sector objects

user_id
required
integer

References a user object

owner_id
required
integer

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Restore a contact

This action restores an archived contact.

Authorizations:
bearerAuth
path Parameters
contact_id
required
integer <int32>
Example: 1

the id of the contact

header Parameters
Accept
required
string
Example: application/json

Responses

Request samples

curl -X PATCH \
  https://api.bexio.com/2.0/contact/{contact_id}/restore \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
application/json
{
  • "success": true
}

Contact Relations

Fetch a list of contact relations

This action fetches a list of all contact relations

Authorizations:
bearerAuth
query Parameters
order_by
string
Default: "id"
Enum: "id" "contact_id" "contact_sub_id" "updated_at"
Example: order_by=contact_id

Defines the order of the results. Multiple sort parameters can be combined by using a comma separator. _asc and _desc can be appended to any parameter to either sort ascending (default) or descending.

limit
integer <int32>
Default: 500
Example: limit=20

Limit the number of results (max is 2000)

offset
integer <int32>
Default: 0
Example: offset=0

Skip over a number of elements by specifying an offset value for the query

header Parameters
Accept
required
string
Example: application/json

Responses

Request samples

curl -X GET \
  https://api.bexio.com/2.0/contact_relation \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
application/json
[
  • {
    }
]

Create contact relation

This action creates a new contact relation

Authorizations:
bearerAuth
header Parameters
Accept
required
string
Example: application/json
Request Body schema: application/json
required
contact_id
required
integer or null

References a contact object

contact_sub_id
required
integer or null

References a contact object

description
string or null

Responses

Request samples

Content type
application/json
{
  • "contact_id": 2,
  • "contact_sub_id": 3,
  • "description": ""
}

Response samples

Content type
application/json
{
  • "id": 4,
  • "nr": null,
  • "contact_type_id": 1,
  • "name_1": "Example Company",
  • "name_2": null,
  • "salutation_id": 2,
  • "salutation_form": null,
  • "title_id": null,
  • "birthday": null,
  • "address": "Smith Street 22",
  • "postcode": 8004,
  • "city": "Zurich",
  • "country_id": 1,
  • "mail": "contact@example.org",
  • "mail_second": "",
  • "phone_fixed": "",
  • "phone_fixed_second": "",
  • "phone_mobile": "",
  • "fax": "",
  • "url": "",
  • "skype_name": "",
  • "remarks": "",
  • "language_id": null,
  • "is_lead": false,
  • "contact_group_ids": "1,2",
  • "contact_branch_ids": null,
  • "user_id": 1,
  • "owner_id": 1,
  • "updated_at": "2019-04-08 13:17:32",
  • "profile_image": "R0lGODlhAQABAIAAAAUEBAAAACwAAAAAAQABAAACAkQBADs="
}

Search contact relations

Search contact relations via query. Please refer to the Search section for detailed instructions.
The following search fields are supported:

  • contact_id
  • contact_sub_id
  • updated_at
Authorizations:
bearerAuth
query Parameters
order_by
string
Default: "id"
Enum: "id" "contact_id" "contact_sub_id" "updated_at"
Example: order_by=contact_id

Defines the order of the results. Multiple sort parameters can be combined by using a comma separator. _asc and _desc can be appended to any parameter to either sort ascending (default) or descending.

limit
integer <int32>
Default: 500
Example: limit=20

Limit the number of results (max is 2000)

offset
integer <int32>
Default: 0
Example: offset=0

Skip over a number of elements by specifying an offset value for the query

header Parameters
Accept
required
string
Example: application/json
Request Body schema: application/json
required
Array
field
required
string <= 255 characters

Field which should be search over

value
required
string <= 255 characters

Value to search for

criteria
string (v2SearchCriteria)
Default: "like"
Enum: "=" "equal" "!=" "not_equal" ">" "greater_than" ">=" "greater_equal" "<" "less_than" "<=" "less_equal" "like" "not_like" "is_null" "not_null" "in" "not_in"

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Fetch a contact relation

This action fetches a single contact relation

Authorizations:
bearerAuth
path Parameters
contact_relation_id
required
integer <int32>
Example: 1

the id of the contact relation

header Parameters
Accept
required
string
Example: application/json

Responses

Request samples

curl -X GET \
  https://api.bexio.com/2.0/contact_relation/{contact_relation_id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
application/json
{
  • "id": 1,
  • "contact_id": 2,
  • "contact_sub_id": 3,
  • "description": "",
  • "updated_at": "2019-04-08 13:17:32"
}

Edit a contact relation

This action edits a single contact relation

Authorizations:
bearerAuth
path Parameters
contact_relation_id
required
integer <int32>
Example: 1

the id of the contact relation

header Parameters
Accept
required
string
Example: application/json
Request Body schema: application/json
contact_id
required
integer or null

References a contact object

contact_sub_id
required
integer or null

References a contact object

description
string or null

Responses

Request samples

Content type
application/json
{
  • "contact_id": 2,
  • "contact_sub_id": 3,
  • "description": ""
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "contact_id": 2,
  • "contact_sub_id": 3,
  • "description": "",
  • "updated_at": "2019-04-08 13:17:32"
}

Delete a contact relation

This action permanently deletes a contact relation. It cannot be undone.

Authorizations:
bearerAuth
path Parameters
contact_relation_id
required
integer <int32>
Example: 1

the id of the contact relation

header Parameters
Accept
required
string
Example: application/json

Responses

Request samples

curl -X DELETE \
  https://api.bexio.com/2.0/contact_relation/{contact_relation_id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
application/json
{
  • "success": true
}

Contact Groups

Fetch a list of contact groups

This action fetches a list of all contact groups

Authorizations:
bearerAuth
query Parameters
order_by
string
Default: "id"
Enum: "id" "name"
Example: order_by=name

Defines the order of the results. Multiple sort parameters can be combined by using a comma separator. _asc and _desc can be appended to any parameter to either sort ascending (default) or descending.

limit
integer <int32>
Default: 500
Example: limit=20

Limit the number of results (max is 2000)

offset
integer <int32>
Default: 0
Example: offset=0

Skip over a number of elements by specifying an offset value for the query

header Parameters
Accept
required
string
Example: application/json

Responses

Request samples

curl -X GET \
  https://api.bexio.com/2.0/contact_group \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
application/json
[
  • {
    }
]

Create contact group

This action creates a new contact group

Authorizations:
bearerAuth
header Parameters
Accept
required
string
Example: application/json
Request Body schema: application/json
required
name
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "Suppliers"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "Suppliers"
}

Search contact groups

Search contact groups via query. Please refer to the Search section for detailed instructions.
The following search fields are supported:

  • name
Authorizations:
bearerAuth
query Parameters
order_by
string
Default: "id"
Enum: "id" "name"
Example: order_by=name

Defines the order of the results. Multiple sort parameters can be combined by using a comma separator. _asc and _desc can be appended to any parameter to either sort ascending (default) or descending.

limit
integer <int32>
Default: 500
Example: limit=20

Limit the number of results (max is 2000)

offset
integer <int32>
Default: 0
Example: offset=0

Skip over a number of elements by specifying an offset value for the query

header Parameters
Accept
required
string
Example: application/json
Request Body schema: application/json
required
Array
field
required
string <= 255 characters

Field which should be search over

value
required
string <= 255 characters

Value to search for

criteria
string (v2SearchCriteria)
Default: "like"
Enum: "=" "equal" "!=" "not_equal" ">" "greater_than" ">=" "greater_equal" "<" "less_than" "<=" "less_equal" "like" "not_like" "is_null" "not_null" "in" "not_in"

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Fetch a contact group

This action fetches a single contact group

Authorizations:
bearerAuth
path Parameters
contact_group_id
required
integer <int32>
Example: 1

the id of the contact group

header Parameters
Accept
required
string
Example: application/json

Responses

Request samples

curl -X GET \
  https://api.bexio.com/2.0/contact_group/{contact_group_id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "Suppliers"
}

Edit a contact group

This action edits a single contact group

Authorizations:
bearerAuth
path Parameters
contact_group_id
required
integer <int32>
Example: 1

the id of the contact group

header Parameters
Accept
required
string
Example: application/json
Request Body schema: application/json
name
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "Suppliers"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "Suppliers"
}

Delete a contact group

This action permanently deletes a contact group. It cannot be undone.

Authorizations:
bearerAuth
path Parameters
contact_group_id
required
integer <int32>
Example: 1

the id of the contact group

header Parameters
Accept
required
string
Example: application/json

Responses

Request samples

curl -X DELETE \
  https://api.bexio.com/2.0/contact_group/{contact_group_id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
application/json
{
  • "success": true
}

Contact Sectors

Fetch a list of contact sectors

This action fetches a list of all contact sectors

Authorizations:
bearerAuth
query Parameters
order_by
string
Default: "id"
Enum: "id" "name"
Example: order_by=name

Defines the order of the results. Multiple sort parameters can be combined by using a comma separator. _asc and _desc can be appended to any parameter to either sort ascending (default) or descending.

limit
integer <int32>
Default: 500
Example: limit=20

Limit the number of results (max is 2000)

offset
integer <int32>
Default: 0
Example: offset=0

Skip over a number of elements by specifying an offset value for the query

header Parameters
Accept
required
string
Example: application/json

Responses

<