Case status and metadata
Retrieve official current case information and supported fields for a known trademark serial or registration number.
USPTO TSDR API Guide
USPTO TSDR API Documentation: A Practical Developer Guide
Understand the official USPTO TSDR API, what it returns, how requests work and which limits matter when integrating trademark case records into an application.
TSDR case workflow
- 1Known serial number
- 2Status + document lookup
- 3Source-backed verification
Data company workflowNormalize / qualify / verify / deliver
On this page
Direct answer
What is the TSDR API?
The USPTO Trademark Status and Document Retrieval (TSDR) API provides programmatic, metered access to public U.S. trademark case status, documents and images. Its principal purpose is record-level retrieval: an application already has a serial number, registration number or other supported identifier, and the API returns information for that case.
This is different from running a broad text search over all trademarks. The official Trademark Search system helps identify candidate marks and records; TSDR then supplies a more detailed status and document trail. If you are designing software for portfolio monitoring, data validation or prospect research, that distinction determines which tool belongs at each stage.
Core TSDR API functions
XML and other supported representations
Use documented response formats and parse record fields carefully; not every endpoint returns the same payload type.
Documents and file wrappers
Inspect case documents, including available Office Actions, filings, responses, notices and registration records.
Document PDF and original content
Retrieve supported rendered PDFs or original-source packages, observing stricter download limits.
Trademark images
Access available images and image representations for a case through documented endpoints.
Multi-case operations
Where supported, use documented multi-case operations while observing the applicable request and download limits.
Choose the correct USPTO data interface before coding
| Research task | Start with |
|---|---|
| Discover trademarks by words, owner or search filters | USPTO Trademark Search; obtain a serial or registration number before looking up detailed case history. |
| Inspect a case's status, history and documents | TSDR public interface or authorized TSDR API using the known case identifier. |
| Retrieve PDF or ZIP case documents | Document retrieval routes under TSDR, with separate per-key file-download limits. |
| Access other USPTO data products | Read that product's current USPTO Open Data Portal/API documentation; do not assume all product credentials or endpoints are interchangeable. |
A reliable TSDR integration workflow
Identify the case
Start with a valid serial number, registration number or another officially supported identifier.
Select the endpoint
Choose case status, a document-list or document-download operation from official TSDR API documentation.
Authenticate securely
Supply your authorized API key through the documented authentication header; never expose it in a public webpage or log.
Validate the response
Check HTTP status, content type, payload structure and whether the response actually belongs to the requested case.
Store evidence, not assumptions
Record the identifier, retrieval timestamp, source endpoint, status fields and document references you rely on.
Schedule respectful rechecks
Use a bounded request queue and account for the USPTO's published rate limits and temporary interruptions.
Documented request examples and formats
Case status, XML example
The USPTO TSDR FAQ lists a sample XML format using /ts/cd/casestatus/sn78787878/info.xml. Replace the sample serial with the case you are checking and follow current authentication instructions.
Case status, HTML example
The official FAQ also provides /ts/cd/casestatus/sn78787878/content as a case-status representation.
Trademark image
A published sample is /ts/cd/rawImage/78787878 for a mark image. Availability depends on the record and request requirements.
API endpoint documentation
Use the current USPTO TSDR API reference as the authority for parameter rules, accepted identifiers and response representations.
Verified request patterns from official TSDR documentation
The examples below use the USPTO's published sample serial number 78787878 and the TSDR authentication header named USPTO-API-KEY. Substitute an authorized credential and the serial number you are researching. The examples illustrate request syntax; they are not live requests and do not embed a working API key.
Use these examples from a terminal or trusted server-side environment—not from a public webpage. A working response depends on the record, the key's authorization, the endpoint's current availability and any published usage limits.
Example 1: Retrieve status XML using a placeholder key
curl --request GET \
--header "USPTO-API-KEY: YOUR_TSDR_API_KEY" \
--output trademark-status.xml \
"https://tsdrapi.uspto.gov/ts/cd/casestatus/sn78787878/info.xml"Example 2: Retrieve a public trademark image
curl --request GET \
--header "USPTO-API-KEY: YOUR_TSDR_API_KEY" \
--output trademark-image \
"https://tsdrapi.uspto.gov/ts/cd/rawImage/78787878"Example 3: Retrieve a supported case ZIP package
curl --request GET \
--header "USPTO-API-KEY: YOUR_TSDR_API_KEY" \
--output trademark-case.zip \
"https://tsdrapi.uspto.gov/ts/cd/casestatus/sn78787878/download.zip"Validate a response before using it as trademark intelligence
| Response item | Validation step |
|---|---|
| HTTP status | A 2xx code indicates successful transport, not trademark availability or legal entitlement. Handle 401/403/404/429/5xx separately. |
| Content-Type | Ensure the returned body matches the expected XML, image, PDF or ZIP format before parsing or opening it. |
| Serial number | Check that the source record identifier matches the record requested. Do not silently assign a response to the wrong case. |
| Current case status | Distinguish live/dead and descriptive current status from historical prosecution events; retain the corresponding status date. |
| Document list | If downloading documents, confirm the document's identity, description and date are associated with the correct public record. |
| Retrieval timestamp | Store when you retrieved the record and preserve provenance to support later rechecks. |
Direct answer
Error-handling and data freshness guidance
For an authorization error (401 or 403), verify the target API, required authentication header and credential status without logging the key. For HTTP 429, reduce load and follow the USPTO's published limits; do not rotate credentials to evade restrictions. Temporary 5xx responses or connection failures should trigger bounded retries with timeouts rather than uncontrolled repeated calls.
Trademark record freshness is a separate concern. A successful XML response does not mean every document submitted moments ago has been indexed or that the newest historical event equals the current procedural state. Retain the serial number, official status date, retrieval time and source document references so a human reviewer can verify the interpretation.
TSDR API vs USPTO Open Data Portal
Do not assume all USPTO APIs share the same gateway, credential format, paths or data products. TSDR API credentials and Open Data Portal credentials have separate product contexts. Follow the documentation for the exact API you are accessing.
Do not assume all USPTO APIs share the same gateway, credential format, paths or data products. TSDR API credentials and Open Data Portal credentials have separate product contexts. Follow the documentation for the exact API you are accessing.
Direct answer
Security and reliability checklist
Keep the API key in a server-side secret store or environment variable. Do not place a key in public JavaScript, screenshots, help tickets or query strings that may be logged. Restrict access to the key within your application, rotate or replace credentials when officially required and avoid logging full request headers.
For each request, use timeouts and bounded retries. A successful transport response is not equivalent to a correct business classification: check that the case identifier, current status date and field meaning are coherent. Preserve the source and retrieval timestamp so users can verify your analysis later.
Developer questions
Can TSDR search every trademark by keyword?
TSDR is primarily a record-level status and document retrieval service; use official Trademark Search or another appropriate discovery source for keyword searches.
Can I download Office Action PDFs?
Supported case documents can be downloaded; check their availability and the stricter PDF/ZIP download limit.
Does a 200 response prove the record is current?
It proves the request succeeded at that time. Record freshness and the distinction between latest event and present case status still need interpretation.
Is a TSDR key interchangeable with an ODP key?
Do not assume so. Use the correct credentials and headers for each API product.
Where do I start if I only have a trademark name?
Start with official USPTO Trademark Search, select a matching application or registration, then use its serial/registration number in TSDR.
What does the TSDR HTTP 429 error mean?
It indicates request throttling. Consult the dedicated TSDR rate-limits article and the current USPTO FAQ; do not confuse it with a trademark status code.
Need TSDR API key access?
If you plan to retrieve public trademark case status, documents or images, review our $20-per-key offering and submit a request with your intended use. Access remains subject to USPTO service availability and usage requirements.