# Insert contract

Endpoint: POST /enrichment/contracts
Version: 2.51.0
Security: OAuth2

## Request fields (application/json):

  - `externalId` (string, required)
    External id of the contract that is globally unique across the provided contract data
    Example: "CONTRACT-2025-0001"

  - `externalClientId` (string)
    Identifier of the client entity in the source system which can be used to separate data
    Example: "CONTRACT-2025-0001"

  - `documentId` (string)
    Document id that was assigned during upload to Hypatos
    Example: "67c02594d4aa80eecbd39bbe"

  - `documents` (array)

  - `documents.id` (string)
    Document id that was assigned during upload to Hypatos
    Example: "63cac12c37bb02accb396cae"

  - `documents.type` (string)
    Document type that was assigned during upload to Hypatos
    Example: "invoice"

  - `contractNumber` (string)
    Contract number assigned in the source system
    Example: "CN-2025-001"

  - `status` (string,null)
    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
    Example: "K9120-12"

  - `externalCompanyId` (string)
    External unique identifier of the company in the source system
    Example: "DE01"

  - `salesOrganizationInfo` (array)

  - `salesOrganizationInfo.externalSalesOrganizationId` (string)
    External identifier for the sales organization
    Example: "1000"

  - `salesOrganizationInfo.distributionChannel` (string)
    Distribution channel for sales
    Example: "2000"

  - `salesOrganizationInfo.division` (string)
    Division under which the sales organization operates
    Example: "3000"

  - `salesOrganizationInfo.salesGroup` (string)
    Sales group associated with the contract
    Example: "4000"

  - `salesOrganizationInfo.salesOffice` (string)
    Sales office responsible for the contract
    Example: "5000"

  - `salesOrganizationInfo.blockedForOrdering` (boolean)
    Indicator if the customer is blocked for ordering in a sales organization
    Example: true

  - `salesOrganizationInfo.blockedForDelivery` (boolean)
    Indicator if the subsidiary is blocked for delivery

  - `salesOrganizationInfo.shippingAddresses` (array)
    List of external id of the related shipping addresses
    Example: ["ADDR001","ADDR002"]

  - `salesOrganizationInfo.billingAddresses` (array)
    List of external id of the related billing addresses
    Example: ["ADDR003"]

  - `salesOrganizationInfo.salesOrganizationCode` (string)
    Code of the sales organization in the source system (not unique across clients)
    Example: "SO001"

  - `salesOrganizationInfo.salesUnit` (object)

  - `salesOrganizationInfo.salesUnit.unitOfMeasure` (string)
    Unit in which the product is sold, different from base unit
    Example: "PK"

  - `salesOrganizationInfo.salesUnit.conversionFactorToBaseUnit` (number)
    Number of base units per sales unit (e.g., 10 means 1 PK = 10 PC)
    Example: 1000

  - `salesOrganizationInfo.salesUnit.description` (string)
    Description of the sales unit packaging
    Example: "Package of 10 units"

  - `businessPartner` (object)
    Details of the business partner associated with the contract

  - `businessPartner.externalId` (string)
    External id of the business partner that is globally unique across the provided business partner data
    Example: "0000100000"

  - `businessPartner.type` (string,null)
    Type of business partner (e.g., Supplier, Customer)
    Enum: "supplier", "customer", null

  - `title` (string)
    Title or name of the contract
    Example: "Software Maintenance Agreement"

  - `description` (string)
    Description of the contract and its purpose
    Example: "Annual software maintenance contract for Acme Corp"

  - `createdDate` (string)
    Date when the contract was created (YYYY-MM-DD)
    Example: "2025-01-15"

  - `startDate` (string)
    Date when the contract becomes effective (YYYY-MM-DD)
    Example: "2025-02-01"

  - `endDate` (string)
    Date when the contract expires (YYYY-MM-DD)
    Example: "2026-01-31"

  - `fiscalYearLabel` (string)
    Fiscal year label associated with the contract
    Example: "2023"

  - `type` (string)
    Type of contract
    Example: "Service Agreement"

  - `subType` (string)
    Subtype of contract
    Example: "Quantity"

  - `currency` (string)
    Currency in which the contract amounts are denominated
    Example: "EUR"

  - `totalNetAmount` (number)
    Total net amount of the contract
    Example: 50000

  - `totalTaxAmount` (number)
    Total tax amount applicable to the contract
    Example: 9500

  - `totalGrossAmount` (number)
    Total gross amount of the contract (net amount + tax)
    Example: 59500

  - `paymentTerms` (object)

  - `paymentTerms.paymentTermKey` (string)
    Key of the payment term as defined in the source system
    Example: "T10"

  - `paymentTerms.descriptions` (array)
    Descriptions of the payment terms in different languages
    Example: [{"text":"Please pay us","language":"en"}]

  - `paymentTerms.descriptions.text` (string)
    Text content
    Example: "Fish & Chips"

  - `paymentTerms.descriptions.language` (string,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

  - `parentContract` (object)
    Details of the business partner associated with the contract

  - `parentContract.externalId` (string)
    External id of the parent contract that is globally unique across the provided parent contract data
    Example: "PARENT-2024-0005"

  - `parentContract.contractNumber` (string)
    Contract number of the parent contract
    Example: "CN-2024-005"

  - `targetQuantity` (number)
    Target quantity specified in the contract
    Example: 1000

  - `targetValue` (number)
    Target value of the contract in the specified currency
    Example: 200000

  - `contractItems` (array)
    List of items included in the contract

  - `contractItems.itemNumber` (string)
    Unique identifier for the contract item
    Example: "001"

  - `contractItems.category` (string)
    Category of the contract item (e.g., Service, Product)
    Example: "Service"

  - `contractItems.description` (string)
    Description of the contract item
    Example: "Annual software maintenance"

  - `contractItems.netAmount` (number)
    Net amount of the contract item
    Example: 25000

  - `contractItems.taxAmount` (number)
    Tax amount applicable to the contract item
    Example: 4750

  - `contractItems.grossAmount` (number)
    Gross amount of the contract item (net + tax)
    Example: 29750

  - `contractItems.unitPrice` (number)
    Price per unit of the contract item
    Example: 25000

  - `contractItems.quantity` (number)
    Quantity of the contract item
    Example: 1

  - `contractItems.unitOfMeasure` (string)
    Unit of measure for the contract item
    Example: "EA"

  - `contractItems.billingCycle` (string)
    Purchase order related to the invoice line item
    Example: "Billing cycle for the contract item"

  - `contractItems.durationMonths` (number)
    Duration of the contract item in months
    Example: 12

  - `contractItems.taxCode` (object)

  - `contractItems.taxCode.code` (string)
    Unique code of the type of tax in the source system
    Example: "DEU_Standard"

  - `contractItems.taxCode.description` (string)
    Description of the type of tax in the source system
    Example: "DEU - Standard (19%)"

  - `additionalAgreements` (array)
    List of additional agreements linked to the contract

  - `additionalAgreements.externalId` (string)
    External id of the agreement that is globally unique across the provided agreement data
    Example: "AGREEMENT-001"

  - `additionalAgreements.type` (string)
    Type of agreement
    Example: "downPaymentAllowed"

  - `additionalAgreements.value` (boolean)
    Value of the agreement condition
    Example: true

  - `obligations` (array)
    List of obligations specified in the contract

  - `obligations.party` (string)
    Party responsible for the obligation
    Example: "Company A"

  - `obligations.description` (string)
    Description of the obligation
    Example: "Company A will deliver 1000 units of Product X per quarter"

  - `contacts` (array)
    List of contact persons associated with the contract

  - `contacts.firstName` (string)
    First name of the contact person
    Example: "Koala"

  - `contacts.lastName` (string)
    Last name of the contact person
    Example: "Hinze"

  - `contacts.email` (string)
    Email address of the contact person
    Example: "accountant@sap.com"

  - `contacts.phoneNumber` (number)
    Phone number of the contact person
    Example: 491001234567891

  - `customFields` (object)
    List of key value pairs containing custom fields from the source system

  - `customMetadata` (object)
    Any nested structure with metadata that source system needs to send
    Example: {"someTopLevelProperty":"value1","someNestedProperty":{"nestedProperty":"value2"},"someArrayProperty":["value3","value4"]}

## Response 200 fields (application/json):

  - `id` (string, required)
    Example: "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"

## Response 422 fields (application/json):

  - `detail` (array)

  - `detail.loc` (array, required)

  - `detail.msg` (string, required)

  - `detail.type` (string, required)


## Response 429 fields