Synchronize your IPMS

Every recipe on this page revolves around POST /patents/sync and its polling companion GET /patents/sync/{importId}. One model runs through all of them: each pushed item is triaged independently, safe changes apply immediately, and deadline-shaping changes wait for a Renewr reviewer. The background is in Pushing your portfolio and Change requests & review.

I want to push my whole portfolio into Renewr. How?

First portfolio load? Go through the Renewr team, not the API

For the very first import of a portfolio, the recommended route is an export from your IPMS handed to the Renewr team: operators load and check it as part of onboarding. Every creation pushed through the API goes to review, so a full first push would queue your entire portfolio for one-by-one manual acceptance; the operator import gets you to the same state faster, and the data is checked along the way. Use the API push for everything that follows, starting with daily deltas.

The recipe below stays valid when agreed with the Renewr team (a small portfolio, a tenant already onboarded). Export your patents with the v2 field names (the same ones you read back from GET /patents), give each item your own reference as providerId, and send everything in one POST:

curl -X POST "https://api.renewr.example/api/v2/external/patents/sync" \
  -H "x-api-key: $RENEWR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @full-portfolio.json

where full-portfolio.json holds one item per patent:

{
  "externalImportRef": "initial-import-2026-08-07",
  "items": [
    {
      "providerId": "ACME-2019-0007",
      "office": "FR",
      "patentType": "PATENT",
      "filingRoute": "NATIONAL",
      "status": "GRANTED",
      "title": "Modular battery pack housing",
      "applicationNumber": "FR1902345",
      "applicationDate": "2019-03-12",
      "grantDate": "2022-06-01",
      "renewalsManagedFrom": "2019-03-12"
    }
  ]
}

There is no size limit. Above 100 items the answer is a 202 with an importId and the batch is processed in the background; poll it. Items matching an existing patent (by providerId) become updates; unknown references propose creations, and creations always go to review, so a first-time import of a fresh tenant will land almost entirely in STAGED and come back ACCEPTED as reviewers process it. A creation must carry at least office, patentType, applicationDate and applicationNumber (renewalsManagedFrom is derived when omitted; send it whenever your IPMS knows it).

I want to push what changed since yesterday. How?

Send the patents that changed. The simplest item shape is the full record: Renewr diffs each item against the live patent and ignores fields that did not actually change, so re-sending unchanged data costs nothing. If your IPMS tracks changes per field, a partial item (the changed fields plus the identity) works too; it is an option, not a requirement:

curl -X POST "https://api.renewr.example/api/v2/external/patents/sync" \
  -H "x-api-key: $RENEWR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalImportRef": "delta-2026-08-07-nightly",
    "items": [
      { "providerId": "ACME-2021-0042", "title": "Heat exchanger with corrugated fins (amended claims)" },
      { "providerId": "ACME-2020-0113", "status": "GRANTED", "grantDate": "2026-07-30" }
    ]
  }'

An omitted field leaves the live value untouched, which is what makes partial items safe. Up to 100 items the 201 response carries every outcome inline: here the title change reads APPLIED immediately, while the grant (a critical change) reads STAGED.

I want to know what happened to each record I pushed. How?

Poll the batch with the importId from the POST response, walking the result pages:

curl "https://api.renewr.example/api/v2/external/patents/sync/$IMPORT_ID?currentPage=1&itemsPerPage=100" \
  -H "x-api-key: $RENEWR_API_KEY"

Read it in this order:

1. status first: PENDING / PROCESSING means keep polling (a few seconds apart). TRIAGED or SETTLED means every item has an outcome.
2. The counters for the shape of the result: autoAppliedItems, stagedItems, rejectedItems, suppressedItems.
3. results.data[] for the per-item verdicts, in the exact order of your POST body: outcome, the reason when rejected or suppressed, and requestId to quote if you contact support.

Outcomes are per item and independent; a REJECTED at index 3 says nothing about index 4. Log rejected reasons into your own error channel: they name the field and the problem (Invalid item: grantDate: …, Forbidden field: version, no identity provided …).

A change I pushed is APPLIED but I want to see it. Where?

In the normal read model, immediately: re-fetch the patent with GET /patents?providerId=… or GET /patents/{patentId} and the applied values are there. If the change touched a critical field through review, remember the renewal events may have been recomputed as a consequence; a window refresh picks that up.

A change I pushed is STAGED. What now?

Nothing to fix: the change awaits a Renewr reviewer, the live patent keeps serving its current values, and your integration can move on. Re-poll the batch later (hours, or the next sync run, on human time):

• The item flips to ACCEPTED once applied. For a created patent, the result row now carries the new renewrPatentId; store it against your record.
• Or it flips to REJECTED with the reviewer's reason, verbatim. See the next recipe.

If you push again while an item is staged, your newer proposal replaces the older one in the review queue ("newer wins"); the old batch keeps showing STAGED for that item forever, so treat the latest batch as the authoritative view. See Change requests & review.

A proposal was refused. How do I fix it?

Read the reason on the rejected item: it is the reviewer's explanation, written for you. Then correct the data in your IPMS and let the next export push the corrected record. It fingerprints as a new proposal and goes to review normally.

What does not work: re-pushing the same refused change unchanged. The item comes back SUPPRESSED (the anti-spam filter recognizes the fingerprint), no reviewer sees it, and it will keep coming back SUPPRESSED until the data actually changes. A scheduled exporter that re-exports its full state does not need any special handling for this: the suppressed outcome is harmless and disappears once the source data is fixed.

My push timed out. How do I retry safely?

Re-send the same externalImportRef with the same items:

curl -X POST "https://api.renewr.example/api/v2/external/patents/sync" \
  -H "x-api-key: $RENEWR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @same-payload-as-before.json

If the first POST got through, the retry is a replay: you receive the state of the existing batch (202 if still running, 201 otherwise) and nothing is imported twice. If it never arrived, the retry is simply the first import. Either way you end with exactly one batch, which is why the reference should identify the export run (a job id, a snapshot label) and never be minted fresh per HTTP attempt.

A 409 with code conflict on this path means the same reference was already used with different items; the body's existingBatchId points at the earlier batch. Mint a new reference for new content instead of reusing old ones. See Errors.