Create booking proposal

POST /accounting/bookingProposals

cURL

cURL

curl --request POST \
  --url https://api.maesn.dev/accounting/bookingProposals \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-ACCOUNT-KEY: <x-account-key>' \
  --header 'X-API-KEY: <x-api-key>' \
  --form 'bookingProposal={
  "addresses": [
    {
      "city": "city"
    }
  ],
  "bankAccountId": "5a6b7f5dw45c1c-403e-ad56-202fbc312414",
  "bankAccountNumber": 5407324931,
  "bankCode": "50010517",
  "bic": "DEUTDEFF",
  "bookingProposalDate": "2025-07-14T00:00:00Z",
  "contactAccountNumber": 70000,
  "contactId": "eaa28f49-6028-4b6e-bb12-d8f6278073fc",
  "contactName": "John Doe",
  "currency": "EUR",
  "deliveryDate": "2025-07-26T00:00:00Z",
  "discountPaymentDate": "2025-07-16T00:00:00Z",
  "discountPaymentDate2": "2025-07-18T00:00:00Z",
  "dueDate": "2025-07-24T00:00:00Z",
  "journalCode": "60",
  "iban": "DE43100500000920018963",
  "isPaymentOrder": true,
  "ledgerName": "Payroll",
  "lineItems": [
    {
      "accountCode": "200",
      "accountId": "db32-4f56-8a9b-1234567890ab",
      "accountName": "EXPENSE",
      "accountNumber": 4900,
      "bookingTaxCode": "9",
      "description": "Item A",
      "dimension1": "Marketing",
      "dimension2": "Service and Maintenance",
      "discountAmount": 100,
      "discountAmount2": 50,
      "discountPercentage": 20,
      "discountPercentage2": 10,
      "taxCode": "02",
      "taxRatePercentage": 19,
      "totalGrossAmount": 500,
      "totalNetAmount": 450,
      "type": "SERVICES"
    }
  ],
  "notes": "Bill for maintenance services",
  "number": "1233330",
  "orderId": "3344566",
  "paidDate": "2021-01-01T00:00:00Z",
  "paymentTermsId": "03",
  "status": "DRAFT",
  "totalGrossAmount": 500,
  "vatId": "DE987654321"
}' \
  --form bookingType=INVOICE \
  --form 'folderManagement={
  "category": "Accounting",
  "folder": "Invoices",
  "register": "2025 January"
}' \
  --form files.items='@example-file'

200

{
  "meta": {
    "warnings": [
      "Field not used by target system"
    ],
    "pagination": {
      "total": 125,
      "perPage": 50,
      "currentPage": 1,
      "totalPages": 3
    }
  },
  "data": {
    "id": "BP-12345",
    "addresses ": [
      {
        "city": "city"
      }
    ],
    "bankAccountId": "5a6b7f5dw45c1c-403e-ad56-202fbc312414",
    "bankAccountNumber": 5407324931,
    "bankCode": "50010517",
    "bic": "DEUTDEFF",
    "bookingProposalDate": "2025-07-14T00:00:00Z",
    "bookingType": "INVOICE",
    "contactAccountNumber": 70000,
    "contactId": "eaa28f49-6028-4b6e-bb12-d8f6278073fc",
    "contactName ": "John Doe",
    "createdDate": "2025-07-16T00:00:00Z",
    "currency": "EUR",
    "deliveryDate": "2025-07-26T00:00:00Z",
    "discountPaymentDate": "2025-07-16T00:00:00Z",
    "discountPaymentDate2": "2025-07-18T00:00:00Z",
    "dueDate": "2025-07-24T00:00:00Z",
    "files": [
      "file1.pdf"
    ],
    "journalCode": "60",
    "iban": "DE43100500000920018963",
    "isPaymentOrder": "true",
    "ledgerName": "Payroll",
    "lineItems": [
      {
        "id": "Item-112233",
        "accountCode": "200",
        "accountId": "db32-4f56-8a9b-1234567890ab",
        "accountName": "EXPENSE",
        "accountNumber": 4900,
        "bookingTaxCode": "9",
        "createdDate": "2021-01-01T00:00:00Z",
        "description": "Item A",
        "dimension1": "Marketing",
        "dimension2": "Service and Maintenance",
        "discountAmount": 100,
        "discountAmount2": 50,
        "discountPercentage": 20,
        "discountPercentage2": 10,
        "taxCode": "02",
        "taxRatePercentage": 19,
        "totalGrossAmount": 500,
        "totalNetAmount": 450,
        "type": "SERVICES",
        "updatedDate": "2021-01-01T00:00:00Z"
      }
    ],
    "notes": "Bill for maintenance services",
    "number": "1233330",
    "orderId": "3344566",
    "paidDate": "2021-01-01T00:00:00Z",
    "paymentTermsId": "03",
    "status": "DRAFT",
    "taskId": "ADHUR74BCBSW8399DCN",
    "totalGrossAmount": 500,
    "updatedDate": "2025-07-16T00:00:00Z",
    "vatId": "DE987654321"
  }
}

Field support per integration

DATEV Unternehmen Online

This endpoint has been deprecated. Please use the Create Booking Proposal Async endpoint.

This endpoints is asynchronous. To check the status of the request, use the GET asyncTask endpoint.

For more info about asynchronous tasks visit the Asynchronous Task section.

If you’re not using the Interactive Authentication Flow, make sure the query parameter companyId is accurately populated with the appropriate company ID. You can obtain this value by using the GET Companies endpoint available under the Authentication section.

Supported Request Parameters:

bookingProposal · string · required

Show properties

id · string

The id field represents the unique identifier of the booking proposal.

The id must be a valid UUID; otherwise, it will be ignored.

This field is only relevant and used when uploading files with the booking proposal.

addresses · Address[]

Show properties

city · string

The city must not exceed 30 characters in length.

bankAccountNumber · number

The bankAccountNumber field must be 1-10 digits long and includes only numbers.

If bankAccountNumber is provided, then bankCode is required.

Example: 532013000

bankCode · string

The bankCode must respect the following pattern: ^([1-9]|[0-9]{2,10})$

If bankCode is provided, then bankAccountNumber is required.

Example: 37040044

bic · string

The bic field must respect the following pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}[A-Z0-9]{0,3}$.

Example: DEUTDEFF.

bookingProposalDate · string · required

For date format details visits the Standardized Data section.

contactAccountNumber · number

The contactAccountNumber field represents the account number of the contact associated with the booking proposal.

It must be a valid number. The length must be equal to the account configured length + 1.

It is the customer account number for INVOICE or the vendor account number for BILL.

contactName · string

The contactName field represents the name of the contact associated with the booking proposal.

It cannot exceed 50 characters in length.

currency · enum · required

The currency field supports ISO 4217 (3-letter codes). For details visits the Standardized Data section.

deliveryDate · string

For date format details visits the Standardized Data section.

discountPaymentDate · string

For date format details visits the Standardized Data section.

The discountPaymentDate field represents the date until which a discount (discountAmount and discountPercentage in line items) can be applied to the payment.

If discountPaymentDate is provided, then discountAmount and discountPercentage are required for each line item.

Its value must be earlier than the dueDate and later than the bookingProposalDate.

discountPaymentDate2 · string

For date format details visits the Standardized Data section.

The discountPaymentDate2 field represents the date until which a discount (discountAmount2 and discountPercentage2 in line items) can be applied to the payment.

If provided, discountPaymentDate, discountAmount, discountPercentage, discountAmount2 and discountPercentage2 are required for each line item.

Its value must be earlier than the dueDate and later than the bookingProposalDate and discountPaymentDate.

dueDate · string

For date format details visits the Standardized Data section.

The dueDate field represents the date by which the payment for the booking proposal is expected to be made.

It is required when discount fields are provided. It must be after the bookingProposalDate.

iban · string

The iban field must respect the following pattern: ^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$.

Example: DE89370400440532013000.

isPaymentOrder · boolean

The isPaymentOrder field determines whether a payment instruction (transfer for bills or direct debit for invoices) should be automatically created when the booking proposal is processed.

It must be false if paymentTermId is equal to 9.

ledgerName · string · required

The ledgerName field represents the name of the correct ledger folder where the data will be sent to.

To get the correct name, you can use the GET Accounts endpoint.

For INVOICE booking proposals, the ledgerName must be of type ACCOUNT_RECEIVABLE, and for BILL booking proposals, it must be of type ACCOUNT_PAYABLE.

lineItems · BookingLineItem[] · required

Depending on the Rechnungsdatenschnittstelle (invoice data interface) settings in DATEV Unternehmen Online, either a single booking proposal or one booking proposal per line item is created. Please check your configuration to ensure the desired behavior.

Show properties

accountName · string

The accountName field specifies the name of the general ledger account linked to the individual line item within the invoice or bill.

It cannot exceed 40 characters in length.

accountNumber · number

The accountNumber field specifies the general ledger account linked to the individual line item within the invoice or bill.

It must be a valid number. The length must be equal to the account configured length.

bookingTaxCode · string

The bookingTaxCode field represents the BU code associated with the line item.

It must be max 4 characters long. Only numbers are allowed.

description · string

The description field provides details about the specific line item in the booking proposal.

It cannot exceed 60 characters in length.

dimension1 · string

The dimension1 field represents the information for cost accounting (KOST1).

It cannot exceed 36 characters in length. It must follow the pattern : ^([\S][\S ]{0,34}[\S]|[\S]{0,1})$.

Example: Marketing.

dimension2 · string

The dimension2 field represents the information for cost accounting (KOST2).

It cannot exceed 36 characters in length. It must follow the pattern : ^([\S][\S ]{0,34}[\S]|[\S]{0,1})$.

Example: IT department.

discountAmount · number

The discountAmount field represents the fixed amount to be discounted if paid by the discountPaymentDate.

It must be a positive number with up to 8 digits before the decimal point and exactly 2 digits after.

It cannot exceed the line item’s totalGrossAmount.

discountAmount2 · number

The discountAmount2 field represents the fixed amount to be discounted if paid by the discountPaymentDate2.

It must be a positive number with up to 8 digits before the decimal point and exactly 2 digits after.

It cannot exceed the line item’s totalGrossAmount and the discountAmount.

discountPercentage · number

The discountPercentage field represents the percentage to be discounted if paid by the discountPaymentDate.

It must be a positive number with up to 2 digits before the decimal point and up to 2 digits after.

It cannot exceed 100%.

discountPercentage2 · number

The discountPercentage2 field represents the percentage to be discounted if paid by the discountPaymentDate2.

It must be a positive number with up to 2 digits before the decimal point and up to 2 digits after.

It must be less then the discountPercentage.

taxRatePercentage · number

The taxRatePercentage field represents the tax rate applied to the line item.

It must be a positive number.

totalGrossAmount · number · required

The totalGrossAmount field represents the total gross amount for the specific line item.

It must be a number with up to 10 digits before the decimal point and up to 2 digits after.

It cannot be zero.

notes · string

The notes field allows for additional information or comments related to the booking proposal. It cannot exceed 120 characters in length.

number · string · required

The number field represents the document number.

It must match the pattern: ^[a-zA-Z0-9$%&*\+\-/]{0,36}$.

orderId · string

The orderId field represents the order identifier associated with the booking proposal.

It must match the pattern: ^[a-zA-Z0-9$%&*+\-./]{1,30}$.

paidDate · string

For date format details visits the Standardized Data section.

paymentTermsId · string

The paymentTermsId field represents the identifier of the payment term associated with the booking proposal.

It is max 3 characters long. It must includes only numbers.

If provided, the discount fields are not allowed.

totalGrossAmount · number · required

The totalGrossAmount field represents the total gross amount for the entire booking proposal.

It cannot be zero and must equal the sum of the totalGrossAmount of all line items.

vatId · string

The vatId field represents the VAT identification number associated with the booking proposal.

It must match pattern: ^[0-9a-zA-Z\. _]{1,15}$.

bookingType · BookingType · required

Available options: INVOICE, BILL

files · file[]

The files array can be used to attach files to the booking proposal.

The name of the uploaded files must include the file extension, for example invoice.pdf.

The file name must not exceed 255 characters in length.

folderManagement · FolderManagement

The folderManagement object defines the three-level folder structure for a booking proposal. If not provided, the default structure will be used.

Show properties

category · string · required

The category field represents the top-level folder in the folder structure.

folder · string · required

The folder field represents the second-level folder in the folder structure.

register · string · required

The register field represents the third-level folder in the folder structure.

Exact Online

If you’re not using the Interactive Authentication Flow, make sure the query parameter companyId is correctly populated. You can obtain this value by using the GET Companies endpoint available under the Authentication section.

Supported Request Parameters:

bookingProposal · string · required

Show properties

bookingProposalDate · string

ISO-8601 date format, e.g., 2024-01-01T00:00:00Z

contactId · string · required

The contactId represents the contact associated with the booking proposal. If the bookingType is BILL, this must be the id of a supplier. If the booking type is INVOICE, this must be the id of a customer.

currency · enum

Available options (3-letter ISO 4217): AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYR, BZD, CAD, CDF, CHF, CLP, CNY, COP, CRC, CUC, CVE, CZK, DJF, DKK, DOP, DZD, EEK, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GQE, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MYR, MZM, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SRD, SYP, SZL, THB, TJS, TMT, TND, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VEB, VND, VUV, WST, XAF, XCD, XDR, XOF, XPF, YER, ZAR, ZMK, ZWR

dueDate · string

ISO-8601 date format, e.g., 2024-01-01T00:00:00Z

journalCode · string · required

lineItems · BookingLineItem[] · required

Show properties

accountId · string · required

The accountId field specifies the id of the general ledger account linked to the individual line item within the booking proposal.

description · string

dimension1 · string

The dimension1 field represents the name of CostCenter category.

dimension2 · string

The dimension2 field represents the name of CostUnit category.

taxCode · string

If the taxCode is not provided, it will be set to the default tax code for the account.

taxRatePercentage · number

totalNetAmount · number

If the taxCode is provided and is of type INCLUSIVE, the totalNetAmount will be treated as a gross amount (i.e., including tax).

notes · string

paymentTermsId · string

The paymentTermsId field represents the code of the payment term associated with the booking proposal.

To get the correct code, you can use the GET PaymentTerms endpoint.

bookingType · BookingType · required

Available options: INVOICE, BILL, INVOICE_CREDIT_NOTE

files · file[]

The file name must not exceed 255 characters in length.

Lexware Office

Supported Request Parameters:

bookingProposal · string · required

Show properties

bookingProposalDate · string

ISO-8601 date format, e.g., 2024-01-01T00:00:00Z

contactId · string · required

The contactId field represents the id of the contact associated with the booking proposal.

deliveryDate · string

ISO-8601 date format, e.g., 2024-01-01T00:00:00Z

It is only supported for booking proposals of type INVOICE.

dueDate · string

ISO-8601 date format, e.g., 2024-01-01T00:00:00Z

lineItems · BookingLineItem[] · required

Show properties

accountId · string · required

The accountId field specifies the id of the posting category in Lexware that represents the general ledger account linked to the individual line item within the booking proposal.

To get the correct accountId, you can use the GET Accounts endpoint.

taxRatePercentage · number · required

totalGrossAmount · number · required

notes · string

number · string

totalGrossAmount · number

bookingType · BookingType · required

Available options: BILL, INVOICE

files · file[]

The file name must not exceed 255 characters in length.

Moneybird

If you’re not using the Interactive Authentication Flow, make sure the query parameter companyId is correctly populated. You can obtain this value by using the GET Companies endpoint available under the Authentication section.

Supported Request Parameters:

bookingProposal · string · required

Show properties

bookingProposalDate · string

ISO-8601 date format, e.g., 2024-01-01T00:00:00Z

It is required for booking proposals of type BILL.

contactId · string · required

The contactId field represents the id of the contact associated with the booking proposal.

dueDate · string

ISO-8601 date format, e.g., 2024-01-01T00:00:00Z

It is only supported for booking proposals of type BILL.

lineItems · BookingLineItem[] · required

Show properties

accountId · string

The accountId field specifies the id of ledger account linked to the individual line item within the booking proposal.

To get the correct accountId, you can use the GET Accounts endpoint.

description · string

taxCode · string

The taxCode field represents the tax code associated with the line item.

To get the correct code, you can use the GET TaxRates endpoint.

It is required for booking proposals of type BILL.

totalGrossAmount · number

number · string

The number field represents the reference number of the booking proposal.

It is required for booking proposals of type BILL.

paymentTermsId · string

The paymentTermsId field represents the reference or description of the payment term associated with the booking proposal.

It is only supported for booking proposals of type INVOICE

bookingType · BookingType · required

Available options: BILL, INVOICE

files · file[]

The file name must not exceed 255 characters in length.

Sage Accounting

This endpoint is available only for the following countries: Accounting Plus: Canada, United Kingdom, Ireland
Accounting Standard: United Kingdom, Ireland
Accounting Start: Canada, United Kingdom, Ireland

When handling a new connection in your integration, it is advisable to first determine which subscription your customer is using to ensure compatibility. To do this, you can use the GET Companies call to retrieve all businesses available for the user. The user will then select one of these businesses. It is also a good practice to verify that the active property of the selected business is set to true before proceeding with the integration setup.

Supported Request Parameters:

bookingProposal · string · required

Show properties

bookingProposalDate · string · required

ISO-8601 date format, e.g., 2024-01-01T00:00:00Z

contactId · string · required

The contactId field represents the id of the contact associated with the booking proposal.

dueDate · string

ISO-8601 date format, e.g., 2024-01-01T00:00:00Z

It is only supported higher subscription levels (Accounting Plus and Accounting Standard).

lineItems · BookingLineItem[] · required

Show properties

accountId · number · required

The accountId field specifies the general ledger account linked to the individual line item within the invoice or bill.

description · string · required

taxCode · string · required

totalGrossAmount · number · required

type · enum · required

Available options: GOODS, SERVICES

notes · string

number · string

paymentTermsId · string

The paymentTermsId field represents the reference or description of the payment term associated with the booking proposal.

bookingType · BookingType · required

Available options: INVOICE

sevdesk

Supported Request Parameters:

bookingProposal · string · required

Show properties

contactId · string · required

The contactId field represents the id of the contact associated with the booking proposal.

contactName · string

The contactName field represents the name of the contact associated with the booking proposal.

currency · enum

Available options (3-letter ISO 4217): AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYR, BZD, CAD, CDF, CHF, CLP, CNY, COP, CRC, CUC, CVE, CZK, DJF, DKK, DOP, DZD, EEK, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GQE, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MYR, MZM, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SRD, SYP, SZL, THB, TJS, TMT, TND, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VEB, VND, VUV, WST, XAF, XCD, XDR, XOF, XPF, YER, ZAR, ZMK, ZWR

deliveryDate · string

ISO-8601 date format, e.g., 2024-01-01T00:00:00Z

dueDate · string

ISO-8601 date format, e.g., 2024-01-01T00:00:00Z

lineItems · BookingLineItem[] · required

Show properties

accountNumber · number · required

The accountNumber field specifies the general ledger account linked to the individual line item within the invoice or bill.

taxRatePercentage · number · required

totalGrossAmount · number · required

Either the totalGrossAmount or totalNetAmount field must be provided.

totalNetAmount · number · required

Either the totalGrossAmount or totalNetAmount field must be provided.

notes · string

paidDate · string

ISO-8601 date format, e.g., 2024-01-01T00:00:00Z

status · enum

Available options : DRAFT, OPEN
A booking proposal must have status OPEN to be marked as paid via the /payments endpoint.

bookingType · BookingType · required

Available options: INVOICE, BILL

files · file[]

The file name must not exceed 255 characters in length.

Snelstart

Supported Request Parameters:

bookingProposal · string · required

Show properties

bookingProposalDate · string · required

ISO-8601 date format, e.g., 2024-01-01T00:00:00Z

contactId · string · required

Id of the related contact. For invoice proposals, this is the customer id. For bill proposals, this is the supplier id.

lineItems · BookingLineItem[] · required

Show properties

accountId · string · required

The accountId field specifies the id of the general ledger account linked to the individual line item within the booking proposal.

description · string

dimension1 · string

taxCode · string

Note that if the taxCode is provided, the taxRatePercentage must be provided too.

taxRatePercentage · string

Note that if the taxRatePercentage is provided, the taxCode must be provided too.

totalNetAmount · number · required

notes · string

number · string · required

paymentTermsId · string

The number of days until the booking proposal is due.

bookingType · BookingType · required

Available options: BILL, INVOICE

files · file[]

The file name must not exceed 255 characters in length.

Visma e-conomic

Supported Request Fields:

bookingProposal · string · required

Show properties

bookingProposalDate · string

ISO-8601 date format, e.g., 2024-01-01T00:00:00Z

currency · string · required

contactId · string · required

The contactId field represents the id of the contact associated with the booking proposal.

journalCode · string · required

lineItems · BookingLineItem[] · required

Show properties

accountId · string · required

taxCode · string

notes · string

totalGrossAmount · number · required

bookingType · BookingType · required

Available options: BILL, INVOICE

Xero

Supported Request Parameters:

bookingProposal · string · required

Show properties

bankAccountId · string · required

The bankAccountId field represents the id of the end user bank account associated with the booking proposal.

To get the correct id, you can use the GET Accounts endpoint. Only accounts of type BANK are accepted.

bookingProposalDate · string

ISO-8601 date format, e.g., 2024-01-01T00:00:00Z

contactId · string · required

The contactId field represents the id of the contact associated with the booking proposal.

lineItems · BookingLineItem[] · required

Show properties

accountCode · string · required

The accountCode field specifies the code of the general ledger account linked to the individual line item within the booking proposal.

To get the correct code, you can use the GET Accounts endpoint.

description · string

totalGrossAmount · number · required

number · string

The number field represents the reference number for the booking proposal transaction.

bookingType · BookingType · required

Available options: BILL, INVOICE

files · file[]

The file name must not exceed 255 characters in length.

Headers

X-API-KEY · string · required

API key

Example:

"example value"

X-ACCOUNT-KEY · string · required

Account key

Example:

"example value"

Query Parameters

companyId · string

Body

multipart/form-data

bookingProposal · object

Show child attributes

bookingType · enum<string>

Available options: INVOICE, BILL, INVOICE_CREDIT_NOTE

files · file[]

Array of files to upload

folderManagement · object

Show child attributes

Response

200 - application/json

meta · object

Show child attributes

data · object

Show child attributes