Patent API Reference

The Patent API allows an organization/agency to create, update or search for patent records.

The following changes were made to Version 3 (v3):

The following changes were made to Version 2 (v2):

Note:

Create Patent, v3

The Create Patent API endpoint allows an organization/agency to create a Patent Report in the iEdison system. Refer to Appendix B for samples of requests and responses.

Endpoint URI

Below is the latest version 3 endpoint for the Create Patent resource. It is recommended to use the latest version of the

POST /iedison/api/v3/patents/create

Request Parameters

The request has the following elements:

Headers: These are the request headers such as Accept or Content-Type. The Accept header defines the expected response format when the API returns the response. The Accept header is required for all requests.

Body: The body contains the data that will be submitted as the POST request. When submitting a form, the format data and file content are sent in the body of the request.

The table below provides the explanation of the Create Patent request header and body parameters that are expected by the iEdison API.

Request Parameter Description Required Data Type Version In
accept Specifies the response format that is expected. Set to “application/json”. Yes String v1+ header
patentRequest The JSON object that contains attributes used in the request. Refer to the table below for a description of the attributes. Yes String v1+ form-data
confirmatoryLicense The Confirmatory License document file for the Patent record. The following file types are allowed: CSV, GIF, JPEG, JPG, PNG, PDF, DOCX, DOC, TIFF, TIF, TXT, XLS, XLSX, PPT, PPTX, ODT, and RTF. The maximum file size is 50MB. No Binary Attachment v1+ form-data
governmentSupportClause The Government Support Clause document file for the Patent record. The following file types are allowed: CSV, GIF, JPEG, JPG, PNG, PDF, DOCX, DOC, TIFF, TIF, TXT, XLS, XLSX, PPT, PPTX, ODT, and RTF. The maximum file size is 50MB. No Binary Attachment v1+ form-data

The table below lists the attributes that will be included in the patentRequest parameter when creating a patent report. The attributes are included in the JSON object as part of the patentRequest form-data text element.

JSON Attribute Name Description Required Data Type Length Version
inventionReportNumber Automatically generated by iEdison for an Invention Report after data has been submitted, checked for errors, and verified. Yes String 25 v1+
granteeOrganizationName The name of the organization established at registration. No String 100 v1+
patentDocketNumber The Patent Docket Number is an internal reference number of the grantee/contractor organization to help track a reported Patent(s). No Integer 30 v1+
patentStatus Indicates the status of the Patent. Refer to Section 12.13 for a list of valid values. Yes String 255 v1+
patentTitle The exact title of the U.S. Patent or Patent application as submitted by the Institution to iEdison or to the USPTO. Yes String 255 v1+
patentApplicationType Patent Application Type of a record. Refer to Section 12.10 for a list of valid values. Yes String 255 v1+
confirmatoryLicenseExcutionDate The date when the Confirmatory License was executed for the Patent. This is required when the confirmatoryLicense document is provided in form-data. Conditional String 10 v1+
nonProvisionalPatentApplication The Non-provisional Patent Application number and date object. This is required only when ORD, DIV, CON, CIP is used for patentApplicationType. Conditional JSON Object   v1+
nonProvisionalApplicationNumber The Non-provisional Patent Application Number field is for the non-provisional Patent application. Yes String 18 v1+
nonProvisionalApplicationDate This field is used for the filing date of the non-provisional Patent application with the U.S. Patent and Trademark Office (USPTO). Format: MM/DD/YYYY Yes String 10 v1+
issuedApplicationNumber The unique identifier of a Patent. No String 50 v1+
issuedApplicationDate The date the Patent number was issued. Format: MM/DD/YYYY No String 10 v1+
expirationDate Estimated date of Patent expiration. Format: MM/DD/YYYY No String 10 v1+
provisionalPatentApplication The Non-provisional Patent Application number and date object. This is required only when PROV is used for patentApplicationType. Conditional JSON Object   v1+
provisionalApplicationNumber The unique identifier for a provisional Patent application created upon filing at the USPTO. Yes String 10 v1+
provisionalApplicationDate Used for the filing date of the U.S. provisional Patent application with the USPTO. Format: MM/DD/YYYY Yes String 10 v1+
pctPatentApplication The Non-provisional Patent Application number and date object. This is required only when PCT is used for patentApplicationType. Conditional JSON Object   v1+
pctApplicationNumber (Patent Cooperation Treaty) number is used to uniquely identify a PCT type Patent application. Yes String 10 v1+
pctApplicationDate This field is used for the filing date of the Patent Cooperation Treaty (PCT) application provided by the World Manufacturer Intellectual Property Organization (WIPO). Format: MM/DD/YYYY Yes String 10 v1+
parentPatents   No Array [JSON Object]   v1+
inventionReportNumber The unique Invention Report Number for the parent Patent. No String 25 v1+
patentDocketNumber The Patent Docket Number is an internal reference number of the grantee/contractor organization to help track a reported Patent(s). No String 30 v1+
inventors List of Inventors Yes Array [JSON Object]   v1+
firstName First name of the inventor. Yes String 80 v1+
lastName Last name of the inventor. Yes String 80 v1+
middleInitial Middle name or first initial of the inventor. No String 30 v1+
fedEmployee Is the inventor a federal employee? true = federal employee, false = not a federal employee (default) No Boolean   v1+
fedAgency If the inventor is a federal employee, the agency the inventor works for. Click here for a list of valid abbreviations. No String 80 v1+
foreignFilings Patent Foreign Filing No Array [JSON Object]   v1+
  The countryName and filingDate do not have to be unique. Users can enter Foreign Filings from the same country on the same date.        
countryName The country name of the foreign filing. The country name does not have to be unique. Refer to Section 12.4 for a list of valid country Name values. Yes String 15 v1+
status The foreign filing status for the Patent. Refer to Section 12.6 for a list of valid values. Yes String   v1+
filingDate The date that the foreign Patent was issued. Format: MM/DD/YYYY Yes String 10 v1+
explanatoryNotes Explanatory notes are used to note information about the report. No JSON Object   v1+
note Explanatory notes are be used to note information about an Invention Report or Patent Report. Explanatory notes should not be used for data that is provided by other iEdison data fields. Yes String 500 v1+
governmentNotes Notes written by the agency regarding the report. If organization client provides value(s) for this list field, the system will ignore them. No JSON Object   v1+
note Government Notes are used to note information about an Invention Report or Patent Report by federal users who have access to view the record. Yes String 500 v1+

Response Parameters

When the request is processed and the patent report is successfully created, the Create Patent API endpoint returns a patentResponse data object. The attributes of this object are described in Section 8.4.

Update Patent, v3

The Update Patent API endpoint allows an organization/agency to update an existing Patent Report in the iEdison system. Refer to Appendix B for samples of requests and responses.

When updating Foreign Filings, the request must contain the complete list of countries. The system will update by removing the old list and replacing it with the new list.

See the table below for examples:

If there is an existing Foreign Filing in the Patent record Submit and update request with the following Foreign Filing(s) Result in iEdison
Country A Country A, Country B Delete Country A from the Foreign Filing list and add Country A and Country B to the Foreign Filing list.
Country A None Delete Country A from the Foreign Filing list and no country is added to the Foreign Filing list.
None Country A, Country B Add Country A and Country B to the Foreign Filing list.
None None No updates or changes.

Endpoint URI

This is an example of the endpoint for the Update Patent resource.

POST /iedison/api/v3/patents/update

Request Parameters

The request has the following elements:

Headers: These are the request headers such as Accept or Content-Type. The Accept header defines the expected response format when the API returns the response. The Accept header is required for all requests.

Body: The body contains the data that will be submitted as the POST request. When submitting a form, the format data and file content are sent in the body of the request.

The table below provides the description of the Update Patent request header and body parameters that are expected by the iEdison API.

Request Parameter Description Required Data Type Version In
accept Specifies the response format that is expected. Set to “application/json”. Yes String v1+ header
patentRequest The JSON object that contains attributes used in the request. Refer to the table below for a description of the attributes. Yes String v1+ form-data
confirmatoryLicense The Confirmatory License document file for the Patent record. The following file types are allowed: CSV, GIF, JPEG, JPG, PNG, PDF, DOCX, DOC, TIFF, TIF, TXT, XLS, XLSX, PPT, PPTX, ODT, and RTF. The maximum file size is 50MB. No Binary Attachment v1+ form-data
governmentSupportClause The Government Support Clause document file for the Patent record. The following file types are allowed: CSV, GIF, JPEG, JPG, PNG, PDF, DOCX, DOC, TIFF, TIF, TXT, XLS, XLSX, PPT, PPTX, ODT, and RTF. The maximum file size is 50MB. No Binary Attachment v1+ form-data

The table below lists the attributes that will be included in the patentRequest parameter when updating a Patent Report. The attributes are included in the JSON object as part of the patentRequest form-data text element.

The system updates the government clause file if it is provided during the update operation. If the government clause file is not provided during the update operation, the system checks for the presence of a government clause file uploaded in previous operations. If a government clause file is not present, the system will not perform an update operation and returns an error.

JSON Attribute Name Description Required Data Type Length Version
inventionReportNumber Automatically generated by iEdison for an Invention Report after data has been submitted, checked for errors, and verified. Yes String 100 v1+
granteeOrganizationName The name of the organization established at registration. The system is no longer using this field. No String 100 v1+
patentDocketNumber The Patent Docket Number is an internal reference number of the grantee/contractor organization to help track a reported Patent(s). No String 30 v1+
patentStatus Indicates the status of the Patent. Refer to Section 12.13 for a list of valid values. Yes String 255 v1+
patentTitle The exact title of the U.S. Patent or Patent application as submitted by the Institution to iEdison or to the USPTO. Yes String   v1+
patentApplicationType Patent Application Type of a record. Refer to Section 12.10 for a list of valid values. Yes String   v1+
pctPatentApplication   Conditional JSON Object   v1+
pctAppNum Patent Cooperation Treaty (PCT) number is used to uniquely identify a PCT type Patent application. Yes String   v1+
pctAppDate This field is used for the filing date of the Patent Cooperation Treaty (PCT) application. Format: MM/DD/YYYY Yes String   v1+
provisionalPatentApplication   Conditional JSON Object   v1+
provisionalAppNum The unique identifier a provisional Patent application created upon filing at the USPTO. Yes String   v1+
provisionalAppDate This field is used for the filing date of the U.S. provisional Patent application with the USPTO. Format: MM/DD/YYYY Yes String   v1+
nonProvisionalPatentApplication   Conditional JSON Object   v1+
nonProvisionalApplicationNumber The Non-provisional Patent Application Number field is for the non-provisional Patent application. Yes String 10 v1+
nonProvisionalApplicationNumber The Non-provisional Patent Application Number field is for the non-provisional Patent application. Yes String 10 v1+
nonProvisionalApplicationDate This field is used for the filing date of the non-provisional Patent application with the U.S. Patent and Trademark Office (USPTO). Format: MM/DD/YYYY Yes String 10 v1+
issuedApplicationNumber The unique identifier of a Patent. No String 50 v1+
issuedApplicationDate The date the Patent number was issued. Format: MM/DD/YYYY No String 10 v1+
expirationDate Estimated date of Patent expiration. Format: MM/DD/YYYY No String 10 v1+
parentPatents Parent Patent No Array [JSON Object]   v1+
inventionReportNumber Automatically generated by iEdison for an Invention Report after data has been submitted, checked for errors, and verified. No String 100 v1+
patentDocketNumber The Patent Docket Number is an internal reference number of the grantee/contractor organization to help track a reported Patent(s). No String 30 v1+
inventors List of Inventors Yes Array [JSON Object]   v1+
firstName First name of the inventor. Yes String 80 v1+
lastName Last name of the inventor. Yes String 80 v1+
middleInitial Middle name or first initial of the inventor. No String 30 v1+
fedEmployee Is the inventor a federal employee? true = federal employee, false = not a federal employee (default) No Boolean   v1+
fedAgency If the inventor is a federal employee, the agency the inventor works for. Click here for a list of valid abbreviations. No String 80 v1+
foreignFilings Patent Foreign Filing No JSON Object   v1+
  The countryName and filingDate do not have to be unique. Users can enter Foreign Filings from the same country on the same date. When updating foreign filings, the request must contain the complete list of countries. The system will update by removing the old list and replacing it with the new list.        
countryName The country name of the foreign filing. The country name does not have to be unique. Refer to Section 12.4 for a list of valid values. Yes String 15 v1+
status The foreign filing status for the Patent. Refer to Section 12.13 for a list of valid values. Yes String   v1+
filingDate The date that the foreign Patent was issued. Format: MM/DD/YYY Yes String 10 v1+
explanatoryNotes Explanatory notes are used to note information about the report. No JSON Object   v1+
note Explanatory notes are be used to note information about an Invention Report or Patent Report. Explanatory notes should not be used for data that is provided by other iEdison data fields. Yes String 500 v1+
governmentNotes Notes written by the agency regarding the report. If organization client provides value(s) for this list field, the system will ignore them. No JSON Object   v1+
note Government Notes are used to note information about an Invention Report or Patent Report by federal users who have access to view the record. Yes String 500 v1+

Response Parameters

When the request is processed and the patent report is successfully updated, the Update Patent API endpoint returns a patentResponse data object. The attributes of this object are described in Section 8.4.

Search Patent, v3

The Search Patent API allows users to specify any combination of the attributes to search for existing Patent Reports. The search criteria are applied using an “AND” operation across the various attributes specified in the JSON request. For example, if the patent search has a Patent Docket Number and Primary Agency, the search results include all the searches that match both the Patent Docket Number and the Primary Agency. Refer to Appendix B for samples of requests and responses.

Endpoint URI

This is an example of the endpoint for the Search Patent resource.

POST /iedison/api/v3/patents/search

Request Parameters

The request has the following elements:

Headers: These are the request headers such as Accept or Content-Type. The Accept header defines the expected response format when the API returns the response. The Accept header is required for all requests.

Body: The body contains the data that will be submitted as the POST request. When submitting a form, the format data and file content are sent in the body of the request.

The table below provides the explanation of the Search Patent request header and body parameters that are expected by the iEdison API.

Request Parameter Description Data Type Version In
accept Specifies the response format that is expected. Set to “application/json”. String v1+ header
patentSearchCriteria The JSON object that contains attributes used in the request. Refer to the table below for a description of the attributes. String v1+  

The table below shows the parameters that will be included in the JSON body only one time during the processing of Search Patents Request.

The table below lists the attributes that will be included in the patentSearchCriteria parameter when searching for a Patent Report. The attributes are included in the JSON object as part of the patentSearchCriteria form-data text element.

JSON Attribute Name Description Required Data Type Length Version
limit Total number of records to be retrieved per page. This field must be a number. Max Value = 100, Default = 20 No Integer   v1+
offset Indicates the page index. Default = 0 if user does not provide any offset in the request No Integer   v1+
inventionReportNumber Automatically generated by iEdison for an Invention Report after data has been submitted, checked for errors, and verified. No String 100 v1+
inventionDocketNumber An internal reference number of the grantee/contractor organization to help track a reported Invention(s). No String 30 v1+
inventionReportDateFrom The From Date that the inventor disclosed the subject Invention in writing to the recipient institution. Format: MM/DD/YYYY No String 10 v1+
inventionReportDateTo The To Date that the inventor disclosed the subject Invention in writing to the recipient institution. Format: MM/DD/YYYY No String 10 v1+
inventionTitle The title of the Invention as it appears in the grantee/contractor’s employee’s Invention Report. No String 255 v1+
primaryAgency The Primary Agency designated for each Invention Report in iEdison. Click here for a list of valid abbreviations. No String 1 v1+
titleElectionStatus The status of the title to rights in the reported Invention. Refer to Section 12.15 for a list of valid values. No Array [String] 50 v1+
granteeOrganizationName The name of the organization established at registration. No String 100 v1+
grantContractNumber The grant or contract number as specified by the agency. The format is defined by the agency. No String 50 v1+
patentApplicationType The Patent Application Type of a record. Refer to Section 12.10 for a list of valid values. No String 25 v1+
patentStatus Indicates the status of the Patent. Refer to Section 12.7 for a list of valid values. No String 50 v1+
patentDocketNumber The Patent Docket Number is an internal reference number of the grantee/contractor organization to help track a reported Patent(s). No String 30 v1+
patentFilingDateFrom The ‘starting from’ search date against the PCT, Provisional, Non-Provisional Patent application filing date. Format: MM/DD/YYYY No String 10 v1+
patentFilingDateTo The ‘up to’ search date against the PCT, Provisional, Non-Provisional Patent application filing date. Format: MM/DD/YYYY No String 10 v1+
patentTitle The exact title of the U.S. Patent or Patent application as submitted by the Institution to iEdison or to the USPTO. No String 50 v1+
inventorFirstName The first name of the inventor. No String 50 v1+
inventorLastName The last name of the inventor. No String 50 v1+
lastUpdatedFrom The ‘start from’ search date against the Patent last updated date. Will use the last updated date for the invention, but if that is null, then the created date will be used. Format: MM/DD/YYYY No String 10 v1+
lastUpdatedTo The ‘up to’ search date against the Patent last updated date. Format: MM/DD/YYYY No String 10 v1+

Response Parameters

When the request is processed, the Search Invention API endpoint returns a list of inventions that match the search criteria in the patentResponse data object. The attributes of this object are described in Section 8.4.

JSON Attribute Name Description Data Type Version
totalRecords The total number of records for the search. Number v1+
limit The limit entered by the user while making the request, i.e., total number of records the user wants to retrieve per page. Number v1+
offset The page index specified by the user. Default offset starts with 0 if user does not provide any offset in the request. Number v1+
patents A list of patent records which contains the patentResponse data object. Array [JSON Object] v1+

patentResponse Data Object

The create, update, and search Patent API shares the same patentResponse data object. The JSON attributes are described in the table below.

Response Parameter Description Data Type Version
id System generated sequence number used for ID of the Patent Integer v1+
patentDocketNum The Patent Docket Number is the internal reference number of the grantee/contractor organization to help track a reported Patent(s). This field is supported in version 1 and version 2 only. This attribute is replaced with patentDocketNumber in version 3. String v1, v2
patentDocketNumber The Patent Docket Number is the internal reference number of the grantee/contractor organization to help track a reported Patent(s). String v3
inventionReportNumber The unique Invention Report Number which identifies the Invention record in iEdison that the Patent is associated with. String v1+
issuedApplicationNumber The Patent number provided by USPTO when the Patent is issued. String v1+
issuedApplicationDate The date the Patent number was issued. String v1+
pctAppNum The Patent Cooperation Treaty (PCT) number is used to uniquely identify a PCT type Patent application. String v1+
pctAppDate The filing date of the Patent Cooperation Treaty (PCT) application. String v1+
provisionalAppNum The unique identifier a provisional Patent application created upon filing at the USPTO. String v1+
provisionalAppDate The filing date of the U.S. provisional Patent application with the USPTO. String v1+
nonProvisionalAppNum The Non-provisional Patent Application Number field is for the non-provisional Patent application. String v1+
nonProvisionalAppDate The filing date of the non-provisional Patent application with the U.S. Patent and Trademark Office (USPTO) String v1+
patentApplicationType The Patent Application Type of a record. Refer to Section 12.10 for a list of valid values. String v1+
patentReceiptDate The date the Patent was received by government. String v1+
expireDate The estimated date the Patent will expire. String v1+
patentTitle The exact title of the U.S. Patent or Patent application as submitted by the Institution to iEdison or to the USPTO. String v1+
patentStatus Indicates the status of the Patent. Refer to Section 12.13 for a list of valid values. String v1+
confLicenseAcceptDate The date the Confirmatory License was accepted. String v2+
confLicenseRejectDate The date the Confirmatory License was rejected by the Government Agency. String v1+
confLicenseRejectComment The reason the Confirmatory License was rejected. String v1+
confLicenseOutdated Indicates if the Confirmatory License is outdated. String v1+
govtSuppClauseAcceptDate The date the Federal Support Clause was accepted by the government. String v2+
govtSuppClauseRejectDate The date the Government Support Clause inclusion was rejected by the Government Agency. String v1+
govtSuppClauseRejectComment The reason for Government Support Clause rejection displayed to grantee/contractor institution. String v1+
govtActionDate Government Action Date String v1+
domesticWaiverDecisionFlag Indicates the Domestic Waiver decision. Boolean v1+
domesticWaiverDecisionDate The Domestic Waiver Decision date. String v1+
parentPatents List of Parent Patents Array [JSON Object] v1+
id The unique identifier for the parent patent record in iEdison system Integer v2+
inventionReportNumber The unique Invention Report Number for the parent Patent. String v1+
patentDocketNumber The Patent Docket Number is an internal reference number of the grantee/contractor organization to help track a reported Patent(s). String v1+
confirmatoryLicenseExcutionDate The Confirmatory License date of execution for EPAS submission. String v1+
abandonedReason The reason a Patent is abandoned. String v1+
extensionDays The number of days Patent provisional application date has been extended. Integer v1+
usptoAppStatus The USPTO application status of the Patent. String v1+
usptoAppStatusDate The date of USPTO application. String v1+
usptoLastSyncDate The date of last sync with USPTO. String v1+
assigned Indicates if the Patent has been assigned to another organization. Boolean v1+
explanatoryNotes Explanatory notes are notes about this patent that are permanently attached to this Patent Report. Array [JSON Object] v1+
id The unique identifier assigned to the explanatory note in the iEdison system. Integer v2+
content Explanatory notes that are permanently attached to this Patent Report. String v1+
code The discriminator value: 1 for Invention Government Note, 2 for Invention Explanatory, 11 for Patent Government Note, 12 for Patent Explanatory, 3 for Discussion” Integer v1+
creatorOrganization Federal Agency or External Institution Name String v1+
governmentNotes Government Notes are used to note information about an Invention Report or Patent Report by federal users who have access to view the record. This is populated only for agency system accounts. Array [JSON Object] v1+
id The unique identifier assigned to the government note in the iEdison system. Integer v2+
content Government notes are used to note information about an Invention Report or Patent Report by federal users who have access to view the record. String v1+
code The discriminator value: 1 for Invention Government Note, 2 for Invention Explanatory, 11 for Patent Government Note, 12 for Patent Explanatory, 3 for Discussion” Integer v1+
creatorOrganization Federal Agency or External Institution Name String v1+
govSupClauseActions Government Support Clause Actions Array [JSON Object] v1+
id The unique identifier assigned to Government Support Clause Action. Int v2+
actionType The type of action. Refer to Section 12.10 for a list of valid values. String v1+
documentType The type of document. Refer to Section 12.10 for a list of valid values. String v1+
actionDate The date the action was taken. Date v1+
reasonText The reason for the action. String v1+
foreignFilings Foreign Filings for the patent. Array [JSON Object] v1+
id The unique identifier assigned to the foreign filing record in the iEdison system. Integer v2+
countryName The country name of the foreign filing record. String v1+
status The status of the foreign filing. String v1+
filingDate The patent foreign filing date. String v1+
inventors The inventor records for the patent. Array [JSON Object] v1+
id The unique identifier assigned to the patent inventor record in the iEdison system. Integer v2
firstName The first name of the inventor. String v1+
lastName The last name of the inventor. String v1+
middleInitial The middle name or first initial of the inventor. String v1+
fedEmployee Is the inventor a federal employee? true = federal employee, false = not a federal employee (default) Boolean v1+
fedAgency If the inventor is a federal employee, the agency the inventor works for. Click here for a list of valid abbreviations. String v1+
createdDate The date the Patent record was created. String v2
lastUpdatedDate The date the Patent record was last updated. String v2