Bulk-fetch projects by ID

POST

/projects/get-many

curl --request POST \
  --url https://app.buildworkpro.com/api/v1/projects/get-many \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "ids": [ 1 ] }'

• Production

Fetch up to 50 projects by ID in a single round-trip. Returns flat project rows only (no phases / tasks / contacts). IDs that don’t exist are silently omitted; compare meta.requested vs meta.returned to detect missing.

Authorizations

• bearerAuth
  projects:read

Parameters

Header Parameters

Idempotency-Key

string format: uuid

<= 255 characters

Idempotent retry key for mutating operations. The first request with a given key executes normally and BuildWorkPro caches the response. Replaying the same key with the same request body (method + path + JSON body, SHA-256 hashed) returns the cached response without re-executing the mutation. Replaying with a DIFFERENT body returns 409 idempotency_key_reused. The cache TTL is 24 hours; after expiry the key is treated as a new operation. Keys are tenant-scoped. Recommended: a fresh UUID v4 per logical operation.

Request Body

Media type application/json

object

ids

required

Array<integer>

>= 1 items <= 50 items

Example ^generated

{
  "ids": [
    1
  ]
}

Responses

200

Projects

Media type application/json

object

data

required

Array<object>

object

id

required

integer

name

required

string

projectNumber

required

string

contactId

required

integer | null

bidId

required

integer | null

projectType

required

string | null

status

required

string

priority

required

string | null

startDate

required

Any of:

string

string format: date-time

string

string

null

null

expectedEndDate

required

Any of:

string

string format: date-time

string

string

null

null

actualEndDate

required

Any of:

string

string format: date-time

string

string

null

null

contractValue

required

string | null

originalContractValue

required

string | null

description

required

string | null

siteAddress

required

string | null

siteCity

string | null

siteState

string | null

siteZipCode

string | null

architectName

string | null

architectProjectNumber

string | null

contractFor

string | null

assignedTo

required

integer | null

createdAt

required

Any of:

string

string format: date-time

string

string

updatedAt

required

Any of:

string

string format: date-time

string

string

meta

required

object

request_id

Server-generated request identifier

string

pagination

object

cursor

required

Opaque cursor for the next page; null when no more results

string | null

has_more

required

Whether more pages are available after this one

boolean

count

required

Items in this page

integer

requested

required

integer

returned

required

integer

Example ^generated

{
  "data": [
    {
      "id": 1,
      "name": "example",
      "projectNumber": "example",
      "contactId": 1,
      "bidId": 1,
      "projectType": "example",
      "status": "example",
      "priority": "example",
      "startDate": "2026-04-15T12:00:00Z",
      "expectedEndDate": "2026-04-15T12:00:00Z",
      "actualEndDate": "2026-04-15T12:00:00Z",
      "contractValue": "example",
      "originalContractValue": "example",
      "description": "example",
      "siteAddress": "example",
      "siteCity": "example",
      "siteState": "example",
      "siteZipCode": "example",
      "architectName": "example",
      "architectProjectNumber": "example",
      "contractFor": "example",
      "assignedTo": 1,
      "createdAt": "2026-04-15T12:00:00Z",
      "updatedAt": "2026-04-15T12:00:00Z"
    }
  ],
  "meta": {
    "request_id": "example",
    "pagination": {
      "cursor": "example",
      "has_more": true,
      "count": 1
    },
    "requested": 1,
    "returned": 1
  }
}

403

Scope insufficient

Media type application/problem+json

object

type

required

URL identifying the problem type

string format: uri

title

required

Short human-readable summary

string

status

required

HTTP status code

integer

detail

Human-readable explanation

string

request_id

Server-generated request identifier

string

errors

Validation error array (422 only)

Array<object>

object

field

required

Field path that failed validation

string

code

required

Validation error code

string

message

required

Human-readable validation message

string

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "request_id": "example",
  "errors": [
    {
      "field": "example",
      "code": "example",
      "message": "example"
    }
  ]
}

422

Validation failed

Media type application/problem+json

object

type

required

URL identifying the problem type

string format: uri

title

required

Short human-readable summary

string

status

required

HTTP status code

integer

detail

Human-readable explanation

string

request_id

Server-generated request identifier

string

errors

Validation error array (422 only)

Array<object>

object

field

required

Field path that failed validation

string

code

required

Validation error code

string

message

required

Human-readable validation message

string

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "request_id": "example",
  "errors": [
    {
      "field": "example",
      "code": "example",
      "message": "example"
    }
  ]
}