Data Model

Successful integrations depend on understanding how contract records, structured data, metadata, documents, and external identifiers move between your systems and SpotDraft.

Use this page to decide what data to send on creation, what to update later, what to sync downstream, and what should remain workspace configuration.

Core entities

• Contract: the main record created, uploaded, imported, retrieved, updated, and tracked through status and lifecycle operations.
• Contract type: workspace configuration that determines the category, intake behavior, access rules, and workflow expectations for a contract.
• Template: a SpotDraft-managed document template used to generate template contracts from structured data.
• Counterparty: the external organization or individual on the other side of the agreement.
• Creator entity: the internal legal entity or business unit that is party to the contract.
• Signatory: the person who signs, which is distinct from the party or legal entity.
• Recipient: a person or participant who receives or interacts with the contract.
• Document: a generated, uploaded, versioned, or executed file associated with the contract.
• Workspace file: a file object that can be uploaded, attached, and later downloaded through signed URLs where supported.

Structured data surfaces

SpotDraft contracts combine document content with machine-readable fields. Use the structured surfaces instead of parsing rendered document text.

Surface	What it is for	Typical integration use
contract_data	Structured values used during template-driven creation or update.	Populate a template from CRM, CPQ, ERP, HRIS, or procurement data.
external_metadata	Integration-owned identifiers and machine-readable correlation fields.	Store CRM opportunity ids, ERP vendor ids, PO numbers, or internal request ids.
Questionnaire responses	Structured answers collected by configured questionnaires.	Read or send values that drive template generation or workflow logic.
Intake-form responses	Structured answers associated with uploaded or intake-driven contracts.	Update values learned after contract creation or route third-party paper correctly.
Key pointers	Extracted or curated structured values exposed on a contract.	Fetch business terms, dates, or parties for downstream sync when exposed by the API.
Notes and related state	Human-readable or workflow-adjacent contract state.	Sync comments, operational context, or workflow signals when an endpoint exposes them.

What is first-class in the API

You should treat these as safe integration primitives:

• contract ids
• contract status
• contract type ids
• contract template ids
• signatory payloads
• external metadata
• contract data, notes, recipients, and key pointers where exposed

Persist the identifiers SpotDraft returns. Do not infer stable identity from contract titles, visible labels, or document text.

Metadata and external metadata

external_metadata is the best place to store durable identifiers from systems outside SpotDraft. It should be predictable, documented, and small enough to use for lookup, reconciliation, and support debugging.

Good examples:

• CRM opportunity id
• CPQ quote id
• ERP vendor id
• purchase order number
• procurement request id
• HRIS employee id
• internal contract request id

Use one consistent key strategy across create, update, webhook processing, and downstream sync. For example, if a CRM opportunity owns the contract process, write that opportunity id when the contract is created and reuse it when processing webhooks or reconciling status back to the CRM.

Avoid using external_metadata for rendered clause text, large document snippets, or fields that should be modeled as contract data, questionnaire responses, or key pointers.

Data flow through an integration

Most production integrations follow this flow:

1. A source system owns the business trigger and sends contract data, counterparties, signatories, and external ids to SpotDraft.
2. SpotDraft creates or imports the contract and stores the structured values that the workflow needs.
3. SpotDraft manages review, approvals, redlining, signature, execution, and repository storage.
4. SpotDraft sends webhook events when lifecycle activity occurs.
5. Your integration verifies the webhook, deduplicates it, and fetches fresh SpotDraft state only when downstream systems need detail.
6. Downstream systems receive status, executed documents, metadata, or analytics-ready identifiers.

Documents and storage

The document model depends on how the contract entered SpotDraft:

• Template contracts are generated from a SpotDraft template and structured request data.
• Third-party paper starts as an uploaded file and moves through review or signature.
• Executed contracts can be imported into the repository with final signed files.
• Versions and download endpoints expose generated or uploaded artifacts where the API supports them.

For downstream storage, wait until the relevant lifecycle event indicates that a document is ready, then fetch the file or signed download link from the API. Do not assume a document is final immediately after contract creation.

What is configuration, not transactional state

• contract-type setup
• template setup
• questionnaire design
• access-control rules
• webhook registration details

Your integration should persist the identifiers it actually receives from the public APIs and avoid inventing its own meaning for workspace configuration. Do not hard-code assumptions about contract routing until you have validated the target contract type, template, and questionnaire setup in the target environment.

Recommended design checklist

Before implementation, define:

• the source-system id that will be stored in external_metadata
• the exact contract type and template ids per environment
• the mapping from upstream fields to contract_data or intake-form fields
• the webhook events that trigger downstream sync
• the dedupe key for webhook processing
• when to fetch contract status, documents, versions, metadata, and key pointers
• which downstream systems receive status, documents, or metadata