NAV
shell php ruby python

Introduction

Welcome to the Bilendo API! You can use our API to access Bilendo API endpoints.

Environments

Development and Test

You can register a new Developer account at s01.bilendo.de

The API-Endpoints for this environment all start with https://s01.bilendo.de

Production

If you want to use our API in production mode, please contact us at developer@bilendo.de

Authentication

Request

curl -X "GET" "https://s01.bilendo.de/" \
    -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN",
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  # Create Request
  req = Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field 'Authorization', 'Token token=YOUR-API-TOKEN'

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests

try:
    response = requests.get(
        url="https://s01.bilendo.de/",
        headers={
            "Authorization": "Token token=YOUR-API-TOKEN",
        }
    )
    print('Response HTTP Status Code: {status_code}'.format(
        status_code=response.status_code))
    print('Response HTTP Response Body: {content}'.format(
        content=response.content))
except requests.exceptions.RequestException:
    print('HTTP Request failed')

Bilendo uses API tokens to allow access to the API. You can get your API-Token in your Bilendo-Account under your account settings.

Once you have your token, you must include it with Bilendo API requests as the HTTP headers.

Header name Header value
Authorization Token token=YOUR-API-TOKEN

Note that all API requests are made over SSL (HTTPS).

Customers

Customer Object

{
  "id": "<customer-id>",
  "external_id": "<your-customer-id>",
  "customer_number": "100001",
  "name": "Company Inc.",
  "address": "Company Inc.\nSome Street 1\n12345 City\nCountry",
  "stop_automatic_reminders": false,
  "shipping_mode": "email",
  "customer_group_id": "<customer-group-id>",
  "note": "Lorem Ipsum",
  "created_at": "2016-01-19T08:42:48+01:00",
  "updated_at": "2016-01-19T08:42:48+01:00",
  "contacts": [
    {
      "id": "<contact-id>",
      "external_id": "<your-contact-id>",
      "name": "John Smith",
      "gender": 1,
      "salutation": 0,
      "email": "john@doe.de",
      "created_at": "2016-01-18T13:53:06+01:00",
      "updated_at": "2016-01-18T13:53:06+01:00"
    }
  ]
}
Attribute type Description
id string Bilendo id of the ustomer
external_id string your id of the customer
customer_number string optional customer number
name string name of the customer
address string customer’s full address starting with the customer name. Lines separated by \n
stop_automatic_reminder boolean prevents automatic reminders
shipping_mode string shipping methods with values:
email
post
dual_shipping (email & post simultaneously)
unknown
We default to the company shipping mode settings if empty.
customer_group_id string the customer’s group id
note string optional note
created_at datetime datetime of creation
updated_at datetime datetime of last update
contacts array all contacts for this customer

Create new Customer

Request

curl -X "POST" "https://s01.bilendo.de/api/v1/customers" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \
  -d "name=Example Inc." \
  -d "external_id=<your-customer-id>" \
  -d "address_line1=Example Inc." \
  -d "address_line2=John Smith" \
  -d "address_line3=Some Street 1" \
  -d "address_line4=Backyard" \
  -d "zip=13245" \
  -d "city=City" \
  -d "country_code=DE" \
  -d "customer_number=1000123" \
  -d "note=Lorem Ipsum" \
  -d "customer_group_id=<customer-group-id>" \
  -d "stop_automatic_reminders=false" \
  -d "shipping_mode=email" \
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/customers');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN",
  "Content-Type: application/x-www-form-urlencoded"
 ]
);
// Create body
$body = [
  "name"                     => "Example Inc.",
  "address_line1"            => "Example Inc.",
  "address_line2"            => "John Smith",
  "address_line3"            => "Some Street 1",
  "address_line4"            => "Backyard",
  "zip"                      => "13245",
  "city"                     => "City",
  "country_code"             => "DE",
  "note"                     => "Lorem Ipsum",
  "stop_automatic_reminders" => "false",
  "customer_number"          => "1000123",
  "external_id"              => "<your-customer-id>",
  "shipping_mode"            => "email",
  "customer_group_id"        => "<customer-group-id>"
  ];
$body = http_build_query($body);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/customers')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  data = {
    "name"                     => "Example Inc.",
    "address_line1"            => "Example Inc.",
    "address_line2"            => "John Smith",
    "address_line3"            => "Some Street 1",
    "address_line4"            => "Backyard",
    "zip"                      => "13245",
    "city"                     => "City",
    "country_code"             => "DE",
    "note"                     => "Lorem Ipsum",
    "stop_automatic_reminders" => "false",
    "customer_number"          => "1000123",
    "external_id"              => "<your-customer-id>",
    "shipping_mode"            => "email",
    "customer_group_id"        => "<customer-group-id>"
  }
  body = URI.encode_www_form(data)

  # Create Request
  req =  Net::HTTP::Post.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"
  # Set header and body
  req.body = body

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.post(
    url = "https://s01.bilendo.de/api/v1/customers",
    headers = {
      "Authorization": "Token token=YOUR-API-TOKEN"
    },
    data = {
      "name":                     "Example Inc.",
      "address_line1":            "Example Inc.",
      "address_line2":            "John Smith",
      "address_line3":            "Some Street 1",
      "address_line4":            "Backyard",
      "zip":                      "13245",
      "city":                     "City",
      "country_code":             "DE",
      "note":                     "Lorem Ipsum",
      "stop_automatic_reminders": "false",
      "customer_number":          "1000123",
      "external_id":              "<your-customer-id>",
      "shipping_mode":            "email",
      "customer_group_id":        "<customer-group-id>"
    }
  )
  print('Response HTTP Status Code: {status_code}'.format(
    status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
    content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "id": "<customer-id>",
  "external_id": "<your-customer-id>",
  "customer_number": "1000123",
  "name": "Example Inc.",
  "address": "Example Inc.\nJohn Smith\nSome Street 1\n12345 City\nDeutschland",
  "stop_automatic_reminders": false,
  "shipping_mode": "email",
  "note": "Lorem Ipsum",
  "customer_group_id": "<customer-group-id>",
  "created_at": "2016-01-19T08:42:48+01:00",
  "updated_at": "2016-01-19T08:42:48+01:00",
  "contacts": []
}
Parameter type Description
name mandatory name of the customer
address_line1 mandatory customer’s address line 1 (customer name)
address_line2 optional customer’s address line 2 (contact name)
address_line3 mandatory customer’s address line 3 (street and house number)
address_line4 optional customer’s address line 4 (additional address)
zip mandatory customer’s zip code
city mandatory customer’s city
country_code mandatory customer’s country isocode
customer_number optional Customer number
external_id optional your customer id
customer_group_id optional customer’s group id
stop_automatic_reminder optional Prevents automatic reminders
shipping_mode optional shipping methods with values:
email
post
dual_shipping (email & post simultaneously)
unknown
We default to the company shipping mode settings if empty.
note optional note

API Endpoint

POST https://s01.bilendo.de/api/v1/customers

Update existing Customer

Request

curl -X "PATCH" "https://s01.bilendo.de/api/v1/customers/<customer-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \
  -d "name=New Companyname Inc." \
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/customers/<customer-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);
// Create body
$body = [
  "name" => "New Companyname Inc."
  ];
$body = http_build_query($body);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/customers/<customer-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  data = {
    "name" => "New Companyname Inc."
  }
  body = URI.encode_www_form(data)

  # Create Request
  req =  Net::HTTP::Patch.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"
  # Set header and body
  req.body = body

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.patch(
      url = "https://s01.bilendo.de/api/v1/customers/<customer-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      },
      data = {
          "name": "New Companyname Inc."
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "id": "<customer-id>",
  "external_id": "<your-customer-id>",
  "customer_number": "1000123",
  "name": "New Companyname Inc.",
  "address": "New Companyname Inc.\nJohn Smith\nSome Street 1\n12345 City\nDeutschland",
  "stop_automatic_reminders": false,
  "shipping_mode": "email",
  "customer_group_id": "<customer-group-id>",
  "note": "Lorem Ipsum",
  "created_at": "2016-01-19T08:42:48+01:00",
  "updated_at": "2016-01-19T08:42:48+01:00",
  "contacts": []
}

API Endpoint

PATCH https://s01.bilendo.de/api/v1/customers/<customer-id>

Get All Customers

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/customers" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/customers');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/customers')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.get(
      url = "https://s01.bilendo.de/api/v1/customers",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "customers":[
    {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Example Inc.",
      "customer_number": "100001",
      "address": "Example Inc.\nJohn Smith\nSome Street 1\n12345 City\nDeutschland",
      "stop_automatic_reminders": false,
      "shipping_mode": "email",
      "customer_group_id": "<customer-group-id>",
      "note": "Lorem Ipsum",
      "created_at": "2016-01-19T08:42:48+01:00",
      "updated_at": "2016-01-19T08:42:48+01:00",
      "contacts": [
        {
          "id": "<contact-id>",
          "external_id": "<your-contact-id>",
          "name": "John Smith",
          "gender": 1,
          "salutation": 0,
          "email": "john@doe.de",
          "created_at": "2016-01-18T13:53:06+01:00",
          "updated_at": "2016-01-18T13:53:06+01:00"
        }
      ]
    }, {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Example Inc. 2",
      "customer_number": "100002",
      "address": "Example Inc. 2\nSome Street 2\n54321 City\nDeutschland",
      "stop_automatic_reminders": false,
      "shipping_mode": "email",
      "customer_group_id": "<customer-group-id>",
      "note": "Lorem Ipsum",
      "created_at": "2016-01-19T08:42:48+01:00",
      "updated_at": "2016-01-19T08:42:48+01:00",
      "contacts": [
        {
          "id": "<contact-id>",
          "external_id": "<your-contact-id>",
          "name": "John",
          "gender": 1,
          "salutation": 0,
          "email": "john@bilendo.de",
          "created_at": "2016-01-18T13:53:06+01:00",
          "updated_at": "2016-01-18T13:53:06+01:00"
        }
      ]
    },
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "per_page": 30,
    "total_count": 2
  }
}

Filter

You can use our pagingation if you set a page parameter

URL-Parameter Description
page number of requested page

Meta

Attribute type Description
current_page integer the current page
next_page integer the next page or null
prev_page integer previous page or null
total_pages integer the number of pages
per_page integer how many items per page
total integer how many items

API Endpoint

GET https://s01.bilendo.de/api/v1/customers

Get a specific Customer

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/customers/<customer-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/customers/<customer-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/customers/<customer-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests

try:
  response = requests.get(
      url = "https://s01.bilendo.de/api/v1/customers/<customer-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "id": "<customer-id>",
  "external_id": "<your-customer-id>",
  "customer_number": "100001",
  "name": "Example Inc.",
  "address": "Example Inc.\nJohn Smith\nSome Street 1\n12345 City\nDeutschland",
  "stop_automatic_reminders": false,
  "shipping_mode": "email",
  "customer_group_id": "<customer-group-id>",
  "note": "Lorem Ipsum",
  "created_at": "2016-01-19T08:42:48+01:00",
  "updated_at": "2016-01-19T08:42:48+01:00",
  "contacts": [
    {
      "id": "<contact-id>",
      "external_id": "<your-contact-id>",
      "name": "John Smith",
      "gender": 1,
      "salutation": 0,
      "email": "john@doe.de",
      "created_at": "2016-01-18T13:53:06+01:00",
      "updated_at": "2016-01-18T13:53:06+01:00"
    }
  ]
}

Api Endpoint

GET https://s01.bilendo.de/api/v1/customers/<customer-id>

Find a specific Customer

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/customers/find/<your-customer-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/customers/find/<your-customer-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/customers/find/<your-customer-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.get(
      url = "https://s01.bilendo.de/api/v1/customers/find/<your-customer-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "id": "<customer-id>",
  "external_id": "<your-customer-id>",
  "customer_number": "100001",
  "name": "Example Inc.",
  "address": "Example Inc.\nJohn Smith\nSome Street 1\n12345 City\nDeutschland",
  "stop_automatic_reminders": false,
  "shipping_mode": "email",
  "customer_group_id": "<customer-group-id>",
  "note": "Lorem Ipsum",
  "created_at": "2016-01-19T08:42:48+01:00",
  "updated_at": "2016-01-19T08:42:48+01:00",
  "contacts": [
    {
      "id": "<contact-id>",
      "external_id": "<your-contact-id>",
      "name": "John Smith",
      "gender": 1,
      "salutation": 0,
      "email": "john@doe.de",
      "created_at": "2016-01-18T13:53:06+01:00",
      "updated_at": "2016-01-18T13:53:06+01:00"
    }
  ]
}

Api Endpoint

GET https://s01.bilendo.de/api/v1/customers/find/<your-customer-id>

Contacts

Contact Object

{
  "contact": {
    "id": "<contact-id>",
    "external_id": "<your-contact-id>",
    "name": "John",
    "gender":1,
    "salutation":0,
    "salutation_text": "Sehr geehrter Herr John",
    "email": "john@bilendo.de",
    "created_at": "2016-01-18T13:53:06+01:00",
    "updated_at": "2016-01-18T13:53:06+01:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc.",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    }
  }
}
Attribute type Description
id string Bilendo id of the contact
external_id string your id of the contact
name string name of the contact
gender integer 0 = unknown
1 = male
2 = female
salutation integer 0 = formal
1 = informal
salutation text string 0 = “Sehr geehrter Herr #{name}”;
“Sehr geehrter Frau #{name}”;
“Sehr geehrte Damen und Herren” (if a name missing)
1 = “Hallo #{name}”
email string email
customer_id string the customer id

Create new Contact

Request

curl -X "POST" "https://s01.bilendo.de/api/v1/contacts" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \
  -d "name=John" \
  -d "external_id=<your-contact-id>" \
  -d "gender=1" \
  -d "salutation=1" \
  -d "customer_id=<customer-id>" \
  -d "customer[external_id]=<your-customer-id>" \
  -d "email=john@bilendo.de" \
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/contacts');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN",
  "Content-Type: application/x-www-form-urlencoded"
 ]
);
// Create body
$body = [
  "name" => "John",
  "external_id" => "<your-contact-id>",
  "gender" => "1",
  "salutation" => "1",
  "customer_id" => "<customer-id>",
  "customer[external_id]" => "<your-customer-id>",
  "email" => "john@bilendo.de"
];
$body = http_build_query($body);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'
begin
  uri = URI('https://s01.bilendo.de/api/v1/contacts')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  data = {
    "name" => "John",
    "external_id" => "<your-contact-id>",
    "gender" => "1",
    "salutation" => "1",
    "customer_id" => "<customer-id>",
    "customer[external_id]" => "<your-customer-id>",
    "email" => "john@bilendo.de"
  }
  body = URI.encode_www_form(data)

  # Create Request
  req =  Net::HTTP::Post.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"
  # Set header and body
  req.body = body

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests

try:
  response = requests.post(
      url = "https://s01.bilendo.de/api/v1/contacts",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      },
      data = {
          "name": "John",
          "external_id": "<your-contact-id>",
          "gender": "1",
          "salutation": "1",
          "customer_id": "<customer-id>",
          "customer[external_id]": "<your-customer-id>",
          "email": "john@bilendo.de"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "contact": {
    "id": "<contact-id>",
    "external_id": "<your-contact-id>",
    "name": "John",
    "gender":1,
    "salutation":1,
    "salutation_text": "Hallo John",
    "email": "john@bilendo.de",
    "created_at": "2016-01-18T13:53:06+01:00",
    "updated_at": "2016-01-18T13:53:06+01:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc.",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    }
  }
}
Parameter type Description
name mandatory name of the contact
gender mandatory 0 = unknown
1 = male
2 = female
external_id optional your contact id
salutation mandatory 0 = formal
1 = informal
email optional email
customer_id or
customer[external_id]
mandatory bilendo-customer-id
your-customer-id

API Endpoint

POST https://s01.bilendo.de/api/v1/contacts

Update existing Contact

Request

curl -X "PATCH" "https://s01.bilendo.de/api/v1/contacts/<contact-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \
  -d "name=New name" \
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/contacts/<contact-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);
// Create body
$body = [
  "name" => "New name"
  ];
$body = http_build_query($body);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/contacts/<contact-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  data = {
    "name" => "New name"
  }
  body = URI.encode_www_form(data)

  # Create Request
  req =  Net::HTTP::Patch.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"
  # Set header and body
  req.body = body

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests

try:
  response = requests.patch(
      url = "https://s01.bilendo.de/api/v1/contacts/<contact-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      },
      data = {
          "name": "New name"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "contact": {
    "id": "<contact-id>",
    "external_id": "<your-contact-id>",
    "name": "New name",
    "gender":1,
    "salutation":1,
    "salutation_text": "Hallo John",
    "email": "john@bilendo.de",
    "created_at": "2016-01-18T13:53:06+01:00",
    "updated_at": "2016-01-18T13:53:06+01:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc.",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    }
  }
}

API Endpoint

PATCH https://s01.bilendo.de/api/v1/contacts/<contact-id>

Get a specific Contact

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/contacts/<contact-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/contacts/<contact-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/contacts/<contact-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests

try:
  response = requests.get(
      url = "https://s01.bilendo.de/api/v1/contacts/<contact-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "contact": {
    "id": "<contact-id>",
    "external_id": "<your-contact-id>",
    "name": "New name",
    "gender":1,
    "salutation":1,
    "salutation_text": "Hallo John",
    "email": "john@bilendo.de",
    "created_at": "2016-01-18T13:53:06+01:00",
    "updated_at": "2016-01-18T13:53:06+01:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc.",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    }
  }
}

Api Endpoint

GET https://s01.bilendo.de/api/v1/contacts/<contact-id>

Find a specific Contact

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/contacts/find/<your-contact-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/contacts/find/<your-contact-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/contacts/find/<your-contact-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests

try:
  response = requests.get(
      url = "https://s01.bilendo.de/api/v1/contacts/find/<your-contact-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN",
      },
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "contact": {
    "id": "<contact-id>",
    "external_id": "<your-contact-id>",
    "name": "New name",
    "gender":1,
    "salutation":1,
    "salutation_text": "Hallo John",
    "email": "john@bilendo.de",
    "created_at": "2016-01-18T13:53:06+01:00",
    "updated_at": "2016-01-18T13:53:06+01:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc.",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    }
  }
}

Api Endpoint

GET https://s01.bilendo.de/api/v1/contacts/find/<your-contact-id>

Invoices

Invoice Object

{
  "invoice": {
    "id": "<invoice-id>",
    "external_id": "<your-invoice-id>",
    "invoice_status": "draft",
    "invoice_number": "400001",
    "additional_number": "300001",
    "total": "606.9",
    "invoice_date": "2014-04-16",
    "due_date": "2014-04-30",
    "time_for_payment": 14,
    "shipping_mode": "email",
    "open_amount": "0.0",
    "created_at": "2016-01-14T11:13:55+01:00",
    "updated_at": "2016-01-18T13:53:32+01:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    },
    "contact": {
      "id": "<contact-id>",
      "external_id": "<your-contact-id>",
      "name": "John Smith",
      "gender":1,
      "salutation":1,
      "email": "john@bilendo.de",
      "created_at": "2016-01-18T13:53:06+01:00",
      "updated_at": "2016-01-18T13:53:06+01:00"
    },
    "payments": [
      {
        "id": "<payment-id>",
        "external_id": "<your-payment-id>",
        "amount": "606.9",
        "payment_date": "2015-12-01",
        "name": "Company Inc",
        "purpose": "Payment Purpose",
        "account_number": "DE123456789",
        "bank_code": "BIC",
        "bank_name": "Example-Bank",
        "note": "Lorem Ipsum",
        "created_at": "2016-04-04T14:53:10+02:00",
        "updated_at": "2016-04-04T14:53:10+02:00"
      }
    ]
  }
}
Attribute Type Description
id string Bilendo id of the invoice
external_id string your id of the invoice
invoice_status string see table below
invoice_number string invoice number
additional_number string any additional number or id (ex: order number)
total decimal gross value
invoice_date date invoice date
due_date date due date
time_for_payment integer difference between invoice_date and due_date
shipping_mode string shipping methods with values:
email
post
dual_shipping (email & post simultaneously)
skip_shipping
unknown
We default to the customer shipping mode settings if empty.
open_amount decimal open amount
customer customer the customer
contact contact the contact

Possible values for invoice_status

Value Description
archived invoice is archived
draft invoice is a draft
sent invoice was sent
due invoice is due
ready_for_reminder1 invoice is due and you should send a first reminder
reminder1_sent first reminder was sent
ready_for_reminder2 invoice is due and you should send a second reminder
reminder2_sent second reminder was sent
ready_for_reminder3 invoice is due and you should send a third reminder
reminder3_sent third reminder was sent
paid invoice is paid
duplicate invoice is a duplicate

Create new Invoice

Request

curl -X "POST" "https://s01.bilendo.de/api/v1/invoices" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "invoice=@invoice.pdf" \
  -F "external_id=<your-invoice-id>" \
  -F "customer_id=<customer-id>" \
  -F "contact_id=<contact-id>" \
  -F "invoice_number=400001" \
  -F "additional_number=300001" \
  -F "total=606.9" \
  -F "invoice_date=01.12.2015" \
  -F "time_for_payment=14" \
  -F "due_date=15.12.2015" \
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'http://localhost:3000/api/v1/invoices');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

// Set secure upload
curl_setopt($ch, CURLOPT_SAFE_UPLOAD, 1);

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Create body
$body = [
  "invoice"           => new CurlFile('invoice.pdf', 'application/pdf'),
  "external_id"       => "<your-invoice-id>",
  "customer_id"       => "<customerid>",
  "contact_id"        => "<contact-id>",
  "invoice_number"    => "400001",
  "additional_number" => "300001",
  "total"             => 606.9,
  "invoice_date"      => "01.12.2015",
  "time_for_payment"  => 14,
  "due_date"          => "15.12.2015"
  ];

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'
require 'net/http/post/multipart'

begin
  uri = URI('https://s01.bilendo.de/api/v1/invoices')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  body = {
    'invoice'           => UploadIO.new(File.new('invoice.pdf'), 'application/pdf'),
    'external_id'       => '<your-invoice-id>',
    'customer_id'       => '<customerid>',
    'contact_id'        => '<contact-id>',
    'invoice_number'    => '400001',
    'additional_number' => '300001',
    'total'             =>  606.9,
    'invoice_date'      => '01.12.2015',
    'time_for_payment'  =>  14,
    'due_date'          => '15.12.2015'
  }

  # Create Request
  req = Net::HTTP::Post::Multipart.new(uri, body)
  # Add headers
  req.add_field 'Authorization', 'Token token=YOUR-API-TOKEN'

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests
try:
    response = requests.post(
        url = 'https://s01.bilendo.de/api/v1/invoices',
        headers = {
            'Authorization': 'Token token=YOUR-API-TOKEN'
        },
        files = {
            'invoice': open('invoice.pdf', 'rb')
        },
        data = {
            'external_id':       '<your-invoice-id>',
            'customer_id':       '<customerid>',
            'contact_id':        '<contact-id>',
            'invoice_number':    '400001',
            'additional_number': '300001',
            'total':              606.9,
            'invoice_date':      '01.12.2015',
            'time_for_payment':   14,
            'due_date':          '15.12.2015'
        }
    )
    print('Response HTTP Status Code: {status_code}'.format(
        status_code=response.status_code))
    print('Response HTTP Response Body: {content}'.format(
        content=response.content))
except requests.exceptions.RequestException:
    print('HTTP Request failed')

Response

{
  "invoice": {
    "id": "<invoice-id>",
    "external_id": "<your-invoice-id>",
    "invoice_status": "draft",
    "invoice_number": "400001",
    "additional_number": "300001",
    "total": "606.9",
    "invoice_date": "2015-12-01",
    "due_date": "2015-12-15",
    "time_for_payment": 14,
    "shipping_mode": "email",
    "open_amount": "0.0",
    "created_at": "2016-01-14T11:13:55+01:00",
    "updated_at": "2016-01-18T13:53:32+01:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    },
    "contact": {
      "id": "<contact-id>",
      "external_id": "<your-contact-id>",
      "name": "John Smith",
      "gender":1,
      "salutation":1,
      "email": "john@bilendo.de",
      "created_at": "2016-01-18T13:53:06+01:00",
      "updated_at": "2016-01-18T13:53:06+01:00"
    },
    "payments": []
  }
}
Parameter Type Description
invoice mandatory PDF-File
external_id optional your invoice id
customer_id optional bilendo customer_id
contact_id optional bilendo contact_id
invoice_number optional invoice number
additional_number optional any additional number or id (ex: order number)
total optional gross value
invoice_date optional invoice date
due_date optional due date
time_for_payment optional difference between invoice_date and due_date

API Endpoint

POST https://s01.bilendo.de/api/v1/invoices

Create new Invoice (Extended)

Request

curl -X "POST" "https://s01.bilendo.de/api/v1/invoices" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "customer[name]=New Company Inc" \
  -d "customer[address_line1]=New Company Inc" \
  -d "customer[address_line2]=John Smith" \
  -d "customer[address_line3]=Some Street 2" \
  -d "customer[address_line4]=Backyard" \
  -d "customer[zip]=54321" \
  -d "customer[city]=City" \
  -d "customer[country_code]=DE" \
  -F "customer[customer_number]=123654" \
  -F "customer[external_id]=<your-customer-id>" \
  -F "customer[stop_automatic_reminders]=false" \
  -F "customer[shipping_mode]=email" \
  -F "customer[customer_group_id]=<customers-group-id>" \
  -F "customer[note]=Lorem Ipsum"\
  -F "contact[name]=John Smith" \
  -F "contact[gender]=1" \
  -F "contact[salutation]=1" \
  -F "contact[email]=smith@email.com" \
  -F "contact[external_id]=<your-contact-id>" \
  -F "customer_id=<customer-id>" \ # Do not provide when creating a new customer
  -F "contact_id=<contact-id>" \ # Do not provide when creating a new contact
  -F "invoice=@invoice.pdf" \
  -F "external_id=<your-invoice-id>" \
  -F "invoice_number=400001" \
  -F "additional_number=300001" \
  -F "total=606.9" \
  -F "invoice_date=01.12.2015" \
  -F "time_for_payment=14" \
  -F "due_date=15.12.2015" \
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/invoices');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

// Set secure upload
curl_setopt($ch, CURLOPT_SAFE_UPLOAD, 1);

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Token token=YOUR-API-TOKEN'
 ]
);
// Create body
$body = [
    'invoice'                            => new CurlFile('invoice.pdf', 'application/pdf'),
    'customer[name]'                     => 'New Company Inc.',
    'customer[address_line1]'            => 'New Company Inc.',
    'customer[address_line2]'            => 'John Smith',
    'customer[address_line3]'            => 'Some Street 2',
    'customer[address_line4]'            => 'Backyard',
    'customer[zip]'                      => '54321',
    'customer[city]'                     => 'City',
    'customer[country_code]'             => 'DE',
    'customer[customer_number]'          => '123456',
    'customer[external_id]'              => '<your-customer-id>',
    'customer[stop_automatic_reminders]' => 'false',
    'customer[shipping_mode]'            => 'email',
    'customer[customer_group_id]         => '<customers-group-id>',
    'customer[note]'                     => 'Lorem Ipsun',
    'contact[name]'                      => 'John Smith',
    'contact[gender]'                    => '1',
    'contact[salutation]'                => '1',
    'contact[email]'                     => 'smith@email.com',
    'contact[external_id]'               => '<your-contact-id>',
    'customer_id'                        => '<customer-id>',
    'contact_id'                         => '<contact-id>',
    'external_id'                        => '<your-invoice-id>',
    'invoice_number'                     => '400001',
    'additional_number'                  => '300001',
    'total'                              => '606.9',
    'due_date'                           => '15.12.2015',
    'time_for_payment'                   => '14',
    'invoice_date'                       => '01.12.2015'
];

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>

require 'net/http'
require 'net/https'
require 'net/http/post/multipart'

begin
    uri = URI('https://s01.bilendo.de/api/v1/invoices')

    # Create client
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_PEER

    body = {
        'invoice'                            => UploadIO.new(File.new('invoice.pdf'), 'application/pdf'),
        'customer[name]'                     => 'New Company Inc.',
        'customer[address_line1]'            => 'New Company Inc.',
        'customer[address_line2]'            => 'John Smith',
        'customer[address_line3]'            => 'Some Street 2',
        'customer[address_line4]'            => 'Backyard',
        'customer[zip]'                      => '54321',
        'customer[city]'                     => 'City',
        'customer[country_code]'             => 'DE',
        'customer[customer_number]'          => '123456',
        'customer[external_id]'              => '<your-customer-id>',
        'customer[stop_automatic_reminders]' => 'false',
        'customer[shipping_mode]'            => 'email',
        'customer[customer_group_id]         => '<customers-group-id>'
        'customer[note]'                     => 'Lorem Ipsum',
        'contact[name]'                      => 'John Smith',
        'contact[gender]'                    => '1',
        'contact[salutation]'                => '1',
        'contact[email]'                     => 'smith@email.com',
        'contact[external_id]'               => '<your-contact-id>',
        'customer_id'                        => '<customer-id>',
        'contact_id'                         => '<contact-id>',
        'external_id'                        => '<your-invoice-number>',
        'invoice_number'                     => '400001',
        'additional_number'                  => '300001',
        'total'                              => '606.9',
        'due_date'                           => '15.12.2015',
        'time_for_payment'                   => '14',
        'invoice_date'                       => '01.12.2015'
    }

    # Create Request
    req = Net::HTTP::Post::Multipart.new(uri, body)
    # Add headers
    req.add_field 'Authorization', 'Token token=YOUR-API-TOKEN'

    # Fetch Request
    res = http.request(req)
    puts "Response HTTP Status Code: #{res.code}"
    puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
    puts "HTTP Request failed (#{e.message})"
end

import requests
try:
    response = requests.post(
        url = 'https://s01.bilendo.de/api/v1/invoices',
        headers = {
            'Authorization': 'Token token=YOUR-API-TOKEN'
        },
        files = {
            'invoice': open('invoice.pdf', 'rb')
        },
        data = {
            'customer[name]':                     'New Company Inc',
            'customer[address_line1]':            'New Company Inc',
            'customer[address_line2]':            'John Smith',
            'customer[address_line3]':            'Some Street 2',
            'customer[address_line4]':            'Backyard',
            'customer[zip]':                      '54321',
            'customer[city]':                     'City',
            'customer[country_code]':             'DE',
            'customer[customer_number]':          '123654',
            'customer[external_id]':              '<your-customer-id>',
            'customer[stop_automatic_reminders]': 'false',
            'customer[shipping_mode]':            'email',
            'customer[customer_group_id]:         '<customers-group-id>'
            'customer[note]':                     'Lorem Ipsu',
            'contact[name]':                      'John Smith',
            'contact[gender]':                    '1',
            'contact[salutation]':                '1',
            'contact[email]':                     'smith@email.com',
            'contact[external_id]':               '<your-contact-id>',
            'customer_id':                        '<customer-id>',
            'contact_id':                         '<contact-id>',
            'external_id':                        '<your-invoice-id>',
            'invoice_number':                     '400001',
            'additional_number':                  '300001',
            'total':                               606.9,
            'invoice_date':                       '01.12.2015',
            'time_for_payment':                    14,
            'due_date':                           '15.12.2015'
        }
    )
    print('Response HTTP Status Code: {status_code}'.format(
        status_code=response.status_code))
    print('Response HTTP Response Body: {content}'.format(
        content=response.content))
except requests.exceptions.RequestException:
    print('HTTP Request failed')

Response

{
  "invoice": {
    "id": "<invoice-id>",
    "external_id": "<your-invoice-id>",
    "invoice_status": "draft",
    "invoice_number": "400001",
    "additional_number": "300001",
    "total": "606.9",
    "invoice_date": "2015-12-01",
    "due_date": "2015-12-15",
    "time_for_payment": 14,
    "shipping_mode": "email",
    "open_amount": "0.0",
    "created_at": "2016-01-14T11:13:55+01:00",
    "updated_at": "2016-01-18T13:53:32+01:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "New Company Inc",
      "customer_number": "123654",
      "address": "New Company Inc\nJohn Smith\nSome Street 2\n54321 City\nDeutschland",
      "stop_automatic_reminders": false,
      "shipping_mode": "email",
      "customer_group_id": "<customers-group-id>"
      "note": "Lorem Ipsum",
      "created_at": "2016-07-22T17:32:18+02:00",
      "updated_at": "2016-07-22T17:32:18+02:00"
    },
    "contact": {
      "id": "<contact-id>",
      "external_id": "<your-contact-id>",
      "name": "John Smith",
      "gender": 1,
      "salutation": 1,
      "email": "smith@email.com",
      "salutation_text": "Hallo Smith",
      "created_at": "2016-07-22T17:32:18+02:00",
      "updated_at": "2016-07-22T17:32:18+02:00"
    },
    "payments": []
  }
}

The extended create allows the creation of an invoice, a customer and a contact with a single request.

Other possible options:


Parameter Type Description
invoice mandatory PDF-File
customer_id optional bilendo customer_id
contact_id optional bilendo contact_id
customer[name] optional name of the customer
customer[address_line1] mandatory customer’s address line 1 (customer name)
customer[address_line2] optional customer’s address line 2 (contact name)
customer[address_line3] mandatory customer’s address line 3 (street and house number)
customer[address_line4] optional customer’s address line 4 (additional address)
customer[zip] optional customer’s zip code
customer[city] optional customer’s city
customer[country_code] optional customer’s country isocode
customer[customer_number] optional optional customer number
customer[external_id] optional your id of the customer
customer[customer_group_id] optional customer’s group id
customer[note] optional optional note
customer[stop_automatic_reminders] optional prevents automatic reminders
customer[shipping_mode] optional shipping methods with values:
email
post
dual_shipping (email & post simultaneously)
unknown
We default to the customer shipping mode settings if emtpy.
contact[name] optional name of the contact
contact[email] optional contact email
contact[gender] optional 0 = unknown
1 = male
2 = female
contact[salutation] optional 0 = formal
1 = informal
contact[external_id]  optional your id of the contact
external_id optional your invoice id
invoice_number optional invoice number
additional_number optional any additional number or id (ex: order number)
total optional gross value
invoice_date optional invoice date
due_date optional due date
time_for_payment optional difference between invoice_date and due_date

API Endpoint

POST https://s01.bilendo.de/api/v1/invoices

Get Invoices

Get All Invoices

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/invoices" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/invoices');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/invoices')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.get(
      url = "https://s01.bilendo.de/api/v1/invoices",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "invoices":[
    {
      "id": "<invoice-id1>",
      "...",
    }, {
      "id": "<invoice-id2>",
      "...",
    }, , {
      "id": "<invoice-id3>",
      "...",
    },
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "per_page": 30,
    "total_count": 3
  }
}

Filter

You can use our pagingation if you set a page parameter

URL-Parameter Description
page number of requested page

Meta

Attribute Type Description
current_page integer the current page
next_page integer the next page or null
prev_page integer previous page or null
total_pages integer the number of pages
per_page integer how many items per page
total integer how many items

API Endpoint

GET https://s01.bilendo.de/api/v1/invoices

Get filtered invoices

Filters

Paramaters Description
all_open all invoices that are not paid
open sent invoices that are not paid and not due
due due invoices without sent reminders
reminder1 invoices with first reminder sent
reminder2 invoices with second reminder sent
reminder3 invoices with third reminder sent
to_inkasso invoices sent to your debt collector
paid all paid invoices

API Endpoint

GET https://s01.bilendo.de/api/v1/invoices?filter=<filter-parameter>

Get a specific Invoice

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/invoices/<invoice-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/invoices/<invoice-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/invoices/<invoice-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests

try:
  response = requests.get(
      url = "https://s01.bilendo.de/api/v1/invoices/<invoice-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "invoice": {
    "id": "<invoice-id>",
    "external_id": "<your-invoice-id>",
    "invoice_status": "draft",
    "invoice_number": "400001",
    "additional_number": "300001",
    "total": "606.9",
    "invoice_date": "2014-04-16",
    "due_date": "2014-04-30",
    "time_for_payment": 14,
    "shipping_mode": "email",
    "open_amount": "0.0",
    "created_at": "2016-01-14T11:13:55+01:00",
    "updated_at": "2016-01-18T13:53:32+01:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    },
    "contact": {
      "id": "<contact-id>",
      "external_id": "<your-contact-id>",
      "name": "John Smith",
      "gender":1,
      "salutation":1,
      "email": "john@bilendo.de",
      "created_at": "2016-01-18T13:53:06+01:00",
      "updated_at": "2016-01-18T13:53:06+01:00"
    },
    "payments": []
  }
}

Api Endpoint

GET https://s01.bilendo.de/api/v1/invoices/<invoice-id>

Find a specific Invoice

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/invoices/find/<your-invoice-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/invoices/find/<your-invoice-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/invoices/find/<your-invoice-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.get(
      url = "https://s01.bilendo.de/api/v1/invoices/find/<your-invoice-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "invoice": {
    "id": "<invoice-id>",
    "external_id": "<your-invoice-id>",
    "invoice_status": "draft",
    "invoice_number": "400001",
    "additional_number": "300001",
    "total": "606.9",
    "invoice_date": "2014-04-16",
    "due_date": "2014-04-30",
    "time_for_payment": 14,
    "shipping_mode": "email",
    "open_amount": "0.0",
    "created_at": "2016-01-14T11:13:55+01:00",
    "updated_at": "2016-01-18T13:53:32+01:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    },
    "contact": {
      "id": "<contact-id>",
      "external_id": "<your-contact-id>",
      "name": "John Smith",
      "gender":1,
      "salutation":1,
      "email": "john@bilendo.de",
      "created_at": "2016-01-18T13:53:06+01:00",
      "updated_at": "2016-01-18T13:53:06+01:00"
    },
    "payments": []
  }
}

Api Endpoint

GET https://s01.bilendo.de/api/v1/invoices/find/<your-invoice-id>

Delete or archive an invoice

Request

curl -X "DELETE" "https://s01.bilendo.de/api/v1/invoices/<invoice-id>?note=<your-note-here>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/invoices/<invoice-id>?note=<your-note-here>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/invoices/<invoice-id>?note=<your-note-here>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Delete.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.delete(
      url = "https://s01.bilendo.de/api/v1/invoices/<invoice-id>?note=<your-note-here>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response body (invoice archived)

{
  "invoice": {
    "id": "<invoice-id>",
    "external_id": "<your-invoice-id>",
    "invoice_status": "archived",
    "invoice_number": "400001",
    "additional_number": "300001",
    "total": "606.9",
    "invoice_date": "2014-04-16",
    "due_date": "2014-04-30",
    "time_for_payment": 14,
    "shipping_mode": "email",
    "open_amount": "0.0",
    "created_at": "2016-01-14T11:13:55+01:00",
    "updated_at": "2016-01-18T13:53:32+01:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    },
    "contact": {
      "id": "<contact-id>",
      "external_id": "<your-contact-id>",
      "name": "John Smith",
      "gender":1,
      "salutation":1,
      "email": "john@bilendo.de",
      "created_at": "2016-01-18T13:53:06+01:00",
      "updated_at": "2016-01-18T13:53:06+01:00"
    },
    "payments": []
  }
}
Action Optional Parameter Condition Response Code
Delete invoice_status IS draft OR duplicate 204 (No Content)
Archive note invoice_status IS NOT draft OR duplicate 200 (OK)

Api Endpoint

DELETE https://s01.bilendo.de/api/v1/invoices/<invoice-id>

Payments

Payment Object

{
  "payment": {
    "id": "<payment-id>",
    "external_id": "<your-payment-id>",
    "amount": "606.9",
    "payment_date": "2015-12-01",
    "name": "Company Inc",
    "purpose": "Payment Purpose",
    "account_number": "DE123456789",
    "bank_code": "BIC",
    "bank_name": "Example-Bank",
    "note": "Lorem Ipsum",
    "inkasso_payment": false,
    "source": "API",
    "created_at": "2016-02-04T14:53:10+02:00",
    "updated_at": "2016-02-04T14:53:10+02:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc.",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "created_at": "2016-01-19T08:42:48+01:00",
      "updated_at": "2016-01-19T08:42:48+01:00"
    },
    "invoice": {
      "id": "<invoice-id>",
      "external_id": "<your-invoice-id>",
      "invoice_number": "400001",
      "total": "606.9",
      "invoice_date": "2014-04-16",
      "due_date": "2014-04-30",
      "open_amount": "0.0"
    }
  }
}
Attribute type Description
id string Bilendo id of the payment
external_id string your id of the payment
amount decimal amount of the payment
payment_date date payment date
name string name
purpose string purpose
account_number string iban number
bank_code string bic code
bank_name string bank name
note string optional note
inkasso_payment boolean payment from your debt collector
source 1 string source of the payment
customer customer the customer
invoice invoice the invoice

Create new Payment

Request

curl -X "POST" "https://s01.bilendo.de/api/v1/payments" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \
  -F "customer_id=<customer-id>" \
  -F "invoice_id=<invoice-id>" \
  -F "customer[external_id]=<your-customer-id>" \
  -F "invoice[external_id]=<your-invoice-id>" \
  -F "external_id=<your-payment-id>" \
  -F "amount=606.9" \
  -F "payment_date=2015-12-01" \
  -F "name=Company Inc" \
  -F "purpose=Payment Purpose" \
  -F "account_number=DE123456789" \
  -F "bank_code=BIC" \
  -F "bank_name=Example-Bank" \
  -F "note=Lorem Ipsum" \
  -F "inkasso_payment=true" \
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/payments');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN",
  "Content-Type: application/x-www-form-urlencoded"
 ]
);
// Create body
$body = [
  "customer_id" => "<customer-id>",
  "invoice_id" => "<invoice-id>",
  "customer[external_id]" => "<your-customer-id>",
  "invoice[external_id]" => "<your-invoice-id>",
  "external_id" => "<your-payment-id>",
  "amount" => "606.9",
  "payment_date" => "2015-12-01",
  "name" => "Company Inc",
  "purpose" => "Payment Purpose",
  "account_number" => "DE123456789",
  "bank_code" => "BIC",
  "bank_name" => "Example-Bank",
  "note" => "Lorem Ipsum",
  "inkasso_payment" => "true"
  ];
$body = http_build_query($body);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/payments')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  data = {
    "customer_id" => "<customer-id>",
    "invoice_id" => "<invoice-id>",
    "customer[external_id]" => "<your-customer-id>",
    "invoice[external_id]" => "<your-invoice-id>",
    "external_id" => "<your-payment-id>",
    "amount" => "606.9",
    "payment_date" => "2015-12-01",
    "name" => "Company Inc",
    "purpose" => "Payment Purpose",
    "account_number" => "DE123456789",
    "bank_code" => "BIC",
    "bank_name" => "Example-Bank",
    "note" => "Lorem Ipsum",
    "inkasso_payment" => "true"
  }
  body = URI.encode_www_form(data)

  # Create Request
  req =  Net::HTTP::Post.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"
  # Set header and body
  req.body = body

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.post(
    url = "https://s01.bilendo.de/api/v1/payments",
    headers = {
      "Authorization": "Token token=YOUR-API-TOKEN"
    },
    data = {
      "customer_id": "<customer-id>",
      "invoice_id": "<invoice-id>",
      "customer[external_id]": "<your-customer-id>",
      "invoice[external_id]": "<your-invoice-id>",
      "external_id": "<your-payment-id>",
      "amount": "606.9",
      "payment_date": "2015-12-01",
      "name": "Company Inc",
      "purpose": "Payment Purpose",
      "account_number": "DE123456789",
      "bank_code": "BIC",
      "bank_name": "Example-Bank",
      "note": "Lorem Ipsum",
      "inkasso_payment": "true"
    }
  )
  print('Response HTTP Status Code: {status_code}'.format(
    status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
    content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "payment": {
    "id": "<payment-id>",
    "external_id": "<your-payment-id>",
    "amount": "606.9",
    "payment_date": "2015-12-01",
    "name": "Company Inc",
    "purpose": "Payment Purpose",
    "account_number": "DE123456789",
    "bank_code": "BIC",
    "bank_name": "Example-Bank",
    "note": "Lorem Ipsum",
    "inkasso_payment": "true",
    "source": "API",
    "created_at": "2016-02-04T14:53:10+02:00",
    "updated_at": "2016-02-04T14:53:10+02:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc.",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "created_at": "2016-01-19T08:42:48+01:00",
      "updated_at": "2016-01-19T08:42:48+01:00"
    },
    "invoice": {
      "id": "<invoice-id>",
      "external_id": "<your-invoice-id>",
      "invoice_number": "400001",
      "total": "606.9",
      "invoice_date": "2014-04-16",
      "due_date": "2014-04-30",
      "open_amount": "0.0"
    }
  }
}
Parameter type Description
amount mandatory the amount of the payment
external_id optional your payment id 1
payment_date optional payment date
name optional name
purpose optional purpose
account_number optional iban number
bank_code optional bic code
bank_name optional bank name
note optional a note
inkasso_payment optional the payment is from your debt collector
customer_id or
customer[external_id]
optional bilendo-customer-id
your-customer-id
invoice_id or
invoice[external_id]
optional bilendo-invoice-id
your-invoice-id

API Endpoint

POST https://s01.bilendo.de/api/v1/payments

Get Payments

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/payments" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/payments');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/payments')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.get(
    url = "https://s01.bilendo.de/api/v1/payments",
    headers = {
      "Authorization": "Token token=YOUR-API-TOKEN"
    }
  )
  print('Response HTTP Status Code: {status_code}'.format(
    status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
    content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "payments":[
    {
      "id": "<payment-id1>",
      ...
    }, {
      "id": "<payment-id2>",
      ...
    }, , {
      "id": "<payment-id3>",
      ...
    },
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "per_page": 30,
    "total_count": 3
  }
}

Filter

You can use our pagingation if you set a page parameter

URL-Parameter Description
page number of requested page

Meta

Attribute type Description
current_page integer the current page
next_page integer the next page or null
prev_page integer previous page or null
total_pages integer the number of pages
per_page integer how many items per page
total integer how many items

API Endpoint

GET https://s01.bilendo.de/api/v1/payments

Get filtered payments

Filters

Paramaters Description
assigned all payments with assigned invoices
notassigned all payments without assigned invoices

API Endpoint

GET https://s01.bilendo.de/api/v1/payments?filter=<filter-parameter>

Get a specific Payment

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/payments/<payment-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/payments/<payment-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/payments/<payment-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests

try:
  response = requests.get(
    url = "https://s01.bilendo.de/api/v1/payments/<payment-id>",
    headers = {
      "Authorization": "Token token=YOUR-API-TOKEN"
    }
  )
  print('Response HTTP Status Code: {status_code}'.format(
    status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
    content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "payment": {
    "id": "<payment-id>",
    "external_id": "<your-payment-id>",
    "amount": "606.9",
    "payment_date": "2015-12-01",
    "name": "Company Inc",
    "purpose": "Payment Purpose",
    "account_number": "DE123456789",
    "bank_code": "BIC",
    "bank_name": "Example-Bank",
    "note": "Lorem Ipsum",
    "inkasso_payment": true,
    "source": "API",
    "created_at": "2016-02-04T14:53:10+02:00",
    "updated_at": "2016-02-04T14:53:10+02:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc.",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "created_at": "2016-01-19T08:42:48+01:00",
      "updated_at": "2016-01-19T08:42:48+01:00"
    },
    "invoice": {
      "id": "<invoice-id>",
      "external_id": "<your-invoice-id>",
      "invoice_number": "400001",
      "total": "606.9",
      "invoice_date": "2014-04-16",
      "due_date": "2014-04-30",
      "open_amount": "0.0"
    }
  }
}

Api Endpoint

GET https://s01.bilendo.de/api/v1/payments/<payment-id>

Find a specific Payment

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/payments/find/<your-payment-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/payments/find/<your-payment-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/payments/find/<your-payment-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.get(
    url = "https://s01.bilendo.de/api/v1/payments/find/<your-payment-id>",
    headers = {
      "Authorization": "Token token=YOUR-API-TOKEN"
    }
  )
  print('Response HTTP Status Code: {status_code}'.format(
    status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
    content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "payment": {
    "id": "<payment-id>",
    "external_id": "<your-payment-id>",
    "amount": "606.9",
    "payment_date": "2015-12-01",
    "name": "Company Inc",
    "purpose": "Payment Purpose",
    "account_number": "DE123456789",
    "bank_code": "BIC",
    "bank_name": "Example-Bank",
    "note": "Lorem Ipsum",
    "inkasso_payment": true,
    "note": "API",
    "created_at": "2016-02-04T14:53:10+02:00",
    "updated_at": "2016-02-04T14:53:10+02:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc.",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "created_at": "2016-01-19T08:42:48+01:00",
      "updated_at": "2016-01-19T08:42:48+01:00"
    },
    "invoice": {
      "id": "<invoice-id>",
      "external_id": "<your-invoice-id>",
      "invoice_number": "400001",
      "total": "606.9",
      "invoice_date": "2014-04-16",
      "due_date": "2014-04-30",
      "open_amount": "0.0"
    }
  }
}

Api Endpoint

GET https://s01.bilendo.de/api/v1/payments/find/<your-payment-id>

Customers Groups

Customers Group Object

{
  "customer_group": {
    "id": "<customers-group-id>",
    "active": true,
    "name": "Example Group",
    "description": "Lorem ipsum",
    "created_at": "2017-06-14T14:39:05+02:00",
    "updated_at": "2017-06-14T18:26:18+02:00",
    "customers": [
      {
        "id": "<customer-id>",
        "external_id": "<your-customer-id>",
        "name": "Company Inc.",
        "customer_number": "100001",
        "address": "Company Inc.\nSome Street 1\n12345 City\nCountry",
        "created_at": "2017-06-13T17:00:14+02:00",
        "updated_at": "2017-06-14T17:49:09+02:00"
      }
    ]
  }
}
Attribute type Description
id string Bilendo id of the customers group
active boolean active or inactive groups. If a group is inactive, its settings are ignored and we fallback to the company settings
name text customers group name
description text customers group description
customers array customers in the group

Get Customers Groups

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/customer_groups" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/customer_groups');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/customer_groups')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.get(
    url = "https://s01.bilendo.de/api/v1/customer_groups",
    headers = {
      "Authorization": "Token token=YOUR-API-TOKEN"
    }
  )
  print('Response HTTP Status Code: {status_code}'.format(
    status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
    content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "customer_groups":[
    {
      "id": "<customer_groups-id1>",
      ...
    }, {
      "id": "<customer_groups-id2>",
      ...
    }, , {
      "id": "<customer_groups-id3>",
      ...
    },
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "per_page": 30,
    "total_count": 3
  }
}

Filter

You can use our pagingation if you set a page parameter

URL-Parameter Description
page number of requested page

Meta

Attribute type Description
current_page integer the current page
next_page integer the next page or null
prev_page integer previous page or null
total_pages integer the number of pages
per_page integer how many items per page
total integer how many items

API Endpoint

GET https://s01.bilendo.de/api/v1/customer_groups

Get a specific Customers Group

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests

try:
  response = requests.get(
    url = "https://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>",
    headers = {
      "Authorization": "Token token=YOUR-API-TOKEN"
    }
  )
  print('Response HTTP Status Code: {status_code}'.format(
    status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
    content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "customer_group": {
    "id": "<customers-group-id>",
    "active": true,
    "name": "Example Group",
    "description": "Lorem ipsum",
    "created_at": "2017-06-14T14:39:05+02:00",
    "updated_at": "2017-06-14T18:26:18+02:00",
    "customers": [
      {
        "id": "<customer-id>",
        "external_id": "<your-customer-id>",
        "name": "Company Inc.",
        "customer_number": "100001",
        "address": "Company Inc.\nSome Street 1\n12345 City\nCountry",
        "created_at": "2017-06-13T17:00:14+02:00",
        "updated_at": "2017-06-14T17:49:09+02:00"
      }
    ]
  }
}

Api Endpoint

GET https://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>

Add Customers

Request

curl -X "PUT" "http://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>/add" \
     -H "Authorization: Token token=YOUR-API-TOKEN" \
     -d $'{ "customers": [
            "<customer-id1>",
            "<customer-id2>"
          ]}'
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'http://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>/add');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Token token=YOUR-API-TOKEN",
    "Content-Type: application/json; charset=utf-8",
  ]
);

// Create body
$json_array = [
    "customers" => [
      "<customer-id1>",
      "<customer-id2>"
    ]
];

$body = json_encode($json_array);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'json'

def send_request
  uri = URI('http://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>/add')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  dict = {
            "customers" => [
              "<customer-id1>",
              "<customer-id2>"
            ]
         }
  body = JSON.dump(dict)

  # Create Request
  req =  Net::HTTP::Put.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"
  # Add headers
  req.add_field "Content-Type", "application/json; charset=utf-8"
  # Set body
  req.body = body

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests
import json

def send_request():
    try:
        response = requests.put(
            url="http://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>/add",
            headers={
                "Authorization": "Token token=YOUR-API-TOKEN",
                "Content-Type": "application/json; charset=utf-8",
            },
            data=json.dumps({
                "customers": [
                  "<customer-id1>",
                  "<customer-id2>"
                ]
            })
        )
        print('Response HTTP Status Code: {status_code}'.format(
            status_code=response.status_code))
        print('Response HTTP Response Body: {content}'.format(
            content=response.content))
    except requests.exceptions.RequestException:
        print('HTTP Request failed')

Response

{
  "customer_group": {
    "id": "<customers-group-id>",
    "active": true,
    "name": "Example Group",
    "description": "Lorem ipsum",
    "created_at": "2017-06-14T14:39:05+02:00",
    "updated_at": "2017-06-14T18:26:18+02:00",
    "customers": [
      {
        "id": "<customer-id1>",
        "external_id": "<your-customer-id1>",
        "name": "Company Inc.",
        "customer_number": "100001",
        "address": "Company Inc.\nSome Street 1\n12345 City\nCountry",
        "created_at": "2017-06-13T17:00:14+02:00",
        "updated_at": "2017-06-14T17:49:09+02:00"
      },
      {
        "id": "<customer-id2>",
        "external_id": "<your-customer-id2>",
        "name": "Company Inc. 2",
        "customer_number": "200001",
        "address": "Company Inc. 2\nSome Street 1\n12345 City\nCountry",
        "created_at": "2017-06-13T17:00:14+02:00",
        "updated_at": "2017-06-14T17:49:09+02:00"
      }
    ]
  }
}
Parameter type Description
customers mandatory customers array
customer_id optional bilendo-customer-id (customer to be added)

API Endpoint

PUT http://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>/add

Remove Customers

Request

curl -X "PUT" "http://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>/remove" \
     -H "Authorization: Token token=YOUR-API-TOKEN" \
     -d $'{ "customers": [
            "<customer-id1>",
            "<customer-id2>"
          ]}'
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'http://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>/remove');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Token token=YOUR-API-TOKEN",
    "Content-Type: application/json; charset=utf-8",
  ]
);

// Create body
$json_array = [
    "customers" => [
      "<customer-id1>",
      "<customer-id2>"
    ]
];

$body = json_encode($json_array);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'json'

def send_request
  uri = URI('http://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>/remove')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  dict = {
            "customers" => [
              "<customer-id1>",
              "<customer-id2>"
            ]
         }
  body = JSON.dump(dict)

  # Create Request
  req =  Net::HTTP::Put.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"
  # Add headers
  req.add_field "Content-Type", "application/json; charset=utf-8"
  # Set body
  req.body = body

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests
import json

def send_request():
    try:
        response = requests.put(
            url="http://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>/remove",
            headers={
                "Authorization": "Token token=YOUR-API-TOKEN",
                "Content-Type": "application/json; charset=utf-8",
            },
            data=json.dumps({
                "customers": [
                  "<customer-id1>",
                  "<customer-id2>"
                ]
            })
        )
        print('Response HTTP Status Code: {status_code}'.format(
            status_code=response.status_code))
        print('Response HTTP Response Body: {content}'.format(
            content=response.content))
    except requests.exceptions.RequestException:
        print('HTTP Request failed')

Response

{
  "customer_group": {
    "id": "<customers-group-id>",
    "active": true,
    "name": "Example Group",
    "description": "Lorem ipsum",
    "created_at": "2017-06-14T14:39:05+02:00",
    "updated_at": "2017-06-14T18:26:18+02:00",
    "customers": []
  }
}
Parameter type Description
customers mandatory customers array
customer_id optional bilendo-customer-id (customer to be removed)

API Endpoint

PUT http://s01.bilendo.de/api/v1/customer_groups/<customers-group-id>/remove

Account

Data Reset

Request

curl -X "PUT" "https://s01.bilendo.de/api/v1/reset" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/reset');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/reset')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  # Create Request
  req = Net::HTTP::Put.new(uri)
  # Add headers
  req.add_field 'Authorization', 'Token token=YOUR-API-TOKEN'

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
    response = requests.put(
        url = "https://s01.bilendo.de/api/v1/reset",
        headers = {
            "Authorization": "Token token=YOUR-API-TOKEN"
        }
    )
    print('Response HTTP Status Code: {status_code}'.format(
        status_code=response.status_code))
    print('Response HTTP Response Body: {content}'.format(
        content=response.content))
except requests.exceptions.RequestException:
    print('HTTP Request failed')

Response (Status: 202)

{
  "message": "Your company data was is being reset. Go to 'api/v1/status' for live poll."
}

Resetting your company data means the following data will be destroyed:

Your company and user settings will remain unchanged.

Status code Message
202 Accepted – Your company data is being reset. Go to ‘api/v1/status’ for live poll.
403 Forbidden – You are not allowed to reset this company data

API Endpoint

PUT https://s01.bilendo.de/api/v1/reset

Data Status

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/status/" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \

<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/status');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/status')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  # Create Request
  req = Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field 'Authorization', 'Token token=YOUR-API-TOKEN'

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests

try:
    response = requests.get(
        url = "https://s01.bilendo.de/api/v1/status",
        headers = {
            "Authorization": "Token token=YOUR-API-TOKEN"
        }
    )
    print('Response HTTP Status Code: {status_code}'.format(
        status_code=response.status_code))
    print('Response HTTP Response Body: {content}'.format(
        content=response.content))
except requests.exceptions.RequestException:
    print('HTTP Request failed')

Response

{
  "invoices":0,
  "reminders":0,
  "customers":0,
  "contacts":0,
  "payments":0
}

This endpoint allows you to view your current data count for all:

API Endpoint

GET https://s01.bilendo.de/api/v1/status

Current Costs

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/billing" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \

<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/billing');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/billing')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  # Create Request
  req = Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field 'Authorization', 'Token token=YOUR-API-TOKEN'

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
    response = requests.get(
        url = "https://s01.bilendo.de/api/v1/billing",
        headers = {
            "Authorization": "Token token=YOUR-API-TOKEN"
        }
    )
    print('Response HTTP Status Code: {status_code}'.format(
        status_code=response.status_code))
    print('Response HTTP Response Body: {content}'.format(
        content=response.content))
except requests.exceptions.RequestException:
    print('HTTP Request failed')

Response (Status: 200)

// without plan upgrade
{  
   "current_stats":{  
      "period_start_date":"2016-09-01",
      "period_end_date":"2016-09-30",
      "selected_plan":"Automatic",
      "invoices_inclusive":250,
      "invoices_processed":0,
      "shippings_ntl_count":0,
      "shippings_intl_count":0,
      "shippings_email_count":0,
      "shippings_additional_count":0
   },
   "current_billing":[
      {  
         "period_start_date":"2016-09-01",
         "period_end_date":"2016-09-30",
         "selected_plan":"Automatic",
         "plan_total":"99.0",
         "shippings":{  
            "shipping_ntl_total":"0.0",
            "shipping_intl_total":"0.0",
            "shipping_additional_total":"0.0"
         }
      }
   ]
}
// with plan upgrade
{  
   "current_stats":{  
      "period_start_date":"2016-09-01",
      "period_end_date":"2016-09-30",
      "selected_plan":"Automatic",
      "invoices_inclusive":250,
      "invoices_processed":0,
      "shippings_ntl_count":0,
      "shippings_intl_count":0,
      "shippings_email_count":0,
      "shippings_additional_count":0
   },
   "current_billing":[  
      {  
         "period_start_date":"2016-09-01",
         "period_end_date":"2016-09-10",
         "selected_plan":"Basic",
         "plan_total":"9.67"
      },
      {  
         "period_start_date":"2016-09-11",
         "period_end_date":"2016-09-30",
         "selected_plan":"Automatic",
         "plan_total":"66.0",
         "shippings":{  
            "shipping_ntl_total":"0.0",
            "shipping_intl_total":"0.0",
            "shipping_additional_total":"0.0"
         }
      }
   ]
}

This endpoint allows you to view all relevant dates and amounts about your expences incurred in the current month:

Attribute type Description
current_stats object object containing all relevant dates and amounts about your expences incurred in the current month
current_billings array array containing objects with the current costs.
(If you upgrade your plan, there will be multiple entries.)

Current Stats

Attribute type Description
period_start_date date start date of your current billing period
period_end_date date end date of your current billing period
selected_plan string your currently selected plan
invoices_inclusive integer amount of inclusive invoices per period
invoices_processed integer amount of processed invoices per period
shippings_ntl_count integer amount of postal shippings (Germany) per period
shippings_intl_count integer amount of postal shippings (international) per period
shippings_email_count integer amout of email shippings per period
shippings_additional_count integer amount of additional invoices per period

Current Billings (per plan)

Attribute type Description
period_start_date date start date of your current billing period
period_end_date date end date of your current billing period
selected_plan string your selected plan
plan_total decimal total costs for your selected plan
shippings object object containing costs for shipping
shipping_ntl_total decimal costs for postal shipping (Germany)
shipping_intl_total decimal costs for postal shipping (international)
shipping_additional_total decimal costs for additional shippings

API Endpoint

GET https://s01.bilendo.de/api/v1/billing

Errors

HTTP Status

The Bilendo API uses the following HTTP error status codes:

Status code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your API token is wrong
403 Forbidden – The server understood the request but refuses to authorize it
404 Not Found – The specified object could not be found
405 Method Not Allowed – You tried to access our API with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The object requested has been removed from our servers
412 Precondition Failed – The server does not meet one of the preconditions that the requester put on the request
418 I’m a teapot
422 Unprocessable Entity – The object is not valid
429 Too Many Requests – You’re requesting too many objects! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Bilendo Error Codes

Request

# Scenario: Creating a new customer with an existing name, customer_number and external _id

curl -X "POST" "https://s01.bilendo.de/api/v1/customers/" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "customer_number=<existing-customer-number>" \
  -F "external_id=<existing-external-id>" \
  -F "name=<existing-name>" \

Response

{
  "error": [
    {
      "name": {
        "title": "Es existiert bereits ein Kunde mit diesem Namen.",
        "code": 1001
      }
    },
    {
      "customer_number": {
        "title": "Es existiert bereits ein Kunde mit dieser Kundennummer.",
        "code": 1002
      }
    },
    {
      "external_id": {
        "title": "Es existiert bereits ein Kunde mit dieser externen ID.",
        "code": 1003
      }
    }
  ]
}

Error Code Object Meaning
1000 Customer The customer name cannot be blank
1001 Customer The provided customer name already exists
1002 Customer The customer number already exists
1003 Customer The provided customer external_id already exists
1004 Customer The provided customer cannot be found
2000 Contact The customer_id can’t be blank
2001 Contact The contact email already exists
2002 Contact The provided contact cannot be found
2003 Contact The provided contact external_id already exists
2004 Contact The provided email is invalid
3000 Invoice The invoice file was not provided or is invalid
3001 Invoice The provided invoice external_id already exists
4000 Payment The provided payment external_id already exists
4001 Payment The amount cannot be greater than the invoice amount
4002 Payment The amount cannot be equal or lower than zero
5000 Customer Group The customers groups module is not active
5001 Customer Group Customers not provided
5002 Customer Group Customers not found

Email dropbox

The email dropbox allows you to import invoices by sending an email to your Email-Dropbox address (eg: IMFjM4gAL5A24w@bilendo.com). Find this in your account settings

Attachments

All attached files must be in .pdf format.

If you sent or need to send additional PDF files that are not invoices, please contact our support team at support@bilendo.de

Restrict Senders

By default, anyone can send files to your Email-Dropbox address. However, this can be restricted to one or multiple senders.

To add or change your allowed senders, go to your Bilendo-Account under your account settings


Webhooks

Webhooks allow you to set a URL to which you receive a notification whenever a status code of an invoice changes. Find this in your account settings

Usage

In order to start using webhooks go to account settings. Here you can find a list of existing webhooks.

To update/delete or view details of the existing webhook click ‘Details’.

To add a new webhook click 'WebHook hinzufügen’.

If your webhook URL requires basic HTTP authentication please add username and password. Otherwise, please leave these optional fields blank.

Possible values for trigger_status

In order to subscribe to all events listed below use “all” as trigger_status in your request.

{
  "webhook_notification": {
    "id": 859645991,
    "created_at": "2016-01-18T13:53:32+01:01",
    "trigger_status": "sent"
  },
  "invoice": {
    "id": "<invoice-id>",
    "external_id": "<your-invoice-id>",
    "invoice_status": "sent",
    "invoice_number": "400001",
    "additional_number": "300001",
    "total": "606.9",
    "invoice_date": "2014-04-16",
    "due_date": "2014-04-30",
    "time_for_payment": 14,
    "shipping_mode": "email",
    "open_amount": "0.0",
    "created_at": "2016-01-14T11:13:55+01:00",
    "updated_at": "2016-01-18T13:53:32+01:00",
    "customer": {
      "id": "<customer-id>",
      "external_id": "<your-customer-id>",
      "name": "Company Inc",
      "customer_number": "100001",
      "address": "Company Inc.\nSome Street\n13245 City",
      "created_at": "2016-01-18T13:52:53+01:00",
      "updated_at": "2016-01-20T16:30:14+01:00"
    },
    "contact": {
      "id": "<contact-id>",
      "external_id": "<your-contact-id>",
      "name": "John Smith",
      "gender":1,
      "salutation":1,
      "email": "john@bilendo.de",
      "created_at": "2016-01-18T13:53:06+01:00",
      "updated_at": "2016-01-18T13:53:06+01:00"
    },
    "payments": [
      {
        "id": "<payment-id>",
        "external_id": "<your-payment-id>",
        "amount": "606.9",
        "payment_date": "2015-12-01",
        "name": "Company Inc",
        "purpose": "Payment Purpose",
        "account_number": "DE123456789",
        "bank_code": "BIC",
        "bank_name": "Example-Bank",
        "note": "Lorem Ipsum",
        "created_at": "2016-04-04T14:53:10+02:00",
        "updated_at": "2016-04-04T14:53:10+02:00"
      }
    ]
  }
}
Value Description
draft invoice is a draft
sent invoice was sent
due invoice is due
ready_for_reminder1 invoice is due and you should send a first reminder
reminder1_sent first reminder was sent
ready_for_reminder2 invoice is due and you should send a second reminder
reminder2_sent second reminder was sent
ready_for_reminder3 invoice is due and you should send a third reminder
reminder3_sent third reminder was sent
ready_for_debt_collection invoice is still due after a third reminder was sent and you should send the invoice to a debt collection service
sent_to_debt_collection invoice was sent to a debt collection service
written_off invoice was written_off
paid invoice is paid
partial_payment partial payment was added
archived invoice was archived
deleted invoice was deleted
all subscription to all events listed above
due_since_x invoice is due for x number of days after a due date(e.g. due_since_30). The maximum allowed number of days is 365. Warning: this event is not included in “all” subscription.*

*in order to subscribe to all events including this event, you must set a number of days and provide due_since_x in addition to 'all’(e.g. events = ['all’, 'due_since_30’])

Receiving notifications

Once you set a URL and selected notifications you will receive notifications in the format as shown on the right hand side.

Notifications always contain a current/latest status. A notification is considered to be successfully sent if we get a response with a request status code 200 within 10 seconds after a request has been made. Otherwise we will trigger up to 19 additional attempts until we get a response with a status code 200.

Notifications are sent in the order they were created. However, it is also possible that during the retry process of sending a previously unsuccessfuly sent notification, an invoice status might change and in that case, another notification is sent. In this case, you can easily sort received notifications in a chronological order, by:

Intervals between repeated attempts

Attempt number Time in seconds
1 0
2 1
3 2
4 4
5 8
6 16
7 32
8 64
9 128
10 256
11 512
12 1024
13 2048
14 4096
15 8192
16 16384
17 32768
18 65536
19 131072
20 262144


Webhook Object

{
  "webhook": {
    "id": "<webhook-id>",
    "url": "https://your.webhook.url",
    "events": ["sent","ready_for_reminder1"],
    "username": "carl_2017",
    "password": "12345",
    "created_at": "2016-02-04T14:53:10+02:00",
    "updated_at": "2016-02-04T15:53:10+02:00"
  }
}
Attribute Type Description
id string Bilendo Id of the Webhook
url string Webhook URL
events array of strings A list of trigger_status values
username string
password string

Create a new Webhook

Request

curl -X "POST" "https://s01.bilendo.de/api/v1/webhooks" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \
  -d "url=<webhook-url>" \
  -d "events[]=sent&events[]=ready_for_reminder1" \
  -d "username=<webhook-auth-username>" \
  -d "password=<webhook-auth-password>" \
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/webhooks');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN",
  "Content-Type: application/x-www-form-urlencoded"
 ]
);
// Create body
$body = [
  "url" => "<webhook-url>",
  "events" => ["sent","ready_for_reminder1"],
  "username" => "<webhook-auth-username>",
  "password" => "<webhook-auth-password>"
  ];
$body = http_build_query($body);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/webhooks')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  data = {
    "url" => "<webhook-url>",
    "events" => ["sent","ready_for_reminder1"],
    "username" => "<webhook-auth-username>",
    "password" => "<webhook-auth-password>"
  }
  body = URI.encode_www_form(data)

  # Create Request
  req =  Net::HTTP::Post.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"
  # Set header and body
  req.body = body

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.post(
    url = "https://s01.bilendo.de/api/v1/webhooks",
    headers = {
      "Authorization": "Token token=YOUR-API-TOKEN"
    },
    data = {
     "id":"<webhook-id>",
     "url":"<webhook-url>",
     "events":["sent","ready_for_reminder1"],
     "username":"<webhook-auth-username>",
     "password":"<webhook-auth-password>",
    }
  )
  print('Response HTTP Status Code: {status_code}'.format(
    status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
    content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response


{
  "webhook": {
    "id":"<webhook-id>",
    "url":"<webhook-url>",
    "events":["sent","ready_for_reminder1"],
    "username":"<webhook-auth-username>",
    "password":"<webhook-auth-password>",
    "created_at":"2017-05-18T11:43:20+02:00",
    "updated_at":"2017-05-18T12:43:20+02:00"
  }
}

Parameter Type Description
url mandatory Webhook URL
events mandatory A list of trigger_status values
username optional
password optional

API Endpoint

POST https://s01.bilendo.de/api/v1/webhooks

Get Webhooks

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/webhooks" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/webhooks');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/webhooks')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.get(
      url = "https://s01.bilendo.de/api/v1/webhooks",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "webhooks":[
    {
      "id":"<webhook-id>",
      "url":"<webhook-url>",
      "events":["sent","ready_for_reminder1"],
      "username":"<webhook-auth-username>",
      "password":"<webhook-auth-password>",
      "created_at":"2017-05-18T11:43:20+02:00",
      "updated_at":"2017-05-18T12:43:20+02:00"
    },
    {
     "id":"<webhook-id2>",
     "url":"<webhook-url2>",
     "events":["paid", "sent","reminder3_sent"],
     "username":"<webhook-auth-username2>",
     "password":"<webhook-auth-password2>",
     "created_at":"2017-05-19T14:43:20+02:00",
     "updated_at":"2017-05-19T15:43:20+02:00"
    }
  ]
}

API Endpoint

GET https://s01.bilendo.de/api/v1/webhooks

Find a specific Webhook

Request

curl -X "GET" "https://s01.bilendo.de/api/v1/webhooks/<webhook-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/webhooks/<webhook-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/webhooks/<webhook-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.get(
      url = "https://s01.bilendo.de/api/v1/webhooks/<webhook-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "webhook": {
    "id":"<webhook-id>",
    "url":"<webhook-url>",
    "events":["sent","ready_for_reminder1"],
    "username":"<webhook-auth-username>",
    "password":"<webhook-auth-password>",
    "created_at":"2017-05-18T11:43:20+02:00",
    "updated_at":"2017-05-18T12:43:20+02:00"
  }
}

API Endpoint

GET https://s01.bilendo.de/api/v1/webhooks/<webhook-id>

Update existing Webhook

Request

curl -X "PATCH" "https://s01.bilendo.de/api/v1/webhooks/<webhook-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN" \
  -d "url=<webhook-url>" \
  -d "events[]=paid&events[]=reminder1_sent" \
  -d "username=<webhook-auth-username>" \
  -d "password=<webhook-auth-password>" \
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/api/v1/webhooks/<webhook-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);
// Create body
$body = [
  "url" => "<webhook-url>",
  "events" => ["paid","reminder1_sent"],
  "username" => "<webhook-auth-username>",
  "password" => "<webhook-auth-password>"
  ];
$body = http_build_query($body);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/webhooks/<webhook-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  data = {
    "url" => "<webhook-url>",
    "events" => ["paid","reminder1_sent"],
    "username" => "<webhook-auth-username>",
    "password" => "<webhook-auth-password>"
  }
  body = URI.encode_www_form(data)

  # Create Request
  req =  Net::HTTP::Patch.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"
  # Set header and body
  req.body = body

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

import requests

try:
  response = requests.patch(
      url = "https://s01.bilendo.de/api/v1/webhooks/<webhook-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      },
      data = {
         "url" => "<webhook-url>",
         "events" => ["paid","reminder1_sent"],
         "username" => "<webhook-auth-username>",
         "password" => "<webhook-auth-password>"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

{
  "webhook": {
    "id":"<webhook-id>",
    "url":"<webhook-url>",
    "events":["paid","reminder1_sent"],
    "username":"<webhook-auth-username>",
    "password":"<webhook-auth-password>",
    "created_at":"2017-05-18T11:43:20+02:00",
    "updated_at":"2017-05-18T12:43:20+02:00"
  }
}

Api Endpoint

PATCH https://s01.bilendo.de/api/v1/webhooks/<webhook-id>

Delete a Webhook

Request

curl -X "DELETE" "https://s01.bilendo.de/api/v1/webhooks/<webhook-id>" \
  -H "Authorization: Token token=YOUR-API-TOKEN"
<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://s01.bilendo.de/webhookapi/v1/webhooks/<webhook-id>');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Token token=YOUR-API-TOKEN"
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

?>
require 'net/http'
require 'net/https'

begin
  uri = URI('https://s01.bilendo.de/api/v1/webhooks/<webhook-id>')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER


  # Create Request
  req =  Net::HTTP::Delete.new(uri)
  # Add headers
  req.add_field "Authorization", "Token token=YOUR-API-TOKEN"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end
import requests

try:
  response = requests.delete(
      url = "https://s01.bilendo.de/api/v1/webhooks/<webhook-id>",
      headers = {
          "Authorization": "Token token=YOUR-API-TOKEN"
      }
  )
  print('Response HTTP Status Code: {status_code}'.format(
      status_code=response.status_code))
  print('Response HTTP Response Body: {content}'.format(
      content=response.content))
except requests.exceptions.RequestException:
  print('HTTP Request failed')

Response

Action Response Code
delete 204 (No Content)

API Endpoint

DELETE https://s01.bilendo.de/api/v1/webhooks/<webhook-id>