22.09.2026-1
New endpoints that address a device or location by the externalId you assign, two ad formats the platform accepts but the catalogue never listed, and several rules that were always in force and are only now written down.
Read and delete by your own externalId
Section titled “Read and delete by your own externalId”Reading or deleting previously needed the server-assigned metadata.id, the value the guide tells you never to send on a write. You no longer have to store it:
| Get device | GET /v1alpha2/inventory/devices/{externalId} |
| Delete device | DELETE /v1alpha2/inventory/devices/{externalId} |
| Delete location | DELETE /v1alpha2/inventory/locations/{externalId} |
GET /v1alpha2/inventory/locations/{externalId} already worked this way and is unchanged.
A device’s externalId is the one derived from the identifier you set, "{key}_{playerId}". A location’s is the top-level externalId field you send on upsert.
The older /v1alpha routes keyed on metadata.id are unchanged and keep working. Nothing you have built stops working.
Two ad formats were missing
Section titled “Two ad formats were missing”The catalogue listed six formats and said those were all of them. The platform accepts eight. The two that were missing:
| Ad-format id | Name | Size (px) |
|---|---|---|
IMAGE-HORIZONTAL_16:9_1920x1080_JPG+PNG |
Image Horizontal HD | 1920×1080 |
IMAGE-VERTICAL_9:16_1080x1920_JPG+PNG |
Image Vertical HD | 1080×1920 |
Both are 10s, 5 MB, JPG or PNG — the same terms as the other image formats. See Ad types & formats for the full set.
An id outside the catalogue will be rejected as INVALID_ARGUMENT on devices:upsert, rather than stored. Until that check ships, an unknown id is still accepted and matches no creative, so the device renders nothing for that format without reporting an error. Send only ids from the catalogue.
Send at most one placement zone
Section titled “Send at most one placement zone”placement.retailGroceryZone and placement.retailMallZone are alternatives — a request carrying both is rejected, even when the one you do not want is set to its _UNSPECIFIED value. Omit the member that does not apply rather than sending it unset.
Sample responses previously showed both members at once. They now show one, because the two-member form was never a valid request body.
An upsert replaces the whole resource
Section titled “An upsert replaces the whole resource”This was always true and is now stated on the pages it applies to. locations:upsert and devices:upsert write the resource exactly as you send it: a field you leave out is cleared, not left alone.
For a location that includes tdlinx, gln, coordinates, salesAreaSqm, address, weeklyHours and dateOverrides. There is no partial update and no field mask, so send the resource in full on every sync.
metadata.name follows the same rule — omitting metadata clears a name already stored, so resend it on every upsert.
Smaller corrections
Section titled “Smaller corrections”address.countrytakes an ISO 3166-1 alpha-2 code —"DE", not"Germany". The samples showed a full country name, which the platform does not return and does not expect.PUTandPATCHare gone from the guides. They were mentioned once and documented nowhere. Anything not in the Reference is not available;upsertis the only write.maskandmetadata.fqnno longer appear on the schemas. Neither was usable:maskhas not been read for some time, andfqnis an internal identifier.- Devices returned by content source now carry their location. Each row of
devices:listByContentSourceis a device together with the location it sits at, so a fleet sync no longer fetches each location separately.