How records change

When a record counts as changed, how changes reach the API, and the bursts and reloads an integration must expect.

​

What counts as a change

A record changes when its stored content changes. That happens when:

• the office publishes something new about the mark: a status, a date, a new owner;
• Pinakel processes the record differently, for example after improving a mapping or the name normalization;
• the register is reloaded from its source.

updated_at is the time of the last change in Pinakel, not the date of the office’s event. The office’s own dates are in dates and status.date.

​

How changes reach you

Each register is checked on its own schedule (update_frequency in GET /v1/jurisdictions). After an update is loaded, the changed records are published to the changes feed in batches. Each feed item is published once per change, with a created_at timestamp (the publication time), and carries the record as it is when you read the page.

complete_through, returned on every feed page, is the time up to which every change has been published. When a page has has_more: false, you have everything published before that time.

​

Bursts

Most days a register changes a little. Some events change a lot of records at once, and your integration should handle them without alarms or manual work:

Event	What you see	How big
Register reload. A register is rebuilt from its source, for example after the office reissues its data.	Every record of the register is published again, with a new updated_at, usually with no visible change.	The whole register. The Chinese register has about 95 million records.
Processing change. Pinakel improves how source data is mapped or normalized.	Records processed after the change are published again, some with changed values such as name_key.	Up to every record in the affected registers, spread over the following update runs.
Normal churn in large registers.	Many records change every day. The United States register changes daily in large numbers.	Thousands to hundreds of thousands per day.

Large republishes are spread over several update runs, so a burst can last hours or days.

To absorb bursts:

• upsert by id, so a repeated record overwrites itself;
• compare the fields you care about with your stored copy before raising a docket event or an alert, and ignore changes to updated_at alone;
• process feed pages in a queue rather than in the request path of your own users;
• keep following the cursor; there is nothing to reset after a burst.

​

Reloads

While a register is reloading:

• its state in GET /v1/jurisdictions is reloading;
• searches skip it and list it in unavailable_jurisdictions;
• retrieving one of its records gets 503 jurisdiction-unavailable, with Retry-After of at least 900 seconds, and batch requests list its ids under unavailable;
• a feed request naming only reloading registers gets the same 503; a wider feed request lists them in unavailable_jurisdictions and continues with the others.

Your stored feed cursor stays valid. When the reload finishes, the register’s changes, including the republished records, flow through the feed in order.

​

Removals

In v1, records the office removes are not announced in the feed. The type trademark.removed is reserved for this and will be added in a later version; ignore change types you do not know.

Until then, verify the records you depend on from time to time: a batch retrieve of your ids lists missing ones under not_found.

​

Not a history

The API serves the current state of each record. It does not keep earlier versions, and the feed is not an event log of the office: if a record changes twice between your polls, the feed item carries the latest state. If you need history, store the versions you receive.