From bf1aea087b12c4b72976728da21e68b88a6e9cc0 Mon Sep 17 00:00:00 2001 From: cynthiaxhe Date: Mon, 16 Mar 2026 14:09:18 -0400 Subject: [PATCH 1/2] feat(PPC2-7034): add Unified Upload API tutorial behind LD flag Add new tutorial page for the Unified Pilot API under the Document Management Integration section. The nav entry is commented out to keep it hidden on GitHub Pages; visibility on developers.procore.com is gated by the document-management-v2-api-visibility LaunchDarkly flag via the existing dev-portal integration. Made-with: Cursor --- _data/navigation.yml | 2 + .../document_management_intro.md | 1 + .../tutorial_unified_uploads.md | 146 ++++++++++++++++++ 3 files changed, 149 insertions(+) create mode 100644 document_management_integration/tutorial_unified_uploads.md diff --git a/_data/navigation.yml b/_data/navigation.yml index 728f2d2..97f25b3 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -233,3 +233,5 @@ # url: /document-management-intro # - title: Technical Guide # url: /document-management-technical-guide +# - title: Unified Upload API Tutorial +# url: /tutorial-unified-uploads diff --git a/document_management_integration/document_management_intro.md b/document_management_integration/document_management_intro.md index 9777cd7..b65a52a 100644 --- a/document_management_integration/document_management_intro.md +++ b/document_management_integration/document_management_intro.md @@ -129,3 +129,4 @@ Consider the following recommendations when building your integration: - [Document Management Metadata Details]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_metadata_details.md %}) - [Document Management Technical Guide]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_technical_guide.md %}) - [File Upload API]({{ site.url }}{{ site.baseurl }}{% link tutorials/tutorial_uploads.md %}) +- [Unified File Upload API]({{ site.url }}{{ site.baseurl }}{% link tutorials/tutorial_unified_uploads.md %}) diff --git a/document_management_integration/tutorial_unified_uploads.md b/document_management_integration/tutorial_unified_uploads.md new file mode 100644 index 0000000..3777567 --- /dev/null +++ b/document_management_integration/tutorial_unified_uploads.md @@ -0,0 +1,146 @@ +--- +permalink: /tutorial-unified-pilot-uploads +title: Unified Upload API Tutorial +layout: default +section_title: Document Management Integration + +--- + +## Overview + +The Unified Upload API is a next-generation file upload service designed for tighter integration with the Document Management tool. +It provides a single, consistent upload path for Document Management workflows and supersedes the use of the legacy v1.1 `/uploads` endpoints for document management integrations. + +> **Beta Feature** — The Unified Upload API is currently available to select partners. Access is controlled via the Document Management integration program. + +This tutorial walks through the end-to-end workflow: creating an upload, transferring the binary file, and associating the upload with a Document Management upload record. + +## Prerequisites + +Before using the Unified Upload API, ensure you have: + +- A Procore [Developer Managed Service Account](https://developers.procore.com/documentation/developer-managed-service-accounts) with Document Management permissions. +- The Document Management tool enabled at the project level. +- OAuth 2.0 authentication configured. See [Choosing an OAuth 2.0 Grant Type]({{ site.url }}{{ site.baseurl }}{% link oauth/oauth_choose_grant_type.md %}). +- Reviewed the [Document Management Integration Overview]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_intro.md %}) for core concepts and workflow context. + +## How the Unified Upload API Differs from the Legacy Upload API + +| | Legacy Upload API (v1.1) | Unified Upload API | +|---|---|---| +| **Endpoint base** | `/rest/v1.1/companies/{id}/uploads` | `/rest/v2.0/companies/{id}/uploads` | +| **Segmented uploads** | Supported | Supported | +| **Non-segmented uploads** | Supported | Supported | +| **Document Management integration** | Manual association via `upload_id` | Native — returned `upload_uuid` is used directly in Document Upload records | +| **Recommended for Document Management** | No | Yes | + +If you are building a new Document Management integration, use the Unified Upload API described in this tutorial. +For general (non-Document Management) file uploads, continue to use the [Direct File Uploads]({{ site.url }}{{ site.baseurl }}{% link tutorials/tutorial_uploads.md %}) guide. + +## Unified Upload Workflow + +The full workflow for uploading a document through the Unified Upload API into Document Management consists of three phases: + +1. **Initialize** — Create an upload record and receive pre-signed storage instructions. +2. **Transfer** — PUT the binary file directly to the storage service using the pre-signed URL. +3. **Associate** — Reference the upload UUID when creating or updating a Document Upload record. + +### Step 1 — Initialize the Upload + +Create a new upload by POSTing to the Unified Upload endpoint. + +- **Request Method:** `POST` +- **Request URL:** `/rest/v2.0/companies/{company_id}/uploads` +- **Auth:** Procore Bearer Token +- **Request Body:** + +```json +{ + "response_filename": "floor-plan-rev3.pdf", + "response_content_type": "application/pdf" +} +``` + +**Example Response:** + +```json +{ + "uuid": "01JQXAMPLE000UNIFIED0UPLOAD", + "url": "https://storage.procore.com/uploads", + "fields": { + "key": "companies/1234/01JQXAMPLE000UNIFIED0UPLOAD", + "Content-Type": "application/pdf", + "Content-Disposition": "inline; filename=\"floor-plan-rev3.pdf\"", + "policy": "", + "x-amz-credential": "...", + "x-amz-algorithm": "AWS4-HMAC-SHA256", + "x-amz-date": "...", + "x-amz-signature": "..." + } +} +``` + +Note the `uuid` — you will use it in Step 3 to associate the upload with a Document Upload record. + +> **Important:** You must complete the binary transfer (Step 2) within one hour of receiving the pre-signed URL, or the URL expires and you must call the Initialize endpoint again. + +### Step 2 — Transfer the Binary File + +Use the `url` and `fields` from Step 1 to POST the file directly to the storage service. +Do not include your Procore Bearer Token in this request — it is directed at the storage service, not the Procore API. + +- **Request Method:** `POST` +- **Request URL:** The `url` value from Step 1 +- **Auth:** None +- **Request Body:** `multipart/form-data` containing all `fields` key-value pairs, plus the binary file under the key `file`. + +A successful transfer returns HTTP `204 No Content`. + +> **Important Considerations:** +> +> - Include all `fields` values as form data fields in the exact order returned. +> - Use `file` as the key name for the binary content. +> - Do not hard-code the `url` or `fields` values — they are generated per upload and may change. +> - Uploads not associated with a Procore resource within one week are automatically deleted. + +### Step 3 — Associate the Upload with a Document Upload Record + +After the binary is in storage, reference the `uuid` from Step 1 when creating or updating a Document Upload. + +Refer to the [Document Management Technical Guide]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_technical_guide.md %}) for the full Document Upload create/update API payload. +The relevant field is `upload_uuid`: + +```json +{ + "document_upload": { + "filename": "floor-plan-rev3.pdf", + "upload_uuid": "01JQXAMPLE000UNIFIED0UPLOAD" + } +} +``` + +Once the Document Upload is enriched with metadata and validated, submit it to create a Document Revision. +See [Document Management Integration Overview — Step 4: Submit Document Upload]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_intro.md %}#step-4-submit-document-upload) for details. + +## Segmented Uploads + +For large files (over 5 GB), the Unified Upload API also supports segmented uploads using the same segment-based approach as the legacy API. +Provide the `segments` array in the initialization request body instead of `response_filename`/`response_content_type`. +Each segment must include `size` (bytes) and `sha256`. + +Refer to the [Direct File Uploads — Segmented Uploads]({{ site.url }}{{ site.baseurl }}{% link tutorials/tutorial_uploads.md %}#segmented-direct-file-uploads) guide for segment preparation steps; the storage transfer pattern is identical. + +## Error Handling + +| HTTP Status | Meaning | Action | +|---|---|---| +| `403 Forbidden` (on storage PUT) | Pre-signed URL expired | Re-initialize upload (Step 1) and retry | +| `422 Unprocessable Entity` (on Document Upload) | Invalid `upload_uuid` or upload not yet complete | Confirm the binary transfer (Step 2) completed successfully | +| `429 Too Many Requests` | Rate limit reached | Back off and retry; see [Rate Limiting]({{ site.url }}{{ site.baseurl }}{% link plan_your_app/rate_limiting.md %}) | + +## See Also + +- [Document Management Integration Overview]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_intro.md %}) +- [Document Management Technical Guide]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_technical_guide.md %}) +- [Document Management API Endpoints]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_api_endpoints.md %}) +- [Direct File Uploads (Legacy)]({{ site.url }}{{ site.baseurl }}{% link tutorials/tutorial_uploads.md %}) From 79967cff6e28e31d6321969e4683bea84213db2a Mon Sep 17 00:00:00 2001 From: cynthiaxhe Date: Mon, 16 Mar 2026 18:17:14 -0400 Subject: [PATCH 2/2] use a tutorial placeholder --- .../tutorial_unified_uploads.md | 139 +----------------- 1 file changed, 3 insertions(+), 136 deletions(-) diff --git a/document_management_integration/tutorial_unified_uploads.md b/document_management_integration/tutorial_unified_uploads.md index 3777567..0771dde 100644 --- a/document_management_integration/tutorial_unified_uploads.md +++ b/document_management_integration/tutorial_unified_uploads.md @@ -1,5 +1,5 @@ --- -permalink: /tutorial-unified-pilot-uploads +permalink: /tutorial-unified-uploads title: Unified Upload API Tutorial layout: default section_title: Document Management Integration @@ -8,139 +8,6 @@ section_title: Document Management Integration ## Overview -The Unified Upload API is a next-generation file upload service designed for tighter integration with the Document Management tool. -It provides a single, consistent upload path for Document Management workflows and supersedes the use of the legacy v1.1 `/uploads` endpoints for document management integrations. +The Unified Upload API is a next-generation file upload service designed to provide a unified upload api for users. -> **Beta Feature** — The Unified Upload API is currently available to select partners. Access is controlled via the Document Management integration program. - -This tutorial walks through the end-to-end workflow: creating an upload, transferring the binary file, and associating the upload with a Document Management upload record. - -## Prerequisites - -Before using the Unified Upload API, ensure you have: - -- A Procore [Developer Managed Service Account](https://developers.procore.com/documentation/developer-managed-service-accounts) with Document Management permissions. -- The Document Management tool enabled at the project level. -- OAuth 2.0 authentication configured. See [Choosing an OAuth 2.0 Grant Type]({{ site.url }}{{ site.baseurl }}{% link oauth/oauth_choose_grant_type.md %}). -- Reviewed the [Document Management Integration Overview]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_intro.md %}) for core concepts and workflow context. - -## How the Unified Upload API Differs from the Legacy Upload API - -| | Legacy Upload API (v1.1) | Unified Upload API | -|---|---|---| -| **Endpoint base** | `/rest/v1.1/companies/{id}/uploads` | `/rest/v2.0/companies/{id}/uploads` | -| **Segmented uploads** | Supported | Supported | -| **Non-segmented uploads** | Supported | Supported | -| **Document Management integration** | Manual association via `upload_id` | Native — returned `upload_uuid` is used directly in Document Upload records | -| **Recommended for Document Management** | No | Yes | - -If you are building a new Document Management integration, use the Unified Upload API described in this tutorial. -For general (non-Document Management) file uploads, continue to use the [Direct File Uploads]({{ site.url }}{{ site.baseurl }}{% link tutorials/tutorial_uploads.md %}) guide. - -## Unified Upload Workflow - -The full workflow for uploading a document through the Unified Upload API into Document Management consists of three phases: - -1. **Initialize** — Create an upload record and receive pre-signed storage instructions. -2. **Transfer** — PUT the binary file directly to the storage service using the pre-signed URL. -3. **Associate** — Reference the upload UUID when creating or updating a Document Upload record. - -### Step 1 — Initialize the Upload - -Create a new upload by POSTing to the Unified Upload endpoint. - -- **Request Method:** `POST` -- **Request URL:** `/rest/v2.0/companies/{company_id}/uploads` -- **Auth:** Procore Bearer Token -- **Request Body:** - -```json -{ - "response_filename": "floor-plan-rev3.pdf", - "response_content_type": "application/pdf" -} -``` - -**Example Response:** - -```json -{ - "uuid": "01JQXAMPLE000UNIFIED0UPLOAD", - "url": "https://storage.procore.com/uploads", - "fields": { - "key": "companies/1234/01JQXAMPLE000UNIFIED0UPLOAD", - "Content-Type": "application/pdf", - "Content-Disposition": "inline; filename=\"floor-plan-rev3.pdf\"", - "policy": "", - "x-amz-credential": "...", - "x-amz-algorithm": "AWS4-HMAC-SHA256", - "x-amz-date": "...", - "x-amz-signature": "..." - } -} -``` - -Note the `uuid` — you will use it in Step 3 to associate the upload with a Document Upload record. - -> **Important:** You must complete the binary transfer (Step 2) within one hour of receiving the pre-signed URL, or the URL expires and you must call the Initialize endpoint again. - -### Step 2 — Transfer the Binary File - -Use the `url` and `fields` from Step 1 to POST the file directly to the storage service. -Do not include your Procore Bearer Token in this request — it is directed at the storage service, not the Procore API. - -- **Request Method:** `POST` -- **Request URL:** The `url` value from Step 1 -- **Auth:** None -- **Request Body:** `multipart/form-data` containing all `fields` key-value pairs, plus the binary file under the key `file`. - -A successful transfer returns HTTP `204 No Content`. - -> **Important Considerations:** -> -> - Include all `fields` values as form data fields in the exact order returned. -> - Use `file` as the key name for the binary content. -> - Do not hard-code the `url` or `fields` values — they are generated per upload and may change. -> - Uploads not associated with a Procore resource within one week are automatically deleted. - -### Step 3 — Associate the Upload with a Document Upload Record - -After the binary is in storage, reference the `uuid` from Step 1 when creating or updating a Document Upload. - -Refer to the [Document Management Technical Guide]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_technical_guide.md %}) for the full Document Upload create/update API payload. -The relevant field is `upload_uuid`: - -```json -{ - "document_upload": { - "filename": "floor-plan-rev3.pdf", - "upload_uuid": "01JQXAMPLE000UNIFIED0UPLOAD" - } -} -``` - -Once the Document Upload is enriched with metadata and validated, submit it to create a Document Revision. -See [Document Management Integration Overview — Step 4: Submit Document Upload]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_intro.md %}#step-4-submit-document-upload) for details. - -## Segmented Uploads - -For large files (over 5 GB), the Unified Upload API also supports segmented uploads using the same segment-based approach as the legacy API. -Provide the `segments` array in the initialization request body instead of `response_filename`/`response_content_type`. -Each segment must include `size` (bytes) and `sha256`. - -Refer to the [Direct File Uploads — Segmented Uploads]({{ site.url }}{{ site.baseurl }}{% link tutorials/tutorial_uploads.md %}#segmented-direct-file-uploads) guide for segment preparation steps; the storage transfer pattern is identical. - -## Error Handling - -| HTTP Status | Meaning | Action | -|---|---|---| -| `403 Forbidden` (on storage PUT) | Pre-signed URL expired | Re-initialize upload (Step 1) and retry | -| `422 Unprocessable Entity` (on Document Upload) | Invalid `upload_uuid` or upload not yet complete | Confirm the binary transfer (Step 2) completed successfully | -| `429 Too Many Requests` | Rate limit reached | Back off and retry; see [Rate Limiting]({{ site.url }}{{ site.baseurl }}{% link plan_your_app/rate_limiting.md %}) | - -## See Also - -- [Document Management Integration Overview]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_intro.md %}) -- [Document Management Technical Guide]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_technical_guide.md %}) -- [Document Management API Endpoints]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_api_endpoints.md %}) -- [Direct File Uploads (Legacy)]({{ site.url }}{{ site.baseurl }}{% link tutorials/tutorial_uploads.md %}) +More content to be added.