Skip to content

Dibito REST API (1.1)

The Dibito REST API provides services to submit, verify and deliver eBills. The API is designed to be used by biller integrations.
Please refer to the API tutorial for your first eBill submission.

API Key

This API requires an API key to be passed in the `X-API-Key` header.
Generate your API key in the Dibito application under "Dibito -> API Keys".

Top level overview

  • Create bills by posting either a QR-Invoice as PDF to the /v1/business-cases` endpoint or a fully populated JSON object to one of the business case type endpoints.
  • If the request succeeds, it passed validation and can be delivered to the eBill recipients.
  • Use the webhook endpoints to be notified about changes to your recipient subscriptions or business case statuses.

Referencing existing bills

If you pass one of the reference parameters or fill in the referenced bills section in your business case, the submitted eBill will:
  • In case of a reminder: Add a reminder to the eBill portal of the reciepient for the referenced bill.
  • In case of a donation inquiry: Will do nothing. Donation inquiries cannot be referenced.
  • In any other case: Replace the referenced bill with the new one in the eBill portal of the recipient. (Hint: Use advices to effectively cancel delivered eBills.)

Product Website

https://www.dibito.ch

Further Informations

Consult our documentation for further informations about creating and handling eBills.
Download OpenAPI description
api-docs.json
api-docs.yaml
Overview
URL

https://www.codeblock.ch

Codeblock GmbH

contact@codeblock.ch

Languages
Servers
Generated server url

https://app.dibito.ch/

00 Examples

Operations

10 Business Cases

Operations

20 Bill Recipients

Operations

21 Bill-Recipient Subscriptions

Operations

30 Events

Operations

31 SIX Events

Operations

40 Webhook Management

Operations

90 PDF

Operations

98 Health Check

Operations

99 Authentication

Operations

webhooks

Webhooks

Bill Recipient Email Address Changed EventWebhook

Request

Security
X-API-Key
Body*/*
idinteger(int32)required

Event ID

Example: 12345
externalIdstring[ 0 .. 36 ] charactersEVID[0-9A-Z]{32}required

external event ID

Example: "EVID82A65938766547EBBBA39BA6F7B07F24"
businessCaseIdinteger(int32)
businessCaseExternalIdstring[ 0 .. 36 ] charactersBCID[0-9A-Z]{32}required

business case ID

Example: "BCID0FB909852BBC4D06AD8336AAE87D7FC9"
timestampstring(date-time)required

timestamp of the event

Example: "2015-01-01T10:00Z"
oldEmailAddressstring[ 1 .. 256 ] characters

the old email address of the bill recipient which has been used in the submission of a business case

Example: "peter@muster.ch"
newEmailAddressstring[ 1 .. 256 ] characters

the new email address of the bill recipient

Example: "peter_new@muster.ch"
No request payload

Responses

Event received

Bill Recipient Subscription Status Changed EventWebhook

Request

Security
X-API-Key
Body*/*
idinteger(int32)required

Event ID

Example: 12345
externalIdstring[ 0 .. 36 ] charactersEVID[0-9A-Z]{32}required

Event ID

Example: "EVID82A65938766547EBBBA39BA6F7B07F24"
timestampstring(date-time)required

timestamp of the event

Example: "2015-01-01T10:00Z"
billRecipientobject(WebhookBillRecipient)required
billRecipient.​emailAddressstring[ 1 .. 256 ] characters

email address of the bill recipient

Example: "peter@muster.ch"
billRecipient.​billRecipientIdstring[ 1 .. 17 ] characters([0-9])*required

ID of the bill recipient

Example: 41010560425610180
billRecipient.​enterpriseIdentificationNumberstring[ 0 .. 12 ] charactersCHE[0-9]{9}

Swiss enterprise identification number (UID) without dashes, dots or extension. Note that this has to contain the swiss enterprise identification number (UID) from the commercial register (Handelsregister) which may be different from the VAT UID (Mehrwertsteuer UID).

Example: "CHE123456789"
billRecipient.​typestringrequired

the type of the bill recipient

Enum"PRIVATE""COMPANY"
billRecipient.​namestring[ 1 .. 70 ] charactersrequired

last name, if private bill recipient company name, if company bill recipient

Example: "for private bill recipient: Muster, for company name: Muster AG"
billRecipient.​firstNamestring[ 0 .. 35 ] characters

first name, if private bill recipient empty, if company bill recipient

Example: "Peter"
billRecipient.​correspondenceLanguagestring[ 1 .. 3 ] charactersrequired

language for correspondence with this bill recipient ISO-639-2/B

Example: "ger"
billRecipient.​addressobject(WebhookRecipientAddress)required
billRecipient.​address.​streetNamestring[ 1 .. 70 ] charactersrequired

street name

Example: "Neustadtstrasse"
billRecipient.​address.​postalCodestring[ 1 .. 9 ] charactersrequired

postal code

Example: 6025
billRecipient.​address.​citystring[ 1 .. 35 ] charactersrequired

city name

Example: "Neudorf"
billRecipient.​address.​countryCodestring[ 0 .. 2 ] characters[A-Z]{2}required

in format ISO 3166-1 alpha 2

Example: "CH"
accountNumberstring[ 0 .. 21 ] characters

Account number of the biller (e.g. iban), if provided from the financial institution

referenceStructuredstring[ 0 .. 27 ] characters([a-zA-Z0-9])*

QR or creditor reference number, if provided from the financial institution.

Example: 1.2345612345678902e+26
billRecipientSubscriptionFormFieldsArray of objects(WebhookBillRecipientSubscriptionFormBillRecipientSubscriptionFormFields)
newStatusstring

the new status of the bill recipient subscription, see "Subscriptions and subscription cancellations" for further information

Enum"INACTIVE""REQUESTED""ACTIVE"
No request payload

Responses

Event received

Business Case Status Changed EventWebhook

Request

Security
X-API-Key
Body*/*
idinteger(int32)required

Event ID

Example: 12345
externalIdstring[ 0 .. 36 ] charactersEVID[0-9A-Z]{32}required

External ID

Example: "EVID82A65938766547EBBBA39BA6F7B07F24"
timestampstring(date-time)required

timestamp of the event

Example: "2015-01-01T10:00Z"
businessCaseExternalIdstring[ 0 .. 36 ] charactersBCID[0-9A-Z]{32}

Business Case ID

Example: "BCID0FB909852BBC4D06AD8336AAE87D7FC9"
businessCaseIdinteger(int32)

Business case ID

Example: 12345
newStatusstring

the new status of the business case

Enum"OPEN""APPROVED""REJECTED""COMPLETED""CHARGEBACK_INITIATED"
approvedAmountobject(WebhookApprovalAmountWithCurrency)
externalDonationPurposeIdstring

optional field only to be used for donation inquiries to represent a potential selection of a donation purpose by the bill recipient, note the connection to the field externalDonationPurposeId from eBill business case specification

No request payload

Responses

Event received

Instalment Status Changed EventWebhook

Request

Security
X-API-Key
Body*/*
idinteger(int32)required

Event ID

Example: 12345
externalIdstring[ 0 .. 36 ] charactersEVID[0-9A-Z]{32}required

Event ID

Example: "EVID82A65938766547EBBBA39BA6F7B07F24"
timestampstring(date-time)required

timestamp of the event

Example: "2015-01-01T10:00Z"
businessCaseIdinteger(int32)

Business Case ID

Example: 12345
businessCaseExternalIdstring
paymentByInstalmentsIdinteger(int32)

Payment by instalments ID

Example: 12345
paymentByInstalmentsExternalIdstring[ 1 .. 36 ] characters

external ID of the respective paymentByInstalment

Example: "298031-2999"
instalmentIdinteger(int32)

Instalment ID

Example: 12345
instalmentExternalIdstring[ 1 .. 36 ] characters

external ID of the instalment

Example: "298031-2999-ACX01"
newStatusstring

the new status of the instalment

Enum"OPEN""APPROVED""REJECTED""COMPLETED""CHARGEBACK_INITIATED"
approvedAmountobject(WebhookApprovalAmountWithCurrency)
No request payload

Responses

Event received

Processing Status Changed EventWebhook

Request

Security
X-API-Key
Body*/*
idinteger(int32)required

Event ID

Example: 12345
timestampstring(date-time)required

timestamp of the event

Example: "2015-01-01T10:00Z"
businessCaseIdinteger(int32)

Business Case ID

newStatusstring
Enum"OPEN""INVALID""PROCESSING""FAILED""DELIVERED""DONE"
No request payload

Responses

Event received

endpoint-controller

Operations