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

Field	Type	Description
client_active	Int	(required) 1 = active, 0 = inactive
client_name	String	(required) Name of Client
client_surname	String	Surname of Client:
client_language	String	ISO-Code. "system" for system language
client_number	String	Client Number, empty for auto
client_invoices_comment	String	Comment printed on invoice
client_invoices_due_after	Integer	Invoice due in x days
client_comment	String	Client Comment
client_address_1	String	e.g. street
client_address_2	String
client_zip	String	ZIP Code
client_city	String	City
client_invoices_comment	String	Comment printed on invoice
client_state	String	state, e.g. BY
client_country	String	country, e.g. DE
client_phone	String	Phone Number
client_fax	String	Fax number
client_mobile	String	Mobile number
client_invoices_comment	String	Comment printed on invoice
client_email	String	E-Mail Address
client_web	String	Web address
client_sepa_mndtId	String	SEPA Debit Mandate ID
client_sepa_dtOfSgntr	String	SEPA Debit Mandate Date
client_sepa_dbtr	String	SEPA Debit Account Owner
client_sepa_iban	String	SEPA IBAN
client_sepa_bic	String	SEPA BIC
client_sepa_sequence	String	Sequence of sepa mandate (1 = first, 2 = recurring, 3 = once)
client_vat_id	String	VAT ID
client_tax_code	Integer	Client Tax Code ID, see in faktorly instance settings
client_gender	Integer	0 = male, 1 = female, 3 = other
client_birthdate	String	Client birthdate YYYY-MM-DD

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

Field	Type	Description
client_id	Int	(required) client_id, see client creation request
number_range_id	Int	(required) ID of number range, see faktorly instance
user_id	Int	(required) User ID, see faktorly instance
invoice_date_created	Date	(required) Invoice Date YYYY-MM-DD
invoice_password	String	Password, if wanted
invoice_date_due	Date	Invoice Due Date YYYY-MM-DD
item_id	Integer	(empty)
item_product_id	Integer	ID of product
item_task_id	Integer	ID of task
item_name	String	Name of item
item_quantity	Integer
item_price	Double
item_description	String	Item Description
item_product_unit_id	Integer	Product Unit, see faktorly instance
item_order	Integer	Sequence
invoice_discount_amount	Double
invoice_discount_percent	Double
invoice_terms	String	Invoice Terms
client_invoices_comment	String	Comment printed on invoice
payment_method	Integer	ID of payment method, see faktorly instance
invoice_account	Integer	accounting account
invoice_tax_rate_id	Integer	ID of tax rate, see faktorly instance
invoice_year_estg	Date	YYYY
invoice_intro	String	Intro printed on invoice

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

Field	Type	Description
invoice_id	Int	ID of invoice

RESULT PARAMETERS

Field	Type	Description
quote_id	Int	ID of linked quote
invoice_id	Int	ID of invoice
client_id	Int	client_id, see client creation request
client_active	Int	(required) 1 = active, 0 = inactive
client_name	String	(required) Name of Client
client_surname	String	Surname of Client:
client_language	String	ISO-Code. "system" for system language
client_number	String	Client Number, empty for auto
client_invoices_comment	String	Comment printed on invoice
client_invoices_due_after	Integer	Invoice due in x days
client_comment	String	Client Comment
client_address_1	String	e.g. street
client_address_2	String
client_zip	String	ZIP Code
client_city	String	City
client_invoices_comment	String	Comment printed on invoice
client_state	String	state, e.g. BY
client_country	String	country, e.g. DE
client_phone	String	Phone Number
client_fax	String	Fax number
client_mobile	String	Mobile number
client_invoices_comment	String	Comment printed on invoice
client_email	String	E-Mail Address
client_web	String	Web address
client_sepa_mndtId	String	SEPA Debit Mandate ID
client_sepa_dtOfSgntr	String	SEPA Debit Mandate Date
client_sepa_dbtr	String	SEPA Debit Account Owner
client_sepa_iban	String	SEPA IBAN
client_sepa_bic	String	SEPA BIC
client_sepa_sequence	String	Sequence of sepa mandate (1 = first, 2 = recurring, 3 = once)
client_vat_id	String	VAT ID
client_tax_code	Integer	Client Tax Code ID, see in faktorly instance settings
client_gender	Integer	0 = male, 1 = female, 3 = other
client_birthdate	String	Client birthdate YYYY-MM-DD
user_id	Int	User ID, see faktorly instance
invoice_date_created	Date	Invoice Date YYYY-MM-DD
invoice_password	String	Password, if wanted
invoice_date_due	Date	Invoice Due Date YYYY-MM-DD
item_id	Integer	(empty)
item_product_id	Integer	ID of product
item_task_id	Integer	ID of task
item_name	String	Name of item
item_quantity	Integer
item_price	Double
item_description	String	Item Description
item_product_unit_id	Integer	Product Unit, see faktorly instance
item_order	Integer	Sequence
invoice_discount_amount	Double
invoice_discount_percent	Double
invoice_terms	String	Invoice Terms
client_invoices_comment	String	Comment printed on invoice
payment_method	Integer	ID of payment method, see faktorly instance
invoice_account	Integer	accounting account
invoice_tax_rate_id	Integer	ID of tax rate, see faktorly instance
invoice_year_estg	Date	YYYY
invoice_intro	String	Intro printed on invoice

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

Field	Type	Description
client_id	Int	(required) client_id, see client creation request
number_range_id	Int	(required) ID of number range, see faktorly instance
user_id	Int	(required) User ID, see faktorly instance
subscription_date_created	Date	(required) Invoice Date YYYY-MM-DD
subscription_next_invoice_date	Date	Next Invoice Date YYYY-MM-DD
subscription_frequency	String	Subscription frequency, e.g. 1M, 1Y, 7d
notes	String	Subscription notes
item_id	Integer	(empty)
item_product_id	Integer	ID of product
item_task_id	Integer	ID of task
item_name	String	Name of item
item_quantity	Integer
item_price	Double
item_description	String	Item Description
item_product_unit_id	Integer	Product Unit, see faktorly instance
item_order	Integer	Sequence
invoice_discount_amount	Double
invoice_discount_percent	Double
invoice_terms	String	Invoice Terms
client_invoices_comment	String	Comment printed on invoice
payment_method	Integer	ID of payment method, see faktorly instance
invoice_account	Integer	accounting account
subscription_tax_rate_id	Integer	ID of tax rate, see faktorly instance
subscription_intro	String	Intro printed on invoices

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:

HTTP Response Status Codes	Meaning
2xx Success	(e.g., 200 OK)
4xx Client Error	(e.g., 400 BAD REQUEST)
5xx Server Error	(e.g., 500 INTERNAL SERVER ERROR)

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