Skip to content

Insert contract

Request

Security
OAuth2(Required scopes: enrichment.write)
Bodyapplication/jsonrequired
externalIdstring^\S+$required

External id of the contract that is globally unique across the provided contract data

Example:"CONTRACT-2025-0001"
externalClientIdstring

Identifier of the client entity in the source system which can be used to separate data

Example:"CONTRACT-2025-0001"
documentIdstring^[0-9a-fA-F]{24}$

Document id that was assigned during upload to Hypatos

Example:"67c02594d4aa80eecbd39bbe"
documentsArray of objects, non-empty(document)
contractNumberstring

Contract number assigned in the source system

Example:"CN-2025-001"
statusstring or null(contractStatus)

Indicates the current lifecycle state of the contract

Enum:"draft""active""pending""suspended""cancelled""expired""terminated"null
Example:"active"
businessPartnerContractNumberstring

Contract number assigned by the business partner

Example:"K9120-12"
externalCompanyIdstring

External unique identifier of the company in the source system

Example:"DE01"
salesOrganizationInfoArray of objects(salesOrganizationInfo)
businessPartnerobject(businessPartner)

Details of the business partner associated with the contract

titlestring

Title or name of the contract

Example:"Software Maintenance Agreement"
descriptionstring

Description of the contract and its purpose

Example:"Annual software maintenance contract for Acme Corp"
createdDatestring, (date)

Date when the contract was created (YYYY-MM-DD)

Example:"2025-01-15"
startDatestring, (date)

Date when the contract becomes effective (YYYY-MM-DD)

Example:"2025-02-01"
endDatestring, (date)

Date when the contract expires (YYYY-MM-DD)

Example:"2026-01-31"
fiscalYearLabelstring

Fiscal year label associated with the contract

Example:"2023"
typestring

Type of contract

Example:"Service Agreement"
subTypestring

Subtype of contract

Example:"Quantity"
currencystring

Currency in which the contract amounts are denominated

Example:"EUR"
totalNetAmountnumber

Total net amount of the contract

Example:50000
totalTaxAmountnumber

Total tax amount applicable to the contract

Example:9500
totalGrossAmountnumber

Total gross amount of the contract (net amount + tax)

Example:59500
paymentTermsobject(paymentTerms)
parentContractobject(parentContract)

Details of the business partner associated with the contract

targetQuantitynumber

Target quantity specified in the contract

Example:1000
targetValuenumber

Target value of the contract in the specified currency

Example:200000
contractItemsArray of objects(contractItem)

List of items included in the contract

additionalAgreementsArray of objects(additionalAgreement)

List of additional agreements linked to the contract

obligationsArray of objects(obligation)

List of obligations specified in the contract

contactsArray of objects(contactItem)

List of contact persons associated with the contract

customFieldsobject(customFields)

List of key value pairs containing custom fields from the source system

customMetadataobject(JsonObject)

Any nested structure with metadata that source system needs to send

Example:
{
  "someTopLevelProperty": "value1",
  "someNestedProperty": {
    "nestedProperty": "value2"
  },
  "someArrayProperty": [
    "value3",
    "value4"
  ]
}
curl -i -X POST \
  https://api.cloud.hypatos.ai/v2/enrichment/contracts \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "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,
        "blockedForDelivery": false,
        "shippingAddresses": [
          "ADDR001",
          "ADDR002"
        ],
        "billingAddresses": [
          "ADDR003"
        ],
        "salesOrganizationCode": "SO001",
        "salesUnit": {
          "unitOfMeasure": "PK",
          "conversionFactorToBaseUnit": 1000,
          "description": "Package of 10 units"
        }
      }
    ],
    "businessPartner": {
      "externalId": "0000100000",
      "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"
      ]
    }
  }'

Responses

Successfully inserted

Bodyapplication/json
idstringrequired
Example:"3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
Response
{
  "id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}