Trademark Documents
Records
Trademark Documents
Office documents for a mark (office actions, certificates, filed forms, correspondence) with lazy first-request metadata fetch and a streaming file proxy
GET
Trademark Documents
When to use this
If you run docketing or an IPMS product, you need office documents the day they issue: the non-final office action a client must answer, the registration certificate, the filed forms in the prosecution history. This endpoint returns that document list for a mark, and each row carries aurl that streams the actual file. USPTO documents are fetched from TSDR on demand the first time you ask, so you get fresh metadata without running your own TSDR poller or fighting its throttles.
The list is document-type media only. Logos, drawings, and specimens live on the media[] array of the trademark record, not here.
Path Parameters
Trademark ID (
tm_...).Query Parameters
Filter by one or more document kinds, comma-separated. Values:
office_action, certificate, correspondence, filed_form, other. Example: document_kind=office_action,certificate.Return documents whose official date is on or after this date (
YYYY-MM-DD).Return documents whose official date is strictly before this date (
YYYY-MM-DD). Must be after official_date_gte when both are supplied.Page size, 1 to 100.
Pagination cursor from a previous response’s
pagination.cursor.Response
A standard list envelope with one extra field,source_sync, describing the freshness of this mark’s document metadata.
Always
list.Freshness of the document metadata for this mark.
Array of trademark document objects, newest official date first.
Whether more pages exist after this one.
Contains
cursor (the token for the next page, or null).First call: metadata fetch in flight
The first time you request documents for a USPTO mark that has never been synced, Signa fetches the metadata inline. If another request already holds the fetch lock, or the upstream fetch is still settling, you getstatus: pending with an empty data array. Request again in a moment.
First call (pending)
Second call: synced with a document row
Once the fetch completes, the list issynced and each row carries its media-proxy url.
Second call (synced)
200 with an empty list and source_sync.status of unsupported. This endpoint never returns an error status for an office that lacks document support.
Code Examples
Downloading document files
Each document row’surl points at the media proxy, GET /v1/trademarks/{id}/media/{mediaId}. Following it streams the file bytes:
- The response is the raw file with its real
Content-Type(application/pdffor office actions and certificates). X-Content-Type-Options: nosniffis set. The proxy never relabels a file: an image row stays an image content type.- The endpoint is unauthenticated so it works directly in
<a href>and<embed>, but it is IP rate-limited, so treat it as a per-download link, not a bulk hose.
502 upstream_error with a Retry-After: 60 header. Honor it and retry after the stated delay. Once persisted, subsequent downloads serve the stored bytes and do not touch TSDR.
cURL
Errors
| Status | Type | Description |
|---|---|---|
| 400 | validation_error | Invalid trademark ID, bad document_kind, or official_date_gte not before official_date_lt |
| 401 | unauthorized | Missing or invalid API key |
| 403 | forbidden | API key lacks the trademarks:read scope |
| 404 | not_found | Trademark does not exist |
502 upstream_error (with Retry-After) when the TSDR download budget is exhausted, and 404 not_found when the media record or upstream file does not exist.
Related Endpoints
- Build a docketing system: the end-to-end recipe using this endpoint
- Trademark Media: image proxy for logos, drawings, and specimens
- Get Trademark: the full record, including the
media[]image array