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

Find events for instalments which changed status

Request

Events for status changes of instalment bills only.

Security
X-API-Key
Query
lastEventSixIdstring

SIX ID of the last received event. If omitted, the result starts with the oldest available event. Example: "EVID967EFC95148C4533B803BE4897E9E490"

limitinteger(int32)<= 1000

Maximum number of items to be returned (technical maximum is 1000, no more will be returned).

Default 100
curl -i -X GET \
  'https://app.dibito.ch/api/v1/events/six/instalment-status-changed?lastEventSixId=string&limit=100' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Instalment status changed events found

Bodyapplication/jsonArray [
idinteger(int32)required

Event ID

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

SIX event ID

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

timestamp of the event

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

Business Case ID

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

business case SIX ID

Example: "BCID0FB909852BBC4D06AD8336AAE87D7FC9"
paymentByInstalmentsIdinteger(int32)required

PaymentByInstalments ID

Example: 12345
paymentByInstalmentsSixIdstring[ 1 .. 36 ] characters

external ID of the respective paymentByInstalment

Example: "298031-2999"
instalmentIdinteger(int32)required

Instalment ID

Example: 12345
instalmentSixIdstring[ 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(ApprovalAmountWithCurrency)
]
Response
application/json
[
  {
    "id": 12345,
    "sixId": "EVID82A65938766547EBBBA39BA6F7B07F24",
    "timestamp": "2015-01-01T10:00Z",
    "businessCaseId": 12345,
    "businessCaseSixId": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
    "paymentByInstalmentsId": 12345,
    "paymentByInstalmentsSixId": "298031-2999",
    "instalmentId": 12345,
    "instalmentSixId": "298031-2999-ACX01",
    "newStatus": "OPEN",
    "approvedAmount": { … }
  }
]

Find events for business cases which changed status

Request

Events for status changes of bills, reminders and donation inquiries.

Security
X-API-Key
Query
lastEventSixIdstring

SIX ID of the last received event. If omitted, the result starts with the oldest available event. Example: "EVID967EFC95148C4533B803BE4897E9E490"

limitinteger(int32)<= 1000

Maximum number of items to be returned (technical maximum is 1000, no more will be returned).

Default 100
curl -i -X GET \
  'https://app.dibito.ch/api/v1/events/six/business-case-status-changed?lastEventSixId=string&limit=100' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Business case status changed events found

Bodyapplication/jsonArray [
idinteger(int32)required

Event ID

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

SIX event ID

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

timestamp of the event

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

Business case ID

Example: 12345
businessCaseSixIdstring[ 0 .. 36 ] charactersBCID[0-9A-Z]{32}

Business Case SIX ID

Example: "BCID0FB909852BBC4D06AD8336AAE87D7FC9"
newStatusstring

the new status of the business case

Enum"OPEN""APPROVED""REJECTED""COMPLETED""CHARGEBACK_INITIATED"
approvedAmountobject(ApprovalAmountWithCurrency)
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

]
Response
application/json
[
  {
    "id": 12345,
    "sixId": "EVID82A65938766547EBBBA39BA6F7B07F24",
    "timestamp": "2015-01-01T10:00Z",
    "businessCaseId": 12345,
    "businessCaseSixId": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
    "newStatus": "OPEN",
    "approvedAmount": { … },
    "externalDonationPurposeId": "string"
  }
]

Find events for bill recipient subscriptions which changed status

Request

Security
X-API-Key
Query
lastEventSixIdstring

SIX ID of the last received event. If omitted, the result starts with the oldest available event. Example: "EVID967EFC95148C4533B803BE4897E9E490"

limitinteger(int32)<= 1000

Maximum number of items to be returned (technical maximum is 1000, no more will be returned).

Default 100
curl -i -X GET \
  'https://app.dibito.ch/api/v1/events/six/bill-recipient-subscription-status-changed?lastEventSixId=string&limit=100' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Bill recipient subscription changed events found

Bodyapplication/jsonArray [
idinteger(int32)required

Event ID

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

SIX Event ID

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

timestamp of the event

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

email address of the bill recipient

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

SIX 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(RecipientAddress)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(BillRecipientSubscriptionFormBillRecipientSubscriptionFormFields)
newStatusstring

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

Enum"INACTIVE""REQUESTED""ACTIVE"
]
Response
application/json
[
  {
    "id": 12345,
    "sixId": "EVID82A65938766547EBBBA39BA6F7B07F24",
    "timestamp": "2015-01-01T10:00Z",
    "billRecipient": { … },
    "accountNumber": "string",
    "referenceStructured": 1.2345612345678902e+26,
    "billRecipientSubscriptionFormFields": [ … ],
    "newStatus": "INACTIVE"
  }
]

Find events for bill recipients email address changes

Request

This event is triggered after a biller has submitted a business case with an outdated, so called historically available email address. It notifies about the changed email address of a bill recipient, which has been adjusted in eBill. An email address is considered to be historically available if it was present up to 15 months prior to the submission time. The billers are able to submit business cases with historically available email addresses of a bill recipient. However, latest 15 months after the email address changed, the billers are required to submit the business cases with the currently valid email address of the bill recipient.

Security
X-API-Key
Query
lastEventSixIdstring

SIX ID of the last received event. If omitted, the result starts with the oldest available event. Example: "EVID967EFC95148C4533B803BE4897E9E490"

limitinteger(int32)<= 1000

Maximum number of items to be returned (technical maximum is 1000, no more will be returned).

Default 100
curl -i -X GET \
  'https://app.dibito.ch/api/v1/events/six/bill-recipient-email-address-changed?lastEventSixId=string&limit=100' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Bill recipient email address changed events found

Bodyapplication/jsonArray [
idinteger(int32)required

Event ID

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

SIX event ID

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

business case SIX 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"
]
Response
application/json
[
  {
    "id": 12345,
    "sixId": "EVID82A65938766547EBBBA39BA6F7B07F24",
    "businessCaseId": 0,
    "businessCaseSixId": "BCID0FB909852BBC4D06AD8336AAE87D7FC9",
    "timestamp": "2015-01-01T10:00Z",
    "oldEmailAddress": "peter@muster.ch",
    "newEmailAddress": "peter_new@muster.ch"
  }
]

40 Webhook Management

Operations

90 PDF

Operations

98 Health Check

Operations

99 Authentication

Operations

webhooks

Webhooks

endpoint-controller

Operations