Skip to content

Insert Goods Receipt

Request

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

External id of the goods receipt that is globally unique across the provided goods receipt data

Example:"GOODS_RECEIPT-0001"
externalClientIdstring

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

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

Document id that was assigned during upload to Hypatos

Example:"63cac12c37bb02accb396cbf"
documentsArray of objects(document)
goodsReceiptNumberstring

Goods receipt number provided in the source system

Example:"GR123456789"
externalCompanyIdstring

External unique id of the company in the source system

Example:"DE01"
externalSupplierIdstring

External unique id of the supplier in the source system

Example:"0000100000"
fiscalYearLabelstring

Label used in the source system for the fiscal year that the goods receipt was posted in

Example:"2023"
issuedDatestring, (date)

Date when the good receipt document was issued

Example:"2024-12-31"
createdDatestring, (date)

Date when the goods receipt was created in the source system

Example:"2025-06-30"
postingDatestring, (date)

Date when the goods receipt was posted

Example:"2025-06-30"
headerTextstring

Header text describing the goods receipt

Example:"doc header text"
statusstring

Status of the goods receipt as defined in the source system

Example:"POSTED"
deliveryNoteNumberstring

Delivery note number associated with the goods receipt

Example:"DN789456123"
isReversalboolean

Indicator if the goods receipt is a reversal

Example:false
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"
  ]
}
goodsReceiptLinesArray of objects, non-empty(goodsReceiptLine)required
curl -i -X POST \
  https://api.cloud.hypatos.ai/v2/enrichment/goods-receipts \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalId": "GOODS_RECEIPT-0001",
    "externalClientId": "EXTERNAL_CLIENT_ID",
    "documentId": "63cac12c37bb02accb396cbf",
    "documents": [
      {
        "id": "63cac12c37bb02accb396cae",
        "type": "invoice"
      }
    ],
    "goodsReceiptNumber": "GR123456789",
    "externalCompanyId": "DE01",
    "externalSupplierId": "0000100000",
    "fiscalYearLabel": "2023",
    "issuedDate": "2024-12-31",
    "createdDate": "2025-06-30",
    "postingDate": "2025-06-30",
    "headerText": "doc header text",
    "status": "POSTED",
    "deliveryNoteNumber": "DN789456123",
    "isReversal": false,
    "customFields": {
      "property1": "string",
      "property2": "string"
    },
    "customMetadata": {
      "someTopLevelProperty": "value1",
      "someNestedProperty": {
        "nestedProperty": "value2"
      },
      "someArrayProperty": [
        "value3",
        "value4"
      ]
    },
    "goodsReceiptLines": [
      {
        "goodsReceiptLineNumber": "GRLINE-0001",
        "externalCompanyId": "DE01",
        "externalPurchaseOrderId": "4500016221",
        "purchaseOrderLineNumber": "00010",
        "type": "Service",
        "quantity": 2,
        "unitOfMeasure": "kg",
        "itemText": "Dell Laptop Latitude D630",
        "status": "invoiced",
        "material": {
          "externalId": "2a6300181f08402e710ea3f180214bc1",
          "supplierNumber": "123456789",
          "type": "Operating Supplies",
          "group": "Electronics",
          "description": "Dell Laptop Latitude D630",
          "manufacturer": "Acme Corporation",
          "manufacturerNumber": "ACME-12345",
          "unspsc": "43211508",
          "ean": "4006381333931",
          "baseUnitOfMeasure": "PCE"
        },
        "plant": "PLANT-001",
        "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"
}