Skip to content

Commit 6f3684a

Browse files
cynthiaxhecynthiaxhe
committed
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
1 parent e345620 commit 6f3684a

2 files changed

Lines changed: 148 additions & 0 deletions

File tree

‎_data/navigation.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -233,3 +233,5 @@
233233
# url: /document-management-intro
234234
# - title: Technical Guide
235235
# url: /document-management-technical-guide
236+
# - title: Unified Upload API Tutorial
237+
# url: /tutorial-unified-pilot-uploads

‎document_management_integration/tutorial_unified_pilot_uploads.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
permalink: /tutorial-unified-pilot-uploads
3+
title: Unified Upload API Tutorial
4+
layout: default
5+
section_title: Document Management Integration
6+
7+
---
8+
9+
## Overview
10+
11+
The Unified Upload API is a next-generation file upload service designed for tighter integration with the Document Management tool.
12+
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.
13+
14+
> **Beta Feature** — The Unified Upload API is currently available to select partners. Access is controlled via the Document Management integration program.
15+
16+
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.
17+
18+
## Prerequisites
19+
20+
Before using the Unified Upload API, ensure you have:
21+
22+
- A Procore [Developer Managed Service Account](https://developers.procore.com/documentation/developer-managed-service-accounts) with Document Management permissions.
23+
- The Document Management tool enabled at the project level.
24+
- OAuth 2.0 authentication configured. See [Choosing an OAuth 2.0 Grant Type]({{ site.url }}{{ site.baseurl }}{% link oauth/oauth_choose_grant_type.md %}).
25+
- Reviewed the [Document Management Integration Overview]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_intro.md %}) for core concepts and workflow context.
26+
27+
## How the Unified Upload API Differs from the Legacy Upload API
28+
29+
| | Legacy Upload API (v1.1) | Unified Upload API |
30+
|---|---|---|
31+
| **Endpoint base** | `/rest/v1.1/companies/{id}/uploads` | `/rest/v2.0/companies/{id}/uploads` |
32+
| **Segmented uploads** | Supported | Supported |
33+
| **Non-segmented uploads** | Supported | Supported |
34+
| **Document Management integration** | Manual association via `upload_id` | Native — returned `upload_uuid` is used directly in Document Upload records |
35+
| **Recommended for Document Management** | No | Yes |
36+
37+
If you are building a new Document Management integration, use the Unified Upload API described in this tutorial.
38+
For general (non-Document Management) file uploads, continue to use the [Direct File Uploads]({{ site.url }}{{ site.baseurl }}{% link tutorials/tutorial_uploads.md %}) guide.
39+
40+
## Unified Upload Workflow
41+
42+
The full workflow for uploading a document through the Unified Upload API into Document Management consists of three phases:
43+
44+
1. **Initialize** — Create an upload record and receive pre-signed storage instructions.
45+
2. **Transfer** — PUT the binary file directly to the storage service using the pre-signed URL.
46+
3. **Associate** — Reference the upload UUID when creating or updating a Document Upload record.
47+
48+
### Step 1 — Initialize the Upload
49+
50+
Create a new upload by POSTing to the Unified Upload endpoint.
51+
52+
- **Request Method:** `POST`
53+
- **Request URL:** `/rest/v2.0/companies/{company_id}/uploads`
54+
- **Auth:** Procore Bearer Token
55+
- **Request Body:**
56+
57+
```json
58+
{
59+
"response_filename": "floor-plan-rev3.pdf",
60+
"response_content_type": "application/pdf"
61+
}
62+
```
63+
64+
**Example Response:**
65+
66+
```json
67+
{
68+
"uuid": "01JQXAMPLE000UNIFIED0UPLOAD",
69+
"url": "https://storage.procore.com/uploads",
70+
"fields": {
71+
"key": "companies/1234/01JQXAMPLE000UNIFIED0UPLOAD",
72+
"Content-Type": "application/pdf",
73+
"Content-Disposition": "inline; filename=\"floor-plan-rev3.pdf\"",
74+
"policy": "<base64-encoded-policy>",
75+
"x-amz-credential": "...",
76+
"x-amz-algorithm": "AWS4-HMAC-SHA256",
77+
"x-amz-date": "...",
78+
"x-amz-signature": "..."
79+
}
80+
}
81+
```
82+
83+
Note the `uuid` — you will use it in Step 3 to associate the upload with a Document Upload record.
84+
85+
> **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.
86+
87+
### Step 2 — Transfer the Binary File
88+
89+
Use the `url` and `fields` from Step 1 to POST the file directly to the storage service.
90+
Do not include your Procore Bearer Token in this request — it is directed at the storage service, not the Procore API.
91+
92+
- **Request Method:** `POST`
93+
- **Request URL:** The `url` value from Step 1
94+
- **Auth:** None
95+
- **Request Body:** `multipart/form-data` containing all `fields` key-value pairs, plus the binary file under the key `file`.
96+
97+
A successful transfer returns HTTP `204 No Content`.
98+
99+
> **Important Considerations:**
100+
>
101+
> - Include all `fields` values as form data fields in the exact order returned.
102+
> - Use `file` as the key name for the binary content.
103+
> - Do not hard-code the `url` or `fields` values — they are generated per upload and may change.
104+
> - Uploads not associated with a Procore resource within one week are automatically deleted.
105+
106+
### Step 3 — Associate the Upload with a Document Upload Record
107+
108+
After the binary is in storage, reference the `uuid` from Step 1 when creating or updating a Document Upload.
109+
110+
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.
111+
The relevant field is `upload_uuid`:
112+
113+
```json
114+
{
115+
"document_upload": {
116+
"filename": "floor-plan-rev3.pdf",
117+
"upload_uuid": "01JQXAMPLE000UNIFIED0UPLOAD"
118+
}
119+
}
120+
```
121+
122+
Once the Document Upload is enriched with metadata and validated, submit it to create a Document Revision.
123+
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.
124+
125+
## Segmented Uploads
126+
127+
For large files (over 5 GB), the Unified Upload API also supports segmented uploads using the same segment-based approach as the legacy API.
128+
Provide the `segments` array in the initialization request body instead of `response_filename`/`response_content_type`.
129+
Each segment must include `size` (bytes) and `sha256`.
130+
131+
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.
132+
133+
## Error Handling
134+
135+
| HTTP Status | Meaning | Action |
136+
|---|---|---|
137+
| `403 Forbidden` (on storage PUT) | Pre-signed URL expired | Re-initialize upload (Step 1) and retry |
138+
| `422 Unprocessable Entity` (on Document Upload) | Invalid `upload_uuid` or upload not yet complete | Confirm the binary transfer (Step 2) completed successfully |
139+
| `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 %}) |
140+
141+
## See Also
142+
143+
- [Document Management Integration Overview]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_intro.md %})
144+
- [Document Management Technical Guide]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_technical_guide.md %})
145+
- [Document Management API Endpoints]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_api_endpoints.md %})
146+
- [Direct File Uploads (Legacy)]({{ site.url }}{{ site.baseurl }}{% link tutorials/tutorial_uploads.md %})

0 commit comments

Comments
 (0)