{ "openapi": "3.0.0", "paths": { "/api/v2/external/patents": { "get": { "operationId": "getPatents", "summary": "List patents (v2)", "description": "Paginated list of the patents owned by the authenticated client. Use **itemsPerPage** and **currentPage** for pagination (server cap: 100 / page). Filter by your own reference with **?providerId=** (exact match). Sort with **?sort=field** (ascending) or **?sort=-field** (descending) over the external field names `clientCaseReference`, `office`, `applicationDate`, `publicationNumber`, `status` (unknown fields are rejected with 400).", "parameters": [ { "name": "itemsPerPage", "required": false, "in": "query", "description": "Number of items per page.", "example": 10, "schema": { "type": "number" } }, { "name": "currentPage", "required": false, "in": "query", "description": "Current page.", "example": 1, "schema": { "type": "number" } }, { "name": "sort", "required": false, "in": "query", "description": "Sort field expressed as `field` (ASC) or `-field` (DESC). Allowed fields: clientCaseReference, office, applicationDate, publicationNumber, status.", "schema": { "type": "string" } }, { "name": "providerId", "required": false, "in": "query", "description": "Exact-match filter on your own client-side reference (provider id). Returns at most one patent.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of patents with the standard v2 list envelope `{ pagination, data }`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatentV2ListSchemaForExternalApiResponse" } } } }, "400": { "description": "Validation failed (`validation_failed`): carries per-field `errors[]` with RFC 6901 JSON Pointers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Missing or invalid API key (`invalid_api_key`), or expired key (`api_key_expired`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "API key lacks the required scope (`insufficient_scope`, with `requiredScope` extension) or the operation is not enabled for this client (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Daily API call limit exceeded (`rate_limit_exceeded`): the `Retry-After` header gives the seconds until reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "tags": [ "Patents (v2)" ], "security": [ { "JWT-auth": [] }, { "x-api-key": [] } ] } }, "/api/v2/external/patents/{patentId}": { "get": { "operationId": "getPatent", "summary": "Get a patent (v2)", "description": "Returns a single patent owned by the authenticated client, identified by its opaque Renewr UUID. To look a patent up by your own reference, use the list endpoint with `?providerId=`.", "parameters": [ { "name": "patentId", "required": true, "in": "path", "description": "The opaque, stable Renewr UUID of the patent.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The patent matching the provided UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatentV2SchemaForExternalApiResponse" } } } }, "400": { "description": "Validation failed (`validation_failed`): carries per-field `errors[]` with RFC 6901 JSON Pointers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Missing or invalid API key (`invalid_api_key`), or expired key (`api_key_expired`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "API key lacks the required scope (`insufficient_scope`, with `requiredScope` extension) or the operation is not enabled for this client (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "The resource does not exist in your portfolio (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Daily API call limit exceeded (`rate_limit_exceeded`): the `Retry-After` header gives the seconds until reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "tags": [ "Patents (v2)" ], "security": [ { "JWT-auth": [] }, { "x-api-key": [] } ] } }, "/api/v2/external/patents/{patentId}/events": { "get": { "operationId": "getPatentEvents", "summary": "List the events of a patent (v2)", "description": "Returns the events (renewals / annuities) of a single patent, identified by its Renewr UUID.", "parameters": [ { "name": "patentId", "required": true, "in": "path", "description": "The opaque, stable Renewr UUID of the patent.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The events of the patent.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PatentEventV2SchemaForExternalApiResponse" } } } } }, "400": { "description": "Validation failed (`validation_failed`): carries per-field `errors[]` with RFC 6901 JSON Pointers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Missing or invalid API key (`invalid_api_key`), or expired key (`api_key_expired`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "API key lacks the required scope (`insufficient_scope`, with `requiredScope` extension) or the operation is not enabled for this client (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "The resource does not exist in your portfolio (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Daily API call limit exceeded (`rate_limit_exceeded`): the `Retry-After` header gives the seconds until reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "tags": [ "Patents (v2)" ], "security": [ { "JWT-auth": [] }, { "x-api-key": [] } ] } }, "/api/v2/external/patents/{patentId}/events/{eventId}": { "get": { "operationId": "getPatentEvent", "summary": "Get a patent event (v2)", "description": "Returns a single event of a patent, identified by the patent UUID and the event UUID.", "parameters": [ { "name": "eventId", "required": true, "in": "path", "description": "The opaque, stable Renewr UUID of the patent event.", "schema": { "type": "string" } }, { "name": "patentId", "required": true, "in": "path", "description": "The opaque, stable Renewr UUID of the patent.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The event matching the provided UUIDs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatentEventV2SchemaForExternalApiResponse" } } } }, "400": { "description": "Validation failed (`validation_failed`): carries per-field `errors[]` with RFC 6901 JSON Pointers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Missing or invalid API key (`invalid_api_key`), or expired key (`api_key_expired`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "API key lacks the required scope (`insufficient_scope`, with `requiredScope` extension) or the operation is not enabled for this client (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "The resource does not exist in your portfolio (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Daily API call limit exceeded (`rate_limit_exceeded`): the `Retry-After` header gives the seconds until reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "tags": [ "Patents (v2)" ], "security": [ { "JWT-auth": [] }, { "x-api-key": [] } ] } }, "/api/v2/external/patents/{patentId}/events/{eventId}/fees": { "get": { "operationId": "getPatentEventFees", "summary": "Get the fees of a patent event (v2)", "description": "Returns the fee breakdown of an event (office, agent, Renewr, grace period), all amounts in the invoice currency as decimal strings. Unified estimated|invoiced: while no invoice exists the response carries the projected amounts (`feesStatus: ESTIMATED`, `invoiceId: null`); once invoiced it carries the billed amounts (`feesStatus: INVOICED`).", "parameters": [ { "name": "eventId", "required": true, "in": "path", "description": "The opaque, stable Renewr UUID of the patent event.", "schema": { "type": "string" } }, { "name": "patentId", "required": true, "in": "path", "description": "The opaque, stable Renewr UUID of the patent.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The fee breakdown of the event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatentFeesV2SchemaForExternalApiResponse" } } } }, "400": { "description": "Validation failed (`validation_failed`): carries per-field `errors[]` with RFC 6901 JSON Pointers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Missing or invalid API key (`invalid_api_key`), or expired key (`api_key_expired`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "API key lacks the required scope (`insufficient_scope`, with `requiredScope` extension) or the operation is not enabled for this client (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "The resource does not exist in your portfolio (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Daily API call limit exceeded (`rate_limit_exceeded`): the `Retry-After` header gives the seconds until reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "tags": [ "Patents (v2)" ], "security": [ { "JWT-auth": [] }, { "x-api-key": [] } ] } }, "/api/v2/external/patent-events": { "get": { "operationId": "getPatentEventsByPeriod", "summary": "List patent events by due period (v2)", "description": "Cross-portfolio, paginated list of patent events due within a window. Provide the window via `dueFrom`+`dueTo` (YYYY-MM-DD) or the `dueMonth` (YYYY-MM) shortcut. Optional filters: `offices`, `owners`, `family`, `eventTypes` (business kind: `RENEWAL` is the only kind today). `include=fees` surfaces the **estimated** fee breakdown on each event. Fuses the legacy `/patent-event/{year}/{month}` and `/estimation` endpoints.", "parameters": [ { "name": "include", "required": false, "in": "query", "description": "Comma-separated; `fees` adds the estimated fee breakdown to each event.", "schema": { "type": "string" } }, { "name": "eventTypes", "required": false, "in": "query", "description": "Business-kind filter (repeatable). RENEWAL is the only kind today: pass it to pin renewals-only ahead of future kinds.", "schema": { "type": "array" } }, { "name": "family", "required": false, "in": "query", "description": "Family filter.", "schema": { "type": "array" } }, { "name": "owners", "required": false, "in": "query", "description": "Owner filter.", "schema": { "type": "array" } }, { "name": "offices", "required": false, "in": "query", "description": "Patent office / authority filter (WO, EP, EA, or national codes).", "schema": { "type": "array" } }, { "name": "dueMonth", "required": false, "in": "query", "description": "Shortcut for a whole month (YYYY-MM).", "schema": { "type": "string" } }, { "name": "dueTo", "required": false, "in": "query", "description": "Window end, inclusive (YYYY-MM-DD).", "schema": { "type": "string" } }, { "name": "dueFrom", "required": false, "in": "query", "description": "Window start, inclusive (YYYY-MM-DD).", "schema": { "type": "string" } }, { "name": "itemsPerPage", "required": false, "in": "query", "description": "Number of items per page.", "example": 10, "schema": { "type": "number" } }, { "name": "currentPage", "required": false, "in": "query", "description": "Current page.", "example": 1, "schema": { "type": "number" } } ], "responses": { "200": { "description": "A page of patent events with the standard v2 list envelope `{ pagination, data }`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatentEventV2ListSchemaForExternalApiResponse" } } } }, "400": { "description": "Validation failed (`validation_failed`): carries per-field `errors[]` with RFC 6901 JSON Pointers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Missing or invalid API key (`invalid_api_key`), or expired key (`api_key_expired`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "API key lacks the required scope (`insufficient_scope`, with `requiredScope` extension) or the operation is not enabled for this client (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Daily API call limit exceeded (`rate_limit_exceeded`): the `Retry-After` header gives the seconds until reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "tags": [ "Patent events (v2)" ], "security": [ { "JWT-auth": [] }, { "x-api-key": [] } ] } }, "/api/v2/external/patent-instructions": { "post": { "operationId": "postPatentInstructions", "summary": "Create patent instructions (v2)", "description": "Applies one decision per patent event (`PROCEED`, `SKIP_THIS_TIME` or `DROP`) and returns the instruction receipt. Execution is immediate and synchronous (DIRECT mode); an executed instruction cannot be modified through the external API. A batch may span several patents, with one event per patent (the chronologically earliest un-instructed one).", "parameters": [], "requestBody": { "required": true, "description": "The instructions to apply, one per patent event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatentInstructionsV2Request" } } } }, "responses": { "201": { "description": "The instruction receipt created for the submitted patent events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstructionReceiptV2SchemaForExternalApiResponse" } } } }, "400": { "description": "Validation failed (`validation_failed`): carries per-field `errors[]` with RFC 6901 JSON Pointers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Missing or invalid API key (`invalid_api_key`), or expired key (`api_key_expired`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "API key lacks the required scope (`insufficient_scope`, with `requiredScope` extension) or the operation is not enabled for this client (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "The resource does not exist in your portfolio (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "The event already carries an executed instruction (`instruction_already_set`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "The instruction cannot be applied (`instruction_too_early`, `instruction_skipped`, `instruction_lapsed`, ...).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Daily API call limit exceeded (`rate_limit_exceeded`): the `Retry-After` header gives the seconds until reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "tags": [ "Patent instructions (v2)" ], "security": [ { "x-api-key": [] } ] } }, "/api/v2/external/exchange-rate-freezes": { "get": { "operationId": "getExchangeRateFreezes", "summary": "List frozen months (v2)", "description": "Returns the months (YYYY-MM) for which the client has frozen exchange rates.", "parameters": [], "responses": { "200": { "description": "The frozen months.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExchangeRateFreezeRefV2SchemaForExternalApiResponse" } } } } }, "401": { "description": "Missing or invalid API key (`invalid_api_key`), or expired key (`api_key_expired`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "API key lacks the required scope (`insufficient_scope`, with `requiredScope` extension) or the operation is not enabled for this client (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Daily API call limit exceeded (`rate_limit_exceeded`): the `Retry-After` header gives the seconds until reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "tags": [ "Exchange rate freezes (v2)" ], "security": [ { "x-api-key": [] }, { "JWT-auth": [] }, { "x-api-key": [] } ] } }, "/api/v2/external/exchange-rate-freezes/{yearMonth}": { "get": { "operationId": "getExchangeRateFreeze", "summary": "Get a month freeze (v2)", "description": "Returns the renewal events affected by the freeze of the given month, with their (potential) frozen fees.", "parameters": [ { "name": "yearMonth", "required": true, "in": "path", "description": "Target month, YYYY-MM.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The freeze of the month.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeRateFreezeV2SchemaForExternalApiResponse" } } } }, "400": { "description": "Validation failed (`validation_failed`): carries per-field `errors[]` with RFC 6901 JSON Pointers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Missing or invalid API key (`invalid_api_key`), or expired key (`api_key_expired`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "API key lacks the required scope (`insufficient_scope`, with `requiredScope` extension) or the operation is not enabled for this client (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Daily API call limit exceeded (`rate_limit_exceeded`): the `Retry-After` header gives the seconds until reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "tags": [ "Exchange rate freezes (v2)" ], "security": [ { "x-api-key": [] }, { "JWT-auth": [] }, { "x-api-key": [] } ] }, "put": { "operationId": "putExchangeRateFreeze", "summary": "Freeze a month (idempotent) (v2)", "description": "Freezes the exchange rates for the given month and returns the affected renewal events. Idempotent.", "parameters": [ { "name": "yearMonth", "required": true, "in": "path", "description": "Target month, YYYY-MM.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The freeze of the month.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeRateFreezeV2SchemaForExternalApiResponse" } } } }, "400": { "description": "Validation failed (`validation_failed`): carries per-field `errors[]` with RFC 6901 JSON Pointers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Missing or invalid API key (`invalid_api_key`), or expired key (`api_key_expired`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "API key lacks the required scope (`insufficient_scope`, with `requiredScope` extension) or the operation is not enabled for this client (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Daily API call limit exceeded (`rate_limit_exceeded`): the `Retry-After` header gives the seconds until reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "tags": [ "Exchange rate freezes (v2)" ], "security": [ { "x-api-key": [] }, { "JWT-auth": [] }, { "x-api-key": [] } ] } }, "/api/v2/external/invoices": { "get": { "operationId": "getInvoices", "summary": "List invoices (v2)", "description": "Paginated, unified list of the invoices owned by the authenticated client. Each invoice carries an `origin` (GENERATED | IMPORTED | REGULARIZATION). This endpoint returns patent invoices (`ipRightType=PATENT`). Use **itemsPerPage** and **currentPage** for pagination (server cap: 100 / page).", "parameters": [ { "name": "itemsPerPage", "required": false, "in": "query", "description": "Number of items per page.", "example": 10, "schema": { "type": "number" } }, { "name": "currentPage", "required": false, "in": "query", "description": "Current page.", "example": 1, "schema": { "type": "number" } } ], "responses": { "200": { "description": "A page of invoices with the standard v2 list envelope `{ pagination, data }`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceV2ListSchemaForExternalApiResponse" } } } }, "401": { "description": "Missing or invalid API key (`invalid_api_key`), or expired key (`api_key_expired`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "API key lacks the required scope (`insufficient_scope`, with `requiredScope` extension) or the operation is not enabled for this client (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Daily API call limit exceeded (`rate_limit_exceeded`): the `Retry-After` header gives the seconds until reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "tags": [ "Invoices (v2)" ], "security": [ { "JWT-auth": [] }, { "x-api-key": [] } ] } }, "/api/v2/external/invoices/{invoiceId}": { "get": { "operationId": "getInvoice", "summary": "Get an invoice (v2)", "description": "Returns a single patent invoice owned by the authenticated client, identified by its opaque Renewr UUID.", "parameters": [ { "name": "invoiceId", "required": true, "in": "path", "description": "The opaque, stable Renewr UUID of the invoice.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The invoice matching the provided UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceV2SchemaForExternalApiResponse" } } } }, "400": { "description": "Validation failed (`validation_failed`): carries per-field `errors[]` with RFC 6901 JSON Pointers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Missing or invalid API key (`invalid_api_key`), or expired key (`api_key_expired`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "API key lacks the required scope (`insufficient_scope`, with `requiredScope` extension) or the operation is not enabled for this client (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "The resource does not exist in your portfolio (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Daily API call limit exceeded (`rate_limit_exceeded`): the `Retry-After` header gives the seconds until reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "tags": [ "Invoices (v2)" ], "security": [ { "JWT-auth": [] }, { "x-api-key": [] } ] } }, "/api/v2/external/patents/{patentId}/events/{eventId}/documents/invoice": { "get": { "operationId": "getInvoiceDocument", "summary": "Download the invoice PDF of a patent event (v2)", "description": "Returns the invoice PDF for a patent event, identified by the patent UUID and the event UUID. Responds 404 until the event has been invoiced.", "parameters": [ { "name": "eventId", "required": true, "in": "path", "description": "The opaque, stable Renewr UUID of the patent event.", "schema": { "type": "string" } }, { "name": "patentId", "required": true, "in": "path", "description": "The opaque, stable Renewr UUID of the patent.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The invoice PDF file (attachment, RFC 6266 Content-Disposition).", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Validation failed (`validation_failed`): carries per-field `errors[]` with RFC 6901 JSON Pointers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Missing or invalid API key (`invalid_api_key`), or expired key (`api_key_expired`).", "content": { "application/pdf": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "API key lacks the required scope (`insufficient_scope`, with `requiredScope` extension) or the operation is not enabled for this client (`forbidden`).", "content": { "application/pdf": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "The resource does not exist in your portfolio (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Daily API call limit exceeded (`rate_limit_exceeded`): the `Retry-After` header gives the seconds until reset.", "content": { "application/pdf": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "tags": [ "Patents (v2)" ], "security": [ { "JWT-auth": [] }, { "x-api-key": [] } ] } }, "/api/v2/external/patents/{patentId}/events/{eventId}/documents/instruction-receipt": { "get": { "operationId": "getInstructionReceiptDocument", "summary": "Download the instruction receipt PDF of a patent event (v2)", "description": "Returns the instruction receipt PDF for a patent event, identified by the patent UUID and the event UUID. Responds 404 until an instruction receipt exists.", "parameters": [ { "name": "eventId", "required": true, "in": "path", "description": "The opaque, stable Renewr UUID of the patent event.", "schema": { "type": "string" } }, { "name": "patentId", "required": true, "in": "path", "description": "The opaque, stable Renewr UUID of the patent.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The instruction receipt PDF file (attachment, RFC 6266 Content-Disposition).", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Validation failed (`validation_failed`): carries per-field `errors[]` with RFC 6901 JSON Pointers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Missing or invalid API key (`invalid_api_key`), or expired key (`api_key_expired`).", "content": { "application/pdf": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "API key lacks the required scope (`insufficient_scope`, with `requiredScope` extension) or the operation is not enabled for this client (`forbidden`).", "content": { "application/pdf": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "The resource does not exist in your portfolio (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Daily API call limit exceeded (`rate_limit_exceeded`): the `Retry-After` header gives the seconds until reset.", "content": { "application/pdf": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "tags": [ "Patents (v2)" ], "security": [ { "JWT-auth": [] }, { "x-api-key": [] } ] } }, "/api/v2/external/patents/{patentId}/events/{eventId}/documents/official-receipt": { "get": { "operationId": "getOfficialReceiptDocument", "summary": "Download the official receipt PDF of a patent event (v2)", "description": "Returns the official receipt PDF for a patent event, identified by the patent UUID and the event UUID. Responds 404 until an official receipt exists.", "parameters": [ { "name": "eventId", "required": true, "in": "path", "description": "The opaque, stable Renewr UUID of the patent event.", "schema": { "type": "string" } }, { "name": "patentId", "required": true, "in": "path", "description": "The opaque, stable Renewr UUID of the patent.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The official receipt PDF file (attachment, RFC 6266 Content-Disposition).", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Validation failed (`validation_failed`): carries per-field `errors[]` with RFC 6901 JSON Pointers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Missing or invalid API key (`invalid_api_key`), or expired key (`api_key_expired`).", "content": { "application/pdf": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "API key lacks the required scope (`insufficient_scope`, with `requiredScope` extension) or the operation is not enabled for this client (`forbidden`).", "content": { "application/pdf": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "The resource does not exist in your portfolio (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Daily API call limit exceeded (`rate_limit_exceeded`): the `Retry-After` header gives the seconds until reset.", "content": { "application/pdf": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "tags": [ "Patents (v2)" ], "security": [ { "JWT-auth": [] }, { "x-api-key": [] } ] } } }, "info": { "title": "Renewr External API", "description": "Renewr external API v2: patents, renewal events, fees, instructions, invoices and exchange-rate freezes.", "version": "2.0", "contact": {} }, "tags": [], "servers": [], "components": { "securitySchemes": { "x-api-key": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key for external endpoints" } }, "schemas": { "ProblemResponse": { "description": "RFC 9457 problem+json error envelope (external API v2).", "type": "object", "properties": { "type": { "description": "A stable URI reference identifying the problem type, e.g. \"/errors/not-found\". Never a JS class name.", "type": "string" }, "title": { "description": "Short, human-readable summary of the problem type (stable per type).", "type": "string" }, "status": { "description": "The HTTP status code generated for this occurrence.", "type": "integer" }, "detail": { "description": "Human-readable, occurrence-specific explanation (localizable, free-form).", "type": "string" }, "instance": { "description": "A URI reference identifying the specific occurrence (typically the request path).", "type": "string" }, "code": { "description": "Stable, machine-readable error code. Distinct from the `type` URI; safe to switch on.", "type": "string", "enum": [ "validation_failed", "invalid_api_key", "api_key_expired", "insufficient_scope", "forbidden", "not_found", "rate_limit_exceeded", "internal_error", "instruction_already_set", "instruction_skipped", "instruction_too_early", "instruction_lapsed", "inconsistent_drop_chain", "invalid_designations", "missing_renewed_designations", "invalid_renewed_designations", "missing_required_documents" ] }, "requestId": { "description": "Correlation id, mirrors the X-Request-Id response header (spec ยง6.9).", "type": "string", "nullable": true }, "errors": { "description": "Field-level validation failures (present for `validation_failed`).", "type": "array", "items": { "description": "A single field-level validation error", "type": "object", "properties": { "pointer": { "description": "RFC 6901 JSON Pointer to the offending field, e.g. \"/instructions/0/eventId\"", "type": "string" }, "code": { "description": "Stable, machine-readable code for this specific field failure", "type": "string" }, "message": { "description": "Human-readable, localizable description of the field failure", "type": "string" } }, "required": [ "pointer", "code", "message" ] } } }, "required": [ "type", "title", "status", "code", "requestId" ] }, "PatentV2ListSchemaForExternalApiResponse": { "type": "object", "properties": { "pagination": { "description": "Pagination metadata", "type": "object", "properties": { "totalItems": { "description": "Total number of items across all pages", "type": "integer" }, "currentPage": { "description": "1-based index of the current page", "type": "integer" }, "itemsPerPage": { "description": "Number of items per page (server cap: 100)", "type": "integer" }, "totalPages": { "description": "Total number of pages", "type": "integer" }, "hasMore": { "description": "True when another page exists after the current one", "type": "boolean" } }, "required": [ "totalItems", "currentPage", "itemsPerPage", "totalPages", "hasMore" ] }, "data": { "description": "Page of results", "type": "array", "items": { "type": "object", "properties": { "object": { "description": "String describing the object type (auto-description)", "type": "string", "enum": [ "patent" ] }, "id": { "description": "Opaque, stable Renewr UUID of the patent", "type": "string", "format": "uuid" }, "providerId": { "description": "Client-provided matching reference; searchable via ?providerId=", "type": "string", "maxLength": 255, "nullable": true }, "clientCaseReference": { "description": "Case reference on the client side", "type": "string", "nullable": true }, "clientFamilyReference": { "description": "Family reference on the client side", "type": "string", "nullable": true }, "title": { "description": "Title of the patent", "type": "string", "nullable": true }, "office": { "description": "Patent office / authority code (WO, EP, EA, or an ISO 3166-1 national office code)", "type": "string" }, "patentType": { "description": "PATENT | UTILITY | DESIGN", "type": "string", "enum": [ "PATENT", "UTILITY", "DESIGN" ], "nullable": true }, "applicationNumber": { "description": "Application (filing) number: DOCDB aligned", "type": "string", "nullable": true }, "applicationDate": { "description": "ISO date string", "type": "string", "nullable": true }, "nationalPhaseEntryDate": { "description": "ISO date string", "type": "string", "nullable": true }, "priorityDate": { "description": "ISO date string", "type": "string", "nullable": true }, "publicationNumber": { "description": "Publication number", "type": "string", "nullable": true }, "publicationDate": { "description": "ISO date string", "type": "string", "nullable": true }, "grantPublicationNumber": { "description": "Grant publication number", "type": "string", "nullable": true }, "grantDate": { "description": "ISO date string", "type": "string", "nullable": true }, "pctApplicationNumber": { "description": "PCT application number", "type": "string", "nullable": true }, "expirationDate": { "description": "ISO date string", "type": "string", "nullable": true }, "extendedExpirationDate": { "description": "ISO date string", "type": "string", "nullable": true }, "lapseDate": { "description": "ISO date string", "type": "string", "nullable": true }, "renewalsManagedFrom": { "description": "ISO date string", "type": "string", "nullable": true }, "status": { "description": "Shared IP right status", "type": "string", "enum": [ "PENDING", "PUBLISHED", "GRANTED", "LAPSED" ], "nullable": true }, "filingRoute": { "description": "How the title was filed", "type": "string", "enum": [ "NATIONAL", "PCT", "EP", "EA", "DIVISIONAL" ], "nullable": true }, "applicantType": { "description": "MICRO | SMALL | LARGE", "type": "string", "enum": [ "MICRO", "SMALL", "LARGE" ], "nullable": true }, "claimCount": { "description": "Number of claims", "type": "integer", "nullable": true }, "designatedCountries": { "description": "ISO 3166-1 alpha-2 designations (EP/regional)", "type": "array", "items": { "type": "string" }, "nullable": true }, "owner": { "description": "Owner (display)", "type": "string", "nullable": true }, "secondaryOwners": { "description": "Co-owners", "type": "array", "items": { "type": "string" }, "nullable": true }, "subCase": { "description": "Sub-case", "type": "string", "nullable": true }, "createdAt": { "description": "ISO 8601 timestamp (UTC)", "type": "string", "format": "date-time", "nullable": true }, "updatedAt": { "description": "ISO 8601 timestamp (UTC)", "type": "string", "format": "date-time", "nullable": true } }, "required": [ "object", "id", "providerId", "clientCaseReference", "clientFamilyReference", "title", "office", "patentType", "applicationNumber", "applicationDate", "nationalPhaseEntryDate", "priorityDate", "publicationNumber", "publicationDate", "grantPublicationNumber", "grantDate", "pctApplicationNumber", "expirationDate", "extendedExpirationDate", "lapseDate", "renewalsManagedFrom", "status", "filingRoute", "applicantType", "claimCount", "designatedCountries", "owner", "secondaryOwners", "subCase", "createdAt", "updatedAt" ] } } }, "required": [ "pagination", "data" ] }, "PatentV2SchemaForExternalApiResponse": { "type": "object", "properties": { "object": { "description": "String describing the object type (auto-description)", "type": "string", "enum": [ "patent" ] }, "id": { "description": "Opaque, stable Renewr UUID of the patent", "type": "string", "format": "uuid" }, "providerId": { "description": "Client-provided matching reference; searchable via ?providerId=", "type": "string", "maxLength": 255, "nullable": true }, "clientCaseReference": { "description": "Case reference on the client side", "type": "string", "nullable": true }, "clientFamilyReference": { "description": "Family reference on the client side", "type": "string", "nullable": true }, "title": { "description": "Title of the patent", "type": "string", "nullable": true }, "office": { "description": "Patent office / authority code (WO, EP, EA, or an ISO 3166-1 national office code)", "type": "string" }, "patentType": { "description": "PATENT | UTILITY | DESIGN", "type": "string", "enum": [ "PATENT", "UTILITY", "DESIGN" ], "nullable": true }, "applicationNumber": { "description": "Application (filing) number: DOCDB aligned", "type": "string", "nullable": true }, "applicationDate": { "description": "ISO date string", "type": "string", "nullable": true }, "nationalPhaseEntryDate": { "description": "ISO date string", "type": "string", "nullable": true }, "priorityDate": { "description": "ISO date string", "type": "string", "nullable": true }, "publicationNumber": { "description": "Publication number", "type": "string", "nullable": true }, "publicationDate": { "description": "ISO date string", "type": "string", "nullable": true }, "grantPublicationNumber": { "description": "Grant publication number", "type": "string", "nullable": true }, "grantDate": { "description": "ISO date string", "type": "string", "nullable": true }, "pctApplicationNumber": { "description": "PCT application number", "type": "string", "nullable": true }, "expirationDate": { "description": "ISO date string", "type": "string", "nullable": true }, "extendedExpirationDate": { "description": "ISO date string", "type": "string", "nullable": true }, "lapseDate": { "description": "ISO date string", "type": "string", "nullable": true }, "renewalsManagedFrom": { "description": "ISO date string", "type": "string", "nullable": true }, "status": { "description": "Shared IP right status", "type": "string", "enum": [ "PENDING", "PUBLISHED", "GRANTED", "LAPSED" ], "nullable": true }, "filingRoute": { "description": "How the title was filed", "type": "string", "enum": [ "NATIONAL", "PCT", "EP", "EA", "DIVISIONAL" ], "nullable": true }, "applicantType": { "description": "MICRO | SMALL | LARGE", "type": "string", "enum": [ "MICRO", "SMALL", "LARGE" ], "nullable": true }, "claimCount": { "description": "Number of claims", "type": "integer", "nullable": true }, "designatedCountries": { "description": "ISO 3166-1 alpha-2 designations (EP/regional)", "type": "array", "items": { "type": "string" }, "nullable": true }, "owner": { "description": "Owner (display)", "type": "string", "nullable": true }, "secondaryOwners": { "description": "Co-owners", "type": "array", "items": { "type": "string" }, "nullable": true }, "subCase": { "description": "Sub-case", "type": "string", "nullable": true }, "createdAt": { "description": "ISO 8601 timestamp (UTC)", "type": "string", "format": "date-time", "nullable": true }, "updatedAt": { "description": "ISO 8601 timestamp (UTC)", "type": "string", "format": "date-time", "nullable": true } }, "required": [ "object", "id", "providerId", "clientCaseReference", "clientFamilyReference", "title", "office", "patentType", "applicationNumber", "applicationDate", "nationalPhaseEntryDate", "priorityDate", "publicationNumber", "publicationDate", "grantPublicationNumber", "grantDate", "pctApplicationNumber", "expirationDate", "extendedExpirationDate", "lapseDate", "renewalsManagedFrom", "status", "filingRoute", "applicantType", "claimCount", "designatedCountries", "owner", "secondaryOwners", "subCase", "createdAt", "updatedAt" ] }, "PatentEventV2SchemaForExternalApiResponse": { "type": "object", "properties": { "object": { "description": "String describing the object type (auto-description)", "type": "string", "enum": [ "patentEvent" ] }, "id": { "description": "Opaque, stable Renewr UUID of the patent event", "type": "string", "format": "uuid" }, "patent": { "description": "The patent this event belongs to: identified both ways (Renewr id + your own reference)", "type": "object", "properties": { "id": { "description": "Renewr UUID of the patent", "type": "string", "format": "uuid" }, "providerId": { "description": "The client's own matching reference for that patent", "type": "string", "nullable": true } }, "required": [ "id", "providerId" ] }, "eventType": { "description": "Business kind of the event: RENEWAL today; new kinds will be added over time (ignore events whose kind you do not handle)", "type": "string", "enum": [ "RENEWAL" ], "x-enumNames": [ "Renewal" ] }, "dueDate": { "description": "Due date of the event (renewal / annuity payment deadline)", "type": "string" }, "gracePeriodEndDate": { "description": "ISO date string", "type": "string", "nullable": true }, "renewal": { "description": "Renewal-specific identification: non-null exactly when eventType is RENEWAL (today: every event)", "type": "object", "properties": { "annuityYear": { "description": "Annuity year covered by the event", "type": "integer" }, "paymentSequenceNumber": { "description": "Office payment sequence number: present only when it differs from annuityYear", "type": "integer", "nullable": true } }, "required": [ "annuityYear", "paymentSequenceNumber" ], "nullable": true }, "appliedDecision": { "description": "PROCEED | SKIP_THIS_TIME | DROP: the instruction applied to this event", "type": "string", "enum": [ "PROCEED", "SKIP_THIS_TIME", "DROP" ], "nullable": true }, "duePeriod": { "description": "Period of the due date relative to now", "type": "string", "enum": [ "LATE", "GRACE_PERIOD", "CURRENT", "UPCOMING", "LAPSED" ], "nullable": true }, "processingStatus": { "description": "Processing status of the event", "type": "string", "enum": [ "NOT_INSTRUCTED", "INSTRUCTED", "PAYMENT_SENT", "PAYMENT_CONFIRMED", "FULFILLED", "UNPROCESSABLE" ], "x-enumNames": [ "NotInstructed", "Instructed", "PaymentSent", "PaymentConfirmed", "Fulfilled", "Unprocessable" ], "nullable": true }, "processingStatusUpdatedAt": { "description": "ISO 8601 timestamp (UTC)", "type": "string", "format": "date-time", "nullable": true }, "isFxRateFrozen": { "description": "True when the FX rate used to compute fees is frozen", "type": "boolean" }, "feesStatus": { "description": "ESTIMATED (projected) or INVOICED (an invoice exists)", "type": "string", "enum": [ "ESTIMATED", "INVOICED" ], "nullable": true }, "createdAt": { "description": "ISO 8601 timestamp (UTC)", "type": "string", "format": "date-time", "nullable": true }, "updatedAt": { "description": "ISO 8601 timestamp (UTC)", "type": "string", "format": "date-time", "nullable": true }, "fees": { "description": "Estimated fee breakdown for this event: present only when requested via include=fees", "type": "object", "properties": { "object": { "description": "String describing the object type (auto-description)", "type": "string", "enum": [ "fees" ] }, "invoiceId": { "description": "Back-reference to the invoice these fees belong to", "type": "string", "format": "uuid", "nullable": true }, "eventId": { "description": "Public UUID of the patent event these fees belong to (trace each fee line back to its event)", "type": "string", "format": "uuid", "nullable": true }, "patent": { "description": "The patent this fee line belongs to: identified both ways (Renewr id + your own reference)", "type": "object", "properties": { "id": { "description": "Renewr UUID of the patent", "type": "string", "format": "uuid", "nullable": true }, "providerId": { "description": "The client's own matching reference for that patent", "type": "string", "nullable": true } }, "required": [ "id", "providerId" ] }, "currency": { "description": "ISO 4217 currency code the client is invoiced in", "type": "string" }, "total": { "description": "Total of all components, in invoice currency (decimal string)", "type": "string", "nullable": true }, "components": { "description": "Per-type fee breakdown (Stripe fee_details style); a component that does not apply is absent (never null). Sums to `total`.", "type": "array", "items": { "type": "object", "properties": { "type": { "description": "OFFICE (national office) | AGENT (external agent) | RENEWR (service fee) | GRACE_PERIOD (late surcharge)", "type": "string", "enum": [ "OFFICE", "AGENT", "RENEWR", "GRACE_PERIOD" ], "x-enumNames": [ "Office", "Agent", "Renewr", "GracePeriod" ] }, "amount": { "description": "Amount of this component, in invoice currency (decimal string)", "type": "string" } }, "required": [ "type", "amount" ] } }, "feesStatus": { "description": "Whether these amounts are ESTIMATED (projected) or INVOICED (final: an invoice exists)", "type": "string", "enum": [ "ESTIMATED", "INVOICED" ] }, "isFxRateFrozen": { "description": "True when the FX rate used to compute these fees is frozen", "type": "boolean" } }, "required": [ "object", "invoiceId", "eventId", "patent", "currency", "total", "components", "feesStatus", "isFxRateFrozen" ] }, "instructability": { "description": "Instruction affordance: whether/how this event can be instructed right now", "type": "object", "properties": { "isAllowed": { "description": "Whether an instruction can be POSTed on this event right now", "type": "boolean" }, "allowedDecisions": { "description": "Valid decisions right now (empty when not allowed; a lapsed event drops PROCEED)", "type": "array", "items": { "type": "string", "enum": [ "PROCEED", "SKIP_THIS_TIME", "DROP" ] } }, "blockedReason": { "description": "Why an instruction is not allowed: ALREADY_INSTRUCTED | TOO_EARLY | EARLIER_EVENT_PENDING (null when allowed)", "type": "string", "enum": [ "ALREADY_INSTRUCTED", "TOO_EARLY", "EARLIER_EVENT_PENDING" ], "x-enumNames": [ "AlreadyInstructed", "TooEarly", "EarlierEventPending" ], "nullable": true }, "opensAt": { "description": "ISO date string", "type": "string", "nullable": true }, "mode": { "description": "How an instruction would be processed now: DIRECT executes immediately", "type": "string", "enum": [ "DIRECT" ], "x-enumNames": [ "Direct" ] } }, "required": [ "isAllowed", "allowedDecisions", "blockedReason", "opensAt", "mode" ] } }, "required": [ "object", "id", "patent", "eventType", "dueDate", "gracePeriodEndDate", "renewal", "appliedDecision", "duePeriod", "processingStatus", "processingStatusUpdatedAt", "isFxRateFrozen", "feesStatus", "createdAt", "updatedAt" ] }, "PatentFeesV2SchemaForExternalApiResponse": { "type": "object", "properties": { "object": { "description": "String describing the object type (auto-description)", "type": "string", "enum": [ "fees" ] }, "invoiceId": { "description": "Back-reference to the invoice these fees belong to", "type": "string", "format": "uuid", "nullable": true }, "eventId": { "description": "Public UUID of the patent event these fees belong to (trace each fee line back to its event)", "type": "string", "format": "uuid", "nullable": true }, "patent": { "description": "The patent this fee line belongs to: identified both ways (Renewr id + your own reference)", "type": "object", "properties": { "id": { "description": "Renewr UUID of the patent", "type": "string", "format": "uuid", "nullable": true }, "providerId": { "description": "The client's own matching reference for that patent", "type": "string", "nullable": true } }, "required": [ "id", "providerId" ] }, "currency": { "description": "ISO 4217 currency code the client is invoiced in", "type": "string" }, "total": { "description": "Total of all components, in invoice currency (decimal string)", "type": "string", "nullable": true }, "components": { "description": "Per-type fee breakdown (Stripe fee_details style); a component that does not apply is absent (never null). Sums to `total`.", "type": "array", "items": { "type": "object", "properties": { "type": { "description": "OFFICE (national office) | AGENT (external agent) | RENEWR (service fee) | GRACE_PERIOD (late surcharge)", "type": "string", "enum": [ "OFFICE", "AGENT", "RENEWR", "GRACE_PERIOD" ], "x-enumNames": [ "Office", "Agent", "Renewr", "GracePeriod" ] }, "amount": { "description": "Amount of this component, in invoice currency (decimal string)", "type": "string" } }, "required": [ "type", "amount" ] } }, "feesStatus": { "description": "Whether these amounts are ESTIMATED (projected) or INVOICED (final: an invoice exists)", "type": "string", "enum": [ "ESTIMATED", "INVOICED" ] }, "isFxRateFrozen": { "description": "True when the FX rate used to compute these fees is frozen", "type": "boolean" } }, "required": [ "object", "invoiceId", "eventId", "patent", "currency", "total", "components", "feesStatus", "isFxRateFrozen" ] }, "PatentEventV2ListSchemaForExternalApiResponse": { "type": "object", "properties": { "pagination": { "description": "Pagination metadata", "type": "object", "properties": { "totalItems": { "description": "Total number of items across all pages", "type": "integer" }, "currentPage": { "description": "1-based index of the current page", "type": "integer" }, "itemsPerPage": { "description": "Number of items per page (server cap: 100)", "type": "integer" }, "totalPages": { "description": "Total number of pages", "type": "integer" }, "hasMore": { "description": "True when another page exists after the current one", "type": "boolean" } }, "required": [ "totalItems", "currentPage", "itemsPerPage", "totalPages", "hasMore" ] }, "data": { "description": "Page of results", "type": "array", "items": { "type": "object", "properties": { "object": { "description": "String describing the object type (auto-description)", "type": "string", "enum": [ "patentEvent" ] }, "id": { "description": "Opaque, stable Renewr UUID of the patent event", "type": "string", "format": "uuid" }, "patent": { "description": "The patent this event belongs to: identified both ways (Renewr id + your own reference)", "type": "object", "properties": { "id": { "description": "Renewr UUID of the patent", "type": "string", "format": "uuid" }, "providerId": { "description": "The client's own matching reference for that patent", "type": "string", "nullable": true } }, "required": [ "id", "providerId" ] }, "eventType": { "description": "Business kind of the event: RENEWAL today; new kinds will be added over time (ignore events whose kind you do not handle)", "type": "string", "enum": [ "RENEWAL" ], "x-enumNames": [ "Renewal" ] }, "dueDate": { "description": "Due date of the event (renewal / annuity payment deadline)", "type": "string" }, "gracePeriodEndDate": { "description": "ISO date string", "type": "string", "nullable": true }, "renewal": { "description": "Renewal-specific identification: non-null exactly when eventType is RENEWAL (today: every event)", "type": "object", "properties": { "annuityYear": { "description": "Annuity year covered by the event", "type": "integer" }, "paymentSequenceNumber": { "description": "Office payment sequence number: present only when it differs from annuityYear", "type": "integer", "nullable": true } }, "required": [ "annuityYear", "paymentSequenceNumber" ], "nullable": true }, "appliedDecision": { "description": "PROCEED | SKIP_THIS_TIME | DROP: the instruction applied to this event", "type": "string", "enum": [ "PROCEED", "SKIP_THIS_TIME", "DROP" ], "nullable": true }, "duePeriod": { "description": "Period of the due date relative to now", "type": "string", "enum": [ "LATE", "GRACE_PERIOD", "CURRENT", "UPCOMING", "LAPSED" ], "nullable": true }, "processingStatus": { "description": "Processing status of the event", "type": "string", "enum": [ "NOT_INSTRUCTED", "INSTRUCTED", "PAYMENT_SENT", "PAYMENT_CONFIRMED", "FULFILLED", "UNPROCESSABLE" ], "x-enumNames": [ "NotInstructed", "Instructed", "PaymentSent", "PaymentConfirmed", "Fulfilled", "Unprocessable" ], "nullable": true }, "processingStatusUpdatedAt": { "description": "ISO 8601 timestamp (UTC)", "type": "string", "format": "date-time", "nullable": true }, "isFxRateFrozen": { "description": "True when the FX rate used to compute fees is frozen", "type": "boolean" }, "feesStatus": { "description": "ESTIMATED (projected) or INVOICED (an invoice exists)", "type": "string", "enum": [ "ESTIMATED", "INVOICED" ], "nullable": true }, "createdAt": { "description": "ISO 8601 timestamp (UTC)", "type": "string", "format": "date-time", "nullable": true }, "updatedAt": { "description": "ISO 8601 timestamp (UTC)", "type": "string", "format": "date-time", "nullable": true }, "fees": { "description": "Estimated fee breakdown for this event: present only when requested via include=fees", "type": "object", "properties": { "object": { "description": "String describing the object type (auto-description)", "type": "string", "enum": [ "fees" ] }, "invoiceId": { "description": "Back-reference to the invoice these fees belong to", "type": "string", "format": "uuid", "nullable": true }, "eventId": { "description": "Public UUID of the patent event these fees belong to (trace each fee line back to its event)", "type": "string", "format": "uuid", "nullable": true }, "patent": { "description": "The patent this fee line belongs to: identified both ways (Renewr id + your own reference)", "type": "object", "properties": { "id": { "description": "Renewr UUID of the patent", "type": "string", "format": "uuid", "nullable": true }, "providerId": { "description": "The client's own matching reference for that patent", "type": "string", "nullable": true } }, "required": [ "id", "providerId" ] }, "currency": { "description": "ISO 4217 currency code the client is invoiced in", "type": "string" }, "total": { "description": "Total of all components, in invoice currency (decimal string)", "type": "string", "nullable": true }, "components": { "description": "Per-type fee breakdown (Stripe fee_details style); a component that does not apply is absent (never null). Sums to `total`.", "type": "array", "items": { "type": "object", "properties": { "type": { "description": "OFFICE (national office) | AGENT (external agent) | RENEWR (service fee) | GRACE_PERIOD (late surcharge)", "type": "string", "enum": [ "OFFICE", "AGENT", "RENEWR", "GRACE_PERIOD" ], "x-enumNames": [ "Office", "Agent", "Renewr", "GracePeriod" ] }, "amount": { "description": "Amount of this component, in invoice currency (decimal string)", "type": "string" } }, "required": [ "type", "amount" ] } }, "feesStatus": { "description": "Whether these amounts are ESTIMATED (projected) or INVOICED (final: an invoice exists)", "type": "string", "enum": [ "ESTIMATED", "INVOICED" ] }, "isFxRateFrozen": { "description": "True when the FX rate used to compute these fees is frozen", "type": "boolean" } }, "required": [ "object", "invoiceId", "eventId", "patent", "currency", "total", "components", "feesStatus", "isFxRateFrozen" ] }, "instructability": { "description": "Instruction affordance: whether/how this event can be instructed right now", "type": "object", "properties": { "isAllowed": { "description": "Whether an instruction can be POSTed on this event right now", "type": "boolean" }, "allowedDecisions": { "description": "Valid decisions right now (empty when not allowed; a lapsed event drops PROCEED)", "type": "array", "items": { "type": "string", "enum": [ "PROCEED", "SKIP_THIS_TIME", "DROP" ] } }, "blockedReason": { "description": "Why an instruction is not allowed: ALREADY_INSTRUCTED | TOO_EARLY | EARLIER_EVENT_PENDING (null when allowed)", "type": "string", "enum": [ "ALREADY_INSTRUCTED", "TOO_EARLY", "EARLIER_EVENT_PENDING" ], "x-enumNames": [ "AlreadyInstructed", "TooEarly", "EarlierEventPending" ], "nullable": true }, "opensAt": { "description": "ISO date string", "type": "string", "nullable": true }, "mode": { "description": "How an instruction would be processed now: DIRECT executes immediately", "type": "string", "enum": [ "DIRECT" ], "x-enumNames": [ "Direct" ] } }, "required": [ "isAllowed", "allowedDecisions", "blockedReason", "opensAt", "mode" ] } }, "required": [ "object", "id", "patent", "eventType", "dueDate", "gracePeriodEndDate", "renewal", "appliedDecision", "duePeriod", "processingStatus", "processingStatusUpdatedAt", "isFxRateFrozen", "feesStatus", "createdAt", "updatedAt" ] } } }, "required": [ "pagination", "data" ] }, "PatentInstructionsV2Request": { "type": "object", "properties": { "instructions": { "description": "Instructions to apply, one per patent event", "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "eventId": { "description": "UUID of the patent event to instruct", "type": "string", "format": "uuid" }, "decision": { "description": "PROCEED | SKIP_THIS_TIME | DROP", "type": "string", "enum": [ "PROCEED", "SKIP_THIS_TIME", "DROP" ] } }, "required": [ "eventId", "decision" ] } } }, "required": [ "instructions" ] }, "InstructionReceiptV2SchemaForExternalApiResponse": { "type": "object", "properties": { "object": { "description": "String describing the object type (auto-description)", "type": "string", "enum": [ "instructionReceipt" ] }, "issueDate": { "description": "ISO date string", "type": "string", "nullable": true }, "reference": { "description": "Stable display reference of the receipt", "type": "string", "nullable": true }, "number": { "description": "Sequential receipt number", "type": "integer", "nullable": true }, "instructions": { "description": "Instructions carried by this receipt", "type": "array", "items": { "type": "object", "properties": { "object": { "description": "String describing the object type (auto-description)", "type": "string", "enum": [ "instruction" ] }, "id": { "description": "Opaque Renewr UUID of the instruction", "type": "string", "format": "uuid" }, "decision": { "description": "PROCEED | SKIP_THIS_TIME | DROP", "type": "string", "enum": [ "PROCEED", "SKIP_THIS_TIME", "DROP" ], "nullable": true }, "status": { "description": "Lifecycle status of the instruction", "type": "string", "enum": [ "PENDING", "SCHEDULED", "EXECUTED", "SUPERSEDED" ] }, "executedAt": { "description": "ISO 8601 timestamp (UTC)", "type": "string", "format": "date-time", "nullable": true }, "scheduledForExecutionAt": { "description": "ISO date string", "type": "string", "nullable": true }, "renewedDesignatedCountries": { "description": "WO designations to renew", "type": "array", "items": { "type": "string" }, "nullable": true }, "excludedDesignatedCountries": { "description": "WO designations to exclude", "type": "array", "items": { "type": "string" }, "nullable": true } }, "required": [ "object", "id", "decision", "status", "executedAt", "scheduledForExecutionAt", "renewedDesignatedCountries", "excludedDesignatedCountries" ] } } }, "required": [ "object", "issueDate", "reference", "number", "instructions" ] }, "ExchangeRateFreezeRefV2SchemaForExternalApiResponse": { "type": "object", "properties": { "object": { "description": "String describing the object type (auto-description)", "type": "string", "enum": [ "exchangeRateFreeze" ] }, "yearMonth": { "description": "Frozen month, YYYY-MM", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" } }, "required": [ "object", "yearMonth" ] }, "ExchangeRateFreezeV2SchemaForExternalApiResponse": { "type": "object", "properties": { "object": { "description": "String describing the object type (auto-description)", "type": "string", "enum": [ "exchangeRateFreeze" ] }, "yearMonth": { "description": "Frozen month, YYYY-MM", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" }, "events": { "description": "Renewal events affected by the freeze", "type": "array", "items": { "type": "object", "properties": { "object": { "description": "String describing the object type (auto-description)", "type": "string", "enum": [ "frozenRateEvent" ] }, "clientCaseReference": { "description": "Client case reference of the IP right", "type": "string", "nullable": true }, "dueDate": { "description": "Renewal / annuity due date of the event", "type": "string" }, "amount": { "description": "Total renewal fees in the event currency (decimal string)", "type": "string" }, "currency": { "description": "ISO 4217 currency code of the event", "type": "string" }, "isFxRateFrozen": { "description": "True when the FX rate for this event is frozen", "type": "boolean" }, "hasInstruction": { "description": "True when an instruction has already been given for this event", "type": "boolean" } }, "required": [ "object", "clientCaseReference", "dueDate", "amount", "currency", "isFxRateFrozen", "hasInstruction" ] } } }, "required": [ "object", "yearMonth", "events" ] }, "InvoiceV2ListSchemaForExternalApiResponse": { "type": "object", "properties": { "pagination": { "description": "Pagination metadata", "type": "object", "properties": { "totalItems": { "description": "Total number of items across all pages", "type": "integer" }, "currentPage": { "description": "1-based index of the current page", "type": "integer" }, "itemsPerPage": { "description": "Number of items per page (server cap: 100)", "type": "integer" }, "totalPages": { "description": "Total number of pages", "type": "integer" }, "hasMore": { "description": "True when another page exists after the current one", "type": "boolean" } }, "required": [ "totalItems", "currentPage", "itemsPerPage", "totalPages", "hasMore" ] }, "data": { "description": "Page of results", "type": "array", "items": { "type": "object", "properties": { "object": { "description": "String describing the object type (auto-description)", "type": "string", "enum": [ "invoice" ] }, "id": { "description": "Opaque, stable Renewr UUID of the invoice", "type": "string", "format": "uuid" }, "reference": { "description": "Stable, unique display reference (the only field guaranteed across all 3 origins)", "type": "string" }, "number": { "description": "Sequential invoice number; absent (null) for IMPORTED invoices", "type": "string", "nullable": true }, "issueDate": { "description": "ISO date string", "type": "string", "nullable": true }, "origin": { "description": "GENERATED | IMPORTED | REGULARIZATION", "type": "string", "enum": [ "GENERATED", "IMPORTED", "REGULARIZATION" ] }, "ipRightType": { "description": "PATENT | TRADEMARK: asset family discriminant", "type": "string", "enum": [ "PATENT", "TRADEMARK" ], "x-enumNames": [ "Patent", "Trademark" ] }, "currency": { "description": "ISO 4217 currency code the client is invoiced in", "type": "string" }, "vatRate": { "description": "VAT rate applied (non-monetary number, e.g. 0.2 for 20%)", "type": "number", "nullable": true }, "vatNumber": { "description": "VAT number on the invoice", "type": "string", "nullable": true }, "subtotalExcludingTax": { "description": "Subtotal before tax, in invoice currency (decimal string)", "type": "string", "nullable": true }, "totalIncludingTax": { "description": "Total including tax, in invoice currency (decimal string)", "type": "string", "nullable": true }, "hasPdfDocument": { "description": "True when a PDF document is available for this invoice", "type": "boolean" }, "hasXlsxDocument": { "description": "True when an XLSX document is available for this invoice", "type": "boolean" }, "fees": { "description": "Full per-component fee breakdown of the invoice", "type": "array", "items": { "type": "object", "properties": { "object": { "description": "String describing the object type (auto-description)", "type": "string", "enum": [ "fees" ] }, "invoiceId": { "description": "Back-reference to the invoice these fees belong to", "type": "string", "format": "uuid", "nullable": true }, "eventId": { "description": "Public UUID of the patent event these fees belong to (trace each fee line back to its event)", "type": "string", "format": "uuid", "nullable": true }, "patent": { "description": "The patent this fee line belongs to: identified both ways (Renewr id + your own reference)", "type": "object", "properties": { "id": { "description": "Renewr UUID of the patent", "type": "string", "format": "uuid", "nullable": true }, "providerId": { "description": "The client's own matching reference for that patent", "type": "string", "nullable": true } }, "required": [ "id", "providerId" ] }, "currency": { "description": "ISO 4217 currency code the client is invoiced in", "type": "string" }, "total": { "description": "Total of all components, in invoice currency (decimal string)", "type": "string", "nullable": true }, "components": { "description": "Per-type fee breakdown (Stripe fee_details style); a component that does not apply is absent (never null). Sums to `total`.", "type": "array", "items": { "type": "object", "properties": { "type": { "description": "OFFICE (national office) | AGENT (external agent) | RENEWR (service fee) | GRACE_PERIOD (late surcharge)", "type": "string", "enum": [ "OFFICE", "AGENT", "RENEWR", "GRACE_PERIOD" ], "x-enumNames": [ "Office", "Agent", "Renewr", "GracePeriod" ] }, "amount": { "description": "Amount of this component, in invoice currency (decimal string)", "type": "string" } }, "required": [ "type", "amount" ] } }, "feesStatus": { "description": "Whether these amounts are ESTIMATED (projected) or INVOICED (final: an invoice exists)", "type": "string", "enum": [ "ESTIMATED", "INVOICED" ] }, "isFxRateFrozen": { "description": "True when the FX rate used to compute these fees is frozen", "type": "boolean" } }, "required": [ "object", "invoiceId", "eventId", "patent", "currency", "total", "components", "feesStatus", "isFxRateFrozen" ] } }, "createdAt": { "description": "ISO 8601 timestamp (UTC)", "type": "string", "format": "date-time", "nullable": true }, "updatedAt": { "description": "ISO 8601 timestamp (UTC)", "type": "string", "format": "date-time", "nullable": true } }, "required": [ "object", "id", "reference", "number", "issueDate", "origin", "ipRightType", "currency", "vatRate", "vatNumber", "subtotalExcludingTax", "totalIncludingTax", "hasPdfDocument", "hasXlsxDocument", "fees", "createdAt", "updatedAt" ] } } }, "required": [ "pagination", "data" ] }, "InvoiceV2SchemaForExternalApiResponse": { "type": "object", "properties": { "object": { "description": "String describing the object type (auto-description)", "type": "string", "enum": [ "invoice" ] }, "id": { "description": "Opaque, stable Renewr UUID of the invoice", "type": "string", "format": "uuid" }, "reference": { "description": "Stable, unique display reference (the only field guaranteed across all 3 origins)", "type": "string" }, "number": { "description": "Sequential invoice number; absent (null) for IMPORTED invoices", "type": "string", "nullable": true }, "issueDate": { "description": "ISO date string", "type": "string", "nullable": true }, "origin": { "description": "GENERATED | IMPORTED | REGULARIZATION", "type": "string", "enum": [ "GENERATED", "IMPORTED", "REGULARIZATION" ] }, "ipRightType": { "description": "PATENT | TRADEMARK: asset family discriminant", "type": "string", "enum": [ "PATENT", "TRADEMARK" ], "x-enumNames": [ "Patent", "Trademark" ] }, "currency": { "description": "ISO 4217 currency code the client is invoiced in", "type": "string" }, "vatRate": { "description": "VAT rate applied (non-monetary number, e.g. 0.2 for 20%)", "type": "number", "nullable": true }, "vatNumber": { "description": "VAT number on the invoice", "type": "string", "nullable": true }, "subtotalExcludingTax": { "description": "Subtotal before tax, in invoice currency (decimal string)", "type": "string", "nullable": true }, "totalIncludingTax": { "description": "Total including tax, in invoice currency (decimal string)", "type": "string", "nullable": true }, "hasPdfDocument": { "description": "True when a PDF document is available for this invoice", "type": "boolean" }, "hasXlsxDocument": { "description": "True when an XLSX document is available for this invoice", "type": "boolean" }, "fees": { "description": "Full per-component fee breakdown of the invoice", "type": "array", "items": { "type": "object", "properties": { "object": { "description": "String describing the object type (auto-description)", "type": "string", "enum": [ "fees" ] }, "invoiceId": { "description": "Back-reference to the invoice these fees belong to", "type": "string", "format": "uuid", "nullable": true }, "eventId": { "description": "Public UUID of the patent event these fees belong to (trace each fee line back to its event)", "type": "string", "format": "uuid", "nullable": true }, "patent": { "description": "The patent this fee line belongs to: identified both ways (Renewr id + your own reference)", "type": "object", "properties": { "id": { "description": "Renewr UUID of the patent", "type": "string", "format": "uuid", "nullable": true }, "providerId": { "description": "The client's own matching reference for that patent", "type": "string", "nullable": true } }, "required": [ "id", "providerId" ] }, "currency": { "description": "ISO 4217 currency code the client is invoiced in", "type": "string" }, "total": { "description": "Total of all components, in invoice currency (decimal string)", "type": "string", "nullable": true }, "components": { "description": "Per-type fee breakdown (Stripe fee_details style); a component that does not apply is absent (never null). Sums to `total`.", "type": "array", "items": { "type": "object", "properties": { "type": { "description": "OFFICE (national office) | AGENT (external agent) | RENEWR (service fee) | GRACE_PERIOD (late surcharge)", "type": "string", "enum": [ "OFFICE", "AGENT", "RENEWR", "GRACE_PERIOD" ], "x-enumNames": [ "Office", "Agent", "Renewr", "GracePeriod" ] }, "amount": { "description": "Amount of this component, in invoice currency (decimal string)", "type": "string" } }, "required": [ "type", "amount" ] } }, "feesStatus": { "description": "Whether these amounts are ESTIMATED (projected) or INVOICED (final: an invoice exists)", "type": "string", "enum": [ "ESTIMATED", "INVOICED" ] }, "isFxRateFrozen": { "description": "True when the FX rate used to compute these fees is frozen", "type": "boolean" } }, "required": [ "object", "invoiceId", "eventId", "patent", "currency", "total", "components", "feesStatus", "isFxRateFrozen" ] } }, "createdAt": { "description": "ISO 8601 timestamp (UTC)", "type": "string", "format": "date-time", "nullable": true }, "updatedAt": { "description": "ISO 8601 timestamp (UTC)", "type": "string", "format": "date-time", "nullable": true } }, "required": [ "object", "id", "reference", "number", "issueDate", "origin", "ipRightType", "currency", "vatRate", "vatNumber", "subtotalExcludingTax", "totalIncludingTax", "hasPdfDocument", "hasXlsxDocument", "fees", "createdAt", "updatedAt" ] } } } }