Getting started

The Renewr External API v2 is a REST API for managing patent annuity renewals: it exposes your patent portfolio, the renewal events falling due, the fees attached to them, and the invoices and receipts that prove payment. You integrate it to read data into your IPMS, decide the fate of each annuity, and reconcile billing, all under your own tenant, isolated by your API key.

With it you can:

• Browse your portfolio: patents and their renewal events. See Syncing data.
• Drive the monthly renewal cycle: list what falls due, send instructions (PROCEED, SKIP_THIS_TIME, DROP). See Monthly renewal cycle and Instructions.
• Track fees and freeze exchange rates for price certainty. See Fees and FX.
• Download proof documents (invoices, instruction receipts, official receipts) as PDF. See Downloading documents.
• Reconcile invoices against events and patents. See the invoice list reference.

Prerequisites

You need an API key issued by the Renewr team. It is a 64-character hexadecimal string that carries everything about your access: your tenant (so no client identifier ever appears in URLs or payloads), your granted scopes, and an expiry date. Keep it server-side and treat it like a password. Details in Authentication.

Base URL

All v2 endpoints live under the /api/v2/external prefix:

https://api.renewr.example/api/v2/external

Your first call

List two patents from your portfolio with GET /patents:

curl "https://api.renewr.example/api/v2/external/patents?itemsPerPage=2" \
  -H "x-api-key: $RENEWR_API_KEY"

A 200 response wraps the page in the standard list envelope:

{
  "pagination": {
    "totalItems": 128,
    "currentPage": 1,
    "itemsPerPage": 2,
    "totalPages": 64,
    "hasMore": true
  },
  "data": [
    {
      "object": "patent",
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "providerId": "ACME-2021-0042",
      "clientCaseReference": "P-2021-0042-EP",
      "title": "Heat exchanger with corrugated fins",
      "office": "EP",
      "applicationNumber": "21305432.1",
      "applicationDate": "2021-04-02",
      "publicationNumber": "EP3891234A1",
      "status": "GRANTED"
      // ... fields truncated for brevity; see the reference for the full schema
    },
    {
      "object": "patent",
      "id": "550e8400-e29b-41d4-a716-446655440000"
      // ...
    }
  ]
}

Rate limit headers

Every authenticated response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers, plus an X-Request-Id you should log for support. See Conventions.

Understand what you are looking at

• A patent is your read-only view of one IP right in your portfolio: bibliographic data, dates, status, office. You never create or edit patents through the API. Renewr keeps them in sync. See Lifecycle.
• Each patent has events: dated obligations, today always eventType: "RENEWAL" (one annuity falling due, e.g. annuity year 5). Events are what you instruct and pay for. Read them per patent with GET /patents/{patentId}/events or across the portfolio with GET /patent-events. See Events and due periods.
• id vs providerId: id is the opaque, stable Renewr UUID and the only identifier used in URL paths. providerId is your own reference, set at import; use ?providerId= on GET /patents to match by it (an unknown value returns an empty page, never a 404). Wherever an event or fee line points at its patent, both keys travel together as patent: { id, providerId }.

Next steps

1. The Cookbook: ready-made recipes phrased as questions ("I want an estimate for the next three months, how?").
2. Monthly renewal cycle: the workhorse integration. List what falls due with GET /patent-events, then instruct with POST /patent-instructions.
3. Conventions: pagination, sorting, date formats, decimal-string amounts, enums.
4. Errors: the application/problem+json envelope and every stable error code.
5. The API reference: start at GET /patents for full request and response schemas.

Migrating from v1? See the v1 to v2 migration guide. Unsure about a term? Check the glossary.