Skip to content

fix: use snake_case for API response fields #347

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
yoasyo25 wants to merge 1 commit into
base: main
Choose a base branch
from
+56 −56
Open

fix: use snake_case for API response fields #347

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions document_management_integration/document_management_intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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)
Expand Down
90 changes: 45 additions & 45 deletions document_management_integration/document_management_metadata_details.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
}
},
Expand Down Expand Up @@ -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 |
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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"
}
}
},
Expand Down
18 changes: 9 additions & 9 deletions document_management_integration/document_management_technical_guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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**
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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
Expand All @@ -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": [
Expand Down
Loading