PatentRef

Data version 20261027.2, as of 2026-10-27: the build these pages were checked against. API version 1.21.0.

Examples

Every request below needs a key in $KEY. The first group is the upstream contract: the 31 requests drawn from the PatentSearch API's own documents, tests and notebooks, which PatentRef answers as upstream did (the contract examples run against every build before it goes into service). Requests on the pre-grant publication endpoints answer 501 in a build without that data set.

Worked examples (all with X-Api-Key)

  1. One patent with inventors and assignees:
    GET /api/v1/patent/?q={"patent_id":"10905426"}&f=["patent_id","patent_title","patent_date","inventors.inventor_name_first","inventors.inventor_name_last","assignees.assignee_organization"]
  2. Patents of an organization since 2020, newest first, 200 a page:
    GET /api/v1/patent/?q={"_and":[{"_begins":{"assignees.assignee_organization":"Apple"}},{"_gte":{"patent_date":"2020-01-01"}}]}&s=[{"patent_date":"desc"},{"patent_id":"asc"}]&o={"size":200}
    next page: o={"size":200,"after":["<patent_date of the last record>","<patent_id of the last record>"]}
  3. Phrase search in titles, counting only:
    GET /api/v1/patent/?q={"_text_phrase":{"patent_title":"solid state battery"}}&o={"size":1} then read total_hits.
  4. Forward citations of a patent:
    GET /api/v1/patent/us_patent_citation/?q={"citation_patent_id":"7861317"}&f=["patent_id","citation_date"]
  5. An inventor's patents by year:
    GET /api/v1/inventor/?q={"inventor_name_last":"Hopper"}&f=["inventor_id","inventor_name_first","inventor_name_last","inventor_years"]
  6. Patents in a CPC group:
    GET /api/v1/patent/?q={"cpc_current.cpc_group_id":"H01M10/0525"}&f=["patent_id","patent_title"]
  7. Problem details on an error:
    curl -G -H "X-Api-Key: $KEY" -H "Accept: application/problem+json" https://patentref.io/api/v1/patent/ --data-urlencode 'q={"not_a_field":"x"}'
  8. Is a patent expired, and can it be revived:
    GET /api/v1/lapse/status/6671888/
    (status expired_term, basis ["term_20y", "pta_days:129", "reinstated:2017-08-30"], reinstatement_possible false: the term end computed from its dates, 2022-08-08, has passed)
  9. Expiry facts for the results of a search:
    GET /api/v1/patent/?q={"_text_phrase":{"patent_title":"solid state battery"}}&f=["patent_id","patent_title","lapse.expiry_status","lapse.expiry_date_estimated","lapse.lapse_date"]
  10. The claims of a patent, claim 1 first:
    GET /api/v1/g_claim/?q={"patent_id":"10000000"}&f=["claim_sequence","claim_number","claim_dependent","claim_text"]
  11. The assignee as printed on the grant, beside PatentsView's disambiguated name:
    GET /api/v1/patent/?q={"patent_id":"6859933"}&f=["patent_id","assignees.assignee_organization","assignees.raw_assignee_organization"]
    (assignees [{"assignee_organization": "SAMSUNG DISPLAY CO., LTD.", "raw_assignee_organization": "Samsung Electronics, Co., Ltd."}]; null in place of the printed name in a data version built before it)

The contract examples

ref_eq_single: GET /api/v1/patent/

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/patent/ \
  --data-urlencode 'q={"patent_id": "7861317"}'

ref_gte_date: GET /api/v1/patent/

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/patent/ \
  --data-urlencode 'q={"_gte": {"patent_date": "2007-01-09"}}'

ref_not: GET /api/v1/patent/

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/patent/ \
  --data-urlencode 'q={"_not": {"patent_type": "design"}}'

ref_value_array_nested: GET /api/v1/patent/

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/patent/ \
  --data-urlencode 'q={"inventors.inventor_name_last": ["Whitney", "Hopper"]}'

ref_and: GET /api/v1/patent/

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/patent/ \
  --data-urlencode 'q={"_and": [{"inventors.inventor_name_last": "Whitney"}, {"patent_date": "1981-10-06"}]}'

ref_complex_1: GET /api/v1/patent/

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/patent/ \
  --data-urlencode 'q={"_and": [{"inventors.inventor_name_last": ["Whitney", "Hopper"]}, {"_not": {"patent_type": "design"}}, {"_gte": {"patent_date": "2007-01-01"}}, {"_lte": {"patent_date": "2007-12-31"}}]}'

ref_or_text_any: GET /api/v1/patent/

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/patent/ \
  --data-urlencode 'q={"_or": [{"inventors.inventor_name_last": ["Whitney", "Hopper"]}, {"_text_any": {"patent_title": "COBOL cotton gin"}}]}'

ref_nested_and_or_phrase: GET /api/v1/patent/

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/patent/ \
  --data-urlencode 'q={"_or": [{"_and": [{"inventors.inventor_name_last": "Whitener"}, {"_text_phrase": {"patent_title": "cotton gin"}}]}, {"_and": [{"inventors.inventor_name_last": "Heath"}, {"_text_all": {"patent_title": "COBOL"}}]}]}'

ref_sort_multi: GET /api/v1/patent/

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/patent/ \
  --data-urlencode 'q={"_gte": {"patent_date": "2007-01-09"}}' \
  --data-urlencode 's=[{"patent_date": "desc"}, {"patent_id": "asc"}]'

ref_after_cursor: GET /api/v1/g_claim/

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/g_claim/ \
  --data-urlencode 'q={"_gte": {"patent_id": "12050000"}}' \
  --data-urlencode 's=[{"patent_id": "asc"}, {"claim_sequence": "desc"}]' \
  --data-urlencode 'o={"size": 100, "after": ["12050006", 2]}'

ex1_id_list: GET /api/v1/patent/

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/patent/ \
  --data-urlencode 'q={"patent_id": ["D345393", "10905426", "11172927"]}' \
  --data-urlencode 'f=["patent_id", "patent_title", "patent_date"]' \
  --data-urlencode 's=[{"patent_id": "asc"}]' \
  --data-urlencode 'o={"size": 200}'

ex2_date_range_post: POST /api/v1/patent/

curl -s -X POST -H "X-Api-Key: $KEY" -H "Content-Type: application/json" https://patentref.io/api/v1/patent/ \
  -d '{"q": {"_and": [{"_gte": {"patent_date": "2020-01-01"}}, {"_lte": {"patent_date": "2020-12-31"}}]}, "f": ["patent_id", "patent_title", "patent_date"], "s": [{"patent_date": "desc"}], "o": {"size": 100}}'

ex3_text_all_abstract: POST /api/v1/patent/

curl -s -X POST -H "X-Api-Key: $KEY" -H "Content-Type: application/json" https://patentref.io/api/v1/patent/ \
  -d '{"q": {"_text_all": {"patent_abstract": "machine learning"}}, "f": ["patent_id", "patent_title", "patent_abstract"], "o": {"size": 50}}'

ex4_DOC_BUG_field_outside_operator: GET /api/v1/patent/

As written in Examples.md this is NOT valid for the parser: 'inventors.inventor_last_name' passes field validation only because subfields are not validated (real field is inventor_name_last), and {field:{_text_all:..}} form emits match:{field:{_text_all:..}} which ES rejects. Kept as a negative example.

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/patent/ \
  --data-urlencode 'q={"_and": [{"_gte": {"patent_date": "2018-01-01"}}, {"_or": [{"assignees.assignee_organization": {"_text_any": "Google Microsoft Amazon"}}, {"inventors.inventor_last_name": "Smith"}]}, {"patent_abstract": {"_text_all": "artificial intelligence"}}]}' \
  --data-urlencode 'f=["patent_id", "patent_title", "patent_date", "patent_abstract", "assignees.assignee_organization", "inventors.inventor_last_name"]' \
  --data-urlencode 's=[{"patent_date": "desc"}]' \
  --data-urlencode 'o={"size": 100}'

ex5_cpc_section: POST /api/v1/patent/

curl -s -X POST -H "X-Api-Key: $KEY" -H "Content-Type: application/json" https://patentref.io/api/v1/patent/ \
  -d '{"q": {"cpc_current.cpc_section": "H"}, "f": ["patent_id", "patent_title", "cpc_current.cpc_section", "cpc_current.cpc_subclass"], "o": {"size": 50}}'

ex6_pagination_page2: POST /api/v1/patent/

curl -s -X POST -H "X-Api-Key: $KEY" -H "Content-Type: application/json" https://patentref.io/api/v1/patent/ \
  -d '{"q": {"patent_type": "utility"}, "f": ["patent_id", "patent_title", "patent_date"], "s": [{"patent_date": "desc"}, {"patent_id": "asc"}], "o": {"size": 100, "after": ["2024-10-01", "US12345678"]}}'

test_neq_list: GET /api/v1/patent/

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/patent/ \
  --data-urlencode 'q={"_neq": {"patent_type": ["utility", "design", "reissue"]}}' \
  --data-urlencode 'f=["patent_id", "patent_title", "patent_date", "patent_type"]'

test_begins_nested: GET /api/v1/patent/

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/patent/ \
  --data-urlencode 'q={"_begins": {"assignees.assignee_organization": "Apple"}}' \
  --data-urlencode 'f=["patent_id", "patent_title", "patent_date", "patent_type", "assignees.assignee_organization"]'

test_contains_nested: GET /api/v1/patent/

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/patent/ \
  --data-urlencode 'q={"_contains": {"inventors.inventor_name_first": "sarvo"}}' \
  --data-urlencode 'f=["patent_id", "patent_title", "patent_date", "patent_type", "inventors.inventor_name_first"]'

test_text_all_title: GET /api/v1/patent/

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/patent/ \
  --data-urlencode 'q={"_text_all": {"patent_title": "transfer data device"}}' \
  --data-urlencode 'f=["patent_id", "patent_title", "patent_date", "patent_type"]'

test_text_phrase_title: GET /api/v1/patent/

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/patent/ \
  --data-urlencode 'q={"_text_phrase": {"patent_title": "Assembly comprising"}}'

test_keyword_exact_org: GET /api/v1/patent/

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/patent/ \
  --data-urlencode 'q={"_eq": {"assignees.assignee_organization": "CNH Industrial Canada, Ltd."}}'

test_keyword_text_any_org: GET /api/v1/patent/

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/patent/ \
  --data-urlencode 'q={"_text_any": {"assignees.assignee_organization": "CNH"}}'

test_mix_text_non_text: GET /api/v1/patent/

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/patent/ \
  --data-urlencode 'q={"_and": [{"_eq": {"inventors.inventor_city": "Boston"}}, {"_text_any": {"patent_title": "assembly component"}}]}'

test_pub_and_nested: GET /api/v1/publication/

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/publication/ \
  --data-urlencode 'q={"_and": [{"_eq": {"inventors.inventor_city": "Boston"}}, {"assignees.assignee_city": "Boston"}]}'

test_pub_text_all: GET /api/v1/publication/

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/publication/ \
  --data-urlencode 'q={"_text_all": {"publication_title": "transfer data device"}}'

nb_patent_year_with_inventors_group: GET /api/v1/patent/

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/patent/ \
  --data-urlencode 'q={"patent_year": "2021"}' \
  --data-urlencode 'f=["patent_id", "patent_title", "patent_date", "inventors"]' \
  --data-urlencode 'o={"size": 3}'

nb_detail_get: GET /api/v1/patent/D345393/

Detail GET: q is built server-side as {pk_field: pk}; 404 if total_hits==0

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/patent/D345393/

nb_inventor_two_names: GET /api/v1/inventor/

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/inventor/ \
  --data-urlencode 'q={"_or": [{"_and": [{"inventor_name_first": "George"}, {"inventor_name_last": "Washington"}]}, {"_and": [{"inventor_name_first": "Abraham"}, {"inventor_name_last": "Lincoln"}]}]}'

patent_withdrawn_override: GET /api/v1/patent/

literal {"withdrawn": true} disables the implicit withdrawn:false filter

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/patent/ \
  --data-urlencode 'q={"withdrawn": true}'

patent_pad_patent_id: GET /api/v1/patent/

patent_id is rewritten to patent_zero_prefix in q, s, f; response key renamed back

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/patent/ \
  --data-urlencode 'q={"_gte": {"patent_id": "D0999999"}}' \
  --data-urlencode 's=[{"patent_id": "asc"}]' \
  --data-urlencode 'o={"pad_patent_id": true}'

The example ex4_DOC_BUG_field_outside_operator reproduces an error in the upstream documents (a field outside its operator); the grammar refuses it with 400 ERR_Q, as upstream did.