Get started

    API Endpoint (repleace your-instance with your faktorly instance):

        https://your-instance.faktorly.cloud/api/
                

Welcome to the faktorly REST API documentation. Our REST API allows developers to integrate faktorly’s robust functionality into their own applications, enabling seamless data management and analytics capabilities.

To use this API, you need an API key. You may setup this in your faktorly instance.

Authentification

# Here is a curl GET example with x-api-key authentification
curl \
 -X GET "https://your-instance.faktorly.cloud/api/invoices/get/1" \ 
 -H "x-api-key: xxx"

                

You need to send with each request a header tag "x-api-key" for authentification. You may setup your key in the settings of your faktorly instance -> System-Settings -> API.
x-api-key: xxx

Create Client

# Here is a curl example for client creation
curl -X POST "https://your-instance.faktorly.cloud/api/Clients/create" \ 
 -H "x-api-key: xxx" \
 -H "Content-Type: application/json" \
 -d '{
    "client_active": 1,
    "client_name": "test test",
    "client_surname": "",
    "client_language": "system",
    "client_number": "",
    "client_invoices_comment": "Du zahlst per SEPA-Lastschrift.",
    "client_invoices_due_after": 7,
    "client_comment": "Created with API",
    "client_address_1": "",
    "client_address_2": "",
    "client_zip": "",
    "client_city": "",
    "client_state": "",
    "client_country": "DE",
    "client_phone": "",
    "client_fax": "",
    "client_mobile": "",
    "client_email": "test@whitedata.de",
    "client_web": "",
    "client_sepa_mndtId": "",
    "client_sepa_dtOfSgntr": "",
    "client_sepa_dbtr": "Testkonto Lastschrift",
    "client_sepa_iban": "DE68721516500008252405",
    "client_sepa_bic": "",
    "client_sepa_sequence": 1,
    "client_vat_id": "",
    "client_tax_code": 1,
    "client_gender": 0,
    "client_birthdate": ""
 }'


                

To create a new client you need to make a POST call to the following url :
https://your-instance.faktorly.cloud/api/Clients/create

Result example :
200 OK
{
    "data":{
       "id":"5142",
       "name":"test test",
       "message":"Client has been created"
    }
 }
                

QUERY PARAMETERS

Response / Result

You will receive a client ID within the response for the newly created client. You can use this for further requests, e.g., to create an invoice for this client.

Create Invoice

# Here is a curl example invoice creation
curl -X POST "https://your-instance.faktorly.cloud/api/invoices/create" \ 
 -H "x-api-key: xxx" \
 -H "Content-Type: application/json" \
 -d '{
    "client_id":"5143",
    "number_range_id":2,
    "user_id":1,
    "invoice_date_created":"2023-01-04",
    "invoice_password":"",
    "invoice_date_due":"2023-01-11",
    "invoice_status_id":1,
    "items":[
       {
          "item_id":"",
          "item_product_id":"",
          "item_task_id":"",
          "item_name":"Musterartikel",
          "item_quantity":1,
          "item_price":21,
          "item_discount_amount":"",
          "item_description":"Musterartikel Beschreibung",
          "item_product_unit_id":"",
          "item_order":1
       }
    ],
    "invoice_discount_amount":"",
    "invoice_discount_percent":"",
    "invoice_terms":"Du hast dich für die Zahlung per PayPal entschieden.",
    "payment_method":4,
    "invoice_account":"",
    "invoice_tax_rate_id":"",
    "invoice_year_estg":"",
    "invoice_intro":"Lieber Kunde, wir bedanken uns für deinen Kauf."
 }'


                

To create a new invoice you need to make a POST call to the following url:
https://your-instance.faktorly.cloud/api/invoices/create

Result example :
200 OK
{
    "data":{
       "status":200,
       "id":"5548",
       "message":"Invoice has been created"
    }
 }
                

QUERY PARAMETERS

GET Invoice

# Here is a curl example invoice retrieval
curl -X GET "https://your-instance.faktorly.cloud/api/invoices/get/5548" \ 
 -H "x-api-key: xxx" 

                

To GET a invoice by invoice_id you need to make a GET call to the following url:
https://your-instance.faktorly.cloud/api/invoices/get/5548

Result example :
200 OK
{
    "quote_id":null,
    "invoice_id":"5548",
    "user_id":"1",
    "client_id":"5142",
    "number_range_id":"2",
    "invoice_group_id":null,
    "quote_status_id":null,
    "quote_date_created":null,
    "quote_date_modified":null,
    "quote_date_expires":null,
    "quote_number":null,
    "quote_discount_amount":null,
    "quote_discount_percent":null,
    "quote_url_key":null,
    "quote_password":null,
    "notes":null,
    "quote_intro":null,
    "user_gln":null,
    "user_rcc":null,
    "client_date_created":"2023-01-04 22:34:53",
    "client_date_modified":"2023-01-04 22:34:53",
    "client_name":"test test",
    "client_address_1":"",
    "client_address_2":"",
    "client_city":"",
    "client_state":"",
    "client_zip":"",
    "client_country":"DE",
    "client_phone":"",
    "client_fax":"",
    "client_mobile":"",
    "client_email":"test@whitedata.de",
    "client_web":"",
    "client_vat_id":"",
    "client_tax_code":"1",
    "client_language":"system",
    "client_active":"1",
    "client_surname":"",
    "client_avs":null,
    "client_insurednumber":null,
    "client_veka":null,
    "client_birthdate":"0000-00-00",
    "client_gender":"0",
    "client_number":"60142",
    "client_comment":"API created",
    "client_sepa_mndtId":"",
    "client_sepa_dtOfSgntr":"0000-00-00",
    "client_sepa_bic":"",
    "client_sepa_dbtr":"Testkonto Lastschrift",
    "client_sepa_iban":"DE68721516500008252405",
    "client_sepa_sequence":"1",
    "client_invoices_due_after":"7",
    "client_invoices_comment":"Du zahlst per SEPA-Lastschrift",
    "invoice_amount_id":"5548",
    "invoice_item_subtotal":"21.0000",
    "invoice_item_tax_total":"0.0000",
    "invoice_tax_total":"3.9900",
    "invoice_total":"24.99",
    "invoice_paid":"0.00",
    "invoice_balance":"24.99",
    "invoice_sign":"1",
    "is_overdue":"0",
    "days_overdue":"-7",
    "invoice_is_recurring":"0",
    "invoice_status_id":"1",
    "is_read_only":null,
    "invoice_password":"",
    "invoice_date_created":"2023-01-04",
    "invoice_time_created":"00:00:00",
    "invoice_date_modified":"2023-01-04 22:55:48",
    "invoice_date_due":"2023-01-11",
    "invoice_number":"KP215548",
    "invoice_discount_amount":"0.00",
    "invoice_discount_percent":"0.00",
    "invoice_terms":"Du zahlst per SEPA-Lastschrift.",
    "invoice_url_key":"nEoLjWGwDd5bNQ1",
    "payment_method":"2",
    "creditinvoice_parent_id":null,
    "invoice_account":"4000",
    "invoice_account_tax":"",
    "invoice_posting_key":"",
    "invoice_dunning_level":"0",
    "invoice_dun_date":"0000-00-00",
    "invoice_year_estg":"0",
    "invoice_intro":"Lieber Kunde, wir bedanken uns für deinen Kauf.",
    "invoice_sepa_debit_sent":"0",
    "invoice_tax_rates":[
       {
          "invoice_tax_rate_name":"Umsatzsteuer normal (19%)",
          "invoice_tax_rate_percent":"19.00",
          "invoice_tax_rate_id":"5774",
          "invoice_id":"5548",
          "tax_rate_id":"1",
          "include_item_tax":"0",
          "invoice_tax_rate_amount":"3.99"
       }
    ]
 }
 
                

QUERY PARAMETERS

RESULT PARAMETERS

GET Invoice by URL Key

# Here is a curl example invoice retrieval by invoice_url_key
curl -X GET "https://your-instance.faktorly.cloud/api/invoices/get_by_invoice_url_key/nEoLjWGwDd5bNQ1" \
 -H "x-api-key: xxx"

                

To GET an invoice by invoice_url_key you need to make a GET call to the following url:
https://your-instance.faktorly.cloud/api/invoices/get_by_invoice_url_key/nEoLjWGwDd5bNQ1

Result example :
200 OK
{
    "invoice_id":"5548",
    "client_id":"5142",
    "invoice_number":"KP215548",
    "invoice_url_key":"nEoLjWGwDd5bNQ1",
    "invoice_status_id":"1",
    "invoice_date_created":"2023-01-04",
    "invoice_date_due":"2023-01-11",
    "invoice_total":"24.99",
    "invoice_balance":"24.99",
    "invoice_tax_rates":[]
}
                

QUERY PARAMETERS

Set Online Payment Options

# Here is a curl example for setting online payment options
curl -X POST "https://your-instance.faktorly.cloud/api/invoices/set_online_payment_options/nEoLjWGwDd5bNQ1" \
 -H "x-api-key: xxx" \
 -H "Content-Type: application/json" \
 -d '{
    "paypal_active": 1,
    "stripe_active": 1,
    "bank_transfer_active": 0,
    "gateway": "Stripe",
    "furl": "https://www.example.com/payment-success"
 }'

                

To set online payment options for an invoice you need to make a POST call to the following url:
https://your-instance.faktorly.cloud/api/invoices/set_online_payment_options/nEoLjWGwDd5bNQ1

Result example :
200 OK
{
    "data":{
       "status":200,
       "message":"Online Payment Options has been set"
    }
 }
                

QUERY PARAMETERS

Set Payment Redirect

# Here is a curl example for setting the redirect after successful payment
curl -X POST "https://your-instance.faktorly.cloud/api/invoices/set_online_payment_options/nEoLjWGwDd5bNQ1" \
 -H "x-api-key: xxx" \
 -H "Content-Type: application/json" \
 -d '{
    "furl": "https://www.example.com/payment-success"
 }'

                

To set a redirect URL after successful payment you need to make a POST call to the following url:
https://your-instance.faktorly.cloud/api/invoices/set_online_payment_options/nEoLjWGwDd5bNQ1

Result example :
200 OK
{
    "data":{
       "status":200,
       "message":"Online Payment Options has been set"
    }
 }
                

QUERY PARAMETERS

Cancel Invoice

# Here is a curl example invoice cancellation
curl -X POST "https://your-instance.faktorly.cloud/api/invoices/cancel" \
 -H "x-api-key: xxx" \
 -H "Content-Type: application/json" \
 -d '{
    "invoice_url_key": "nEoLjWGwDd5bNQ1"
 }'

                

To cancel an invoice you need to make a POST call to the following url:
https://your-instance.faktorly.cloud/api/invoices/cancel

Result example :
200 OK
{
    "data":{
       "status":200,
       "id":"5548",
       "message":"Invoice has been cancelled"
    }
 }
                

QUERY PARAMETERS

Send Invoice Email

# Here is a curl example invoice email
curl -X POST "https://your-instance.faktorly.cloud/api/email/send_invoice" \
 -H "x-api-key: xxx" \
 -H "Content-Type: application/json" \
 -d '{
    "invoice_url_key": "nEoLjWGwDd5bNQ1",
    "email_recipient": "customer@example.com",
    "email_subject": "Your invoice",
    "email_text": "Hello, please find your invoice attached."
 }'

                

To send an invoice by email you need to make a POST call to the following url:
https://your-instance.faktorly.cloud/api/email/send_invoice

Result example :
200 OK
{
    "data":{
       "status":200,
       "id":"5548",
       "message":"Invoice has been sent"
    }
 }
                

QUERY PARAMETERS

Create Subscription

# Here is a curl example subscription creation
curl -X POST "https://your-instance.faktorly.cloud/api/subscriptions/create" \ 
 -H "x-api-key: xxx" \
 -H "Content-Type: application/json" \
 -d '{
    "client_id": 2214,
    "subscription_date_created": "2025-04-30",
    "subscription_password": "",
    "user_id": 1,
    "number_range_id": 5,
    "subscription_next_invoice_date": "2025-05-30",
    "subscription_frequency": "1M",
    "notes": "Test subscription",
    "items": [
        {
            "item_id": 1,
            "item_name": "Test Item",
            "item_description": "Test Description",
            "item_price": 100,
            "item_quantity": 1,
            "item_order": 1,
            "item_tax_rate_id": 1
        }
    ]
}

                

To create a new subscription you need to make a POST call to the following url:
https://your-instance.faktorly.cloud/api/subscriptions/create

Result example :
200 OK
{
    "data":{
       "status":200,
       "id":"5548",
       "message":"Subscription has been created"
    }
 }
                

QUERY PARAMETERS

GET Subscription

# Here is a curl example subscription retrieval
curl -X GET "https://your-instance.faktorly.cloud/api/subscriptions/get/5548" \
 -H "x-api-key: xxx"

                

To GET a subscription by ID you need to make a GET call to the following url:
https://your-instance.faktorly.cloud/api/subscriptions/get/5548

Result example :
200 OK
{
    "invoice_id":"5548",
    "client_id":"5142",
    "invoice_number":"KP215548",
    "invoice_url_key":"nEoLjWGwDd5bNQ1",
    "invoice_status_id":"1",
    "invoice_date_created":"2023-01-04",
    "invoice_date_due":"2023-01-11",
    "invoice_total":"24.99",
    "invoice_balance":"24.99",
    "invoice_tax_rates":[]
}
                

QUERY PARAMETERS

GET Subscription by URL Key

# Here is a curl example subscription retrieval by invoice_url_key
curl -X GET "https://your-instance.faktorly.cloud/api/subscriptions/get_by_invoice_url_key/nEoLjWGwDd5bNQ1" \
 -H "x-api-key: xxx"

                

To GET a subscription by invoice_url_key you need to make a GET call to the following url:
https://your-instance.faktorly.cloud/api/subscriptions/get_by_invoice_url_key/nEoLjWGwDd5bNQ1

Result example :
200 OK
{
    "invoice_id":"5548",
    "client_id":"5142",
    "invoice_number":"KP215548",
    "invoice_url_key":"nEoLjWGwDd5bNQ1",
    "invoice_status_id":"1",
    "invoice_date_created":"2023-01-04",
    "invoice_date_due":"2023-01-11",
    "invoice_total":"24.99",
    "invoice_balance":"24.99",
    "invoice_tax_rates":[]
}
                

QUERY PARAMETERS

Set Subscription Online Payment Options

# Here is a curl example for setting subscription online payment options
curl -X POST "https://your-instance.faktorly.cloud/api/subscriptions/set_online_payment_options/nEoLjWGwDd5bNQ1" \
 -H "x-api-key: xxx" \
 -H "Content-Type: application/json" \
 -d '{
    "paypal_active": 1,
    "stripe_active": 1,
    "bank_transfer_active": 0,
    "gateway": "Stripe",
    "furl": "https://www.example.com/payment-success"
 }'

                

To set online payment options for a subscription invoice you need to make a POST call to the following url:
https://your-instance.faktorly.cloud/api/subscriptions/set_online_payment_options/nEoLjWGwDd5bNQ1

Result example :
200 OK
{
    "data":{
       "status":200,
       "message":"Online Payment Options has been set"
    }
 }
                

QUERY PARAMETERS

Cancel Subscription

# Here is a curl example subscription cancellation
curl -X POST "https://your-instance.faktorly.cloud/api/subscriptions/cancel" \
 -H "x-api-key: xxx" \
 -H "Content-Type: application/json" \
 -d '{
    "invoice_url_key": "nEoLjWGwDd5bNQ1"
 }'

                

To cancel a subscription invoice you need to make a POST call to the following url:
https://your-instance.faktorly.cloud/api/subscriptions/cancel

Result example :
200 OK
{
    "data":{
       "status":200,
       "id":"5548",
       "message":"Invoice has been cancelled"
    }
 }
                

QUERY PARAMETERS

Send WhatsApp Template

# Here is a curl example WhatsApp template message
curl -X POST "https://your-instance.faktorly.cloud/api/whatsapp/send_template" \
 -H "x-api-key: xxx" \
 -H "Content-Type: application/json" \
 -d '{
    "client_id": 5142,
    "template_name": "invoice_reminder",
    "language_code": "de",
    "parameters": [
        "Max Mustermann",
        "KP215548"
    ]
 }'

                

To send a WhatsApp template message to a client you need to make a POST call to the following url:
https://your-instance.faktorly.cloud/api/whatsapp/send_template

Result example :
200 OK
{
    "data":{
       "client_id":5142,
       "template_name":"invoice_reminder",
       "language_code":"de",
       "parameters":["Max Mustermann","KP215548"],
       "status":"sent",
       "notice":null,
       "whatsapp_id":"wamid.xxx"
    }
 }
                

QUERY PARAMETERS

Search

# Here is a curl example search request
curl -X POST "https://your-instance.faktorly.cloud/api/search" \
 -H "x-api-key: xxx" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d "query=invoice"

                

To search functions, clients, invoices, suppliers, incoming invoices and documentation articles you need to make a POST call to the following url:
https://your-instance.faktorly.cloud/api/search

Result example :
200 OK
[
    {
        "url":"https://your-instance.faktorly.cloud/invoices/view/5548",
        "name":"KP215548 - test test",
        "type":"Invoice",
        "target":"_self"
    }
]
                

QUERY PARAMETERS

Info Version

# Here is a curl example version request
curl -X GET "https://your-instance.faktorly.cloud/api/info/version" \
 -H "x-api-key: xxx"

                

To GET the application version you need to make a GET call to the following url:
https://your-instance.faktorly.cloud/api/info/version

Result example :
200 OK
{
    "data":{
       "version":"26.5.6-1306"
    }
}
                

HTTP Response Status Codes

In each response, an HTTP response status code is included. Based on this status code, the result can be verified. The API provides the following categories of status codes:

Important Note

We will specify the status codes more precisely in the future. This means that some requests currently answered with "200 OK" (e.g., when creating a customer) will be replaced by the more detailed 2xx code (e.g., 201 CREATED when creating a customer). Therefore, we recommend that you check for 2xx codes in your implementations rather than specifically checking for 200 OK.

For more information on status codes, visit MDN Web Docs - HTTP Status Codes.

Legal information

Impressum | Datenschutz | AGB

© 2024 faktorly GmbH. All rights reserved.