Developer Reference

API Documentation

REST API for searching 14M+ USPTO trademark records. Two endpoints, Bearer token auth, JSON responses. Get an API key →

Overview

The Goalie IP Trademark API provides structured access to the USPTO trademark database — the same data that powers our search tools. Query by mark name, owner, status, international class, serial number, and more.

Base URL	`https://goalieip.com`
Version	`v1`
Format	JSON request and response bodies
Auth	Bearer token in `Authorization` header

Authentication

Every request must include your API key as a Bearer token in the Authorization header. Keys are created and managed in your portal.

Authorization: Bearer gip_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are prefixed with gip_live_ and are 40 characters total. Keep them secret — they are shown only once at creation. You can create up to 5 active keys per account.

Quick start

Search for all active registrations of a mark in a specific class:

curl -X POST https://goalieip.com/api/v1/trademarks/search \
  -H "Authorization: Bearer gip_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "markLiteral": "ACME",
    "markLiteralMode": "exact",
    "currentStatusCode": ["700", "800"],
    "internationalClasses": ["025"],
    "page": 1,
    "pageSize": 25
  }'

Look up a specific trademark by serial number:

curl https://goalieip.com/api/v1/trademarks/97123456 \
  -H "Authorization: Bearer gip_live_your_key_here"

POST/api/v1/trademarks/search

Search and filter the trademark database. Returns a paginated list of matching records. All filter fields are optional — omitting all filters returns the full dataset sorted by filing date descending.

Request

POST /api/v1/trademarks/search
Authorization: Bearer gip_live_...
Content-Type: application/json

{
  "markLiteral": "NIKE",
  "markLiteralMode": "exact",
  "ownerName": "Nike, Inc.",
  "currentStatusCode": ["700", "800"],
  "internationalClasses": ["025", "035"],
  "filingDateFrom": "2020-01-01",
  "page": 1,
  "pageSize": 25
}

Response

{
  "data": [
    {
      "serialNumber": "97123456",
      "registrationNumber": "6789012",
      "markLiteral": "NIKE",
      "ownerName": "Nike, Inc.",
      "currentStatusCode": "700",
      "currentStatusDate": "2022-03-15T00:00:00.000Z",
      "filingDate": "2021-06-01T00:00:00.000Z",
      "internationalClasses": ["025"],
      "goodsAndServices": "Athletic footwear and apparel",
      ...
    }
  ],
  "meta": {
    "total": 61,
    "page": 1,
    "pageSize": 25,
    "callsUsed": 1,
    "callsRemaining": 4999
  }
}

GET/api/v1/trademarks/{serialNumber}

Retrieve a single trademark record by its USPTO serial number. Returns the full record or 404 if not found.

GET /api/v1/trademarks/97123456
Authorization: Bearer gip_live_...

Response

{
  "data": {
    "serialNumber": "97123456",
    "registrationNumber": "6789012",
    "markLiteral": "NIKE",
    ...
  },
  "meta": {
    "callsUsed": 2,
    "callsRemaining": 4998
  }
}

Search parameters

All fields are optional. Combining multiple fields narrows results (AND logic).

Mark filters

Field	Type	Description
`markLiteral`	string	The text of the mark. Case-insensitive.
`markLiteralMode`	`"contains"` `"exact"` `"fuzzy"`	How to match `markLiteral`. contains — substring match (default). exact — full string equality. fuzzy — phonetic similarity using trigram matching; useful for finding confusingly similar marks.
`markDrawingCode`	string	Filter by drawing type code. See Drawing codes.

Owner & attorney filters

Field	Type	Description
`ownerName`	string	Substring match on the registrant/owner name.
`attorneyName`	string	Substring match on the attorney of record.

Classification & goods filters

Field	Type	Description
`internationalClasses`	string[]	Filter by Nice Classification codes. Pass multiple to match any (OR logic). Values are zero-padded three-digit strings, e.g. `"025"`, `"035"`.
`goodsAndServices`	string	Substring match on the goods and services description.

Status & identifier filters

Field	Type	Description
`serialNumber`	string	Exact match on the USPTO serial number.
`registrationNumber`	string	Exact match on the registration number.
`currentStatusCode`	string[]	Filter by one or more status codes (OR logic). E.g. `["700", "800"]` for all registered marks. See Status codes.

Date range filters

Field	Type	Description
`filingDateFrom`	ISO 8601 date string	Include only records filed on or after this date. Example: `"2023-01-01"`.
`filingDateTo`	ISO 8601 date string	Include only records filed on or before this date. Example: `"2023-01-01"`.
`currentStatusDateFrom`	ISO 8601 date string	Filter by status change date (on or after). Example: `"2023-01-01"`.
`currentStatusDateTo`	ISO 8601 date string	Filter by status change date (on or before). Example: `"2023-01-01"`.

Pagination & sorting

Field	Type	Default	Description
`page`	integer	1	Page number, 1-indexed.
`pageSize`	integer	25	Results per page. Max 500.
`sortField`	string	`filingDate`	Field to sort by. One of: `serialNumber`, `filingDate`, `transactionDate`, `markLiteral`, `ownerName`, `currentStatusCode`, `currentStatusDate`, `registrationNumber`.
`sortDir`	`"asc"` `"desc"`	`"asc"`	Sort direction.

Response fields

Each record in data[] contains the following fields.

Field	Type	Description
`serialNumber`	string	USPTO serial number. Unique identifier for each application.
`registrationNumber`	string \| null	Registration number once granted. "0000000" means not yet registered.
`markLiteral`	string \| null	The text of the mark. Null for purely design marks.
`markDrawingCode`	string	Code indicating the type of mark drawing. See Drawing codes.
`ownerName`	string \| null	Name of the current owner/registrant.
`ownerAddress`	object \| null	Structured address: city, country, postcode, address_1, nationality_country, legal_entity_type_code.
`correspondentAddress`	string \| null	Full mailing address of the correspondent of record.
`attorneyName`	string \| null	Attorney of record at the USPTO.
`attorneyDocketNumber`	string \| null	Attorney's internal docket reference, if recorded.
`filingDate`	ISO datetime \| null	Date the application was filed.
`transactionDate`	ISO datetime	Date of the most recent USPTO transaction.
`currentStatusCode`	string	Current application/registration status code. See Status codes.
`currentStatusDate`	ISO datetime	Date the current status was set.
`statusHistory`	array	Ordered list of all status events: { code, date, description }.
`publishedForOppositionDate`	ISO datetime \| null	Date published for opposition in the Official Gazette, if applicable.
`internationalClasses`	string[]	Nice Classification class codes, e.g. ["025", "035"]. Empty array if unclassified.
`goodsAndServices`	string \| null	Full goods and services description from the application.
`currentLocation`	string \| null	Current physical location at the USPTO (e.g. "PUBLICATION AND ISSUE SECTION").
`employeeName`	string \| null	USPTO examining attorney assigned to the application.
`headerFlags`	object	Boolean flags for application attributes (see below).
`createdAt`	ISO datetime	When this record was added to the Goalie IP database.
`updatedAt`	ISO datetime	When this record was last updated.

headerFlags

Boolean attributes of the application. Commonly useful flags:

Flag	Meaning when true
`trademark_in`	Filed as a trademark (vs. service mark, collective mark, etc.)
`service_mark_in`	Filed as a service mark
`intent_to_use_in`	Original filing basis was intent-to-use (§1(b))
`use_application_currently_in`	Current basis is use in commerce (§1(a))
`standard_characters_claimed_in`	Mark is in standard characters with no design claim
`color_drawing_current_in`	Color is currently claimed as a feature of the mark
`section_8_filed_in`	Section 8 declaration of use has been filed
`section_15_filed_in`	Section 15 declaration of incontestability has been filed
`renewal_filed_in`	Renewal application has been filed
`opposition_pending_in`	Opposition proceeding is currently pending
`cancellation_pending_in`	Cancellation proceeding is currently pending
`foreign_priority_in`	Foreign priority claim under §44(d)

Field	Description
`total`	Total number of records matching the query (across all pages).
`page`	Current page number.
`pageSize`	Number of results returned on this page.
`callsUsed`	Total API calls made by your account this calendar month, including this request.
`callsRemaining`	Calls remaining this month before your quota is exhausted.

Status codes

The currentStatusCode field uses USPTO internal codes. The most commonly encountered codes by category:

Live / Pending

Code	Description
`630`	New application — not yet assigned to examiner
`638`	New application — assigned to examiner
`641`	Non-final office action mailed
`645`	Final refusal mailed
`680`	Approved for publication
`686`	Published for opposition
`688`	Notice of allowance issued
`718–734`	Statement of use extension requests (ITU)
`744`	Statement of use filed
`760`	Ex parte appeal pending
`774`	Opposition pending

Live / Registered

Code	Description
`700`	Registered
`701`	Section 8 accepted (declaration of use filed)
`702`	Section 8 & 15 accepted — incontestable
`703`	Section 15 acknowledged
`800`	Registered and renewed

Dead / Abandoned

Code	Description
`600`	Abandoned — incomplete response
`601`	Abandoned — express
`602`	Abandoned — failure to respond or late response
`606`	Abandoned — no statement of use filed
`900`	Expired

Dead / Cancelled

Code	Description
`709`	Cancelled — Section 71
`710`	Cancelled — Section 8 (failure to file maintenance)
`711`	Cancelled — Section 7
`712`	Cancelled by court order (Section 37)
`626`	Registered backfile — cancelled or expired

To filter for all live registered marks, pass "currentStatusCode": ["700", "701", "702", "703", "704", "705", "800"].

Drawing codes

The markDrawingCode field indicates the form of the mark drawing submitted to the USPTO.

Code	Description
`1`	Typed drawing — plain word mark, no design element
`2`	Design without color claim
`3`	Design with color claim
`4`	Standard character mark — word in any font, size, or color
`5`	Standard character mark with color claim
`6`	Special form — word combined with design element

To find only word marks (no design element), filter for markDrawingCode: "4" (standard characters) or "1" (typed drawing).

Note: Our database contains trademark metadata only — it does not store mark images or design specimens. For trademarks that consist solely of a design or logo (drawing codes 2, 3, 5, and 6), the API will return all available textual fields but no image URL or image data. To view the actual mark image, use the USPTO's TSDR portal at tsdr.uspto.gov.

Error responses

Errors return a JSON body with an error string and the appropriate HTTP status code.

{ "error": "Monthly call quota of 5000 calls exceeded. Upgrade at https://goalieip.com/subscribe" }

Status	Cause	Resolution
`400`	Invalid JSON body or a request parameter failed validation.	Check the error message for the specific field that failed.
`401`	Missing, malformed, or revoked API key.	Verify the Authorization header is present and the key is active in your portal.
`404`	Serial number not found (lookup endpoint only).	Verify the serial number. USPTO serial numbers are 8 digits.
`429`	Monthly call quota exceeded.	Upgrade your plan or wait until the quota resets on the 1st of next month.
`500`	Internal server error.	Retry the request. If it persists, contact reid@goalieip.com.

Rate limits

Quotas are enforced at the account level — all API keys on the same account share one monthly pool. The quota resets on the 1st of each calendar month.

Plan	Calls / month	Overage
Free	200	None — requests return 429 when exhausted
API Starter ($19/mo)	5,000	+$0.004 per call
API Professional ($49/mo)	30,000	+$0.002 per call

Every response includes meta.callsUsed and meta.callsRemaining so you can monitor consumption in your application. Upgrade your plan →