Die digitalePoststelle
Briefe online frankierenund versenden

Getting Started

You can easily access tybird using our printer driver, and you can integrate tybird with most web applications using our Zapier app. For advanced integration or automation tasks, we also offer a standards-based REST API.

Stability

All of our API endpoint URLs contain a version number ("v1"). We will try to keep our API as stable as possible by introducing new API versions if necessary.

Security & Authentication

All API requests and responses are secured using HTTPS to keep your information is safe. Note that you will receive an error when trying to use the API over unencrypted HTTP.

Our REST API uses API keys for authentication. You can create and manage API keys in your account settings.

Headers, Requests, Content-Types

 

All API endpoints require your API key to be sent in the HTTP Authorization header, specifically, tybird uses the standard Basic Authorization encoding. The username is always "apikey", and the password is your API key.

The reponse to all API requests is JSON data (Content-Type: application/json) and a HTTP status code.

An example API call using the curl tool

When using curl, pass -u 'apikey:YOURAPIKEY' to send the API key. The following call will return a list of all your printer slots in JSON format:

curl -u 'apikey:9e3cb68b-6741-4496-85cf-818a8d6a7a1b' 'https://api.tybird.com/api/v1/slots'

Function overview

The base URL of all API endpoints is api.tybird.com/api/v1.

 

TypeDescriptionURL
GETGet list of printer slots
GETGet list of templates/api/v1/templates
GETGet name of API key/api/v1/name
POSTPrint letter with placeholders/api/v1/templates/{template}/slots/{printIdentity}/print
POSTPrint PDF document/api/v1/slots/{slot}/print_file

API: Getting information

Get list of printer slots

Admin users can configure print identities and their visibility for each user account. The print identities assigned to you will show up in your (virtual) printer as printer slots.

GET api.tybird.com/api/v1/slots

Authentication: Send "apikey:YOURAPIKEY" as HTTP Basic Auth in the Authorization header.

Result: JSON data listing the visible slots.

{"slots":[
          {"id":5,"name":"Buchhaltung (duplex, sw)"},
   {"id":18,"name":"Testbriefe (noduplex, color)"}
]}

HTTP status codes:

200 OK.
403 API key error.
500 Other error. See JSON field 'message' for details.

Get list of letter templates

Admin users can configure letter templates that contain placeholders. See below for the API call that creates a print job using a template.

This API endpoint lets you list all letter templates available for the current user.

GET api.tybird.com/api/v1/templates

Authentication: Send "apikey:YOURAPIKEY" as HTTP Basic Auth in the Authorization header.

Result: JSON data listing available letter templates.

Example of result:

{"templates":[
   {"id":1,
     "name":"acknowledge the receipt",
     "placeholders":{
          "mandatory":["SALUTATION",
                       "DOCUMENTSLIST",
                       "SIGNATURE",
                       "fullname",
                       "street",
                       "zip",
                       "city"],
          "optional":["country",
                      "street2"]
      }},
   {"id":3,
    "name":"Happy Birthday",
    "placeholders":{
          "mandatory":["SALUTATION",
                       "CODE",
                       "fullname",
                       "street",
                       "zip",
                       "city"],
          "optional":["country",
                      "street2"]}}
]}

HTTP status codes:

200 OK.
403 API key error.
500 Other error. See JSON field 'message' for details.

Get name of API key

Each API key can have a name. This name can be fetched using this API call to enable external services to display the name of the current API key.

The returned name is prefixed with "tybird: ". If there is no associated name, it is replaced by "Account" in the function call result.

GET api.tybird.com/api/v1/name

Authentication: Send "apikey:YOURAPIKEY" as HTTP Basic Auth in the Authorization header.

Result: JSON data listing the associated name.

If there is a associated name:

   {"name": "tybird: Zapier integration"}

 

If there is no associated name:
   {"name": "tybird: Account"}

HTTP status codes:

200 OK.
403 API key error.
500 Other error. See JSON field 'message' for details.

API: Sending letters

Print a letter by filling in placeholders

Admin users can create letter templates where only a few short placeholders have to be provided in order to create a print job.

Before calling this API, you should retrieve the ID of both the template and the printer slot using the API functions listed above. The endpoint for listing letter templates will also return information about which placeholders apply to each letter template, and which placeholders are mandatory.

POST https://api.tybird.com/api/v1/templates/{template}/slots/{slot}/print

Parameters:

  • {template}: ID of the letter template
  • {slot}: ID of the virtual printer slot (also kown as print identity)

Authentication: Send "apikey:YOURAPIKEY" as HTTP Basic Auth in the Authorization header.

POST data:

  • A single JSON object the values for each placeholder: {"fullname":"Isa Musterfrau","street":"Hauptstraße 12b",...}

Pre-defined placeholders for the address:

The following values are needed to construct the address field. Every letter template supports these placeholders, plus any additional user-defined placeholders.

  • fullname: Full name of the recipient.
  • street: Street address.
  • street2: (Optional) Second street line.
  • zip: Zip code (Postleitzahl) of the destination city.
  • city: Destination city.
  • country: (optional) Destination country. The default is Germany.

Result: A JSON object with the ID of the created document.

{"documentId":59}

HTTP status codes:

200 OK.
403 API key error.
500 Other error. See JSON field 'message' for details.

 

Print PDF document

You can upload a PDF file to send it as a letter. The file has to be a business letter according to DIN 5008 (Type B) with the address printed on the first page.

Before calling this API endpoint, you should find the ID of your printer slot as shown above.

POST api.tybird.com/api/v1/slots/{slot}/print_file

Parameters:

  • {slot} : Id of the virtual printer slot (also kown as print identity)

Authentication: Send "apikey:YOURAPIKEY" as HTTP Basic Auth in the Authorization header.

POST data: This endpoint accepts data in the common form-data/multipart format. The data must only contain a single file upload. You can create a print job using curl by passing the following option: -F "pdf=@/local/filename.pdf"

Result: A JSON object with the ID of the created document.

{"documentId":23423}

HTTP status codes:

200 OK.
403 API key error.
500 Other error. See JSON field 'message' for details.