Skip to main content
POST
/
builders
/
{builderId}
/
photo-gallery
/
bulk-upsert
Bulk upsert photos
curl --request POST \
  --url https://api.buildpass.global/builders/{builderId}/photo-gallery/bulk-upsert \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "externalSourceId": "supasite:photo-page:page_123",
  "sourceApp": "supasite",
  "projectId": "proj_ckproject123456789012345678",
  "folderName": "Site walkthrough - 2026-06-11",
  "photos": [
    {
      "externalSourceId": "<string>",
      "fileName": "<string>",
      "contentType": "<string>",
      "sequenceId": 123,
      "imageUrl": "<string>",
      "width": 123,
      "height": 123,
      "capturedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "folderId": "<string>"
}
'
{
  "folderId": "<string>",
  "createdAttachmentIds": [
    "<string>"
  ],
  "skippedExternalSourceIds": [
    "<string>"
  ],
  "failedPhotos": [
    {}
  ]
}
Requires write:photos. Bulk upserts photos into a project gallery folder. projectId is required and must belong to the builder. Upload attachment bytes first with POST /builders/{builderId}/attachments/bulk-upload, then pass each returned { key, regionId, type } as photos[].imageAttachment. This endpoint accepts JSON only. Approved HTTPS imageUrl imports are supported only for hosts reviewed and enabled by BuildPass. If you want to import photos from your own image URL hosts, please contact BuildPass. The endpoint is idempotent by metadata.externalSourceId, so repeated sends skip existing photos. When syncing the same external source again, pass the previously returned folderId so new photos are added to the same BuildPass folder. Omit folderId for a different external source, even when the folder name and date are the same. Use DELETE /builders/{builderId}/photo-gallery/bulk-upsert with the same externalSourceId, projectId, and optional folderId to archive photos created for that external source and remove the now-empty folder when possible.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

​
builderId
string
required

Body

application/json
​
externalSourceId
string
required
Example:

"supasite:photo-page:page_123"

​
sourceApp
string
required
Example:

"supasite"

​
projectId
string
required
Example:

"proj_ckproject123456789012345678"

​
folderName
string
required
Example:

"Site walkthrough - 2026-06-11"

​
photos
object[]
required
​
folderId
string

Existing BuildPass photo folder id for this external source. Omit on first upsert to create a new folder.

Response

200 - application/json

Photos synced

​
folderId
string
​
createdAttachmentIds
string[]
​
skippedExternalSourceIds
string[]
​
failedPhotos
object[]
​
status
enum<string>
Available options:
synced,
partial