Creating a Procore change event over the API

Auth: a service account, not per-user OAuth#

A Data Management Service Account (DMSA) with client_credentials works for reads and writes, which means an integration can run server side on a schedule with nobody logged in.

POST https://login.procore.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=...&client_secret=...

Two things to know. The body must be form encoded, because JSON is rejected here even though it is accepted elsewhere. And tokens last 5400 seconds, so refresh a little early rather than letting a long request straddle expiry.

Most endpoints also want a Procore-Company-Id header. GET /rest/v1.0/companies is the useful exception: it answers without one, which is how a multi-company integration finds out which companies it has been installed on in the first place.

Paths are not consistent, and this is the biggest time sink#

Financial resources hang off a ?project_id= query parameter. Directory-shaped ones nest under /projects/{id}/. There is no rule you can infer, so check each one.

Creating the change event#

This body works:

POST /rest/v1.0/change_events?project_id={project_id}

{ "change_event": {
    "title": "T&M 2026-08-09 — Removed unmarked footing at grid C-4",
    "description": "...",
    "event_scope": "out_of_scope",
    "status": "open",
    "origin_id": "your-own-id",
    "origin_data": "{\"captured\":\"...\"}"
} }

event_scope takes in_scope, out_of_scope or tbd. status takes the lowercase mapped_to_status string, not the status id. Statuses are configured per company and carry their own ids, so read the list rather than hardcoding it.

The empty line item you did not ask for#

Creating a change event auto-creates one line item with no content. It cannot be deleted (every delete path we tried returns 404) but it can be patched into a real one.

PATCH /rest/v1.0/change_events/{id}/line_items/{line_item_id}?project_id={project_id}

So the first real line should reuse it and the rest should be posted normally. Otherwise every record you write carries a stray $0.00 row, which is exactly the kind of detail that makes a project manager stop trusting an integration.

Line items, and amounts that must be strings#

A line item needs a budget_code. A bare cost_code_id is rejected with budget_code: is missing.

POST /rest/v1.0/change_events/{id}/line_items?project_id={project_id}

{ "line_item": {
    "description": "Operator — 6h",
    "budget_code": { "id": 1870754 },
    "cost_impact": { "estimate": {
      "quantity": "6.00",
      "unit_cost": "95.00",
      "calculation_strategy": "automatic"
    } }
} }

unit_of_measure validates against a list we never found. Both hr and hour are rejected, so we omit it.

The read shape is not the write shape. A POST takes and returns cost_impact.estimate; a later GET on the change event returns flat estimated_cost_amount, estimated_cost_quantity and estimated_cost_unit_cost on the nested line items. Same numbers, two representations, so parse both.

The budget_code field has a trap of its own that is worth its own page: the segment_items form returns 200 and is silently discarded.

Attachments#

Photos ride on a multipart PATCH of the change event itself, not on a separate attachments endpoint.

PATCH /rest/v1.0/change_events/{id}?project_id={project_id}
Content-Type: multipart/form-data

attachments[]=@photo.jpg

If the provenance matters (when the photo was taken, where, who directed the work) write it into origin_data as well. Do not assume EXIF survives the upload.

Idempotency, and the fact that makes review possible#

Set your own origin_id on create and you can look the record up later instead of writing a second one. That makes retries safe.

More usefully: setting origin_id does not lock the record. Procore locks Direct Costs, Sub Invoices, Payments, and approved Commitments and Change Orders, but a change event stays editable after an integration creates it. A PATCH after creation succeeds.

That is a real argument for change events as a write target beyond anything strategic. A record you can correct supports a review loop. A record that freezes on creation does not, and field data always needs correcting.

Rate limits and a pagination trap#

The spike limit is 25 requests per 10 seconds, and it is easy to hit on a first unthrottled run. Serializing calls roughly 450ms apart stays under it comfortably. The response headers are authoritative, including x-rate-limit-reset as a unix timestamp, so respect that before falling back to your own backoff.