Entity types

​

What is a canonical object?

• A typed, prefixed ID generated deterministically from the source system and entity. Prefix indicates the entity type: pay_ for payments, proj_ for projects, cust_ for customers, cor_ for contracts, inv_ for invoices.
• An object discriminator ("payment", "project", "invoice", etc.) for type safety.
• An external_ids map preserving each platform’s native identifiers - Procore’s numeric IDs, Dynamics’ GUIDs, and any secondary identifiers needed for lossless round-trip conversion.
• An optional provider_metadata map storing platform-specific fields that have no canonical equivalent, so nothing is lost in translation.

​

Support matrix

​

Example: Payment #1 - Lusail Boulevard Tower

{
  "id": 1823456,
  "amount": "1700000.00",
  "status": "pending",
  "check_number": "CHK-2026-0101",
  "contract_id": 1945782,
  "project_id": 341276,
  "requisition_id": 10061,
  "invoice_number": "INV-2025-0061",
  "date": "2026-02-01",
  "payment_number": 24,
  "notes": "Substructure progress payment #1"
}

{
  "id": "a34e74db-53c7-4368-8fe7-bb87c83c7902",
  "amount": 6188000,
  "postingDate": "2026-02-05",
  "documentNumber": "CR-6101",
  "externalDocumentNumber": "CHK-2026-0101",
  "appliesToInvoiceNumber": "INV-2025-0061",
  "description": "Substructure progress payment #1",
  "dimensions": [
    { "code": "PROJECT", "valueCode": "J-LEX-147" }
  ]
}

{
  "id": "pay_xK9mN2vL8gM3y6P",
  "object": "payment",
  "amount": {
    "amount": 170000000,
    "currency": "USD"
  },
  "status": "pending",
  "payment_date": "2026-02-01",
  "check_number": "CHK-2026-0101",
  "invoice_number": "INV-2025-0061",
  "payment_number": 24,
  "notes": "Substructure progress payment #1",
  "external_ids": {
    "procore": {
      "id": 1823456,
      "contract_id": 1945782,
      "project_id": 341276,
      "requisition_id": 10061
    },
    "dynamics": {
      "id": "a34e74db-53c7-4368-8fe7-bb87c83c7902"
    }
  }
}

• Money in minor units. Procore sends "1700000.00" (a string in dollars). The canonical stores 170000000 (an integer in cents). This eliminates floating-point rounding across systems.
• ISO 4217 currency codes. The canonical amount object carries the currency code explicitly. Dynamics’ payment (6188000) is in QAR (Qatari Riyal) - a different currency for the same payment. Structural normalizes to the canonical amount in the source currency.
• external_ids for lossless round-trip. Procore’s numeric IDs and Dynamics’ GUIDs are both preserved. The reverse mapper reads these to reconstruct the original platform payload exactly.
• Cross-entity references. The canonical payment references its project and invoice via typed ObjectReference fields (omitted from this example for brevity) that link to other canonical objects by their prefixed IDs.