Skip to content

List patent offices and their requirements ​

GET /api/v2/external/patent-offices

Authentication: x-api-key header, with the patents:read scope. See Authentication and limits.

Paginated list of the patent offices Renewr manages, each with the fields it requires before a patent can be managed (requiredFields) and the fields whose change on an existing patent is staged for review (stagedFields). Office-code order by default; sort with ?sort=office (ascending) or ?sort=-office (descending). Unknown sort fields are rejected with 400.

Query parameters ​

NameTypeRequiredDescription
itemsPerPagenumberNoNumber of items per page. Default 10; values above 100 are silently clamped to 100 (hard server cap, spec §6.1).
currentPagenumberNoCurrent page (1-based). Offset pagination: a page can shift if the collection mutates between calls; re-fetch from page 1 for a consistent sweep.
sortstringNoSort field expressed as field (ASC) or -field (DESC). Allowed fields: office.

Response ​

200 A page of patent offices with the standard v2 list envelope { pagination, data }.

json
{
  "pagination": {
    "totalItems": 128,
    "currentPage": 1,
    "itemsPerPage": 10,
    "totalPages": 13,
    "hasMore": true
  },
  "data": [
    {
      "object": "patentOffice",
      "office": "EP",
      "requiredFields": [
        "office",
        "patentType",
        "filingRoute",
        "applicationNumber",
        "applicationDate",
        "applicantType"
      ],
      "stagedFields": [
        "office",
        "filingRoute",
        "patentType",
        "status",
        "applicationDate",
        "publicationDate",
        "grantDate",
        "lapseDate",
        "expirationDate",
        "extendedExpirationDate",
        "nationalPhaseEntryDate",
        "renewalsManagedFrom",
        "applicationNumber",
        "publicationNumber",
        "grantPublicationNumber",
        "pctApplicationNumber"
      ]
    }
  ]
}
Response fields
FieldTypeDescription
paginationobjectPagination metadata.
pagination.totalItemsintegerTotal number of items across all pages.
pagination.currentPageinteger1-based index of the current page.
pagination.itemsPerPageintegerNumber of items per page (server cap: 100).
pagination.totalPagesintegerTotal number of pages.
pagination.hasMorebooleanTrue when another page exists after the current one.
dataarray of objectsPage of results.
data[].objectstringString describing the object type (auto-description). One of: patentOffice.
data[].officestringPatent office / authority code (WO, EP, EA, or an ISO 3166-1 national office code).
data[].requiredFieldsarray of stringFields this office needs before a patent can be managed. Declarative: a creation is rejected only when it lacks office, patentType, applicationNumber or applicationDate; any other listed field may be missing, the item is still accepted and staged, and the reviewer completes it.
data[].stagedFieldsarray of stringFields whose change on an existing patent is staged for review instead of being applied. Applies to updates only: a creation is always staged. The four patent numbers (applicationNumber, publicationNumber, grantPublicationNumber, pctApplicationNumber) are always in this list.

Errors ​

Errors use the application/problem+json envelope with stable machine-readable codes. See the Errors guide.

StatusDescription
400Validation failed (validation_failed): carries per-field errors[] with RFC 6901 JSON Pointers.
401Missing or invalid API key (invalid_api_key), or expired key (api_key_expired).
403API key lacks the required scope (insufficient_scope, with requiredScope extension) or the operation is not enabled for this client (forbidden).
429Daily API call limit exceeded (rate_limit_exceeded): the Retry-After header gives the seconds until reset.

Example request ​

bash
curl "https://api.renewr.example/api/v2/external/patent-offices?itemsPerPage=50" \
  -H "x-api-key: $RENEWR_API_KEY"

Renewr External API v2. Access on invitation.