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.
| Type | Description | URL |
|---|---|---|
| GET | Get list of printer slots | |
| GET | Get list of templates | /api/v1/templates |
| GET | Get name of API key | /api/v1/name |
| POST | Print letter with placeholders | /api/v1/templates/{template}/slots/{printIdentity}/print |
| POST | Print 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.