From 79c8c7a36c97ddd5c35f05bf324281bd4ec3870f Mon Sep 17 00:00:00 2001 From: Yohanan Assefa Date: Wed, 1 Apr 2026 09:10:09 -0400 Subject: [PATCH] fix: use snake_case for API response fields --- .../document_management_intro.md | 4 +- .../document_management_metadata_details.md | 90 +++++++++---------- .../document_management_technical_guide.md | 18 ++-- 3 files changed, 56 insertions(+), 56 deletions(-) diff --git a/document_management_integration/document_management_intro.md b/document_management_integration/document_management_intro.md index e4267da1..6c44c7ef 100644 --- a/document_management_integration/document_management_intro.md +++ b/document_management_integration/document_management_intro.md @@ -57,7 +57,7 @@ For all available API endpoints, see [Document Management API Endpoints]({{ site **Step 3: Prepare and Validate Document Upload** - Update the Document Upload with the file upload ID (from step 2) and enrich your metadata fields. During this phase, the system initiates asynchronous processing for ML analysis and naming standard extraction. Before submitting, verify the upload is ready: - required fields are populated. Query the [Project Upload Requirements](https://developers.procore.com/reference/rest/project-upload-requirements?version=2.0) endpoint for upload rules and qualifiers - - ML has finished processing the file and `integrationStatuses.ML` has transitioned to `completed` for PDFs + - ML has finished processing the file and `integration_statuses.ml` has transitioned to `completed` for PDFs - the Document Upload has `upload_status` of `COMPLETED` Note: the update API exposes a batch update endpoint for updating multiple uploads; batch updates may return HTTP 207 with partial success/failure results. See [Technical Guide]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_technical_guide.md %}) for complete examples and error-handling patterns. @@ -88,7 +88,7 @@ If your project enforces a naming standard and documents are named according to - **PDF-only** - ML predictions apply to PDF files - **Asynchronous Processing** - ML classification occurs asynchronously after a Document Upload is created, not during the API call itself. Your integration should not expect metadata to be populated immediately after creating an upload -- **Completion Status** - The `integrationStatuses.ML` field in the Document Upload response will change from `"in_progress"` to `"completed"` once ML analysis finishes. Check this status before submitting the Document Upload as a Document Revision to ensure ML-inferred metadata is included +- **Completion Status** - The `integration_statuses.ml` field in the Document Upload response will change from `"in_progress"` to `"completed"` once ML analysis finishes. Check this status before submitting the Document Upload as a Document Revision to ensure ML-inferred metadata is included - **User-provided values take precedence** - If your integration provides values for any ML-processed fields when creating a Document Upload, those values will not be overridden by ML predictions - **Automatic application** - If no user values are provided for these fields, ML predictions will be automatically applied when available. - **Best practices** - For optimal results, refer to the [Procore Support: What data can be automatically populated FAQ](https://v2.support.procore.com/faq-what-data-can-procore-automatically-populate-when-uploading-files-to-the-document-management-tool) diff --git a/document_management_integration/document_management_metadata_details.md b/document_management_integration/document_management_metadata_details.md index 8460eba4..f29fab3f 100644 --- a/document_management_integration/document_management_metadata_details.md +++ b/document_management_integration/document_management_metadata_details.md @@ -87,31 +87,31 @@ This reference describes the metadata structure returned by **Document Upload** ] } }, - "matchCriteria": "string", + "match_criteria": "string", "upload_status": "string", - "integrationStatuses": { - "ML": "string", - "FILENAME_SCRAPING": "string", - "integrationResponse": { - "type_ML": { - "valueId": "string", - "valueName": "string" + "integration_statuses": { + "ml": "string", + "filename_scraping": "string", + "integration_response": { + "type_ml": { + "value_id": "string", + "value_name": "string" }, - "number_ML": { - "valueId": "string", - "valueName": "string" + "number_ml": { + "value_id": "string", + "value_name": "string" }, - "description_ML": { - "valueId": "string", - "valueName": "string" + "description_ml": { + "value_id": "string", + "value_name": "string" }, "number_scraping": { - "valueId": "string", - "valueName": "string" + "value_id": "string", + "value_name": "string" }, - "date_authored_ML": { - "valueId": "string", - "valueName": "string" + "date_authored_ml": { + "value_id": "string", + "value_name": "string" } } }, @@ -177,11 +177,11 @@ System-generated fields are automatically populated and cannot be directly modif | **file_key** | string | File upload ID returned by the file upload API. | Set on file upload | | **format** | string | File format/type derived from MIME type. | Set on file upload | | **id** | string | Unique identifier assigned at upload creation. Use this ID for update operations. | Set at creation | -| **integrationStatuses** | object | Status of active integrations. | Set at creation, updates during processing | +| **integration_statuses** | object | Status of active integrations. | Set at creation, updates during processing | | **integrations** | object | Detailed integration information. | Set at creation, updates during processing | | **item_content** | lov_entry | Indicates whether the item is a Document or a Placeholder. | Set at creation | | **latest_event_id** | string | Event ID for optimistic concurrency control. | Updated on each state change | -| **matchCriteria** | string | Identifier generated based on naming standard and file format used for grouping documents into containers. | Set at creation, updates on metadata change | +| **match_criteria** | string | Identifier generated based on naming standard and file format used for grouping documents into containers. | Set at creation, updates on metadata change | | **original_filename** | string | Original file name of a document at the time of upload. | Set at creation | | **position_within_container** | string | Sort position within the document container. | Set when containerized | | **recycled_at** | timestamp | Timestamp when the document was moved to the Recycle Bin. | Set on recycling | @@ -459,18 +459,18 @@ Here's how a single upload response might display different value sources: ### Integration Status Monitoring -When a Document Upload is returned, it includes `integrationStatuses` indicating the state of automated processing: +When a Document Upload is returned, it includes `integration_statuses` indicating the state of automated processing: ```json { - "integrationStatuses": { - "ML": "in_progress", // One of: in_progress, completed, error, not_applicable - "FILENAME_SCRAPING": "in_progress" // One of: in_progress, completed, error, not_applicable + "integration_statuses": { + "ml": "in_progress", // One of: in_progress, completed, error, not_applicable + "filename_scraping": "in_progress" // One of: in_progress, completed, error, not_applicable } } ``` -Before submitting a Document Upload as a Document Revision, verify that integrations have completed: check that `integrationStatuses.ML` and `integrationStatuses.FILENAME_SCRAPING` (if applicable) have transitioned to either `completed`, `error`, or `not_applicable`. +Before submitting a Document Upload as a Document Revision, verify that integrations have completed: check that `integration_statuses.ml` and `integration_statuses.filename_scraping` (if applicable) have transitioned to either `completed`, `error`, or `not_applicable`. ### BIM Processing Integration @@ -1016,31 +1016,31 @@ Document Management can process 3D model files (BIM/Building Information Models) ] } }, - "matchCriteria": "TEST4-SP-I-17|application/pdf", + "match_criteria": "TEST4-SP-I-17|application/pdf", "upload_status": "COMPLETED", - "integrationStatuses": { - "ML": "completed", - "FILENAME_SCRAPING": "completed", - "integrationResponse": { - "type_ML": { - "valueId": "YU0H5NUOLP7TA1VLNBQAZIHMG", - "valueName": "Drawing" + "integration_statuses": { + "ml": "completed", + "filename_scraping": "completed", + "integration_response": { + "type_ml": { + "value_id": "YU0H5NUOLP7TA1VLNBQAZIHMG", + "value_name": "Drawing" }, - "number_ML": { - "valueId": "MP000", - "valueName": "MP000" + "number_ml": { + "value_id": "MP000", + "value_name": "MP000" }, - "description_ML": { - "valueId": "MECHANICAL PIPE SCHEDULE", - "valueName": "MECHANICAL PIPE SCHEDULE" + "description_ml": { + "value_id": "MECHANICAL PIPE SCHEDULE", + "value_name": "MECHANICAL PIPE SCHEDULE" }, "number_scraping": { - "valueId": "I", - "valueName": "I" + "value_id": "I", + "value_name": "I" }, - "date_authored_ML": { - "valueId": "2000-01-01T00:00:00.000Z", - "valueName": "2000-01-01T00:00:00.000Z" + "date_authored_ml": { + "value_id": "2000-01-01T00:00:00.000Z", + "value_name": "2000-01-01T00:00:00.000Z" } } }, diff --git a/document_management_integration/document_management_technical_guide.md b/document_management_integration/document_management_technical_guide.md index b2036402..fde868d4 100644 --- a/document_management_integration/document_management_technical_guide.md +++ b/document_management_integration/document_management_technical_guide.md @@ -543,8 +543,8 @@ The show response includes `latest_event_id` for every upload. Save this value 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). -- **Filename scraping** — Procore attempts to extract metadata from the filename when the project has a naming standard configured. Check `integrationStatuses.FILENAME_SCRAPING` to determine the status of filename scraping. +- **ML** (PDF files only) — Procore analyzes file content and may populate fields such as Type, Description, Number, Revision, and Date Authored. Check `integration_statuses.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 `integration_statuses.ml` and `integration_statuses.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). +- **Filename scraping** — Procore attempts to extract metadata from the filename when the project has a naming standard configured. Check `integration_statuses.filename_scraping` to determine the status of filename scraping. **3. Verify all required metadata** @@ -593,9 +593,9 @@ GET /rest/v2.0/companies/{company_id}/projects/{project_id}/document_management/ } ], "upload_status": "COMPLETED", - "integrationStatuses": { - "ML": "completed", - "FILENAME_SCRAPING": "completed" + "integration_statuses": { + "ml": "completed", + "filename_scraping": "completed" }, "latest_event_id": "01JDXMPK0REV0D87H0JVVZ8M2W", "permissions": { @@ -931,7 +931,7 @@ Verify your upload ID appears in `success` and `failed` is empty before proceedi **7. Get latest event ID — `GET .../document_uploads/{id}`** -Call the show endpoint to retrieve `latest_event_id`. For PDF files, also check `integrationStatuses.ML` — if it is still `"in_progress"` and you want to use ML-populated fields, wait until it reaches `"completed"` or `"error"` before submitting. +Call the show endpoint to retrieve `latest_event_id`. For PDF files, also check `integration_statuses.ml` — if it is still `"in_progress"` and you want to use ML-populated fields, wait until it reaches `"completed"` or `"error"` before submitting. ``` GET /rest/v2.0/companies/8089/projects/2305/document_management/document_uploads/01JDXMPK0MTP0H41D4PYZ62R6R @@ -943,9 +943,9 @@ Response: "data": { "id": "01JDXMPK0MTP0H41D4PYZ62R6R", "upload_status": "COMPLETED", - "integrationStatuses": { - "ML": "completed", - "FILENAME_SCRAPING": "completed" + "integration_statuses": { + "ml": "completed", + "filename_scraping": "completed" }, "latest_event_id": "01JDXMPK0REV0D87H0JVVZ8M2W", "fields": [