2026-08-18 API deprecation wave

On 2026-12-01, the API version snapshots listed in this guide stop being served. Requests
pinned to them are automatically served by the current version instead. Your calls will keep
working, but request validation is stricter in the current version, and some responses change
shape, so payloads that are accepted today may be rejected afterwards.

This guide lists exactly what to change.

1. Check whether you're affected

Look at your response headers. Affected responses include:

Deprecation: true
Sunset:      Tue, 01 Dec 2026 00:00:00 GMT
Link:        <https://developers.fieldwire.com/changelog/deprecation-2026-08-18>; rel="deprecation"

These headers are returned per request, so they tell you precisely which of your calls need
attention. A call that does not return Deprecation: true needs no changes.

Two things worth knowing:

• A version date alone doesn't determine exposure. Each endpoint is served by the oldest
  snapshot newer than your pinned version that implements that endpoint. Pinned to 2024-01-01,
  a GET /projects is already served by the current version and is unaffected, while
  POST /projects is affected. Same pin, different answer per endpoint.
• If you don't send Fieldwire-Version at all, API-key integrations default to today's date,
  so you're already on the current version and nothing changes. We still recommend pinning
  explicitly.

2. Update your request payloads

This is the change that affects the most integrations. It applies to every integration pinned
below 2026-04-07 on the endpoints in this table.

All endpoints are under /api/v3. No GET endpoint is affected by this section — if your
integration only reads data, skip to section 3.

What changes

Previously, request bodies on these endpoints were accepted loosely: unrecognized keys were
silently dropped and malformed values were passed through. From 2026-04-07, request bodies are
validated up front and rejected with 422 Unprocessable Entity if they don't conform.

A rejection looks like:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{ "errors": ["<description of the invalid field>"] }

How to find failures before the sunset date

Replay your existing write requests against the new version in a test environment and look for
422 responses:

curl -X POST 'https://client-api.super.fieldwire.com/api/v3/projects/<project_id>/attachments' \
  -H 'Authorization: <your auth>' \
  -H 'Fieldwire-Version: 2026-04-07' \
  -H 'Content-Type: application/json' \
  -d '{ "attachment": { ... your real payload ... } }'

Every 422 is a request that will start failing on 2026-12-01. Fix the payload and re-run until
clean.

Also worth updating

These aren't failures, but the behavior differs and may affect your results:

• markup_options is now honored on attachment create/update (markups are burned into crops).
  Previously it was ignored.
• unique_id is ignored on batch create for attachments and sheet uploads, but required to be passed it. Should be any unique string per request.
• last_editor_user_id is now required on sheet upload updates.

3. Check response and behavior changes

These apply only if you're pinned further back. Find your pinned version and review every row
at or above it.

Pinned before 2016-07-01: bubbles

• The tags array is no longer returned or accepted on bubbles. Remove it from your payloads
  and stop reading it from responses.
• Bubble responses gain attachment_id, latitude, longitude, captured_at,
  original_created_at, original_creator, and several URL fields.
• floorplan_crop now requires floorplan_id alongside the coordinates.
• Listing uses the current pagination style rather than page-based headers.

Pinned before 2017-01-27: listings

GET /projects and the project-scoped listings for attachments, bubbles, sheet_uploads, and
tasks move to current behavior:

• Pagination changes. These endpoints currently return X-Total-Pages, X-Current-Page, and
  X-Count page-based headers. Re-check how you paginate.
• GET /projects supports filter_type and account-scoped listing for API keys.
• GET /tasks supports the min_verified_at filter.
• GET /sheet_uploads bounds the is_processed filter to a 1-day updated_after window, so older
  records no longer appear.

The same snapshot also serves these project-scoped listings, which move to current behavior at the
same time, so verify them if you use them:
attachments_multi_hyperlinks, automatic_hyperlinks, bubble_markups, entity_taggings,
entity_tags, floorplans, folders, hyperlinks, markups, multi_hyperlinks, sheets,
task_check_items, task_relations, teams, template_checklists, users.

Pinned before 2019-02-19: project plan names

plan_name currently reports "Free" for Basic accounts and "Business" for Business Plus. It
now returns the actual plan name.

Pinned before 2019-11-20: attachment kinds

GET /attachments currently returns only file, photo, video, and photo_sphere. Additional
kinds now appear, so make sure an unrecognized kind doesn't break your parser.

GET /projects/:project_id/folders also moves to current behavior at this point.

Pinned before 2020-05-11: access_token removed

Project payloads currently include an access_token field. It is no longer returned. If you
read it, switch to an API key or a token obtained through the standard authentication flow.

Pinned before 2020-05-15: blocked_at

blocked_at is currently set to the current time for projects using features your pinned version
can't render, which effectively hides them. It now reflects the real value, so those projects
appear in your results, meaning your integration needs to handle project data it previously never saw.

Pinned before 2020-07-21: task user fields

For API-key requests, creator_user_id and last_editor_user_id are currently filled in
automatically when omitted. They become required: omitting them returns 422. See
section 2.

Pinned before 2023-01-25: attachment updates

• PUT /attachments/:id currently returns 200 without applying the update when the
  attachment is linked in more than one place. Updates now apply and are validated, so verify you
  aren't relying on the no-op.
• The multi_hyperlink_id filter on GET /attachments is no longer available.
• thumb_url and flattened_file_url are no longer overridden by the linking record.

The same snapshot also serves attachment_markups (including POST .../flatten and the versions
nested under attachments and rfi_attachments), multi_hyperlinks/:id/attachments,
attachments_multi_hyperlinks, and form_section_record_input_values. These move to current
behavior at the same time.

Pinned before 2023-04-01: attachment deletes and visibility

• DELETE /attachments/:id currently returns 204 without deleting when the attachment is
  used elsewhere. Deletion now behaves consistently.
• GET /attachments now respects follower permissions, so users with follower access may see
  fewer attachments than before.

Pinned before 2023-06-01: project plan fields

plan_name currently maps Business Plus to "Business", and is_business currently means "has
business features". Now, is_business means the project is on the Business plan specifically, with
is_business_plus and has_business_features exposed as separate fields. Update any logic keyed
on these.

Pinned before 2025-09-15: task creation permissions

POST /tasks, POST /tasks/:id/duplicate, and POST /tasks/batch now enforce the project-level
task-creation permission. Confirm the users your integration authenticates as hold a project role
that permits creating tasks, or these calls will return an authorization error.

4. Endpoints that are being removed (404)

This section applies only if you are pinned below 2023-01-25. These endpoints exist solely
in that snapshot, with no current equivalent, so on 2026-12-01 they stop resolving and return
404. This is a removal, not a behavior change, and it needs a code change on your side.

attachment_markups

The single polymorphic attachment_markups collection (addressed with
markupable_id / markupable_type) is replaced by one endpoint per entity type:

• /projects/:project_id/attachments_multi_hyperlink_markups
• /projects/:project_id/form_section_record_input_value_markups
• /projects/:project_id/rfi_attachment_markups
• /projects/:project_id/bubble_markups

There is no drop-in equivalent, so plan for a real change: pick the endpoint matching the entity
you are annotating rather than passing a markupable_type. Two legacy behaviors also disappear:
creating a markup no longer fans it out to every place the attachment is linked, and update/delete
on a reused attachment's markup is no longer a silent no-op.

GET /projects/:project_id/multi_hyperlinks/:multi_hyperlink_id/attachments

Replace with
GET /projects/:project_id/multi_hyperlinks/:multi_hyperlink_id/attachments_multi_hyperlinks,
which returns the link records with their attachment embedded. POST and DELETE on the original
path are unaffected, only the listing is removed.

5. Endpoints that are not affected

Endpoints served by version snapshots outside this change are unaffected and continue to behave as
they do today, including markups at 2019-06-19 / 2023-01-10 / 2023-03-16, floorplans at
2021-03-30, template_checklists at 2021-04-15, forms and form data at 2020-05-06 /
2020-06-22 / 2024-08-01 / 2025-07-28, hyperlinks at 2018-04-25, and BIM versions.

6. Migration checklist

• Locate the Fieldwire-Version your integration sends. If it's absent and you use an API key,
  you're already current, so no action needed.
• Identify which of your calls return Deprecation: true.
• If pinned below 2023-01-25: migrate off attachment_markups and
  GET .../multi_hyperlinks/:id/attachments, since these 404 after sunset and are the only changes
  requiring new endpoints.
• Replay your write requests against Fieldwire-Version: 2026-04-07 and fix every 422
  (section 2). Start with unrecognized keys.
• Review the response changes for your pinned version
  (section 3).
• If you create tasks, confirm your integration's users hold a role that permits it.
• Update the Fieldwire-Version header to 2026-04-07 (or later) and deploy before
  2026-12-01.
• Confirm Deprecation headers no longer appear in your responses.