Procore Version-Aware Submittal Workflow
Overview
Submittal endpoints coexist across versions and may expose beta surfaces. Select the documented version per operation, preserve company routing and notification controls, and reconcile workflow state instead of assuming a generic approve-or-reject contract.
Prerequisites
- Target company and project with Submittals enabled
- Current endpoint version and changelog reviewed for every intended operation
- Required managers, approvers, specification context, and notification policy resolved
Instructions
Step 1: Select the endpoint version
Open the current Submittals API reference and choose the supported route for the required operation. Record whether a surface is beta and obtain explicit risk acceptance before using it.
Step 2: Discover project data
List a bounded page of submittals and retrieve workflow data for a representative record. Capture required headers, fields, allowed filters, and pagination metadata.
Step 3: Validate the proposal
Resolve project users and specification references, obtain any next-number value through the documented endpoint, and make email behavior explicit. Never invent a workflow status.
Step 4: Approve the mutation
Render a sanitized request preview with target project, selected API version, recipients, and expected outcome. Require approval before creating or changing a submittal.
Step 5: Execute and reconcile
Send the mutation once, then fetch the submittal and its workflow data. Confirm the observed workflow state rather than trusting a local projection.
Step 6: Record compatibility
Keep endpoint-version selection in an adapter and test both current response fields and failure shapes so future migrations remain bounded.
Authentication
Submittal calls authenticate with an OAuth 2.0 Bearer token. Provide Procore-Company-Id wherever the endpoint reference requires it, and rely on the principal's project and Submittals permissions.
Tool Discipline
Use Read and Grep to inspect endpoint versions, workflow fields, and project configuration. Use Write or Edit only for the approved adapter, test, proposal, or receipt; do not perform an unapproved submittal mutation.
Output
- Endpoint-version and permission decision
- Validated submittal proposal and approval record
- Read-after-write workflow-state receipt
Return the selected route version, project, submittal identifier, notification choice, observed workflow state, and rollback owner.
Examples
Before creating a submittal, an adapter reads the current reference, requests the project's next available number, resolves the manager and approvers, and previews whether emails will be sent. It then reconciles the returned workflow data after approval.
Error Handling
| Failure | Response |
|---|---|
| Only beta endpoint fits | Document the gap and obtain risk acceptance; do not label beta as stable. |
| Required actor or spec is missing | Stop and resolve the project dependency before mutation. |
| 403 or 422 response | Preserve the provider detail and verify permissions, fields, and workflow constraints. |
| Read-after-write disagrees | Treat Procore as authoritative and halt downstream publication until reconciled. |