Open
Conversation
yoasyo25
force-pushed
the
ya/DOCINT-1073/document-upload-technical-guide
branch
6 times, most recently
from
3869b08 to
b229b82
Compare
yoasyo25
force-pushed
the
ya/DOCINT-1073/document-upload-technical-guide
branch
2 times, most recently
from
d7a6ec3 to
92d3b77
Compare
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new end-to-end technical guide intended to help integrators implement the full Procore Document Management (PDM) V2 upload + revision submission workflow, with scenario-based sequencing and error-handling guidance.
Changes:
- Replaces the placeholder technical guide with a detailed 8-step upload/submission workflow, integration patterns, examples, and an error reference.
- Adds a new “Constructing the Fields Array for API Requests” section to the metadata details reference to standardize how integrators format metadata payloads.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
document_management_integration/document_management_technical_guide.md |
Adds the comprehensive step-by-step PDM V2 upload/revision technical guide, including examples and error reference tables. |
document_management_integration/document_management_metadata_details.md |
Adds guidance + a quick reference table for constructing fields arrays used in Document Uploads POST/PATCH payloads. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
document_management_integration/document_management_technical_guide.md
Outdated
Show resolved
Hide resolved
document_management_integration/document_management_technical_guide.md
Outdated
Show resolved
Hide resolved
document_management_integration/document_management_technical_guide.md
Outdated
Show resolved
Hide resolved
document_management_integration/document_management_metadata_details.md
Outdated
Show resolved
Hide resolved
yoasyo25
force-pushed
the
ya/DOCINT-1073/document-upload-technical-guide
branch
from
92d3b77 to
9a2adf3
Compare
kangster
reviewed
Mar 9, 2026
document_management_integration/document_management_technical_guide.md
Outdated
Show resolved
Hide resolved
document_management_integration/document_management_technical_guide.md
Outdated
Show resolved
Hide resolved
cagmz
reviewed
Mar 9, 2026
document_management_integration/document_management_technical_guide.md
Outdated
Show resolved
Hide resolved
cagmz
reviewed
Mar 9, 2026
document_management_integration/document_management_technical_guide.md
Outdated
Show resolved
Hide resolved
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
document_management_integration/document_management_technical_guide.md
Outdated
Show resolved
Hide resolved
document_management_integration/document_management_technical_guide.md
Outdated
Show resolved
Hide resolved
Comment on lines
+567
to
+568
| | `uploads[].termination_reason` | string | Conditional | Required when `terminated_revision_status_id` is provided. Reason for terminating existing revision workflows (e.g., `"Superseded"`). See [Handling Workflow Conflicts](#handling-workflow-conflicts). | | ||
| | `uploads[].terminated_revision_status_id` | string | Conditional | Required when `termination_reason` is provided. The metadata value ID of the status to set on terminated revisions. | |
document_management_integration/document_management_technical_guide.md
Outdated
Show resolved
Hide resolved
document_management_integration/document_management_api_endpoints.md
Outdated
Show resolved
Hide resolved
yoasyo25
force-pushed
the
ya/DOCINT-1073/document-upload-technical-guide
branch
from
33d8406 to
4e3598b
Compare
cagmz
reviewed
Mar 17, 2026
|
|
||
| Push your binary file to Procore's storage service. Because file storage and document metadata are handled by separate microservices, this step requires you to step outside the V2 Document Management endpoints and use the V2.1 Unified Uploads API. The purpose of this step is to get your file into Procore's storage and obtain the `upload_id` field from the response, which is referred to as `file_upload_id` in subsequent steps. This ID is the critical link between your binary file and the document upload record you created in Step 4. | ||
|
|
||
| For full request/response details, authentication requirements, and multipart uploads, see the Unified Uploads API *(documentation coming soon)*. |
There was a problem hiding this comment.
Can we add a placeholder curl or HTTP example showing the request shape (e.g., endpoint, headers, multipart body), even if it's marked as preliminary? A "coming soon" note without actionable guidance breaks the workflow for anyone following this end-to-end.
document_management_integration/document_management_technical_guide.md
Outdated
Show resolved
Hide resolved
document_management_integration/document_management_api_endpoints.md
Outdated
Show resolved
Hide resolved
document_management_integration/document_management_technical_guide.md
Outdated
Show resolved
Hide resolved
document_management_integration/document_management_technical_guide.md
Outdated
Show resolved
Hide resolved
|
|
||
| The show response includes `latest_event_id` for every upload. Save this value — you must pass it as `upload_latest_event_id` when submitting in Step 8. If you don't need ML-enriched metadata, grab this ID and proceed to step 8. | ||
|
|
||
| **2. Check async processing status** |
There was a problem hiding this comment.
Would it be worth adding some guidance around polling here? Maybe something like "poll every 5–10 seconds with exponential backoff with a timeout of 5 minutes"? We know how our systems behave and their approximate latencies (most of the time), so I think it would be helpful to pass this knowledge to integrators.
document_management_integration/document_management_technical_guide.md
Outdated
Show resolved
Hide resolved
yoasyo25
commented
Mar 23, 2026
|
|
||
| Step 5 (binary file upload) can be performed before or after Step 4 (initialize document upload records). Both steps must be completed before Step 6 (Patch document uploads). | ||
| Keep batches to 100 items or fewer in Steps 4, 6, and 8 as larger payloads increase the risk of timeouts and make partial-failure recovery more complex. | ||
| If you need to process more than 100 documents, it is recommeneded to split them into sequential batches. |
Contributor
Author
There was a problem hiding this comment.
Based on discussion in slack here. Need to verify once performance testing is done with PDM Pilot API.
yoasyo25
commented
Mar 23, 2026
|
|
||
| Two background processes may auto-populate fields after `upload_status` is set to `COMPLETED`: | ||
|
|
||
| - **ML** (PDF files only) — Procore analyzes file content and may populate fields such as Type, Description, Number, Revision, and Date Authored. Check `integrationStatuses.ML` — once it reaches `completed` or `error`, ML processing is finished. There is no webhook for ML completion; you can poll the show endpoint to detect ML status. ML typically finishes within 10–30 seconds. It is recommended that you start polling 5 seconds after setting upload_status to COMPLETED, then repeat every 5–10 seconds. Stop when both integrationStatuses.ML and integrationStatuses.FILENAME_SCRAPING report completed or error, or after 3 minutes — whichever comes first. If the timeout is reached, proceed with patching metadata fields manually. For details on which fields ML populates, precedence rules, and limitations, see [ML and Automated Features]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_intro.md %}#machine-learning-ml-and-automated-features). |
Contributor
Author
There was a problem hiding this comment.
3 min suggestion based on ML_SPINNER_TIMEOUT_IN_MIN in doc-control-ui-service for how long the browser waits for ML processing
cagmz
reviewed
Mar 23, 2026
| | 2 | `.../fields` | GET | Fetch available project fields and their IDs | | ||
| | 3 | `.../fields/{field_id_or_name}/values` | GET | Fetch field value IDs for dropdown list field types | | ||
| | 4 | `.../document_uploads` | POST | Initialize document upload records | | ||
| | 5 | `/rest/v2.1/companies/{companyId}/projects/{projectId}/uploads` | POST, PUT, PATCH | Upload binary file to Procore storage using the **V2.1 Unified Uploads API** | |
There was a problem hiding this comment.
non-blocking: Use snake_case for consistency.
Suggested change
| | 5 | `/rest/v2.1/companies/{companyId}/projects/{projectId}/uploads` | POST, PUT, PATCH | Upload binary file to Procore storage using the **V2.1 Unified Uploads API** | | |
| | 5 | `/rest/v2.1/companies/{company_id}/projects/{project_id}/uploads` | POST, PUT, PATCH | Upload binary file to Procore storage using the **V2.1 Unified Uploads API** | |
cagmz
reviewed
Mar 23, 2026
|
|
||
| Step 5 (binary file upload) can be performed before or after Step 4 (initialize document upload records). Both steps must be completed before Step 6 (Patch document uploads). | ||
| Keep batches to 100 items or fewer in Steps 4, 6, and 8 as larger payloads increase the risk of timeouts and make partial-failure recovery more complex. | ||
| If you need to process more than 100 documents, it is recommeneded to split them into sequential batches. |
There was a problem hiding this comment.
Suggested change
| If you need to process more than 100 documents, it is recommeneded to split them into sequential batches. | |
| If you need to process more than 100 documents, it is recommended to split them into sequential batches. |
cagmz
reviewed
Mar 23, 2026
|
|
||
| Push your binary file to Procore's storage service using the **V2.1 Unified Uploads API**. As file storage and document metadata are handled by separate services, this step requires you to step outside the V2 Document Management endpoints. The file upload flow includes: **POST** to initialize the upload session and receive presigned URLs, **PUT** to push bytes directly to storage, then **PATCH** to complete. The `upload_id` returned by POST is what you pass as `file_upload_id` in Step 6. | ||
|
|
||
| > **Documentation in progress:** The V2.1 Unified Uploads API reference is not yet published. The examples below reflect the designed API contract. |
There was a problem hiding this comment.
non-blocking: should this be in a more prominent location, like a banner at the top of the page? It seems important to note that one of the APIs we/integrators depend on is subject to change.
cagmz
reviewed
Mar 23, 2026
|
|
||
| **3. Verify all required metadata** | ||
|
|
||
| Inspect the `fields` array to confirm all required fields are populated, either by you or by ML, before proceeding. |
There was a problem hiding this comment.
non-blocking: can we specify whether the fields array is paginated? That way, integrators know whether all fields are returned, or if they need to paginate, before validating required fields.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Jira Ticket:
🎫 DOCINT-1073
Adds a comprehensive step-by-step technical guide for API integrators building against the Procore Document Management V2 API.
Covers: