Enrichment

Endpoints for data enrichment

Insert invoice including invoice lines

SecurityOAuth2

Request

Request Body schema: application/json
required

externalId required	string^\S+$ External id of the invoice that is globally unique across the provided invoice data
externalClientId	string Identifier of the client entity in the source system which can be used to separate data
documentId	string^[0-9a-fA-F]{24}$ Document id that was assigned during upload to Hypatos
	Array of objects (document) non-empty
supplierInvoiceNumber	string Invoice number provided by the issuing supplier
invoiceNumber	string Number of the invoice in the source system (not unique across clients)
externalCompanyId	string External unique id of the company in the source system
externalSupplierId	string External unique id of the supplier in the source system
externalBankAccountId	string External unique id of the bank account that the invoice payment was transferred to
fiscalYearLabel	string Label used in the source system for the fiscal year that the invoice was posted in
issuedDate	string <date> Date when the invoice was issued by the supplier (printed on invoice document)
receivedDate	string <date> Date when the invoice was recieved by the company
postingDate	string <date> Date when the invoice was posted in the source system
isCanceled	boolean Indicator if the invoice is canceled
relatedInvoice	string externalInvoiceId of related invoice
currency	string or null (CurrencyCode) Three letter currency code as defined in ISO 4217 Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYN" "BZD" "CAD" "CDF" "CHE" "CHF" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "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" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRU" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "QAR" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLE" "SLL" "SOS" "SRD" "SSP" "STN" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "UYI" "UYU" "UYW" "UZS" "VED" "VES" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL" null
totalNetAmount	number Total net amount of invoice (sum of line item net amounts)
totalFreightCharges	number Sum of all freight charges
totalOtherCharges	number Sum of all charges other than freight charges
totalTaxAmount	number Total tax amount of invoice (sum of all taxes)
totalGrossAmount	number Total gross amount of invoice (total net amount + total freight charges + total other charges + total tax amount)
	object (paymentTerms)
externalApproverId	string External unique id of the first approver of an invoice in the source system
	object (customFields) List of key value pairs containing custom fields from the source system
	object (JsonObject) Any nested structure with metadata that source system needs to send
headerText	string Header Text describing the invoice
type	string type of the invoice as defined in th source system
required	Array of objects (invoiceLine) non-empty
	Array of objects (withholdingTax)
documentType	string document type as defined in the source system

Responses

200

Successfully inserted

422

Validation error

429

Rate limit exceeded

post/enrichment/invoices

Request samples

Payload
curl
Node.js
Python
Java

application/json

{"externalId": "SUPPLIER_INVOICE-3-1",
"externalClientId": "EXTERNAL_CLIENT_ID",
"documentId": "63cac12c37bb02accb396cae",
"documents": [{"id": "63cac12c37bb02accb396cae",
"type": "invoice"
}
],
"supplierInvoiceNumber": "10000001",
"invoiceNumber": "12345",
"externalCompanyId": "DE01",
"externalSupplierId": "0000100000",
"externalBankAccountId": "12341234",
"fiscalYearLabel": "2023",
"issuedDate": "2000-12-31",
"receivedDate": "2000-12-31",
"postingDate": "2000-12-31",
"isCanceled": false,
"relatedInvoice": "SUPPLIER_INVOICE-3-2",
"currency": "EUR",
"totalNetAmount": 81,
"totalFreightCharges": 9,
"totalOtherCharges": 10,
"totalTaxAmount": 19,
"totalGrossAmount": 119,
"paymentTerms": {"paymentTermKey": "T10",
"descriptions": [{"text": "Please pay us",
"language": "en"
}
]
},
"externalApproverId": "UserID#1234",
"customFields": {"property1": "string",
"property2": "string"
},
"customMetadata": {"someTopLevelProperty": "value1",
"someNestedProperty": {"nestedProperty": "value2"
},
"someArrayProperty": ["value3",
"value4"
]
},
"headerText": "doc header text",
"type": "FI",
"invoiceLines": [{"externalId": "00000001",
"externalCompanyId": "DE01",
"accountAssignments": [{"externalGlAccountId": "0000100GL1",
"externalCostCenterId": "0000100CO1",
"glAccountCode": "GL1",
"costCenterCode": "CO1",
"quantity": 2,
"externalProjectId": "EPI1",
"externalOrderId": "EOI1",
"costElementCode": "CE1"
}
],
"type": "Service",
"quantity": 2,
"netAmount": 1.23,
"totalTaxAmount": 1.23,
"grossAmount": 100.01,
"unitOfMeasure": "kg",
"unitPrice": 19.0123,
"taxCode": {"code": "DEU_Standard",
"description": "DEU - Standard (19%)"
},
"taxJurisdictionCode": "PA0000000",
"itemText": "Virtual Event ABC",
"externalPurchaseOrderId": "4500016221",
"purchaseOrderLineNumber": "00010",
"centralBankIndicator": "123",
"customFields": {"property1": "string",
"property2": "string"
},
"customMetadata": {"someTopLevelProperty": "value1",
"someNestedProperty": {"nestedProperty": "value2"
},
"someArrayProperty": ["value3",
"value4"
]
}
}
],
"withholdingTax": [{"key": "WHT-432",
"baseAmount": 632.78,
"amount": 21.39,
"currency": "EUR"
}
],
"documentType": "supplier invoice"
}

Response samples

application/json

{"id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}

Mark invoice as deleted

SecurityOAuth2

Request

path Parameters

externalId

required

string

Previously sent externalId

query Parameters

lineNumber

string

Line number of one of the line numbers inside the Invoice. Optional, omitting means the whole Invoice is deleted.

Responses

204

Successfully marked as deleted

404

Not Found error

429

Rate limit exceeded

delete/enrichment/invoices/{externalId}

Request samples

curl
Node.js
Python
Java

Response samples

application/json

{"status": 404,
"title": "Not found"
}

Insert company

SecurityOAuth2

Request

Request Body schema: application/json
required

externalId required	string^\S+$ External id of the company that is globally unique across the provided company data
externalClientId	string Identifier of the client entity in the source system which can be used to separate data
code	string Code of the company in the source system (not unique across clients)
name required	string^[\S ]\S[\S ]$ Name of the company
nameAlternative1	string Alternative name of the company
nameAlternative2	string Alternative name of the company
nameAlternative3	string Alternative name of the company
nameAlternative4	string Alternative name of the company
street	string Street and street number where the company is located
addressAdditional	string Additional address data (e.g. apartment or suite)
postcode	string Postcode where the company is located
city	string City where the company is located
state	string State where the company is located
countryCode	string or null (CountryCode) Two letter country code as defined in ISO 3166-1 alpha-2 Enum: "AF" "AX" "AL" "DZ" "AS" "AD" "AO" "AI" "AQ" "AG" "AR" "AM" "AW" "AU" "AT" "AZ" "BS" "BH" "BD" "BB" "BY" "BE" "BZ" "BJ" "BM" "BT" "BO" "BQ" "BA" "BW" "BV" "BR" "IO" "BN" "BG" "BF" "BI" "KH" "CM" "CA" "CV" "KY" "CF" "TD" "CL" "CN" "CX" "CC" "CO" "KM" "CG" "CD" "CK" "CR" "CI" "HR" "CU" "CW" "CY" "CZ" "DK" "DJ" "DM" "DO" "EC" "EG" "SV" "GQ" "ER" "EE" "ET" "FK" "FO" "FJ" "FI" "FR" "GF" "PF" "TF" "GA" "GM" "GE" "DE" "GH" "GI" "GR" "GL" "GD" "GP" "GU" "GT" "GG" "GN" "GW" "GY" "HT" "HM" "VA" "HN" "HK" "HU" "IS" "IN" "ID" "IR" "IQ" "IE" "IM" "IL" "IT" "JM" "JP" "JE" "JO" "KZ" "KE" "KI" "KP" "KR" "KW" "KG" "LA" "LV" "LB" "LS" "LR" "LY" "LI" "LT" "LU" "MO" "MK" "MG" "MW" "MY" "MV" "ML" "MT" "MH" "MQ" "MR" "MU" "YT" "MX" "FM" "MD" "MC" "MN" "ME" "MS" "MA" "MZ" "MM" "NA" "NR" "NP" "NL" "NC" "NZ" "NI" "NE" "NG" "NU" "NF" "MP" "NO" "OM" "PK" "PW" "PS" "PA" "PG" "PY" "PE" "PH" "PN" "PL" "PT" "PR" "QA" "RE" "RO" "RU" "RW" "BL" "SH" "KN" "LC" "MF" "PM" "VC" "WS" "SM" "ST" "SA" "SN" "RS" "SC" "SL" "SG" "SX" "SK" "SI" "SB" "SO" "ZA" "GS" "SS" "ES" "LK" "SD" "SR" "SJ" "SZ" "SE" "CH" "SY" "TW" "TJ" "TZ" "TH" "TL" "TG" "TK" "TO" "TT" "TN" "TR" "TM" "TC" "TV" "UG" "UA" "AE" "GB" "US" "UM" "UY" "UZ" "VU" "VE" "VN" "VG" "VI" "WF" "EH" "YE" "ZM" "ZW" null
	Array of objects (vatId) List of VAT IDs assigned to the company
	Array of objects (taxId) List of Tax IDs assigned to the company
	object (customFields) List of key value pairs containing custom fields from the source system
	object (JsonObject) Any nested structure with metadata that source system needs to send

Responses

200

Successfully inserted

422

Validation error

429

Rate limit exceeded

post/enrichment/companies

Request samples

Payload
curl
Node.js
Python
Java

application/json

{"externalId": "DE01",
"externalClientId": "EXTERNAL_CLIENT_ID",
"code": "CODE1",
"name": "Acmne Corp.",
"nameAlternative1": "Acmne Corp.",
"nameAlternative2": "Acmne Corp.",
"nameAlternative3": "Acmne Corp.",
"nameAlternative4": "Acmne Corp.",
"street": "Hauptstr. 1",
"addressAdditional": "Eingang B",
"postcode": "10001",
"city": "Berlin",
"state": "Berlin",
"countryCode": "DE",
"vatIds": [{"id": "DE123456789",
"countryCode": "DE"
}
],
"taxIds": [{"id": "123-456-789",
"type": "TIN"
}
],
"customFields": {"property1": "string",
"property2": "string"
},
"customMetadata": {"someTopLevelProperty": "value1",
"someNestedProperty": {"nestedProperty": "value2"
},
"someArrayProperty": ["value3",
"value4"
]
}
}

Response samples

application/json

{"id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}

Mark company as deleted

SecurityOAuth2

Request

path Parameters

externalId

required

string

Previously sent externalId

Responses

204

Successfully marked as deleted

404

Not Found error

429

Rate limit exceeded

delete/enrichment/companies/{externalId}

Request samples

curl
Node.js
Python
Java

Response samples

application/json

{"status": 404,
"title": "Not found"
}

Insert supplier including related subsidiaries

SecurityOAuth2

Request

Request Body schema: application/json
required

	object
externalId required	string^\S+$ External id of the supplier that is globally unique across the provided supplier data
externalClientId	string Identifier of the client entity in the source system which can be used to separate data
code	string Code of the supplier in the source system (not unique across clients)
name required	string^[\S ]\S[\S ]$ Name of the supplier
nameAlternative1	string Alternative name of the supplier
nameAlternative2	string Alternative name of the supplier
nameAlternative3	string Alternative name of the supplier
nameAlternative4	string Alternative name of the supplier
street	string Street and street number where the supplier is located
addressAdditional	string Additional address data (e.g. apartment or suite)
postcode	string Postcode where the supplier is located
city	string City where the supplier is located
state	string State where the company is located
countryCode	string or null (CountryCode) Two letter country code as defined in ISO 3166-1 alpha-2 Enum: "AF" "AX" "AL" "DZ" "AS" "AD" "AO" "AI" "AQ" "AG" "AR" "AM" "AW" "AU" "AT" "AZ" "BS" "BH" "BD" "BB" "BY" "BE" "BZ" "BJ" "BM" "BT" "BO" "BQ" "BA" "BW" "BV" "BR" "IO" "BN" "BG" "BF" "BI" "KH" "CM" "CA" "CV" "KY" "CF" "TD" "CL" "CN" "CX" "CC" "CO" "KM" "CG" "CD" "CK" "CR" "CI" "HR" "CU" "CW" "CY" "CZ" "DK" "DJ" "DM" "DO" "EC" "EG" "SV" "GQ" "ER" "EE" "ET" "FK" "FO" "FJ" "FI" "FR" "GF" "PF" "TF" "GA" "GM" "GE" "DE" "GH" "GI" "GR" "GL" "GD" "GP" "GU" "GT" "GG" "GN" "GW" "GY" "HT" "HM" "VA" "HN" "HK" "HU" "IS" "IN" "ID" "IR" "IQ" "IE" "IM" "IL" "IT" "JM" "JP" "JE" "JO" "KZ" "KE" "KI" "KP" "KR" "KW" "KG" "LA" "LV" "LB" "LS" "LR" "LY" "LI" "LT" "LU" "MO" "MK" "MG" "MW" "MY" "MV" "ML" "MT" "MH" "MQ" "MR" "MU" "YT" "MX" "FM" "MD" "MC" "MN" "ME" "MS" "MA" "MZ" "MM" "NA" "NR" "NP" "NL" "NC" "NZ" "NI" "NE" "NG" "NU" "NF" "MP" "NO" "OM" "PK" "PW" "PS" "PA" "PG" "PY" "PE" "PH" "PN" "PL" "PT" "PR" "QA" "RE" "RO" "RU" "RW" "BL" "SH" "KN" "LC" "MF" "PM" "VC" "WS" "SM" "ST" "SA" "SN" "RS" "SC" "SL" "SG" "SX" "SK" "SI" "SB" "SO" "ZA" "GS" "SS" "ES" "LK" "SD" "SR" "SJ" "SZ" "SE" "CH" "SY" "TW" "TJ" "TZ" "TH" "TL" "TG" "TK" "TO" "TT" "TN" "TR" "TM" "TC" "TV" "UG" "UA" "AE" "GB" "US" "UM" "UY" "UZ" "VU" "VE" "VN" "VG" "VI" "WF" "EH" "YE" "ZM" "ZW" null
	Array of objects (vatId) List of VAT IDs assigned to the supplier
	Array of objects (taxId) List of Tax IDs assigned to the supplier
blockedForPosting	boolean Indicator if the supplier is blocked for posting
blockedForPayment	boolean Indicator if the supplier is blocked for payment
	Array of objects (subsidiary)
	Array of objects (bankAccount)
	object (customFields) List of key value pairs containing custom fields from the source system
	object (JsonObject) Any nested structure with metadata that source system needs to send

Responses

200

Successfully inserted

422

Validation error

429

Rate limit exceeded

post/enrichment/suppliers

Request samples

Payload
curl
Node.js
Python
Java

application/json

{"defaultAccountAssignment": {"glAccountCode": "0000100GL1",
"costCenterCode": "0000100CC1",
"externalApproverId": "MMUSTERMANN",
"externalProjectId": "PROJ1234",
"externalOrderId": "ORDER1234"
},
"externalId": "0000100000",
"externalClientId": "EXTERNAL_CLIENT_ID",
"code": "CODE1",
"name": "Acmne Corp.",
"nameAlternative1": "Acmne Corp.",
"nameAlternative2": "Acmne Corp.",
"nameAlternative3": "Acmne Corp.",
"nameAlternative4": "Acmne Corp.",
"street": "Hauptstr. 1",
"addressAdditional": "Eingang B",
"postcode": "10001",
"city": "Berlin",
"state": "Berlin",
"countryCode": "DE",
"vatIds": [{"id": "DE123456789",
"countryCode": "DE"
}
],
"taxIds": [{"id": "123-456-789",
"type": "TIN"
}
],
"blockedForPosting": false,
"blockedForPayment": false,
"supplierSubsidiaries": [{"defaultAccountAssignment": {"glAccountCode": "0000100GL1",
"costCenterCode": "0000100CC1",
"externalApproverId": "MMUSTERMANN",
"externalProjectId": "PROJ1234",
"externalOrderId": "ORDER1234"
},
"externalCompanyId": "DE01",
"paymentTerms": {"paymentTermKey": "T10",
"descriptions": [{"text": "Please pay us",
"language": "en"
}
]
},
"blockedForPosting": false,
"blockedForPayment": false,
"enabledForAutoPosting": true,
"withholdingTaxInfo": [{"key": "WHT-432",
"descriptions": [{"text": "Some very deep description of the type of withholding tax",
"language": "en"
}
]
}
]
}
],
"supplierBankAccounts": [{"externalId": "12341234",
"countryCode": "DE",
"bankAccountNumber": "78090",
"bankAccountHolder": "Maximilian Mustermann",
"iban": "DE91100000000123456789",
"bic": "CHASUS33XXX",
"bankName": "Deutsche Bank",
"bankStreet": "Hauptstr. 1",
"bankPostcode": "10001",
"bankCity": "Berlin",
"isActive": true,
"type": "SAVINGS",
"bankKey": "60-16-13"
}
],
"customFields": {"property1": "string",
"property2": "string"
},
"customMetadata": {"someTopLevelProperty": "value1",
"someNestedProperty": {"nestedProperty": "value2"
},
"someArrayProperty": ["value3",
"value4"
]
}
}

Response samples

application/json

{"id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}

Mark supplier as deleted

SecurityOAuth2

Request

path Parameters

externalId

required

string

Previously sent externalId

Responses

204

Successfully marked as deleted

404

Not Found error

429

Rate limit exceeded

delete/enrichment/suppliers/{externalId}

Request samples

curl
Node.js
Python
Java

Response samples

application/json

{"status": 404,
"title": "Not found"
}

Insert purchase order including purchase order lines

SecurityOAuth2

Request

Request Body schema: application/json
required

externalId required	string^\S+$ External id of the purchase order that is globally unique across the provided purchase order data
externalClientId	string Identifier of the client entity in the source system which can be used to separate data
purchaseOrderNumber	string Number of the purchase order in the source system (not unique across clients)
createdDate	string <date> Date when the purchase order was created in the external system
fiscalYearLabel	string Label used in the source system for the fiscal year that the purchase order was created in
language	string or null Two letter language code as defined in ISO 639-1 Enum: "aa" "ab" "ae" "af" "ak" "am" "an" "ar" "as" "av" "ay" "az" "ba" "be" "bg" "bh" "bi" "bm" "bn" "bo" "br" "bs" "ca" "ce" "ch" "co" "cr" "cs" "cu" "cv" "cy" "da" "de" "dv" "dz" "ee" "el" "en" "eo" "es" "et" "eu" "fa" "ff" "fi" "fj" "fo" "fr" "fy" "ga" "gd" "gl" "gn" "gu" "gv" "ha" "he" "hi" "ho" "hr" "ht" "hu" "hy" "hz" "ia" "id" "ie" "ig" "ii" "ik" "io" "is" "it" "iu" "ja" "jv" "ka" "kg" "ki" "kj" "kk" "kl" "km" "kn" "ko" "kr" "ks" "ku" "kv" "kw" "ky" "la" "lb" "lg" "li" "ln" "lo" "lt" "lu" "lv" "mg" "mh" "mi" "mk" "ml" "mn" "mr" "ms" "mt" "my" "na" "nb" "nd" "ne" "ng" "nl" "nn" "no" "nr" "nv" "ny" "oc" "oj" "om" "or" "os" "pa" "pi" "pl" "ps" "pt" "qu" "rm" "rn" "ro" "ru" "rw" "sa" "sc" "sd" "se" "sg" "si" "sk" "sl" "sm" "sn" "so" "sq" "sr" "ss" "st" "su" "sv" "sw" "ta" "te" "tg" "th" "ti" "tk" "tl" "tn" "to" "tr" "ts" "tt" "tw" "ty" "ug" "uk" "ur" "uz" "ve" "vi" "vo" "wa" "wo" "xh" "yi" "yo" "za" "zh" "zu" null
externalCompanyId	string Company that the purchase order is assigned to
type	string type of the purchase order as defined in the source system
externalSupplierId	string External unique id of the supplier in the source system
status	string Status of purchase order as defined in source system
currency	string or null (CurrencyCode) Three letter currency code as defined in ISO 4217 Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYN" "BZD" "CAD" "CDF" "CHE" "CHF" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "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" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRU" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "QAR" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLE" "SLL" "SOS" "SRD" "SSP" "STN" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "UYI" "UYU" "UYW" "UZS" "VED" "VES" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL" null
totalNetAmount	number Total net amount of purchase order (sum of line item net amounts)
totalFreightCharges	number Sum of all freight charges as defined on the purchase order
totalOtherCharges	number Sum of all charges other than freight charges as defined on the purchase order
totalTaxAmount	number Total tax amount of purchase order (sum of all taxes)
totalGrossAmount	number Total gross amount of purchase order (total net amount + total freight charges + total other charges + total tax amount)
	object (paymentTerms)
	object (customFields) List of key value pairs containing custom fields from the source system
	object (JsonObject) Any nested structure with metadata that source system needs to send
	Array of objects (purchaseOrderLine)
productNumber	string Number of the product as defined by the purchaser

Responses

200

Successfully inserted

422

Validation error

429

Rate limit exceeded

post/enrichment/purchase-orders

Request samples

Payload
curl
Node.js
Python
Java

application/json

{"externalId": "4500016221",
"externalClientId": "EXTERNAL_CLIENT_ID",
"purchaseOrderNumber": "PoNumber123",
"createdDate": "2000-12-31",
"fiscalYearLabel": "2023",
"language": "string",
"externalCompanyId": "DE01",
"type": "Service",
"externalSupplierId": "0000100000",
"status": "OPEN",
"currency": "EUR",
"totalNetAmount": 81,
"totalFreightCharges": 9,
"totalOtherCharges": 10,
"totalTaxAmount": 19,
"totalGrossAmount": 119,
"paymentTerms": {"paymentTermKey": "T10",
"descriptions": [{"text": "Please pay us",
"language": "en"
}
]
},
"customFields": {"property1": "string",
"property2": "string"
},
"customMetadata": {"someTopLevelProperty": "value1",
"someNestedProperty": {"nestedProperty": "value2"
},
"someArrayProperty": ["value3",
"value4"
]
},
"purchaseOrderLines": [{"purchaseOrderLineNumber": "00010",
"externalCompanyId": "DE01",
"accountAssignments": [{"externalGlAccountId": "0000100GL1",
"externalCostCenterId": "0000100CO1",
"glAccountCode": "GL1",
"costCenterCode": "CO1",
"quantity": 2,
"externalProjectId": "EPI1",
"externalOrderId": "EOI1",
"costElementCode": "CE1"
}
],
"type": "Service",
"subType": "Extra Qualifier",
"quantity": 2,
"status": "OPEN",
"netAmount": 1.23,
"totalTaxAmount": 1.23,
"grossAmount": 100.01,
"unitOfMeasure": "kg",
"unitPrice": 19.0123,
"taxCode": {"code": "DEU_Standard",
"description": "DEU - Standard (19%)"
},
"itemText": "Dell Laptop Latitude D630",
"material": {"externalId": "2a6300181f08402e710ea3f180214bc1",
"supplierNumber": "123456789",
"type": "Operating Supplies",
"group": "Electronics",
"description": "Dell Laptop Latitude D630",
"manufacturer": "Acme Corporation",
"manufacturerNumber": "ACME-12345",
"unspsc": "43211508"
},
"plant": "PLANT-001",
"delivered": true,
"completelyInvoiced": true,
"approved": true,
"customFields": {"property1": "string",
"property2": "string"
},
"customMetadata": {"someTopLevelProperty": "value1",
"someNestedProperty": {"nestedProperty": "value2"
},
"someArrayProperty": ["value3",
"value4"
]
}
}
],
"productNumber": "123456789"
}

Response samples

application/json

{"id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}

Mark purchase Order as deleted

SecurityOAuth2

Request

path Parameters

externalId

required

string

Previously sent externalId

query Parameters

lineNumber

string

Line number of one of the line numbers inside the PO. Optional, omitting means the whole PO is deleted.

Responses

204

Successfully marked as deleted

404

Not Found error

429

Rate limit exceeded

delete/enrichment/purchase-orders/{externalId}

Request samples

curl
Node.js
Python
Java

Response samples

application/json

{"status": 404,
"title": "Not found"
}

Insert general ledger account

SecurityOAuth2

Request

Request Body schema: application/json
required

externalId required	string^\S([\S ]*\S)?$ External id of the general ledger account that is globally unique across the provided general ledger account data
externalClientId	string Identifier of the client entity in the source system which can be used to separate data
code required	string^\S([\S ]*\S)?$ Code of the general ledger account in the source system (not unique across clients)
companyAssignment	Array of strings List of externalCompanyIds that the approver is assigned to
	object (languagedTextWithValue)
	object (languagedTextWithValue)
	Array of objects (languagedText) Label describing the general ledger account
	Array of objects (languagedText) Short label describing the general ledger account
	object (customFields) List of key value pairs containing custom fields from the source system
	object (JsonObject) Any nested structure with metadata that source system needs to send

Responses

200

Successfully inserted

422

Validation error

429

Rate limit exceeded

post/enrichment/gl-accounts

Request samples

Payload
curl
Node.js
Python
Java

application/json

{"externalId": "0000100GL1",
"externalClientId": "EXTERNAL_CLIENT_ID",
"code": "GL1",
"companyAssignment": ["DE01",
"US01"
],
"type": {"value": "OE",
"labels": [{"text": "Fish & Chips",
"language": "en"
}
]
},
"category": {"value": "OE",
"labels": [{"text": "Fish & Chips",
"language": "en"
}
]
},
"label": [{"text": "Entertainment Expenses",
"language": "en"
}
],
"shortLabel": [{"text": "Entertainment Exp.",
"language": "en"
}
],
"customFields": {"property1": "string",
"property2": "string"
},
"customMetadata": {"someTopLevelProperty": "value1",
"someNestedProperty": {"nestedProperty": "value2"
},
"someArrayProperty": ["value3",
"value4"
]
}
}

Response samples

application/json

{"id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}

Mark general ledger account as deleted

SecurityOAuth2

Request

path Parameters

externalId

required

string

Previously sent externalId

Responses

204

Successfully marked as deleted

404

Not Found error

429

Rate limit exceeded

delete/enrichment/gl-accounts/{externalId}

Request samples

curl
Node.js
Python
Java

Response samples

application/json

{"status": 404,
"title": "Not found"
}

Insert cost center

SecurityOAuth2

Request

Request Body schema: application/json
required

externalId required	string^\S([\S ]*\S)?$ External id of the cost center that is globally unique across the provided cost center data
externalClientId	string Identifier of the client entity in the source system which can be used to separate data
code required	string^\S([\S ]*\S)?$ Code of the cost center in the source system (not unique across clients)
companyAssignment	Array of strings List of externalCompanyIds that the approver is assigned to
	object (languagedTextWithValue)
	object (languagedTextWithValue)
	Array of objects (languagedText) Label describing the cost center
	Array of objects (languagedText) Short label describing the cost center
	object (customFields) List of key value pairs containing custom fields from the source system
	object (JsonObject) Any nested structure with metadata that source system needs to send

Responses

200

Successfully inserted

422

Validation error

429

Rate limit exceeded

post/enrichment/cost-centers

Request samples

Payload
curl
Node.js
Python
Java

application/json

{"externalId": "0000100CO1",
"externalClientId": "EXTERNAL_CLIENT_ID",
"code": "CO1",
"companyAssignment": ["DE01",
"US01"
],
"type": {"value": "OE",
"labels": [{"text": "Fish & Chips",
"language": "en"
}
]
},
"category": {"value": "OE",
"labels": [{"text": "Fish & Chips",
"language": "en"
}
]
},
"label": [{"text": "Sales Engineers",
"language": "en"
}
],
"shortLabel": [{"text": "Sales Eng.",
"language": "en"
}
],
"customFields": {"property1": "string",
"property2": "string"
},
"customMetadata": {"someTopLevelProperty": "value1",
"someNestedProperty": {"nestedProperty": "value2"
},
"someArrayProperty": ["value3",
"value4"
]
}
}

Response samples

application/json

{"id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}

Mark cost Center as deleted

SecurityOAuth2

Request

path Parameters

externalId

required

string

Previously sent externalId

Responses

204

Successfully marked as deleted

404

Not Found error

429

Rate limit exceeded

delete/enrichment/cost-centers/{externalId}

Request samples

curl
Node.js
Python
Java

Response samples

application/json

{"status": 404,
"title": "Not found"
}

Insert approver

SecurityOAuth2

Request

Request Body schema: application/json
required

externalId required	string^\S+$ External id of the approver that is globally unique across the provided approver data
externalClientId	string Identifier of the client entity in the source system which can be used to separate data
code	string Code of the approver in the source system (not unique across clients)
companyAssignment	Array of strings List of externalCompanyIds that the approver is assigned to
isActive	boolean
firstName	string First name of the approving person
lastName	string Last name of the approving person
email	string <email> Email address of the approving person
phoneNumber	string Phone number of the approving person
	object (customFields) List of key value pairs containing custom fields from the source system
	object (JsonObject) Any nested structure with metadata that source system needs to send

Responses

200

Successfully inserted

422

Validation error

429

Rate limit exceeded

post/enrichment/approvers

Request samples

Payload
curl
Node.js
Python
Java

application/json

{"externalId": "UserID#1234",
"externalClientId": "EXTERNAL_CLIENT_ID",
"code": "CODE1",
"companyAssignment": ["DE01",
"US01"
],
"isActive": true,
"firstName": "Koala",
"lastName": "Hinze",
"email": "accountant@sap.com",
"phoneNumber": 491001234567891,
"customFields": {"property1": "string",
"property2": "string"
},
"customMetadata": {"someTopLevelProperty": "value1",
"someNestedProperty": {"nestedProperty": "value2"
},
"someArrayProperty": ["value3",
"value4"
]
}
}

Response samples

application/json

{"id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}

Mark approver as deleted

SecurityOAuth2

Request

path Parameters

externalId

required

string

Previously sent externalId

Responses

204

Successfully marked as deleted

404

Not Found error

429

Rate limit exceeded

delete/enrichment/approvers/{externalId}

Request samples

curl
Node.js
Python
Java

Response samples

application/json

{"status": 404,
"title": "Not found"
}

Insert customer

SecurityOAuth2

Request

Request Body schema: application/json
required

externalId required	string^\S+$ External id of the customer that is globally unique across the provided customer data
externalClientId	string Identifier of the client entity in the source system which can be used to separate data
code	string Code of the customer in the source system (not unique across clients)
name required	string^[\S ]\S[\S ]$ Name of the customer
nameAlternative1	string Alternative name of the customer
nameAlternative2	string Alternative name of the customer
nameAlternative3	string Alternative name of the customer
nameAlternative4	string Alternative name of the customer
street	string Street and street number where the customer is located
addressAdditional	string Additional address data (e.g. apartment or suite)
postcode	string Postcode where the customer is located
city	string City where the customer is located
countryCode	string or null (CountryCode) Two letter country code as defined in ISO 3166-1 alpha-2 Enum: "AF" "AX" "AL" "DZ" "AS" "AD" "AO" "AI" "AQ" "AG" "AR" "AM" "AW" "AU" "AT" "AZ" "BS" "BH" "BD" "BB" "BY" "BE" "BZ" "BJ" "BM" "BT" "BO" "BQ" "BA" "BW" "BV" "BR" "IO" "BN" "BG" "BF" "BI" "KH" "CM" "CA" "CV" "KY" "CF" "TD" "CL" "CN" "CX" "CC" "CO" "KM" "CG" "CD" "CK" "CR" "CI" "HR" "CU" "CW" "CY" "CZ" "DK" "DJ" "DM" "DO" "EC" "EG" "SV" "GQ" "ER" "EE" "ET" "FK" "FO" "FJ" "FI" "FR" "GF" "PF" "TF" "GA" "GM" "GE" "DE" "GH" "GI" "GR" "GL" "GD" "GP" "GU" "GT" "GG" "GN" "GW" "GY" "HT" "HM" "VA" "HN" "HK" "HU" "IS" "IN" "ID" "IR" "IQ" "IE" "IM" "IL" "IT" "JM" "JP" "JE" "JO" "KZ" "KE" "KI" "KP" "KR" "KW" "KG" "LA" "LV" "LB" "LS" "LR" "LY" "LI" "LT" "LU" "MO" "MK" "MG" "MW" "MY" "MV" "ML" "MT" "MH" "MQ" "MR" "MU" "YT" "MX" "FM" "MD" "MC" "MN" "ME" "MS" "MA" "MZ" "MM" "NA" "NR" "NP" "NL" "NC" "NZ" "NI" "NE" "NG" "NU" "NF" "MP" "NO" "OM" "PK" "PW" "PS" "PA" "PG" "PY" "PE" "PH" "PN" "PL" "PT" "PR" "QA" "RE" "RO" "RU" "RW" "BL" "SH" "KN" "LC" "MF" "PM" "VC" "WS" "SM" "ST" "SA" "SN" "RS" "SC" "SL" "SG" "SX" "SK" "SI" "SB" "SO" "ZA" "GS" "SS" "ES" "LK" "SD" "SR" "SJ" "SZ" "SE" "CH" "SY" "TW" "TJ" "TZ" "TH" "TL" "TG" "TK" "TO" "TT" "TN" "TR" "TM" "TC" "TV" "UG" "UA" "AE" "GB" "US" "UM" "UY" "UZ" "VU" "VE" "VN" "VG" "VI" "WF" "EH" "YE" "ZM" "ZW" null
	Array of objects (vatId) List of VAT IDs assigned to the customer
	Array of objects (taxId) List of Tax IDs assigned to the customer
blockedForPosting	boolean Indicator if the customer is blocked for posting
blockedForPayment	boolean Indicator if the customer is blocked for payment
blockedForOrdering	boolean Indicator if the customer is blocked for ordering globally
	Array of objects (subsidiary)
	Array of objects (bankAccount)
	object (customFields) List of key value pairs containing custom fields from the source system
	object (JsonObject) Any nested structure with metadata that source system needs to send
	Array of objects (salesOrganizationInfo)

Responses

200

Successfully inserted

422

Validation error

429

Rate limit exceeded

post/enrichment/customers

Request samples

Payload
curl
Node.js
Python
Java

application/json

{"externalId": "0000100000",
"externalClientId": "EXTERNAL_CLIENT_ID",
"code": "CODE1",
"name": "Acmne Corp.",
"nameAlternative1": "Acmne Corp.",
"nameAlternative2": "Acmne Corp.",
"nameAlternative3": "Acmne Corp.",
"nameAlternative4": "Acmne Corp.",
"street": "Hauptstr. 1",
"addressAdditional": "Eingang B",
"postcode": "10001",
"city": "Berlin",
"countryCode": "DE",
"vatIds": [{"id": "DE123456789",
"countryCode": "DE"
}
],
"taxIds": [{"id": "123-456-789",
"type": "TIN"
}
],
"blockedForPosting": false,
"blockedForPayment": false,
"blockedForOrdering": false,
"customerSubsidiaries": [{"defaultAccountAssignment": {"glAccountCode": "0000100GL1",
"costCenterCode": "0000100CC1",
"externalApproverId": "MMUSTERMANN",
"externalProjectId": "PROJ1234",
"externalOrderId": "ORDER1234"
},
"externalCompanyId": "DE01",
"paymentTerms": {"paymentTermKey": "T10",
"descriptions": [{"text": "Please pay us",
"language": "en"
}
]
},
"blockedForPosting": false,
"blockedForPayment": false,
"enabledForAutoPosting": true,
"withholdingTaxInfo": [{"key": "WHT-432",
"descriptions": [{"text": "Some very deep description of the type of withholding tax",
"language": "en"
}
]
}
]
}
],
"customerBankAccounts": [{"externalId": "12341234",
"countryCode": "DE",
"bankAccountNumber": "78090",
"bankAccountHolder": "Maximilian Mustermann",
"iban": "DE91100000000123456789",
"bic": "CHASUS33XXX",
"bankName": "Deutsche Bank",
"bankStreet": "Hauptstr. 1",
"bankPostcode": "10001",
"bankCity": "Berlin",
"isActive": true,
"type": "SAVINGS",
"bankKey": "60-16-13"
}
],
"customFields": {"property1": "string",
"property2": "string"
},
"customMetadata": {"someTopLevelProperty": "value1",
"someNestedProperty": {"nestedProperty": "value2"
},
"someArrayProperty": ["value3",
"value4"
]
},
"salesOrganizationInfo": [{"externalSalesOrganizationId": 1000,
"distributionChannel": 2000,
"division": 3000,
"salesGroup": 4000,
"salesOffice": 5000,
"blockedForOrdering": true,
"shippingAddresses": ["ADDR001",
"ADDR002"
],
"billingAddresses": ["ADDR003"
],
"salesOrganizationCode": "SO001"
}
]
}

Response samples

application/json

{"id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}

Mark customer as deleted

SecurityOAuth2

Request

path Parameters

externalId

required

string

Previously sent externalId

Responses

204

Successfully marked as deleted

404

Not Found error

429

Rate limit exceeded

delete/enrichment/customers/{externalId}

Request samples

curl
Node.js
Python
Java

Response samples

application/json

{"status": 404,
"title": "Not found"
}

Insert data row to lookup table

SecurityOAuth2

Request

path Parameters

type

required

string

type of data being sent

Request Body schema: application/json
required

externalId required	string External id of the lookup-table-row that is globally unique across the provided lookup-table-row data
externalClientId	string Identifier of the client entity in the source system which can be used to separate data
code	string Number of the lookup table record in the source system (not unique across clients)
property name* additional property	string <= 20 properties

Responses

200

Successfully inserted

422

Validation error

429

Rate limit exceeded

post/enrichment/lookup-tables/{type}

Request samples

Payload
curl
Node.js
Python
Java

application/json

{"externalId": "12345",
"externalClientId": "EXTERNAL_CLIENT_ID",
"dimension1": "someValue",
"dimension2": "anotherValue",
"customField": "dynamicValue"
}

Response samples

application/json

{"id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}

Mark data row in lookup table as deleted

SecurityOAuth2

Request

path Parameters

type required	string type of data from which we should delete the row
externalId required	string Previously sent `externalId`

Responses

204

Successfully marked as deleted

404

Not Found error

429

Rate limit exceeded

delete/enrichment/lookup-tables/{type}/{externalId}

Request samples

curl
Node.js
Python
Java

Response samples

application/json

{"status": 404,
"title": "Not found"
}

Insert contract

SecurityOAuth2

Request

Request Body schema: application/json
required

externalId required	string^\S+$ External id of the contract that is globally unique across the provided contract data
externalClientId	string Identifier of the client entity in the source system which can be used to separate data
documentId	string^[0-9a-fA-F]{24}$ Document id that was assigned during upload to Hypatos
	Array of objects (document) non-empty
contractNumber	string Contract number assigned in the source system
status	string or null (contractStatus) Indicates the current lifecycle state of the contract Enum: "draft" "active" "pending" "suspended" "cancelled" "expired" "terminated" null
businessPartnerContractNumber	string Contract number assigned by the business partner
externalCompanyId	string External unique identifier of the company in the source system
	Array of objects (salesOrganizationInfo)
	object (businessPartner) Details of the business partner associated with the contract
title	string Title or name of the contract
description	string Description of the contract and its purpose
createdDate	string <date> Date when the contract was created (YYYY-MM-DD)
startDate	string <date> Date when the contract becomes effective (YYYY-MM-DD)
endDate	string <date> Date when the contract expires (YYYY-MM-DD)
fiscalYearLabel	string Fiscal year label associated with the contract
type	string Type of contract
subType	string Subtype of contract
currency	string Currency in which the contract amounts are denominated
totalNetAmount	number Total net amount of the contract
totalTaxAmount	number Total tax amount applicable to the contract
totalGrossAmount	number Total gross amount of the contract (net amount + tax)
	object (paymentTerms)
	object (parentContract) Details of the business partner associated with the contract
targetQuantity	number Target quantity specified in the contract
targetValue	number Target value of the contract in the specified currency
	Array of objects (contractItem) List of items included in the contract
	Array of objects (additionalAgreement) List of additional agreements linked to the contract
	Array of objects (obligation) List of obligations specified in the contract
	Array of objects (contactItem) List of contact persons associated with the contract
	object (customFields) List of key value pairs containing custom fields from the source system
	object (JsonObject) Any nested structure with metadata that source system needs to send

Responses

200

Successfully inserted

422

Validation error

429

Rate limit exceeded

post/enrichment/contracts

Request samples

Payload
curl
Node.js
Python
Java

application/json

{"externalId": "CONTRACT-2025-0001",
"externalClientId": "CONTRACT-2025-0001",
"documentId": "67c02594d4aa80eecbd39bbe",
"documents": [{"id": "63cac12c37bb02accb396cae",
"type": "invoice"
}
],
"contractNumber": "CN-2025-001",
"status": "active",
"businessPartnerContractNumber": "K9120-12",
"externalCompanyId": "DE01",
"salesOrganizationInfo": [{"externalSalesOrganizationId": 1000,
"distributionChannel": 2000,
"division": 3000,
"salesGroup": 4000,
"salesOffice": 5000,
"blockedForOrdering": true,
"shippingAddresses": ["ADDR001",
"ADDR002"
],
"billingAddresses": ["ADDR003"
],
"salesOrganizationCode": "SO001"
}
],
"businessPartner": {"externalId": 32768,
"type": "supplier"
},
"title": "Software Maintenance Agreement",
"description": "Annual software maintenance contract for Acme Corp",
"createdDate": "2025-01-15",
"startDate": "2025-02-01",
"endDate": "2026-01-31",
"fiscalYearLabel": "2023",
"type": "Service Agreement",
"subType": "Quantity",
"currency": "EUR",
"totalNetAmount": 50000,
"totalTaxAmount": 9500,
"totalGrossAmount": 59500,
"paymentTerms": {"paymentTermKey": "T10",
"descriptions": [{"text": "Please pay us",
"language": "en"
}
]
},
"parentContract": {"externalId": "PARENT-2024-0005",
"contractNumber": "CN-2024-005"
},
"targetQuantity": 1000,
"targetValue": 200000,
"contractItems": [{"itemNumber": "001",
"category": "Service",
"description": "Annual software maintenance",
"netAmount": 25000,
"taxAmount": 4750,
"grossAmount": 29750,
"unitPrice": 25000,
"quantity": 1,
"unitOfMeasure": "EA",
"billingCycle": "Billing cycle for the contract item",
"durationMonths": 12,
"taxCode": {"code": "DEU_Standard",
"description": "DEU - Standard (19%)"
}
}
],
"additionalAgreements": [{"externalId": "AGREEMENT-001",
"type": "downPaymentAllowed",
"value": true
}
],
"obligations": [{"party": "Company A",
"description": "Company A will deliver 1000 units of Product X per quarter"
}
],
"contacts": [{"firstName": "Koala",
"lastName": "Hinze",
"email": "accountant@sap.com",
"phoneNumber": 491001234567891
}
],
"customFields": {"property1": "string",
"property2": "string"
},
"customMetadata": {"someTopLevelProperty": "value1",
"someNestedProperty": {"nestedProperty": "value2"
},
"someArrayProperty": ["value3",
"value4"
]
}
}

Response samples

application/json

{"id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}

Mark contract as deleted

SecurityOAuth2

Request

path Parameters

externalId

required

string

Previously sent externalId

Responses

204

Successfully marked as deleted

404

Not Found error

429

Rate limit exceeded

delete/enrichment/contracts/{externalId}

Request samples

curl
Node.js
Python
Java

Response samples

application/json

{"status": 404,
"title": "Not found"
}

Insert sales order

SecurityOAuth2

Request

Request Body schema: application/json
required

externalId required	string^\S+$ External id of the sales order that is globally unique across the provided sales order data
externalClientId	string Identifier of the client entity in the source system which can be used to separate data
documentId	string^[0-9a-fA-F]{24}$ Document id that was assigned during upload to Hypatos
	Array of objects (document)
customerOrderNumber	string Sales order number provided by the issuing customer
salesOrderNumber	string Number of the sales order in the source system (not unique across clients)
externalCompanyId	string External unique id of the company in the source system
externalCustomerId	string External unique id of the customer in the source system
salesOrganizationCode	string Sales organization code
distributionChannel	string Distribution channel code
division	string Division code
salesGroup	number Sales group responsible for the order
salesOffice	number Sales office responsible for the order
type	string Type of the invoice as defined in the source system
subType	string Sub type of the invoice as defined in the source system
issuedDate	string <date> Date when the invoice was issued by the supplier (printed on invoice document)
receivedDate	string <date> Date when the invoice was received by the company
fiscalYearLabel	string Label used in the source system for the fiscal year that the invoice was posted in
requestedDeliveryDate	string <date> Requested delivery date
isCanceled	boolean Indicator if the invoice is canceled
currency	string or null (CurrencyCode) Three letter currency code as defined in ISO 4217 Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYN" "BZD" "CAD" "CDF" "CHE" "CHF" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "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" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRU" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "QAR" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLE" "SLL" "SOS" "SRD" "SSP" "STN" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "UYI" "UYU" "UYW" "UZS" "VED" "VES" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL" null
totalNetAmount	number Total net amount of sales order (sum of line item net amounts)
totalTaxAmount	number Total tax amount of sales order (sum of all taxes)
totalGrossAmount	number Total gross amount of sales order (total net amount + total tax amount)
	object (paymentTerms)
headerText	string Header Text describing the invoice
	object (customFields) List of key value pairs containing custom fields from the source system
	object (JsonObject) Any nested structure with metadata that source system needs to send
	Array of objects (salesOrderLine)

Responses

200

Successfully inserted

422

Validation error

429

Rate limit exceeded

post/enrichment/sales-orders

Request samples

Payload
curl
Node.js
Python
Java

application/json

{"externalId": "DE01",
"externalClientId": "EXTERNAL_CLIENT_ID",
"documentId": "63cac12c37bb02accb396cae",
"documents": [{"id": "63cac12c37bb02accb396cae",
"type": "invoice"
}
],
"customerOrderNumber": "CUSTOMER_ORDER_NUMBER",
"salesOrderNumber": "SALES_ORDER_NUMBER",
"externalCompanyId": "DE01",
"externalCustomerId": "CO01",
"salesOrganizationCode": "SO001",
"distributionChannel": "CH1",
"division": "DIV01",
"salesGroup": 123456,
"salesOffice": 123456,
"type": "OR",
"subType": "recurring",
"issuedDate": "2000-12-31",
"receivedDate": "2000-12-31",
"fiscalYearLabel": "2023",
"requestedDeliveryDate": "2000-12-31",
"isCanceled": false,
"currency": "EUR",
"totalNetAmount": 100,
"totalTaxAmount": 19,
"totalGrossAmount": 119,
"paymentTerms": {"paymentTermKey": "T10",
"descriptions": [{"text": "Please pay us",
"language": "en"
}
]
},
"headerText": "doc header text",
"customFields": {"property1": "string",
"property2": "string"
},
"customMetadata": {"someTopLevelProperty": "value1",
"someNestedProperty": {"nestedProperty": "value2"
},
"someArrayProperty": ["value3",
"value4"
]
},
"salesOrderLines": [{"orderLineNumber": "00000001",
"externalCompanyId": "DE01",
"externalProductId": "PO01",
"orderQuantity": 2,
"unitOfMeasure": "kg",
"unitPrice": 100,
"netAmount": 200,
"totalTaxAmount": 38,
"grossAmount": 238,
"taxCode": {"code": "DEU_Standard",
"description": "DEU - Standard (19%)"
},
"description": "DEU - Standard (19%)",
"plant": "PLANT-001",
"storageLocation": "BOX-001",
"externalShippingAddressId": "DE-123E",
"externalBillingAddressId": "DE-123E",
"itemText": "Sold item ABC",
"type": "Item type",
"externalQuoteId": "EQ01",
"quoteLineNumber": "LN01",
"externalContractId": "ECID01",
"customFields": {"property1": "string",
"property2": "string"
},
"customMetadata": {"someTopLevelProperty": "value1",
"someNestedProperty": {"nestedProperty": "value2"
},
"someArrayProperty": ["value3",
"value4"
]
}
}
]
}

Response samples

application/json

{"id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}

Mark sales order as deleted

SecurityOAuth2

Request

path Parameters

externalId

required

string

Previously sent externalId

Responses

204

Successfully marked as deleted

404

Not Found error

429

Rate limit exceeded

delete/enrichment/sales-orders/{externalId}

Request samples

curl
Node.js
Python
Java

Response samples

application/json

{"status": 404,
"title": "Not found"
}

Insert product

SecurityOAuth2

Request

Request Body schema: application/json
required

externalId required	string^\S+$ External ID of the product that is globally unique across the provided product data
externalClientId	string Identifier of the client entity in the source system which can be used to separate data
productNumber	string Number of the product as defined by the supplier
type	string Type of the product as defined in the company’s product master (e.g., Operating Supplies)
group	string Group of the product as defined in the product master of the company
description	string Description of the product
shortDescription	string Shortened version of the product description
manufacturer	string Name of the product manufacturer
unspsc	string Universal Product Code (UPC-A)
ean	string European Article Number (EAN-13)
upc	string Universal Product Code (UPC-A)
baseUnitOfMeasure	string The base unit in which the product is managed in the system
customsTariffNumber	string Customs tariff number (HS/TARIC code) used for cross-border trade and customs
	object
plants	Array of strings
status	string Current status of the product Enum: "ACTIVE" "INACTIVE" "DISCONTINUED"
grossWeight	number Gross weight of the product including packaging
netWeight	number Net weight of the product excluding packaging
weightUnit	string Unit for weight values
volume	number Volume of the product
volumeUnit	string Unit for volume values
	Array of objects (salesOrganizationInfo)
	object (customFields) List of key value pairs containing custom fields from the source system
	object (JsonObject) Any nested structure with metadata that source system needs to send

Responses

200

Successfully inserted

422

Validation error

429

Rate limit exceeded

post/enrichment/products

Request samples

Payload
curl
Node.js
Python
Java

application/json

{"externalId": "DE01",
"externalClientId": "EXTERNAL_CLIENT_ID",
"productNumber": "NO123",
"type": "Operating Supplies",
"group": "Electronics",
"description": "A Laptop XP",
"shortDescription": "A great laptop",
"manufacturer": "Corporation ABC",
"unspsc": "43211508",
"ean": "4006381333931",
"upc": "036000291452",
"baseUnitOfMeasure": "kg",
"customsTariffNumber": "8471300000",
"salesUnit": {"unitOfMeasure": "PK",
"conversionFactorToBaseUnit": 1000,
"description": "Package of 10 units"
},
"plants": ["PLANT-001"
],
"status": "ACTIVE",
"grossWeight": 2.5,
"netWeight": 2.3,
"weightUnit": "KG",
"volume": 0.015,
"volumeUnit": "M3",
"salesOrganizationInfo": [{"externalSalesOrganizationId": 1000,
"distributionChannel": 2000,
"division": 3000,
"salesGroup": 4000,
"salesOffice": 5000,
"blockedForOrdering": true,
"shippingAddresses": ["ADDR001",
"ADDR002"
],
"billingAddresses": ["ADDR003"
],
"salesOrganizationCode": "SO001"
}
],
"customFields": {"property1": "string",
"property2": "string"
},
"customMetadata": {"someTopLevelProperty": "value1",
"someNestedProperty": {"nestedProperty": "value2"
},
"someArrayProperty": ["value3",
"value4"
]
}
}

Response samples

application/json

{"id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}

Mark product as deleted

SecurityOAuth2

Request

path Parameters

externalId

required

string

Previously sent externalId

Responses

204

Successfully marked as deleted

404

Not Found error

429

Rate limit exceeded

delete/enrichment/products/{externalId}

Request samples

curl
Node.js
Python
Java

Response samples

application/json

{"status": 404,
"title": "Not found"
}

Insert address

SecurityOAuth2

Request

Request Body schema: application/json
required

externalId required	string^\S+$ External id of the address that is globally unique across the provided address data
businessPartnerNumber	string Number of the business partner related to this address (e.g. customer number)
parentBusinessPartnerNumber	string Number of the parent business partner of this address (e.g. customer number)
type	string Type of the address Enum: "shippingAddress" "billingAddress"
addressOrder	number Order of the address (in case there’s several addresses of the same type)
externalClientId	string Identifier of the client entity in the source system which can be used to separate data
globalLocationNumber	string 13-digit Global Location Number (GLN) used for unique location identification in B2B transactions
companyName	string^[\S ]\S[\S ]$ Name of the company associated with the address
nameAlternative1	string Alternative name of the company (e.g. trade name or local language)
nameAlternative2	string Alternative name of the company
nameAlternative3	string Alternative name of the company
nameAlternative4	string Alternative name of the company
street	string Street and street number where the address is located
addressAdditional	string Additional address data (e.g. building, entrance, apartment, or suite)
postcode	string Postcode where the address is located
city	string City where the address is located
postOfficeBox	string Post office box number, if used instead of street address
countryCode	string or null Two letter country code as defined in ISO 3166-1 alpha-2
region	string Region, state, or province of the address (e.g. "CA" for California or "BE" for Berlin)
transportationZone	string Code identifying the transportation or logistics zone relevant for shipping or route planning
phoneNumber	string Phone number of the location or contact point
faxNumber	string Fax number of the location or contact point
email	string Email address associated with the location or contact point
validFrom	string <date> Start date from which the address is considered valid (format: YYYY-MM-DD)
validTo	string <date> End date until which the address is considered valid (format: YYYY-MM-DD)
isDefault	boolean Indicator whether this address is the default for the given type (e.g., default ship-to address)
latitude	number Geographical latitude coordinate of the address (in decimal degrees)
longitude	number Geographical longitude coordinate of the address (in decimal degrees)
	object (customFields) List of key value pairs containing custom fields from the source system
	object (JsonObject) Any nested structure with metadata that source system needs to send

Responses

200

Successfully inserted

422

Validation error

429

Rate limit exceeded

post/enrichment/addresses

Request samples

Payload
curl
Node.js
Python
Java

application/json

{"externalId": "ADDR12345",
"businessPartnerNumber": "BP12345",
"parentBusinessPartnerNumber": "PBP12345",
"type": "shippingAddress",
"addressOrder": 1,
"externalClientId": "CLIENT123",
"globalLocationNumber": "1234567890123",
"companyName": "Acme Corporation",
"nameAlternative1": "Acme Corp.",
"nameAlternative2": "Acme Inc.",
"nameAlternative3": "Acme Ltd.",
"nameAlternative4": "Acme GmbH",
"street": "123 Main St",
"addressAdditional": "Building A, Suite 101",
"postcode": "12345",
"city": "Berlin",
"postOfficeBox": "PO Box 123",
"countryCode": "DE",
"region": "BE",
"transportationZone": "TZ123",
"phoneNumber": "+491234567890",
"faxNumber": "+491234567891",
"email": "contact@acme.com",
"validFrom": "2023-01-01",
"validTo": "2023-12-31",
"isDefault": true,
"latitude": 52.520008,
"longitude": 13.404954,
"customFields": {"property1": "string",
"property2": "string"
},
"customMetadata": {"someTopLevelProperty": "value1",
"someNestedProperty": {"nestedProperty": "value2"
},
"someArrayProperty": ["value3",
"value4"
]
}
}

Response samples

application/json

{"id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}

Mark address as deleted

SecurityOAuth2

Request

path Parameters

externalId

required

string

Previously sent externalId

Responses

204

Successfully marked as deleted

404

Not Found error

429

Rate limit exceeded

delete/enrichment/addresses/{externalId}

Request samples

curl
Node.js
Python
Java

Response samples

application/json

{"status": 404,
"title": "Not found"
}

Insert quotes

SecurityOAuth2

Request

Request Body schema: application/json
required

externalId required	string^\S+$ External id of the sales order that is globally unique across the provided sales order data
externalClientId	string Identifier of the client entity in the source system which can be used to separate data
documentId	string Document id that was assigned during upload to Hypatos
	Array of objects
quoteNumber	string Quote number from the source system
customerOrderNumber	string Customer order number the quote refers to
externalCompanyId	string External unique id of the company in the source system
externalCustomerId	string External unique id of the customer in the source system
status	string Status of the quote
salesOrganizationCode	string Sales organization code
distributionChannel	string Distribution channel code
division	string Division code
salesGroup	number Sales group responsible for the quote
salesOffice	number Sales office responsible for the quote
type	string Type of the quote as defined in the source system
subType	string Sub-type of the quote as defined in the source system
issuedDate	string <date> Date when the quote was issued
validUntilDate	string <date> Date until the quote is valid
fiscalYearLabel	string Fiscal year label used in the source system
isCanceled	boolean Indicator if the quote is canceled
currency	string Three letter currency code as defined in ISO 4217
totalNetAmount	number Total net amount of the quote
totalTaxAmount	number Total tax amount of the quote
totalGrossAmount	number Total gross amount of the quote
	object (paymentTerms)
headerText	string Header text describing the quote
	object (customFields) List of key value pairs containing custom fields from the source system
	object (JsonObject) Any nested structure with metadata that source system needs to send
	Array of objects

Responses

200

Successfully inserted

422

Validation error

429

Rate limit exceeded

post/enrichment/quotes

Request samples

Payload
curl
Node.js
Python
Java

application/json

{"externalId": "QUOTE12345",
"externalClientId": "CLIENT123",
"documentId": "DOC12345",
"documents": [{"id": "DOC12345",
"type": "invoice"
}
],
"quoteNumber": "Q12345",
"customerOrderNumber": "CO12345",
"externalCompanyId": "COMP123",
"externalCustomerId": "CUST123",
"status": "approved",
"salesOrganizationCode": "SO123",
"distributionChannel": "DC123",
"division": "DIV123",
"salesGroup": 123,
"salesOffice": 456,
"type": "standard",
"subType": "recurring",
"issuedDate": "2023-01-01",
"validUntilDate": "2023-12-31",
"fiscalYearLabel": "FY2023",
"isCanceled": false,
"currency": "USD",
"totalNetAmount": 1000,
"totalTaxAmount": 190,
"totalGrossAmount": 1190,
"paymentTerms": {"paymentTermKey": "T10",
"descriptions": [{"text": "Please pay us",
"language": "en"
}
]
},
"headerText": "This is a sample quote.",
"customFields": {"property1": "string",
"property2": "string"
},
"customMetadata": {"someTopLevelProperty": "value1",
"someNestedProperty": {"nestedProperty": "value2"
},
"someArrayProperty": ["value3",
"value4"
]
},
"quoteLines": [{"quoteLineNumber": "QL12345",
"externalCompanyId": "COMP123",
"product": {"externalId": "PROD123",
"productNumber": "PN123",
"customerProductNumber": "CPN123",
"type": "standard",
"group": "electronics",
"description": "A high-quality electronic product.",
"manufacturer": "Acme Corp.",
"manufacturerNumber": "MN123",
"unspsc": "43211508",
"ean": "4006381333931",
"upc": "036000291452"
},
"status": "approved",
"quantity": 10,
"targetQuantity": 15,
"unitOfMeasure": "kg",
"unitPrice": 100,
"netAmount": 1000,
"totalTaxAmount": 190,
"grossAmount": 1190,
"taxCode": {"code": "DEU_Standard",
"description": "DEU - Standard (19%)"
},
"description": "This is a sample quote line.",
"plants": [["PLANT123"
]
],
"storageLocation": "LOC123",
"externalShippingAddressId": "ADDR123",
"externalBillingAddressId": "ADDR456",
"itemText": "Sample item text.",
"type": "standard",
"externalContractId": "CONTRACT123",
"customFields": {"property1": "string",
"property2": "string"
},
"customMetadata": {"someTopLevelProperty": "value1",
"someNestedProperty": {"nestedProperty": "value2"
},
"someArrayProperty": ["value3",
"value4"
]
}
}
]
}

Response samples

application/json

{"id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}

Mark quote as deleted

SecurityOAuth2

Request

path Parameters

externalId

required

string

Previously sent externalId

Responses

204

Successfully marked as deleted

404

Not Found error

429

Rate limit exceeded

delete/enrichment/quotes/{externalId}

Request samples

curl
Node.js
Python
Java

Response samples

application/json

{"status": 404,
"title": "Not found"
}

➔ Next to Companies

Enrichment

Insert invoice including invoice lines

Request Body schema: application/jsonrequired

Mark invoice as deleted

path Parameters

query Parameters

Insert company

Request Body schema: application/jsonrequired

Mark company as deleted

path Parameters

Insert supplier including related subsidiaries

Request Body schema: application/jsonrequired

Mark supplier as deleted

path Parameters

Insert purchase order including purchase order lines

Request Body schema: application/jsonrequired

Mark purchase Order as deleted

path Parameters

query Parameters

Insert general ledger account

Request Body schema: application/jsonrequired

Mark general ledger account as deleted

path Parameters

Insert cost center

Request Body schema: application/jsonrequired

Mark cost Center as deleted

path Parameters

Insert approver

Request Body schema: application/jsonrequired

Mark approver as deleted

path Parameters

Insert customer

Request Body schema: application/jsonrequired

Mark customer as deleted

path Parameters

Insert data row to lookup table

path Parameters

Request Body schema: application/jsonrequired

Mark data row in lookup table as deleted

path Parameters

Insert contract

Request Body schema: application/jsonrequired

Mark contract as deleted

path Parameters

Insert sales order

Request Body schema: application/jsonrequired

Mark sales order as deleted

path Parameters

Insert product

Request Body schema: application/jsonrequired

Mark product as deleted

path Parameters

Insert address

Request Body schema: application/jsonrequired

Mark address as deleted

path Parameters

Insert quotes

Request Body schema: application/jsonrequired

Mark quote as deleted

path Parameters

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required