IEDISON 

INVENTION, PATENT AND 

UTILIZATION (IPU)

REST API Specifications and Examples

Version 2.1

OCTOBER 27, 2023

NATIONAL INSTITUTE OF STANDARDS AND TECHNOLOGY (NIST)

 
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

1

Table of Contents

1.0. Scope......................................................................................................................................5

2.0. Prerequisites...........................................................................................................................5

3.0. PKI Authentication...................................................................................................................6

4.0. Authorization ..........................................................................................................................6

5.0. Environment and URI...............................................................................................................6

5.1. Specification File..................................................................................................................7

6.0. Invention API Reference...........................................................................................................7

6.1. Create Invention..................................................................................................................7

6.1.1. Endpoint URI................................................................................................................7

6.1.2. Request Parameters .....................................................................................................7

6.1.3. Response Parameters.................................................................................................11

6.1.4. Request and Response Examples.................................................................................16

6.2. Update Invention...............................................................................................................20

6.2.1. Endpoint URI..............................................................................................................20

6.2.2. Request Parameters ...................................................................................................20

6.2.3. Response Parameters.................................................................................................25

6.2.4. Request and Response Examples.................................................................................31

6.3. Search Invention................................................................................................................34

6.3.1. Endpoint URI..............................................................................................................34

6.3.2. Request Parameters ...................................................................................................35

6.3.3. Response Parameters.................................................................................................37

6.3.4. Request and Response Example ..................................................................................43

7.0. Patent API Reference.............................................................................................................46

7.1. Create Patent ....................................................................................................................46

7.1.1. Endpoint URI..............................................................................................................46

7.1.2. Request Parameters ...................................................................................................46

7.1.3. Response Parameters.................................................................................................52

7.1.4. Request Example........................................................................................................58

7.1.5. Response Examples ....................................................................................................58

7.2. Update Patent...................................................................................................................60
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

2

7.2.1. Endpoint URI..............................................................................................................60

7.2.2. Request Parameters ...................................................................................................60

7.2.3. Response Parameters.................................................................................................65

7.2.4. Request and Response Examples.................................................................................70

7.3. Search Patent....................................................................................................................72

7.3.1. Endpoint URI..............................................................................................................72

7.3.2. Request Parameters ...................................................................................................72

7.3.3. Response Parameters.................................................................................................74

7.3.4. Request and Response Examples.................................................................................78

8.0. Utilization API Reference........................................................................................................79

8.1. Create Utilization...............................................................................................................79

8.1.1. Endpoint URI..............................................................................................................79

8.1.2. Request Parameters ...................................................................................................80

8.1.3. Response Parameters.................................................................................................83

8.1.4. Request Examples.......................................................................................................86

8.1.5. Response Examples ....................................................................................................87

8.2. Create Utilization V2 ..........................................................................................................88

8.2.1. Endpoint URI..............................................................................................................88

8.2.2. Request Parameters ...................................................................................................88

8.2.3. Response Parameters.................................................................................................96

8.2.4. Request Examples.....................................................................................................101

8.2.5. Response Examples ..................................................................................................104

8.3. Update Utilization............................................................................................................107

8.3.1. Endpoint URI............................................................................................................107

8.3.2. Request Parameters .................................................................................................107

8.3.3. Response Parameters...............................................................................................111

8.3.4. Request Example......................................................................................................114

8.3.5. Response Examples ..................................................................................................114

8.4. Update Utilization V2.......................................................................................................116

8.4.1. Endpoint URI............................................................................................................116

8.4.2. Request Parameters .................................................................................................116
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

3

8.4.3. Response Parameters...............................................................................................123

8.4.4. Request Example......................................................................................................129

8.4.5. Response Examples ..................................................................................................132

8.5. Search Utilization.............................................................................................................135

8.5.1. Endpoint URI............................................................................................................135

8.5.2. Request Parameters .................................................................................................136

8.5.3. Response Parameters...............................................................................................137

8.5.4. Request Example......................................................................................................141

8.5.5. Response Example....................................................................................................141

8.6. Search Utilization V2........................................................................................................142

8.6.1. Endpoint URI............................................................................................................142

8.6.2. Request Parameters .................................................................................................143

8.6.3. Response Parameters...............................................................................................144

8.6.4 Request Example......................................................................................................151

8.6.5 Response Example....................................................................................................151

9.0 Document API Reference .....................................................................................................155

9.1 Search Document ............................................................................................................155

9.1.1 Endpoint URI............................................................................................................155

9.1.2 Request Parameters .................................................................................................155

9.1.3 Response Parameters...............................................................................................158

9.1.4 Request and Response Examples...............................................................................159

9.2 Download Document .......................................................................................................161

9.2.1 Endpoint URI............................................................................................................162

9.2.2 Request Parameters .................................................................................................162

9.2.3 Response Parameters...............................................................................................162

9.2.4 Request and Response Examples...............................................................................163

10.0 Notification API Reference ...................................................................................................163

10.1 Endpoint URI............................................................................................................163

10.2 Request Parameters .................................................................................................164

10.3 Response Parameters...............................................................................................165

10.4 Request and Response Examples...............................................................................166
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

4

11.0 Appendix.............................................................................................................................169

11.1 Mappings........................................................................................................................169

11.1.1 Invention Development Stage...........................................................................................169

11.1.2 Patent Filing Status ..........................................................................................................169

11.1.3 Patent Application Types..................................................................................................170

11.1.4 Award Type .....................................................................................................................170

11.1.5 Agreement Types.............................................................................................................171

11.1.6 Inventor US Federal Employee..........................................................................................171

11.1.7 Patent Status...................................................................................................................171

11.1.8 Agency Mapping List........................................................................................................171

11.1.9 Country List.....................................................................................................................172

11.1.10 States List.................................................................................................................177

11.1.11 Title Election Status..................................................................................................180

11.1.12 Invention Disposition................................................................................................180

11.1.13 Utilization Reporting Year .........................................................................................181

11.1.14 Year of First Commercial Sale....................................................................................182

11.1.15 Utilization Commercial Product Type.........................................................................182

11.1.16 Utilization Commercial Product Government Review Status........................................183

11.1.17 Utilization Public Announced.....................................................................................183

11.1.18 Utilization Manufacturing Location First Date Type.....................................................183

11.1.19 Invention Does Not Retain Title Reason .....................................................................183

11.1.20 Utilization Commercialization Plan ............................................................................183

11.1.21 Licensed Utilization Questions Logics for US Manufacturing ........................................184

11.1.22 Commercialized Utilization Questions Logics for US Manufacturing .............................184

Sample Code Snippet to Consume APIs............................................................................................185

Abbreviations.................................................................................................................................186

Document Change Log:

Date Author Description of Change Reason for Change Impacted Users

9/25/2023 OISM Modified tables, content, and 

reviewed for formatting and ease of 

use.

Updates before 

release

n/a
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

5

1.0. Scope

This document depicts the prerequisites, request, and response schemas for the Invention, 

Patent, and Utilization (IPU) REST API implementation. 

2.0. Prerequisites

A system account and a valid PKI certificate issued by an authorized certificate issuer are 

required to consume the REST API services. Please contact your agency or organization

administrator for a system account setup and a PKI certificate.

New System Account Requirements for Agency or Organization:

1. ISA Document: Download a template from iEdison, sign and upload during the 

system account request process.

2. PKI Certificate: Acquire a cert before requesting a system account and upload during 

the system account request process. 

Note: iEdison will only accept certificate validity no longer than two years.

The following are authorized certificate issuers.

Certificate Issuer Expire Date

DigiCert EV RSA CA G2 Jul 2, 2030

DIGICERT SHA2 ASSURED ID CA Nov 08, 2028

DIGICERT SHA2 HIGH ASSURANCE SERVER CA Oct 22, 2028

DIGICERT SHA2 ASSURED ID CA Nov 05, 2028

DIGICERT SHA2 HIGH ASSURANCE SERVER CA Oct 22, 2028

DIGICERT TLS RSA SHA256 2020 CA1 April 13, 2031

ENTRUST CERTIFICATION AUTHORITY – L1K Dec 05, 2030

GO DADDY SECURE CERTIFICATION AUTHORITY Nov 15, 2026

GO DADDY SECURE CERTIFICATE AUTHORITY – G2 May 03, 2031

HydrantID Server CA O1 Dec 12, 2029

INCOMMON RSA SERVER CA Sep 09, 2024

SECTIGO RSA ORGANIZATION VALIDATION 

SECURE SERVER CA

Dec 31, 2030

Table 2-1: Certificate Issuers list
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

6

3.0. PKI Authentication

REST API endpoint requests initiated by API consumers are authenticated by Mutual TLS 

authentication. An iEdison API consumer’s client system must present a client PKI certificate 

issued by a trusted issuer (See section 2.0). 

iEdison will retrieve and verify the serial number, issuer, and validity of the client certificate in 

the context of the request against the system user records in the database. The serial number 

and issuer’s Common Name (CN) combination is used to uniquely identify a system user. 

• The PKI client certificate and the TLS 1.2 protocol are used together for 

authentication to consume iEdison REST API services. 

• To authenticate REST API services, digitally signs Invention, Patent, and Utilization

data and sends both the certificate and the signed data across the network. 

• The digital signature in PKI certificate associated with API consumer data provides 

evidence to the REST API Services for authentication. 

• The server authenticates the client user’s identity based on the PKI certificate 

provided by the API consumer.

4.0. Authorization

Each system account is identified by the combination of the Serial Number and Issuer’s 

Common Name (CN) from the PKI certificate. The system account is associated with an 

organization/institution record which is used to control what data can be accessed and 

modified. The iEdison REST API provides endpoints for retrieving information about Invention, 

Patent, and Utilization records of an organization or agency. Documentation about the REST API 

services can be found in this document.

5.0. Environment and URI

• User Acceptance Testing (UAT)

URI: https://api-iedisonuat.nist.gov/iedison/api/{version}/{resourcetype}/{action}

version : [v1]

resourcetype : [invention, Patent, utilization]

action : [create, update, search]

• Production 

URI: https://api-iedison.nist.gov/iedison/api/{version}/{resourcetype}/{action}

version : [v1]

resourcetype : [invention, Patent, utilization]

action : [create, update, search]
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

7

5.1. Specification File

You can view the full details of this API in the specification file. (The file generated by Swagger.)

6.0. Invention API Reference

6.1. Create Invention

Organization users can create an Invention owned by a user’s affiliated organization and with 

any agency as the Primary Agency. Agency users can create an Invention owned by any 

institution and with a user’s affiliated agency as Primary Agency.

6.1.1. Endpoint URI

Here’s an example of the v1 endpoint for the Create Invention resource.

POST /iedison/api/v1/inventions/create

6.1.2. Request Parameters

The API POST request has the following elements:

• Headers: these are the request headers such as Accept or Content-Type. The Accept 

header parameter defines the expected response body format when the API returns 

the response. For example, you can define a response as JSON by modifying the Accept 

header. This Accept header is required in all requests. 

• Body: body contains the data which will be submitted as the post request. For example, 

when submitting a form, format data and file content are sent in the body of the 

request.

The table below provides the explanation of the create Invention POST request Header and 

Body parameters which are expected by iEdison API.

Table 6-2: Invention Create API Request Parameter

The table below shows the parameters that will be included in the JSON body during the 

processing of create invention request. The below parameters are included as JSON object in 

Table 6-2: Invention Create API Request Parameter

Request Parameters Description Required Data Type Version In

accept Setting to application/json Yes String v1 header

inventionRequest The Invention Request JSON content. See table

Table 6-1: inventionRequest JSON Attribute List for 

JSON attributes.

Yes String v1 formdata

inventionDisclosure Invention Disclosure document containing the 

written description of the Invention, a signed copy 

of the government Confirmatory License, and the 

Government Support Clause which is in a Patent or 

Patent application.

Yes File Binary v1 formdata
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

8

JSON body as part of the inventionRequest form-data Text element. The JSON object represents 

the metadata for the Invention that needs to be created.

Table 6-3: inventionRequest JSON Attribute List

No. JSON Attribute Name Description Required Data Type Length Version In

1 granteeOrganizationName The name of the organization 

established at registration.

No String 100 v1 body

2 institutionCode The unique code assigned to the 

reporting organizations.

Yes String 10 v1 body

3 dunsNumber The Data Universal Numbering System 

(DUNS) number provided by Dun & 

Bradstreet that identifies the 

grantee/contractor.

No String 9 v1 body

4 inventionTitle The title of the Invention as it appears 

in the grantee/contractors employee’s 

Invention Report.

Yes String 255 v1 body

5 inventionDocketNumber An internal reference number of the 

grantee/contractor organization to help 

track a reported Invention(s)

No String 30 v1 body

6 doesNumber The DOE S-number is assigned to each 

DOE Invention. The number is mainly 

used in DOE’s Invention tracking 

system.

No String 15 v1 body

7 parentInventionNumber Invention Report number used when an 

Invention is combined into another 

Invention as a parent Invention.

No String 25 v1 body

8 inventionReportDate The date the inventor disclosed the 

subject Invention in writing to the 

recipient institution. MM/DD/YYYY 

format.

Yes String 10 v1 body

9 firstPublicationDate The date of first publication, on sale, or 

public use initiating the one-year 

statutory period wherein valid Patent 

protection can still be obtained in the 

United States. MM/DD/YYYY format.

No String 10 v1 body

10 keywords This field enables the 

grantee/contractor organization to 

designate key terms for searching for 

Invention Reports.

No [String] 80 v1 body

11 doeWaiver DOE Waiver No String v1 body

12 institutionCodeForOtherInstitutions Institution code for other organizations 

to view Inventions and other related 

parents. A maximum of three additional 

iEdison registered organizations may be 

granted view-only access to an 

Invention Report.

No [String] v1 body

13 isInventionUnderFundingAgreement Invention under Funding Agreement. No Boolean v1 body

14 Inventors List of Inventors Array

firstName First name of an inventor. Yes String 80

lastName Last name of an inventor. Yes String 80
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

9

Table 6-3: inventionRequest JSON Attribute List

No. JSON Attribute Name Description Required Data Type Length Version In

middleInitial Middle initial of an inventor. No String 30

fedEmployee Is the inventor a federal employee? No boolean

fedAgency If the inventor is a federal employee, 

what agency does the inventor work 

for? Refer to pg. 159, 11.1.8 Agency 

Mapping List for a list of valid 

abbreviations.

No String 80

15 primaryAgency A Primary Agency must be designated 

for each Invention Report in iEdison. 

Refer to Section 11.1.8 Agency Mapping 

List for a list of valid abbreviations.

Yes String 50 v1 body

16 bayhDoleActVersion The Bayh Dole Act Version for the 

Invention. This allows 1980 or 2018. 

Default: 2018

No Integer V1 body

17 fundingAgreements The funding agreement is identified and 

reported in two parts, the Agency 

Designation (the acronym for the 

Federal Agency name) and the grant or 

contract award number corresponding 

to the agency that contributed to the 

Invention.

Array v1 body

agency The federal government agency that 

made an award that was used to 

support the conception of the Invention 

or its first actual reduction to practice. 

Refer to Section 11.1.8 Agency Mapping 

List for a list of valid abbreviations.

Yes String 80

grantNumber The corresponding grant or contract 

number. The format of the grant or 

contract number is specified by the 

associated agency.

Yes String 40

awardType Identifies if an award is a primary award 

or sub-award. Refer to Section 11.1.4 

Award Type for a list of valid values.

String 5

agreementType Identify cooperative agreement type of 

an agency agreement. Refer to Section 

11.1.5 Agreement Types for a list of 

valid values.

String 80

18 subContractInfos Subcontractor Information Array v1 body

subContractNumber An additional grant or contract number 

for an Invention or Patent.

Yes String 150

contractorName The name of the subcontractor that 

provided the grant or contract.

String 120

contractorDUNS The DUNS number of the subcontractor 

that provided the grant or contract.

String 9

contractorCity The city of the subcontractor that 

provided the grant or contract.

String 35

contractorState The state of the subcontractor that 

provided the grant or contract. Refer to 

Section 11.1.10 States List for a list of 

valid Code values.

String 2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

10

Table 6-3: inventionRequest JSON Attribute List

No. JSON Attribute Name Description Required Data Type Length Version In

contractorCountry The country name of the subcontractor 

that provided the grant or contract. 

Refer to 11.1.9 Country List for a list of 

valid country Name values.

String 15

19 inventionStatus The Title Election Status No JSON Object v1

titleElectionStatus The current status of the title to rights 

in the reported Invention. Refer to 

Section 11.1.11 Title Election Status for 

a list of valid values.

String 80

titleElectionDate The legally binding date that the 

grantee/contractor elected to retain 

title to an Invention. MM/DD/YYYY 

format.

String 10

notElectTitleReason This field is for the grantee/contractor 

to select the reason for 

titleElectionStatus is ‘Does Not Retain 

Title’ in an Invention Report. Refer to 

11.1.19 Invention Does Not Retain Title 

Reason for a list of valid values.

String 255

notElectTitleOtherReason If the titleElectionStatus is ‘Does Not 

Retain Title’ and notElectTitleReason is 

‘Other’, this field is used to provide the 

description of the custom reason for 

not electing title.

String 255

doesNotRetainTitleDate The date the grantee/contractor chose 

to Not Elect Title or retain Title in an 

Invention Report. MM/DD/YYYY format.

String 10

dispositionRightsDate The date the government decided on 

the disposition of rights. MM/DD/YYYY.

String 10

20 explanatoryNotes Explanatory notes may be used to note 

information about an Invention Report 

or Patent Report.

No JSON Object v1

note Explanatory notes may 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

21 governmentNotes Government Notes. 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

22 budgetIdentifiers This contains a list of Budget Identifiers 

for the Invention report.

No Array [String] v1

23 agencyCustom1 Agency custom note field only available 

for agency users.

No String 2000 v1

24 agencyCustom2 Agency custom note field only available 

for agency users.

No String 2000 v1

25 agencyCustom3 Agency custom note field only available 

for agency users.

No String 2000 v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

11

Table 6-3: inventionRequest JSON Attribute List

Please send the following parameters for Binary Attachments as a form-data File element along with the 

above Invention JSON Object Text element.

Note: The allowed file types for Invention disclosure document are (csv, gif, jpeg, jpg, png, pdf, docx, doc, tiff, tif, txt, xls, xlsx, ppt, 

pptx, odt, rtf.) Max File Size: 25MB

6.1.3. Response Parameters

This section documents the different responses based on the HTTP Status Code

HTTP Status 200 (OK) 

When the request parameters process and create an Invention successfully, the Create 

Invention API endpoint returns the below response parameters.

Table 6-4: Invention Create API Success JSON Attribute List

Response JSON Attribute Name Description Data Type Ver.

inventionReportNumber Automatically generated by the iEdison 

system for a new Invention Report after 

data has been submitted, checked for 

errors, and verified.

String v1

granteeOrganizationName The name of the organization 

established at registration.

String v1

institutionCode The unique code assigned to the 

reporting organizations.

String v1

dunsNumber The Data Universal Numbering System 

(DUNS) number provided by Dun &

Bradstreet that identifies the 

grantee/contractor.

String v1

Table 6-3: inventionRequest JSON Attribute List

No. JSON Attribute Name Description Required Data Type Length Version In

26 governmentStaff Used to identify government staff. No String 200 v1

27 governmentCounsel Used to identify the Government 

Counsel (law firm) for an Invention 

Report.

No String 200 v1

Request Parameter Description Required Data Type Length Version In

inventionDisclosure Invention Disclosure document 

containing the written description of 

the Invention, a signed copy of the 

government Confirmatory License, and 

the Government Support Clause which 

is in a Patent or Patent application. 

Yes File v1 body
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

12

Table 6-4: Invention Create API Success JSON Attribute List

Response JSON Attribute Name Description Data Type Ver.

inventionTitle The title of the Invention as it appears in 

the grantee/contractor employee’s 

Invention Report.

String v1

inventionDocketNumber An internal reference number of the 

grantee/contractor organization to help 

track a reported Invention(s).

String v1

doesNumber The DOE S-number assigned to each 

DOE Invention. The number is mainly 

used in DOE’s Invention tracking system.

String v1

parentInventionNumber Invention Report number used when an 

Invention is combined into another 

Invention as a parent Invention.

String v1

inventionReportDate The date the inventor discloses the 

subject Invention in writing to the 

recipient institution. 

String v1

inventionSubmitDate The date when the Invention is 

submitted to the agency.

String v1

reportingOverdue Invention Reporting Overdue field to 

indicate if the Invention is submitted 

outside the limit of 60 days or 6 months.

boolean v1

firstPublicationDate The date of first publication, on sale, or 

public use initiating the one-year 

statutory period wherein valid Patent 

protection can still be obtained in the 

United States.

String v1

domesticManufactureWaiver Used to indicate whether a Domestic 

Manufacture Waiver was requested by 

the organization.

Boolean v1

doeWaiver DOE Waiver. String v1

institutionCodeForOtherInstitutions Institution code for other organizations 

to view the Invention. A maximum of 

three additional iEdison registered 

organizations may be granted view-only 

access to an Invention Report.

Array 

[String]

v1

keywords This contains a list of keywords for the 

Invention report.

Array 

[String]

v1

isInventionUnderFundingAgreement Invention under Funding Agreement. Boolean v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

13

Table 6-4: Invention Create API Success JSON Attribute List

Response JSON Attribute Name Description Data Type Ver.

inventors List of Inventors Array v1

firstName First name of an inventor. String v1

lastName Last name of an inventor. String v1

middleInitial Middle initial of an inventor. String v1

fedEmployee Is the inventor a federal employee? Boolean v1

fedAgency If the inventor is a federal employee, 

what agency does the inventor work 

for? Refer to Section 11.1.8 Agency 

Mapping List for a list of valid 

abbreviations.

String v1

primaryAgency A Primary Agency must be designated 

for each Invention Report in iEdison. 

Refer to Section 11.1.8 Agency Mapping 

List for a list of valid abbreviations.

String v1

fundingAgreements The funding agreement is identified and 

reported in two parts, the Agency 

Designation (the acronym for the 

Federal Agency name) and the grant or 

contract award number corresponding 

to the agency that contributed to the 

Invention.

Array v1

agency The federal government agency that 

made an award that was used to 

support the conception of the Invention 

or its first actual reduction to practice. 

Refer to Section 11.1.8 Agency Mapping 

List for a list of valid abbreviations.

String v1

grantNumber The corresponding grant or contract 

number. The format of the grant or 

contract number is specified by the 

associated agency.

String v1

awardType Identify if an award is a primary award 

or sub-award. Refer to Section 11.1.4 

Award Type for a list of valid values.

String v1

agreementType Identify cooperative agreement type of 

an agency agreement. Refer to Section 

11.1.5 Agreement Types for a list of 

valid values.

String v1

subContractInfos Subcontractor Information Array v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

14

Table 6-4: Invention Create API Success JSON Attribute List

Response JSON Attribute Name Description Data Type Ver.

subContractNumber An additional grant or contract number 

for an Invention or Patent.

String v1

contractorName The name of the subcontractor that 

provided the grant or contract.

String v1

contractorDUNS The DUNS number of the subcontractor 

that provided the grant or contract.

String v1

contractorCity The city of the subcontractor that 

provided the grant or contract.

String v1

contractorState The state of the subcontractor that 

provided the grant or contract. Refer to 

Section 11.1.10 States List for a list of 

valid Code values.

String v1

contractorCountry The country of the subcontractor that 

provided the grant or contract. Refer to 

11.1.9 Country List for a list of valid 

country Name values.

String v1

inventionStatus The Title Election Status JSON 

Object

v1

titleElectionStatus The current status of the title to rights in 

the reported Invention. Refer to Section 

11.1.11 Title Election Status for a list of 

valid values.

String v1

titleElectionDate The legally binding date that the 

grantee/contractor elected to retain 

title to an Invention.

String v1

notElectTitleReason This field is for the grantee/contractor 

to select the reason for Not Elect Title 

where titleElectionStatus is ‘Does Not 

Retain Title’ in an Invention Report. 

Refer to 11.1.19 Invention Does Not 

Retain Title Reason for a list of valid 

values.

String v1

notElectTitleOtherReason If the Invention Report status or Patent 

Status selected is Not Elect Title and the 

Not Elect Title Reason selected is Other, 

this field is for a clear description of the 

other reason for not electing title.

String v1

dispositionStatus Government’s decision/outcome of the 

disposition of rights. Refer to Section 

11.1.12 Invention Disposition for a list of 

valid values.

String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

15

Table 6-4: Invention Create API Success JSON Attribute List

Response JSON Attribute Name Description Data Type Ver.

dispositionRightsDate The date the government decided on 

the disposition of rights.

String v1

doesNotRetainTitleDate The date the grantee/contractor chose 

to Not Elect Title or Retain Title in an 

Invention Report.

String v1

explanatoryNotes Explanatory Notes JSON 

Object

v1

note Explanatory notes may 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.

String v1

creatorName The full name of the user who entered 

the Explanatory Note.

String v1

createdDate The date when the user entered the 

Explanatory Note. MM/DD/YYYY format.

String v1

governmentNotes Government Notes 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.

String v1

creatorName The full name of the user who entered 

the Explanatory Note.

String v1

createdDate The date when the user entered the 

Explanatory Note. MM/DD/YYYY format.

String v1

budgetIdentifiers This contains a list of Budget Identifiers 

for the Invention report.

Array 

[String]

v1

agencyCustom1 Agency custom note field only available 

for agency users.

String v1

agencyCustom2 Agency custom note field only available 

for agency users.

String v1

agencyCustom3 Agency custom note field only available 

for agency users.

String v1

governmentStaff Used to identify government staff. String v1

governmentCounsel Used to identify the Government 

Counsel (law firm) for an Invention 

Report.

String v1

disclosureDocumentAcceptDate Disclosure document accept date. Date v1

disclosureDocumentRejectDate Disclosure document reject date. Date v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

16

Table 6-4: Invention Create API Success JSON Attribute List

Response JSON Attribute Name Description Data Type Ver.

disclosureDocumentRejectReasons Disclosure document reject reasons. Array 

[String]

v1

createdDate The date created in the iEdison system 

for the Invention Record.

String v1

lastUpdatedDate The date last updated in the iEdison 

system for the Invention Report.

String v1

Table 6-4: Invention Create API Success JSON Attribute List

HTTP Status 400 (Bad Request) and HTTP Status 500 (Internal Server Error) 

When the system found know errors related to validation or JSON formatting, the system will 

return the following response in JSON format.

Table 6-5: Invention Create API Error 400 and 500 JSON Attribute List

Error Response JSON 

Attribute Name

Description Data 

Type

Ver.

responseCode Response Code. String v1

message Response Message. String v1

errors Errors JSON 

Object

v1

code Error Code. String v1

field Error Field of the parameter that fails validation or 

cause the error.

String v1

message Error Message. String v1

Table 6-5: Invention Create API Error 400 and 500 JSON Attribute List

HTTP Status 401 (Unauthorized) 

Table 6-6: Invention Create API Unauthorized JSON

6.1.4. Request and Response Examples

This section documents the request and response examples for the create Invention API.

Example for inventionRequest JSON 

A sample request for the Invention Create REST API is shown below:

{

 "institutionCode": "7654321",

Table 6-6: Invention Create API Unauthorized JSON

Unauthorized JSON 

Attribute Name

Description Data Type Ver.

message The message to indicate Access 

Denied.

String v1

timestamp The time and date string when the 

access was denied.

String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

17

 "dunsNumber": "790934285",

 "inventionTitle": "REST – Create Invention108",

 "inventionDocketNumber": "REST-DOCK-0108",

 "doesNumber": "",

 "parentInventionNumber": "",

 "inventionReportDate": "01/31/2022",

 "firstPublicationDate": "01/31/2022",

 "isInventionUnderFundingAgreement": false,

 "keywords": ["Test Key 1", "Test Key 2"],

 "inventionStatus": {

 "titleElectionStatus": "Elect to Retain Title"

 },

 "inventors": [

 {

 "firstName": "John",

 "lastName": "Stewart",

 "fedEmployee": true,

 "middleInitial": "Q",

 "fedAgency": "NIST"

 }

 ],

 "primaryAgency": "ARMY/ARO",

 "fundingAgreements": [

 {

 "agreementType": "Grant",

 "agency": "ARMY/ARO",

 "grantNumber": "DAAH04-12-1-1234",

 "awardType": "Prime Award"

 }

 ],

 "subContractInfos": [

 {

 "contractorState": "CO",

 "contractorCity": "Denver",

 "contractorName": "James",

 "subContractNumber": "AS-787342",

 "contractorCountry": "United States",

 "contractorDUNS": "738739399"

 }

 ],

 "explanatoryNotes": [{

 "note": "This is a testing note"

 }]

}
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

18

HTTP Status 200 (OK) 

A sample response for the Invention Create REST API is shown below:

{

 "inventionReportNumber": "07654321-22-0103",

 "granteeOrganizationName": "DAN’S INSTITUTION",

 "institutionCode": "7654321",

 "dunsNumber": "123456789",

 "inventionTitle": "REST – Create Invention108",

 "inventionDocketNumber": "REST-DOCK-0108",

 "doesNumber": "",

 "parentInventionNumber": "",

 "inventionReportDate": "01/31/2022",

 "inventionSubmitDate": "06/10/2022",

 "reportingOverdue": false,

 "firstPublicationDate": "01/31/2022",

 "domesticManufactureWaiver": false,

 "doeWaiver": "",

 "isInventionUnderFundingAgreement": false,

 "keywords": [

 "Test Key 1",

 "Test Key 2"

 ],

 "inventors": [

 {

 "firstName": "John",

 "lastName": "Stewart",

 "fedEmployee": true,

 "middleInitial": "Q",

 "fedAgency": "1149"

 }

 ],

 "primaryAgency": "ARMY/ARO",

 "fundingAgreements": [

 {

 "agreementType": "Grant",

 "agency": "ARMY/ARO",

 "grantNumber": "DAAH04-12-1-1234",

 "awardType": "Prime Award"

 }

 ],

 "subContractInfos": [
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

19

 {

 "contractorState": "CO",

 "contractorCity": "Denver",

 "contractorName": "James",

 "subContractNumber": "AS-787342",

 "contractorCountry": "United States",

 "contractorDUNS": "738739399"

 }

 ],

 "inventionStatus": {

 "titleElectionStatus": "Elect to Retain Title",

 "titleElectionDate": "06/10/2022"

 },

 "explanatoryNotes": [

 {

 "note": "This is a testing note",

 "creatorName": "",

 "createdDate": "06/10/2022"

 }

 ],

 "governmentNotes": []

}

 

HTTP Status 400 (Bad Request) or 500 (Internal Server Error) 

{

 "responseCode": 400,

 "message": "JSON Validation Failed",

 "errors": [

 {

 "code": "400",

 "field": "inventionTitle",

 "message": "Invention Title value is required."

 }

 ]

}

HTTP Status 401 (Unauthorized) 

{

 "message": "Access Denied",

 "timestamp": "2022-06-10T09:58:10.534055700"

}
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

20

6.2. Update Invention

Organization users can access Invention records owned by the user’s affiliated 

organization. Agency users can access Invention records with one or more funding 

agreements provided by the user’s affiliated agency.

6.2.1. Endpoint URI

Here’s an example of the v1 endpoint for the Update Invention resource.

POST /iedison/api/v1/inventions/update

6.2.2. Request Parameters

The API POST request has the following elements:

• Headers: these are the request headers such as Accept or Content-Type. The Accept 

header parameter defines the expected response body format when the API returns 

the response. For example, you can define a response as JSON by modifying the Accept 

header. This Accept header is required in all requests. 

• Body: body contains the data which will be submitted as the post request. For example, 

when submitting a form, format data and file content are sent in the body of the 

request.

The table below provides the explanation of the update Invention POST request Header and 

Body parameters which are expected by iEdison API.

Table 6-7: Invention Update API Request Parameter

The table below shows the parameters that will be included in the JSON body during the

processing of Update Inventions Request. The below parameters are included as JSON 

object in JSON body. The JSON object represents the metadata of the Invention that 

needs to be updated:

Table 6-7: Invention Update API Request Parameter

Request 

Parameters

Description Required Data 

Type

Version In

accept Setting to application/json Yes String v1 header

inventionRequest The Invention Request JSON content. 

See Table 6-8 for JSON attribute list.

Yes String v1 formdata

inventionDisclosure The Invention disclosure document 

for updating the document in 

iEdison.

No Binary v1 formdata
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

21

Table 6-8: inventionRequest for Invention Update API

JSON Attribute Name Description Required Data Type LGT. Ver. In

inventionReportNumber Automatically generated by the iEdison 

system for a new Invention Report after 

data has been submitted, checked for 

errors, and verified.

Yes String 25 v1 body

granteeOrganizationName The name of the organization established 

at registration.

No String 100 v1 body

institutionCode The unique code is assigned to the 

reporting organizations.

Yes String 10 v1 body

dunsNumber The Data Universal Numbering System 

(DUNS) number provided by Dun & 

Bradstreet that identifies the 

grantee/contractor.

No String 9 v1 body

inventionTitle The title of the Invention as it appears in 

the grantee/contractors employee’s 

Invention Report.

Yes String 255 v1 body

inventionDocketNumber An internal reference number of the 

grantee/contractor organization to help 

track a reported Invention(s).

No String 30 v1 body

doesNumber The DOE S-number is assigned to each DOE 

Invention. The number is mainly used in 

DOE’s Invention tracking system.

No String 15 v1 body

parentInventionNumber Invention Report number used when an 

Invention is combined into another 

Invention as a parent Invention.

No String 25 v1 body

inventionReportDate The date that the inventor discloses the 

subject Invention in writing to the recipient 

institution. MM/DD/YYYY format.

Yes String 10 v1 body

firstPublicationDate The date of first publication, on sale, or 

public use initiating the one-year statutory 

period wherein valid Patent protection can 

still be obtained in the United States. 

MM/DD/YYYY format.

No String 10 v1 body

inventionSubmitDate The date when Invention is submitted to 

agency. MM/DD/YYYY format.

No String 10 v1 body

keywords This field enables the grantee/contractor 

organization to designate key terms for 

searching for Invention Reports.

No Array 

[String]

80 v1 body

doeWaiver DOE Waiver. No String v1 body

institutionCodeForOtherInstitutions Institution code for other organizations to 

view Inventions and other related parents. 

A maximum of three additional iEdison 

registered organizations may be granted 

view-only access to an Invention Report.

No Array 

[String]

v1 body
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

22

Table 6-8: inventionRequest for Invention Update API

JSON Attribute Name Description Required Data Type LGT. Ver. In

isInventionUnderFundingAgreement Invention under Funding Agreement. No boolean v1 body

inventors List of Inventors Yes Array v1 body

firstName First name of an inventor. Yes String 80 v1

lastName Last name of an inventor. Yes String 80 v1

middleInitial Middle initial of an inventor. No String 30 v1

fedEmployee Is the inventor a federal employee? No boolean 1 v1

fedAgency If the inventor is a federal employee, what 

agency does the inventor work for? Refer 

to Section 11.1.8 Agency Mapping List for a 

list of valid abbreviations.

No String 80 v1

primaryAgency A Primary Agency must be designated for 

each Invention Report in the iEdison. Refer 

to Section 11.1.8 Agency Mapping List for a 

list of valid abbreviations.

Yes String 50 v1 body

fundingAgreements The funding agreement is identified and 

reported in two parts, the Agency 

Designation (the acronym for the Federal 

Agency name) and the grant or contract 

award number corresponding to the 

agency that contributed to the Invention.

Yes Array v1 body

agency The federal government agency that made 

an award that was used to support the 

conception of the Invention or its first 

actual reduction to practice. Refer to 

Section 11.1.8 Agency Mapping List for a 

list of valid abbreviations.

Yes String 80 v1

grantNumber The corresponding grant or contract 

number. The format of the grant or 

contract number is specified by the 

associated agency.

Yes String 40 v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

23

Table 6-8: inventionRequest for Invention Update API

JSON Attribute Name Description Required Data Type LGT. Ver. In

awardType Identify if an award is a primary award or 

sub-award. Refer to Section 11.1.4 Award 

Type for a list of valid values.

No String 5 v1

agreementType Identify cooperative agreement type of an 

agency agreement. Refer to Section 11.1.5 

Agreement Types for a list of valid values.

No String 80 v1

subContractInfos Subcontractor Information Array v1 body

subContractNumber An additional grant or contract number for 

an Invention or Patent

Yes String 150 v1

contractorName The name of the subcontractor that 

provided the grant or contract.

No String 120 v1

contractorDUNS The DUNS number of the subcontractor 

that provided the grant or contract.

No String 9 v1

contractorCity The city of the subcontractor that provided 

the grant or contract.

No String 35 v1

contractorState The state of the subcontractor that 

provided the grant or contract. Refer to 

Section 11.1.10 States List for a list of valid 

Code values.

No String 2 v1

contractorCountry The country of the subcontractor that 

provided the grant or contract. Refer to 

11.1.9 Country List for a list of valid country 

Name values.

No String 15 v1

inventionStatus The Title Election Status No JSON 

Object

v1

titleElectionStatus The current status of the title to rights in 

the reported Invention. Refer to Section 

11.1.11 Title Election Status for a list of 

valid values.

Yes String 80 v1

titleElectionDate The legally binding date that the 

grantee/contractor elected to retain title 

to an Invention. MM/DD/YYYY format.

No String 10 v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

24

Table 6-8: inventionRequest for Invention Update API

JSON Attribute Name Description Required Data Type LGT. Ver. In

notElectTitleReason This field is for the grantee/contractor to 

select the reason for choosing to Not Elect 

Title where titleElectionStatus is ‘Does Not 

Retain Title’ in an Invention Report. Refer 

to 11.1.19 Invention Does Not Retain Title 

Reason for a list of valid values.

No String 255 v1

notElectTitleOtherReason If the titleElectionStatus is ‘Does Not Elect 

Title’ and the notElectTitleReason is 

‘Other’, this field is used to provide 

description of the custom reason for not 

electing title.

No String 255 v1

doesNotRetainTitleDate The date the grantee/contractor chose to 

Not Elect Title or retain Title in an 

Invention Report. MM/DD/YYYY format.

No String 10 v1

dispositionRightsDate The date the government decided on the 

disposition of rights. MM/DD/YYYY format. 

This is a Read Only field.

No String 10 v1

explanatoryNotes Explanatory notes may be used to note 

information about the report.

No JSON 

Object

v1

note Explanatory notes may 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.

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

budgetIdentifiers This contains a list of Budget Identifiers for 

the Invention report.

No Array 

[String]

v1 body

agencyCustom1 Agency custom note field only available for 

agency users.

No String 2000 v1 body

agencyCustom2 Agency custom note field only available for 

agency users.

No String 2000 v1 body

agencyCustom3 Agency custom note field only available for 

agency users.

No String 2000 v1 body
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

25

Table 6-8: inventionRequest for Invention Update API

JSON Attribute Name Description Required Data Type LGT. Ver. In

governmentStaff Used to identify government staff. No String 200 v1 body

governmentCounsel Used to identify the Government Counsel 

(law firm) for an Invention Report.

No String 200 v1 body

Table 6-8: inventionRequest for Invention Update API

Please send the following parameters for Binary Attachments along with the above Invention JSON 

Object. 

Note: The allowed file types for Invention disclosure document are (csv, gif, jpeg, jpg, png, pdf, docx, doc, tiff, tif, txt, xls, xlsx, ppt, 

pptx, odt, rtf.) Max File Size:25MB

6.2.3. Response Parameters

Based on the request parameters, API provides the below response parameters.

HTTP Status 200 (OK) 

When the request parameters are process and created an Invention successfully, the Create 

Invention API endpoint provides below response parameters.

Table 6 9: Invention Update API Success JSON Attribute List

Response JSON Attribute Name Description Data Type Version

inventionReportNumber

Automatically generated by the iEdison 

system for a new Invention Report 

after data has been submitted, 

checked for errors, and verified.

String v1

granteeOrganizationName The name of the organization 

established at registration. String v1

institutionCode The unique code is assigned to the 

reporting organizations. String v1

Request 

Parameter

Description Required Data 

Type

Length Version In

inventionDisclosure Invention Disclosure document 

containing the written description 

of the Invention, a signed copy of 

the government Confirmatory 

License, and the Government 

Support Clause which is in a 

Patent or Patent application. 

No File v1 form-data
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

26

Table 6 9: Invention Update API Success JSON Attribute List

Response JSON Attribute Name Description Data Type Version

dunsNumber

The Data Universal Numbering System 

(DUNS) number provided by Dun & 

Bradstreet that identifies the 

grantee/contractor.

String v1

inventionTitle

The title of the Invention as it appears 

in the grantee/contractors employee’s 

Invention Report.

String v1

inventionDocketNumber

An internal reference number of the 

grantee/contractor organization to 

help track a reported Invention(s).

String v1

doesNumber

The DOE S-number is assigned to each 

DOE Invention. The number is mainly 

used in DOE’s Invention tracking 

system.

String v1

parentInventionNumber

Invention Report number used when 

an Invention is combined into another 

Invention as a parent Invention.

String v1

inventionReportDate

The date the inventor discloses the 

subject Invention in writing to the 

recipient institution. 

String v1

inventionSubmitDate The date when the Invention is 

submitted to the agency. String v1

reportingOverdue

Invention Reporting Overdue field to 

indicate if Invention is submitted 

outside the 60 days or 6 months limit.

boolean v1

firstPublicationDate

The date of first publication, on sale, or 

public use initiating the one-year 

statutory period wherein valid Patent 

protection can still be obtained in the 

United States.

String v1

domesticManufactureWaiver

Used to indicate whether a Domestic 

Manufacture Waiver was requested by 

the organization.

Boolean v1

doeWaiver DOE Waiver. String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

27

Table 6 9: Invention Update API Success JSON Attribute List

Response JSON Attribute Name Description Data Type Version

institutionCodeForOtherInstitutions

Institution code for other organizations 

to view the Invention. A maximum of 

three additional iEdison registered 

organizations may be granted viewonly access to an Invention Report.

Array [String] v1

keywords This contains a list of keywords for the 

Invention report. Array [String] v1

inventors List of Inventors Array v1

firstName First name of an inventor. String v1

lastName Last name of an inventor. String v1

middleInitial Middle initial of an inventor. String v1

fedEmployee Is the inventor a federal employee? Boolean v1

fedAgency

If the inventor is a federal employee, 

what agency does the inventor work 

for? Refer to Section 11.1.8 Agency 

Mapping List for a list of valid 

abbreviations.

String v1

primaryAgency

A Primary Agency must be designated 

for each Invention Report in the 

iEdison. Refer to Section 11.1.8 Agency 

Mapping List for a list of valid 

abbreviations.

String v1

fundingAgreements

The funding agreement is identified 

and reported in two parts, the Agency 

Designation (the acronym for the 

Federal Agency name) and the grant or 

contract award number corresponding 

to the agency that contributed to the 

Invention.

Array v1

agency

The federal government agency that 

made an award that was used to 

support the conception of the 

Invention or its first actual reduction to 

practice. Refer to Section 11.1.8 

Agency Mapping List for a list of valid 

abbreviations.

String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

28

Table 6 9: Invention Update API Success JSON Attribute List

Response JSON Attribute Name Description Data Type Version

grantNumber

The corresponding grant or contract 

number. The format of the grant or 

contract number is specified by the 

associated agency.

String v1

awardType

Identify if an award is a primary award 

or sub-award. Refer to Section 11.1.4 

Award Type for a list of valid values.

String v1

agreementType

Identify cooperative agreement type of 

an agency agreement. Refer to Section 

11.1.5 Agreement Types for a list of 

valid values.

String v1

subContractInfos Subcontractor Information Array v1

subContractNumber An additional grant or contract number 

for an Invention or Patent. String v1

contractorName The name of the subcontractor that 

provided the grant or contract. String v1

contractorDUNS

The DUNS number of the 

subcontractor that provided the grant 

or contract.

String v1

contractorCity The city of the subcontractor that 

provided the grant or contract. String v1

contractorState

The state of the subcontractor that 

provided the grant or contract. Refer to 

Section 11.1.10 States List for a list of 

valid Code values.

String v1

contractorCountry

The country of the subcontractor that 

provided the grant or contract. Refer to 

11.1.9 Country List for a list of valid 

country Name values.

String v1

inventionStatus The Title Election Status JSON Object v1

titleElectionStatus

The current status of the title to rights 

in the reported Invention. Refer to 

Section 11.1.11 Title Election Status for 

a list of valid values.

String v1

titleElectionDate

The legally binding date that the 

grantee/contractor elected to retain 

title to an Invention.

String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

29

Table 6 9: Invention Update API Success JSON Attribute List

Response JSON Attribute Name Description Data Type Version

notElectTitleReason

This field is for the grantee/contractor 

to select the reason for choosing to 

Not Elect Title where 

titleElectionStatus is ‘Does Not Retain 

Title’ in an Invention Report. Refer to 

11.1.19 Invention Does Not Retain Title 

Reason for a list of valid values.

String v1

notElectTitleOtherReason

If the titleElectionStatus is ‘Does Not 

Elect Title’ and the notElectTitleReason 

is ‘Other’, this field is used to provide a 

description of the custom reason for 

not electing title.

String v1

dispositionStatus

Government’s decision/outcome of the 

disposition of rights. Refer to Section 

Invention Disposition for a list of valid 

values.

String v1

dispositionRightsDate The date the government decided on 

the disposition of rights. String v1

doesNotRetainTitleDate

The date the grantee/contractor chose 

to Not Elect Title or retain Title in an 

Invention Report.

String v1

explanatoryNotes Explanatory Notes JSON Object v1

note

Explanatory notes may 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.

String v1

creatorName The full name of the user who entered 

the Explanatory Note. String v1

createdDate

The date when the user entered the 

Explanatory Note. MM/DD/YYYY 

format.

String v1

governmentNotes Government Notes 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.

String v1

creatorName The full name of the user who entered 

the Explanatory Note. String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

30

Table 6 9: Invention Update API Success JSON Attribute List

Response JSON Attribute Name Description Data Type Version

createdDate

The date when the user entered the 

Explanatory Note. MM/DD/YYYY 

format.

String v1

budgetIdentifiers This contains a list of Budget Identifiers 

for the Invention report. Array [String] v1

agencyCustom1 Agency custom note field only available 

for agency users. String v1

agencyCustom2 Agency custom note field only available 

for agency users. String v1

agencyCustom3 Agency custom note field only available 

for agency users. String v1

governmentStaff Used to identify government staff. String v1

governmentCounsel

Used to identify the Government 

Counsel (law firm) for an Invention 

Report.

String v1

disclosureDocumentAcceptDate Disclosure document accept date. Date v1

disclosureDocumentRejectDate Disclosure document reject date. Date v1

disclosureDocumentRejectReasons Disclosure document reject reasons. Array [String] v1

createdDate The date created in the iEdison system 

for the Invention Record. String v1

lastUpdatedDate The date last updated in the iEdison 

system for the Invention Report. String v1

Table 6-9: Invention Update API Success JSON Attribute List

HTTP Status 400 (Bad Request) and HTTP Status 500 (Internal Server Error) 

When the system found know errors related to validation or JSON formatting, the system will 

return the following response in JSON format.

Table 6 10: Invention Update API Error 400 and 500 JSON Attribute List

Error Response JSON 

Attribute Name Description Data Type Version

responseCode Response Code String v1

message Response Message String v1

errors Errors JSON 

Object v1

code Error Code String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

31

field

Error Field of the parameter that 

fails validation or cause the 

error.

String v1

message Error Message String v1

Table 6-10: Invention Update API Error 400 and 500 JSON Attribute List

HTTP Status 401 (Unauthorized) 

Table 6-11: Invention Update API Unauthorized JSON

6.2.4. Request and Response Examples

This section documents the request and response examples for the create Invention API.

Example for inventionRequest JSON 

A sample request for the Invention Create REST API is shown below:

{

 "inventionReportNumber": "07654321-22-0103",

 "institutionCode": "7654321",

 "dunsNumber": "790934285",

 "inventionTitle": "REST – Create Invention108",

 "inventionDocketNumber": "REST-DOCK-0108",

 "doesNumber": "",

 "parentInventionNumber": "",

 "inventionReportDate": "01/31/2022",

 "firstPublicationDate": "01/31/2022",

 "isInventionUnderFundingAgreement": false,

 "keywords": ["Test Key 1", "Test Key 2", "Test Update Key3"],

 "inventionStatus": {

 "titleElectionStatus": "Elect to Retain Title"

 },

 "inventors": [

 {

 "firstName": "John",

 "lastName": "Stewart",

 "fedEmployee": true,

 "middleInitial": "Q",

 "fedAgency": "NIST"

 }

 ],

 "primaryAgency": "ARMY/ARO",

Table 6 11: Invention Update API Unauthorized JSON

Unauthorized JSON Attribute 

Name

Description Data Type Version

message The message to indicate Access Denied. String v1

timestamp The time and date string when the 

access was denied.

String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

32

 "fundingAgreements": [

 {

 "agreementType": "Grant",

 "agency": "ARMY/ARO",

 "grantNumber": "DAAH04-12-1-1234",

 "awardType": "Prime Award"

 }

 ],

 "subContractInfos": [

 {

 "contractorState": "CO",

 "contractorCity": "Denver",

 "contractorName": "James",

 "subContractNumber": "AS-787342",

 "contractorCountry": "United States",

 "contractorDUNS": "738739399"

 }

 ],

 "explanatoryNotes": [{

 "note": "This is a testing note"

 }, 

 {

 "note": "This is an update note to update keyword"

 }

 ]

}

HTTP Status 200 (OK) 

A sample response for the Invention Updated REST API is shown below:

{

 "inventionReportNumber": "07654321-22-0103",

 "granteeOrganizationName": "DAN’S INSTITUTION",

 "institutionCode": "7654321",

 "dunsNumber": "123456789",

 "inventionTitle": "REST – Create Invention108",

 "inventionDocketNumber": "REST-DOCK-0108",

 "doesNumber": "",

 "parentInventionNumber": "",

 "inventionReportDate": "01/31/2022",

 "inventionSubmitDate": "06/10/2022",

 "reportingOverdue": false,

 "firstPublicationDate": "01/31/2022",

 "domesticManufactureWaiver": false,

 "doeWaiver": "",
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

33

 "institutionCodeForOtherInstitutions": [],

 "isInventionUnderFundingAgreement": false,

 "keywords": [

 "Test Key 1",

 "Test Key 2",

 "Test Update Key3"

 ],

 "inventors": [

 {

 "firstName": "John",

 "lastName": "Stewart",

 "fedEmployee": true,

 "middleInitial": "Q",

 "fedAgency": "NIST"

 }

 ],

 "primaryAgency": "ARMY/ARO",

 "fundingAgreements": [

 {

 "agreementType": "Grant",

 "agency": "ARMY/ARO",

 "grantNumber": "DAAH04-12-1-1234",

 "awardType": "Prime Award"

 }

 ],

 "subContractInfos": [

 {

 "contractorState": "CO",

 "contractorCity": "Denver",

 "contractorName": "James",

 "subContractNumber": "AS-787342",

 "contractorCountry": "United States",

 "contractorDUNS": "738739399"

 }

 ],

 "inventionStatus": {

 "titleElectionStatus": "Elect to Retain Title",

 "titleElectionDate": "06/10/2022"

 },

 "explanatoryNotes": [

 {

 "note": "This is a testing note",

 "creatorName": "",

 "createdDate": "06/10/2022"

 },
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

34

 {

 "note": "This is an update note to update keyword",

 "creatorName": "",

 "createdDate": "06/10/2022"

 }

 ],

 "governmentNotes": []

}

HTTP Status 400 (Bad Request) or 500 (Internal Server Error) 

{

 "responseCode": 400,

 "message": "JSON Validation Failed",

 "errors": [

 {

 "code": "400",

 "field": " inventionReportNumber ",

 "message": "Invention Report Number value is required."

 }

 ]

}

HTTP Status 401 (Unauthorized) 

{

 "message": "Access Denied",

 "timestamp": "2022-06-10T09:58:10.534055700"

}

6.3. Search Invention

Any desired combination of the attributes can be used to perform the Invention report 

search. The search will encompass all the Invention reports from user’s organization and 

from other organizations that have granted the user permission to view their Invention

reports. Once the user finds the Invention report, they will be able to modify the 

Invention, add a Patent report, or add a utilization report.

6.3.1. Endpoint URI

Here’s an example of the v1 endpoint for the Search Invention resource.

POST /iedison/api/v1/inventions/search
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

35

6.3.2. Request Parameters

The API POST request has the following elements:

• Headers: these are the request headers such as Accept or Content-Type. The Accept 

header parameter defines the expected response body format when the API returns 

the response. For example, you can define a response as JSON by modifying the Accept 

header. This Accept header is required in all requests. 

• Body: body contains the data which will be submitted as the post request. For example, 

when submitting a form, format data and file content are sent in the body of the 

request.

The table below provides the explanation of the search Invention POST request Header and 

Body parameters which are expected by iEdison API.

Table 6-12: Invention Search API Request Parameter

Request Parameters Description Data Type Version In

accept Setting to application/json String v1 header

inventionSearchCriteria The Invention search criteria with the filters client 

selected for the search.

String v1 formdata

Table 6-12: Invention Search API Request Parameter

The table below shows the parameters that will be included in the JSON body only one 

time during the processing of Search Inventions Request.
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

36

Table 6-13

Request Parameter Description Data Type Length Version In

limit Total number of records to be 

retrieved per page. This field must 

be a number. Max Value = 100. 

The Default = 20.

Integer v1 body

offset Page index specified by a user. 

Default offset starts with 0 if user 

does not provide any offset in the 

request

Integer v1 body

inventionReportNumber Automatically generated by the 

iEdison system for a new 

Invention Report after data has 

been submitted, checked for 

errors, and verified.

String 100 v1 body

inventionDocketNumber An internal reference number of 

the grantee/contractor 

organization to help track a 

reported Invention(s)

String 30 v1 body

grantContractNumber The grant or contract number as 

specified by the agency. The 

format is defined by the agency. 

String 80 v1 body

inventorFirstName First name of an inventor. String 50 v1 body

inventorLastName Last name of an inventor. String 50 v1 body

primaryAgency A Primary Agency must be 

designated for each Invention 

Report in iEdison. Refer to Section 

11.1.8 Agency Mapping List for a 

list of valid abbreviations.

String 50 v1 body

granteeOrganizationName The name of the organization 

established at registration.

String 100 v1 body

titleElectionStatus The current status of the title to 

rights in the reported Invention.

Refer to Section 1111.1.11 Title 

Election Status for a list of valid 

values.

JSON Object 10 v1 body

inventionTitle The title of the Invention as it 

appears in the 

grantee/contractors employee’s 

Invention Report.

String 255 v1 body

inventionReportDateFrom The From Date that the inventor 

disclosed in the subject Invention

in writing to the recipient 

institution. MM/DD/YYYY format.

String 10 v1 body
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

37

Table 6-13

6.3.3. Response Parameters

This section documents the response JSON objects, attributes and types for a success or error 

response.

HTTP Status 200 (OK) 

Based on the request parameters, Search Invention API provides below response parameters.

Table 6 14: Invention Search API JSON Attributes

Response JSON Attribute 

Name

Description Data Type Version

totalRecords Total number of records for the search. Number v1

limit Limit entered by a user while making the request i.e.,

total number of records the user wished to retrieve per 

page.

Number v1

offset Page index specified by a user. Default offset starts with 0 

if user does not provide any offset in the request.

Number v1

inventions A list of Invention record with Invention Response JSON 

attributes below.

Array v1

Table 6-13: Invention Search API JSON Attributes

Table 6-13

Request Parameter Description Data Type Length Version In

inventionReportDateTo The To Date that the inventor 

disclosed in the subject Invention

in writing to the recipient 

institution. MM/DD/YYYY format.

String 10 v1 body

inventionKeyword This field enables the 

grantee/contractor organization 

to designate key terms for 

searching for Invention Reports.

String 80 v1 body

doeWaiver DOE Waiver. String v1 body

governmentCounsel Used to identify the Government 

Counsel (law firm) for an Invention 

Report.

String v1 body

governmentStaff Used to identify government staff. String v1 body

lastUpdatedFrom The ‘start from’ search date 

against the Patent last updated 

date. MM/DD/YYYY format.

String v1 body

lastUpdatedTo The ‘up to’ search date against the 

Patent last updated date. 

MM/DD/YYYY format.

String v1 body
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

38

The following is the Invention Response JSON attributes.

Table 6-15: Invention Search API – InventionResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

inventionReportNumber

Automatically generated by the iEdison 

system for a new Invention Report after 

data has been submitted, checked for 

errors, and verified.

String v1

granteeOrganizationName The name of the organization 

established at registration. String v1

institutionCode The unique code assigned to the 

reporting organizations. String v1

dunsNumber

The Data Universal Numbering System 

(DUNS) number provided by Dun &

Bradstreet that identifies the 

grantee/contractor.

String v1

inventionTitle

The title of the Invention as it appears in 

the grantee/contractors employee’s 

Invention Report.

String v1

inventionDocketNumber

An internal reference number of the 

grantee/contractor organization to help 

track a reported Invention(s).

String v1

doesNumber

The DOE S-number is assigned to each 

DOE Invention. The number is mainly 

used in DOE’s Invention tracking system.

String v1

parentInventionNumber

Invention Report number used when an 

Invention is combined into another 

Invention as a parent Invention.

String v1

inventionReportDate

The date that the inventor discloses the 

subject Invention in writing to the 

recipient institution. 

String v1

inventionSubmitDate The date when Invention is submitted to 

the agency. String v1

reportingOverdue

Invention Reporting Overdue field to 

indicate if an Invention is submitted 

outside limit of 60 days or 6 months.

boolean v1

firstPublicationDate

The date of first publication, on sale, or 

public use initiating the on- year 

statutory period wherein valid Patent 

protection can still be obtained in the 

United States.

String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

39

Table 6-15: Invention Search API – InventionResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

domesticManufactureWaiver

Used to indicate whether a Domestic 

Manufacture Waiver was requested by 

the organization.

Boolean v1

doeWaiver DOE Waiver. String v1

institutionCodeForOtherInstitutions

Institution code for other organizations 

to view the Invention. A maximum of 

three additional iEdison registered 

organizations may be granted view-only 

access to an Invention Report.

Array [String] v1

keywords This contains a list of keywords for the 

Invention report. Array [String] v1

inventors List of Inventors Array v1

firstName First name of an inventor. String v1

lastName Last name of an inventor. String v1

middleInitial Middle initial of an inventor. String v1

fedEmployee Is the inventor a federal employee? Boolean v1

fedAgency

If the inventor is a federal employee, 

what agency does the inventor work for? 

Refer to Section 11.1.8 Agency Mapping 

List for a list of valid abbreviations.

String v1

primaryAgency

A Primary Agency must be designated 

for each Invention Report in iEdison. 

Refer to Section 11.1.8 Agency Mapping 

List for a list of valid abbreviations.

String v1

fundingAgreements

The funding agreement is identified and 

reported in two parts, the Agency 

Designation (the acronym for the 

Federal Agency name) and the grant or 

contract award number corresponding 

to the agency that contributed to the 

Invention.

Array v1

agency

The federal government agency that 

made an award that was used to support 

the conception of the Invention or its 

first actual reduction to practice. Refer 

to Section 11.1.8 Agency Mapping List 

for a list of valid abbreviations.

String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

40

Table 6-15: Invention Search API – InventionResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

grantNumber

The corresponding grant or contract 

number. The format of the grant or 

contract number is specified by the 

associated agency.

String v1

awardType

Identify if an award is a primary award or 

sub-award. Refer to Section 11.1.4 

Award Type for a list of valid values.

String v1

agreementType

Identify cooperative agreement type of 

an agency agreement. Refer to Section 

11.1.5 Agreement Types for a list of valid 

values.

String v1

subContractInfos Subcontractor Information Array v1

subContractNumber An additional grant or contract number 

for an Invention or Patent. String v1

contractorName The name of the subcontractor that 

provided the grant or contract.

String v1

contractorDUNS The DUNS number of the subcontractor 

that provided the grant or contract. String v1

contractorCity The city of the subcontractor that 

provided the grant or contract. String v1

contractorState

The state of the subcontractor that 

provided the grant or contract. Refer to 

Section11 States List for a list of valid 

Code values.

String v1

contractorCountry

The country of the subcontractor that 

provided the grant or contract. Refer to 

11.1.9 Country List for a list of valid 

country Name values.

String v1

inventionStatus The Title Election Status and Disposition 

status JSON object JSON Object v1

titleElectionStatus

The current status of the title to rights in 

the reported Invention. Refer to Section 

11.1.11 Title Election Status for a list of 

valid values.

String v1

titleElectionDate

The legally binding date that the 

grantee/contractor elected to retain title 

to an Invention.

String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

41

Table 6-15: Invention Search API – InventionResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

notElectTitleReason

This field is for the grantee/contractor to 

select the reason for choosing to Does 

Not Retain Title in an Invention Report. 

Refer to 11.1.19 Invention Doe s Not 

Retain Title Reason for a list of valid 

values.

String v1

notElectTitleOtherReason

If the titleElectionStatus is ‘Does Not 

Retain Title’ and notElectTitleReason is 

‘Other’, this field is used to provide the 

description of the custom reason for not 

electing title.

String v1

dispositionStatus

Government’s decision/outcome of the 

disposition of rights. Refer to Section 

11.1.12 Invention Disposition for a list of 

valid values.

String v1

dispositionRightsDate The date the government decided on the 

disposition of rights. String v1

doesNotRetainTitleDate

The date the grantee/contractor chose 

to Not Elect Title or retain Title in an 

Invention Report.

String v1

explanatoryNotes Explanatory Notes JSON Object v1

note

Explanatory notes may 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.

String v1

creatorName The full name of the user who entered 

the Explanatory Note. String v1

createdDate The date when the user entered the 

Explanatory Note. MM/DD/YYYY format. String v1

governmentNotes Government Notes which only return for 

agency system users.

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.

String v1

creatorName The full name of the user who entered 

the Government Note. String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

42

Table 6-15: Invention Search API – InventionResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

createdDate

The date when the user entered the 

Government Note. MM/DD/YYYY 

format.

String v1

budgetIdentifiers This contains a list of Budget Identifiers 

for the Invention report. Array [String] v1

agencyCustom1 Agency custom note field only available 

for agency users. String v1

agencyCustom2 Agency custom note field only available 

for agency users. String v1

agencyCustom3 Agency custom note field only available 

for agency users. String v1

governmentStaff Used to identify government staff. String v1

governmentCounsel

Used to identify the Government 

Counsel (law firm) for an Invention 

Report.

String v1

disclosureDocumentAcceptDate Disclosure document accept date Date v1

disclosureDocumentRejectDate Disclosure document reject date Date v1

disclosureDocumentRejectReasons Disclosure document reject reasons Array [String] v1

createdDate The date created in the iEdison system 

for the Invention Record. String v1

lastUpdatedDate The date last updated in the iEdison 

system for the Invention Report. String v1

Table 6-14: Invention Search API – InventionResponse JSON Attributes

HTTP Status 400 (Bad Request) and HTTP Status 500 (Internal Server Error) 

When the system finds known errors related to validation or JSON formatting, it will return the 

following response in JSON format.

Table 6-16: Invention Search API Error 400 and 500 JSON Attribute List

Error Response JSON Attribute Name Description Data Type Version

responseCode Response Code String v1

message

Response 

Message String v1

errors Errors JSON Object v1

code Error Code String v1

field

Error Field of the 

parameter that 

fails validation 

String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

43

Table 6-16: Invention Search API Error 400 and 500 JSON Attribute List

Error Response JSON Attribute Name Description Data Type Version

or cause the 

error.

message Error Message String v1

Table 6-15: Invention Search API Error 400 and 500 JSON Attribute List

HTTP Status 401 (Unauthorized) 

Table 6-16: Invention Search API Unauthorized JSON

6.3.4. Request and Response Example

A sample request for the Search Invention REST API is shown below:

{

 "primaryAgency": "NIST",

 "inventionReportDateFrom": "2015-01-01",

 "inventionReportDateTo": "2015-12-31",

 "grantContractNumber": "60NANB14D279"

}

A sample response for the Search Invention REST API is shown below:

{

 "inventions": [

 {

 "granteeOrganizationName": "UNIV OF MARYLAND, COLLEGE PARK",

 "institutionCode": "0820102",

 "dunsNumber": "790934285",

 "inventionTitle": "The Cyber Supply Chain Risk Management Portal",

 "inventionDocketNumber": "IS-2015-016",

 "doesNumber": "",

 "parentInventionNumber": "",

 "inventionReportDate": "01/29/2015",

Table 6 17: Invention Search API Unauthorized JSON

Unauthorized JSON Attribute 

Name

Description Data Type Version

message The message to indicate Access Denied. String v1

timestamp The time and date string when the 

access was denied.

String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

44

 "inventionSubmitDate": "07/28/2017",

 "reportingOverdue": false,

 "domesticManufactureWaiver": false,

 "doeWaiver": "",

 "isInventionUnderFundingAgreement": false,

 "keywords": [],

 "inventionReportNumber": "0820102-15-0070",

 "inventors": [

 {

 "firstName": "Sandor",

 "lastName": "Boyson",

 "fedEmployee": false,

 "middleInitial": "",

 "fedAgency": ""

 },

 {

 "firstName": "Holly",

 "lastName": "Mann",

 "fedEmployee": false,

 "middleInitial": "",

 "fedAgency": ""

 },

 {

 "firstName": "Hart",

 "lastName": "Rossman",

 "fedEmployee": false,

 "middleInitial": "",

 "fedAgency": ""

 },

 {

 "firstName": "Thomas",

 "lastName": "Corsi",

 "fedEmployee": false,

 "middleInitial": "M.",

 "fedAgency": ""

 },

 {

 "firstName": "John",

 "lastName": "Paraskevas",

 "fedEmployee": false,

 "middleInitial": "",
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

45

 "fedAgency": ""

 },

 {

 "firstName": "Chris",

 "lastName": "Keegan",

 "fedEmployee": false,

 "middleInitial": "",

 "fedAgency": ""

 }

 ],

 "primaryAgency": "National Institute of Standards and Technology",

 "fundingAgreements": [

 {

 "agreementType": "",

 "agency": "National Institute of Standards and Technology",

 "grantNumber": "60NANB14D279",

 "awardType": ""

 }

 ],

 "subContractInfos": [],

 "inventionStatus": "NOT ELECT TITLE; ASSIGN TO OTHER PARTY",

 "explanatoryNotes": [

 {

 "note": "By: DAUERBACH_EDI\nOn: 2017-07-28\n\nI attempted to report this Invention to 

iEdison in 2015 but was unable to due to a glitch in iEdison so I reported it (as well as the release of Patent

rights) directly to the Grants Officer and Grants Specialist listed on the award document on 11/11/2015. "

 }

 ],

 "governmentNotes": []

 }

 ],

 "totalRecords": 1,

 "limit": 100,

 "offset": 0

}

HTTP Status 400 (Bad Request) and HTTP Status 500 (Internal Server Error) 

{

 "responseCode": 400,

 "message": "Invalid form-data content",

 "errors": [
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

46

 {

 "code": "400",

 "field": "inventionSearchCriteria",

 "message": "One or more parameters in request JSON are Invalid. Please verify 

and submit again : ‘primaryAgencfday’"

 }

 ]

}

HTTP Status 401 (Unauthorized) 

{

 "message": "Access Denied",

 "timestamp": "2022-06-10T09:58:10.534055700"

}

7.0. Patent API Reference

7.1. Create Patent

7.1.1. Endpoint URI

Here’s an example of the v1 endpoint for the Create Patent resource.

POST /iedison/api/v1/patents/create

7.1.2. Request Parameters

The API POST request has the following elements:

• Headers: these are the request headers such as Accept or Content-Type. The Accept 

header parameter defines the expected response body format when the API returns 

the response. For example, you can define a response as JSON by modifying the Accept 

header. This Accept header is required in all requests. 

• Body: body contains the data which will be submitted as the post request. For example, 

when submitting a form, format data and file content are sent in the body of the 

request.

The table below provides the explanation of the create Patent POST request Header and Body 

parameters which are expected by iEdison API.
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

47

Table 7-1: Patent Create API parameters

The table below shows the parameters that will be included in the JSON body during 

the processing of Create Patents Request. The below parameters are included as a 

JSON object in JSON body. The JSON object represents the metadata for the Patent 

that needs to be created.

Table 7-2: Patent Create API – patentRequest JSON Attribute List

Request Parameter Description Required Data 

Type

Length Version

inventionReportNumber

Automatically generated 

by the iEdison system for 

a new 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 field is for an 

internal reference 

number of the 

grantee/contractor 

organization to help track 

a reported Patent(s).

No Int 30 v1

patentStatus

Used to identify the 

current status of a Patent. 

Refer to Section 11.1.7 

Patent Status for a list of 

valid values.

Yes String 255 v1

Table 7-1: Patent Create API parameters

Request Parameters Description Required Data Type Version In

accept Setting to application/json. Yes String v1 header

patentRequest The Patent JSON object content use to create 

the Patent in iEdison. Refer to Table 7-2: Patent 

Create API – patentRequest JSON Attribute List 

below for details.

Yes String v1 formdata

confirmatoryLicense The Confirmatory License document file for the 

Patent record.

No File Binary v1 formdata

governmentSupportClause The Government Support Clause document file 

for the Patent record.

No File Binary v1 formdata
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

48

Table 7-2: Patent Create API – patentRequest JSON Attribute List

Request Parameter Description Required Data 

Type

Length Version

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 11.1.3 Patent 

Application Types for a list 

of valid values.

Yes String 255 v1

inventionReportNumber

Automatically generated 

by the iEdison system for 

a new 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 field is for an 

internal reference 

number of the 

grantee/contractor 

organization to help track 

a reported Patent(s).

No Int 30 v1

patentStatus

Used to identify the 

current status of a Patent. 

Refer to Section 11.1.7 

Patent Status 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 11.1.3 Patent 

Application Types for a list 

of valid values.

Yes String 255 v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

49

Table 7-2: Patent Create API – patentRequest JSON Attribute List

Request Parameter Description Required Data 

Type

Length Version

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 nonprovisional Patent 

application with the U.S. 

Patent and Trademark 

Office (USPTO). 

MM/DD/YYYY format.

Yes String 10 v1

issuedApplicationNumber The unique identifier of a 

Patent.

No String 50 v1

issuedApplicationDate

The date the Patent 

number was issued. 

MM/DD/YYYY format.

No String 10 v1

expirationDate

Estimated date of Patent 

expiration. MM/DD/YYYY 

format.

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
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

50

Table 7-2: Patent Create API – patentRequest JSON Attribute List

Request Parameter Description Required Data 

Type

Length Version

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. MM/DD/YYYY 

format.

Yes String 10 v 1

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 Intellectual 

Property Organization 

(WIPO). MM/DD/YYYY.

Yes String 10 v1

parentPatents No

JSON 

Object v1

inventionReportNumber

The unique Invention 

Report Number for the 

parent Patent.

No String 25 v1

patentDocketNumber

The Patent Docket 

Number field is for 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 v1

firstName First name of an inventor. Yes String 80 v1

lastName Last name of an inventor. Yes String 80 v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

51

Table 7-2: Patent Create API – patentRequest JSON Attribute List

Request Parameter Description Required Data 

Type

Length Version

middleInitial Middle initial of an 

inventor. No String 30 v1

fedEmployee Is the inventor a federal 

employee? No boolean v1

fedAgency

If the inventor is a federal 

employee, what agency 

does the inventor work 

for? Refer to Section 

11.1.8 Agency Mapping 

List for a list of valid 

abbreviations.

No String 80 v1

foreignFilings Patent Foreign Filing No

JSON 

Object v1

countryName

The country name of the 

foreign filing. Refer to 

11.1.9 Country List for a 

list of valid country Name 

values.

Yes String 15 v1

status

The foreign filing status 

for the Patent. Refer to 

Section 11.1.2 Patent 

Filing Status for a list of 

valid values.

Yes JSON 

Array

v1

filingDate

The date that the foreign 

Patent was issued. 

MM/DD/YYYY format.

Yes String 10 v1

explanatoryNotes

Explanatory notes may be 

used to note information 

about the report.

No JSON 

Object v1

note

Explanatory notes may 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.

No

JSON 

Object V1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

52

Table 7-2: Patent Create API – patentRequest JSON Attribute List

Request Parameter Description Required Data 

Type

Length Version

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

Table 7-2: Patent Create API – patentRequest JSON Attribute List

Please send the following parameters for Binary Attachments along with the above Patent JSON Object 

Note: The allowed file types for Confirmatory License Document are (csv, gif, jpeg, jpg, png, pdf, docx, doc, tiff, tif, txt, xls, xlsx, 

ppt, pptx, odt, rtf.) Max File Size:25MB.

Note: The allowed file types for Government Support Clause document are (csv, gif, jpeg, jpg, png, pdf, docx, doc, tiff, tif, txt, xls, 

xlsx, ppt, pptx, odt, rtf.) Max File Size:25MB

7.1.3. Response Parameters

This section documents the response JSON objects, attributes, and types for a success or error 

response.

Request Parameter Description Required Data Type Length Version

confirmatoryLicense Document that 

provides the federal 

government a nonexclusive, nontransferable, 

irrevocable, paid-up 

right to practice the 

Invention or have the 

Invention practiced 

on its behalf for 

federal government 

purposes.

Yes Binary 

Attachment

v1

governmentSupportClause Document/statement 

acknowledging 

federal support of a 

subject Invention that 

MUST be included in 

the specification of a 

U.S. Patent

application or a U.S. 

issued Patent.

Yes Binary 

Attachment

v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

53

HTTP Status 200 (OK) 

Based on the request parameters, Create Patent API provides the below response parameters.

Table 7-3: Patent Create API – PatentResponse JSON Attributes

Response Parameter Description Data Type Version

id System generated sequence 

number used for ID of the Patent Int v1

patentDocketNum

The Patent Docket Number field 

is for an internal reference 

number of the 

grantee/contractor organization 

to help track a reported Patent(s).

String v1

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

Patent Cooperation Treaty (PCT) 

number is used to uniquely 

identify a PCT type Patent 

application.

String v1

pctAppDate

This field is used for 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

This field is used for 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
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

54

Table 7-3: Patent Create API – PatentResponse JSON Attributes

Response Parameter Description Data Type Version

nonProvisionalAppDate

This field is used for either the 

filing date of the non-provisional 

Patent application with the U.S. 

Patent and Trademark Office 

(USPTO)

String v1

patentApplicationType

Patent Application Type of a 

record. Refer to Section 11.1.3 

Patent Application Types for a list 

of valid values.

String v1

patentReceiptDate Date Patent was received by 

government.

String v1

expireDate Estimated date of Patent 

expiration. 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 The Patent Status. String v1

confLicenseReceiptDate Confirmatory License Receipt 

Date.

String v1

confLicenseRejectDate Date Confirmatory License is 

rejected by Government Agency. String v1

confLicenseRejectComment

Reason for Confirmatory License 

rejection shared with the 

organization.

String v1

confLicenseOutdated Used to indicate if the 

Confirmatory License is outdated. String v1

govtSuppClauseReceiptDate

The date the Federal Support 

Clause was received by the 

government.

String v1

govtSuppClauseRejectDate

Date Government Support Clause 

inclusion is rejected by 

Government Agency.

String v1

govtSuppClauseRejectComment

Reason for Government Support 

Clause rejection displayed to 

grantee/contractor institution.

String v1

govtActionDate Government Action Date String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

55

Table 7-3: Patent Create API – PatentResponse JSON Attributes

Response Parameter Description Data Type Version

domesticWaiverDecisionFlag Used to indicate Domestic Waiver 

decision. boolean v1

domesticWaiverDecisionDate Domestic Waiver Decision Date. String v1

parentPatents Parent Patents list. JSON 

Object v1

inventionReportNumber The unique Invention Report 

Number for the parent Patent. String v1

patentDocketNumber

The Patent Docket Number 

field is for an internal 

reference number of the 

grantee/contractor 

organization to help track a 

reported Patent(s).

String v1

confirmatoryLicenseExcutionDate Confirmatory license date of 

execution for EPAS submission. String v1

abandonedReason The reason why a Patent is 

abandoned. String v1

extensionDays

Number of days Patent 

provisional application date has 

been extended.

Int v1

usptoAppStatus USPTO application status of the 

Patent.

String v1

usptoAppStatusDate Date of USPTO application. String v1

usptoLastSyncDate Date of last sync with USPTO String v1

assigned

Used to indicate if the Patent has 

been assigned to another 

organization.

boolean v1

explanatoryNotes

Explanatory notes may 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.

Array 

[JSON 

Object]

v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

56

Table 7-3: Patent Create API – PatentResponse JSON Attributes

Response Parameter Description Data Type Version

note

Explanatory notes may 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.

String v1

creatorName The full name of the user who 

entered the Explanatory Note. String v1

createdDate

The date when the user entered 

the Explanatory Note. 

MM/DD/YYYY format.

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

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.

String v1

creatorName The full name of the user who 

entered the Government Note. String v1

createdDate

The date when the user entered 

the Government Note. 

MM/DD/YYYY format.

String v1

govSupClauseActions Government Support Clause 

Actions

Array 

[JSON 

Object]

v1

actionDate

actionType

id

reasonText

documentType
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

57

Table 7-3: Patent Create API – PatentResponse JSON Attributes

Response Parameter Description Data Type Version

createdDate The created Date for the Patent 

record String v1

updatedDate The last updated date for the 

Patent record String v1

Table 7-3: Patent Create API – PatentResponse JSON Attributes

HTTP Status 400 (Bad Request) and HTTP Status 500 (Internal Server Error) 

When the system finds known errors related to validation or JSON formatting, it will return the 

following response in JSON format.

Table 7-4: Patent Create API Error 400 and 500 JSON Attribute List

Error Response 

JSON Attribute 

Name

Description Data Type Version

responseCode Response Code String v1

message Response Message String v1

errors Errors JSON Object v1

code Error Code String v1

field

Error Field of the parameter 

that fails validation or cause 

the error.

String v1

message Error Message String v1

Table 7-4: Patent Create API Error 400 and 500 JSON Attribute List

HTTP Status 401 (Unauthorized) 

Table 7-5: Patent Create API Unauthorized JSON

Table 7-5: Patent Create API Unauthorized JSON

Unauthorized JSON Attribute 

Name

Description Data Type Version

message The message to indicate Access Denied. String v1

timestamp The time and date string when the 

access was denied.

String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

58

7.1.4. Request Example

A sample request for the Patent Create REST API is shown below:

{

 "inventionReportNumber": "07654321-22-0103",

 "patentDocketNumber": "REST-PAT-0017",

 "patentStatus": "Institution Retains Rights",

 "patentTitle": "REST PAT 0017",

 "patentApplicationType": "PROV",

 "provisionalPatentApplication": {

 "provisionalApplicationNumber": "64/999,910",

 "provisionalApplicationDate": "02/02/2022"

 },

 "inventors": [

 {

 "firstName": "John",

 "lastName": "Stewart",

 "fedEmployee": true,

 "middleInitial": "Q",

 "fedAgency": "NIST"

 },

 {

 "firstName": "Jane",

 "lastName": "Doe",

 "fedEmployee": false,

 "middleInitial": "",

 "fedAgency": ""

 }

 ],

 "foreignFilings": [

 {

 "countryName": "AFGHANISTAN",

 "status": "active",

 "filingDate": "02/02/2021"

 }

 ]

}

7.1.5. Response Examples

HTTP Status 200 (OK) 

A sample success response for the Patent Create REST API is shown below:

{

 "id": 338529127,

 "patentDocketNum": "REST-PAT-0018",

 "inventionReportNumber": "07654321-22-0103",
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

59

 "issuedApplicationNumber": "",

 "pctAppNum": "",

 "provisionalAppNum": "64/999,911",

 "provisionalAppDate": "02/02/2022",

 "nonProvisionalAppNum": "",

 "patentApplicationType": "PROV",

 "patentTitle": "REST PAT 0018",

 "confLicenseRejectComment": "",

 "govtSuppClauseRejectComment": "",

 "abandonedReason": "",

 "usptoAppStatus": "",

 "assigned": false,

 "patentStatus": "Institution Retains Rights",

 "explanatoryNotes": [],

 "governmentNotes": [],

 "govSupClauseActions": [],

 "inventors": [

 {

 "firstName": "John",

 "lastName": "Stewart",

 "fedEmployee": true,

 "middleInitial": "Q"

 },

 {

 "firstName": "Jane",

 "lastName": "Doe",

 "fedEmployee": false

 }

 ],

 "foreignFilings": [

 {

 "patentForeignFilingId": 12345,

 "countryName": "AFGHANISTAN",

 "status": "active",

 "filingDate": "02/02/2021"

 }

 ]

}

HTTP Status 400 (Bad Request) or 500 (Internal Server Error) 

{

 "responseCode": 400,

 "message": "Failed Validation",

 "errors": [
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

60

 {

 "code": "400",

 "field": "provAppNum",

 "message": "Provisional Application Number value is required."

 }

 ]

}

HTTP Status 401 (Unauthorized) 

{

 "message": "Access Denied",

 "timestamp": "2022-06-10T09:58:10.534055700"

}

7.2. Update Patent

7.2.1. Endpoint URI

Here’s an example of the v1 endpoint for the Update Patent resource.

POST /iedison/api/v1/patents/update

7.2.2. Request Parameters

The API POST request has the following elements:

• Headers: these are the request headers such as Accept or Content-Type. The Accept 

header parameter defines the expected response body format when the API returns 

the response. For example, you can define a response as JSON by modifying the Accept 

header. This Accept header is required in all requests. 

• Body: body contains the data which will be submitted as the post request. For example, 

when submitting a form, format data and file content are sent in the body of the 

request.

The table below provides the explanation of the update Patent POST request Header and Body 

parameters which are expected by iEdison API.

Request Parameters Description Required Data Type Version In

accept Setting to application/json. Yes String v1 header

patentRequest The Patent JSON object content use to create 

the Patent in iEdison. Refer to Table 7-6: Patent 

Update API – patentResponse JSON Attributes 

below for details.

Yes String v1 formdata
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

61

confirmatoryLicense The Confirmatory License document file for the 

Patent record.

No File Binary v1 formdata

governmentSupportClause The Government Support Clause document file 

for the Patent record.

No File Binary v1 formdata

The table below shows the parameters that will be included in the JSON body during the 

processing of Update Patents Request. The below parameters are included as JSON objects 

multiple times in JSON body as JSON Array. Each JSON object represents the metadata of each 

Patent that needs to be updated. The system updates the government clause file, if it is 

provided during update operation. If the government clause file is not provided during 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. 

Table 7-6: Patent Update API – patentRequest JSON Attributes

Request Parameter Description Required Data 

Type Length Version

inventionReportNumber

Automatically generated by the 

iEdison system for a new 

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. No String 100 v1

patentDocketNumber

The Patent Docket Number 

field is for an internal reference 

number of the 

grantee/contractor 

organization to help track a 

reported Patent(s).

No String 30 v1

patentStatus

Used to identify the current 

status of a Patent. Refer to 

Section 11.1.7 Patent Status 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
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

62

Table 7-6: Patent Update API – patentRequest JSON Attributes

Request Parameter Description Required Data 

Type

Length Version

patentApplicationType

Patent Application Type of a 

record. Refer to Section 11.1.3 

Patent Application Types 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. 

MM/DD/YYYY format.

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. MM/DD/YYYY format.

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). MM/DD/YYYY format.

Yes String 10 v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

63

Table 7-6: Patent Update API – patentRequest JSON Attributes

Request Parameter Description Required Data 

Type

Length Version

issuedApplicationNumber The unique identifier of a 

Patent.

No String 50 v1

issuedApplicationDate

The date the Patent number 

was issued. MM/DD/YYYY 

format.

No String 10 v1

expirationDate

Estimated date of Patent 

expiration. MM/DD/YYYY 

format.

No String 10 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. 

MM/DD/YYYY format.

Yes String 10 v1

pctApplicationNumber

Patent Cooperation Treaty 

(PCT) 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 

Intellectual Property 

Organization (WIPO). 

MM/DD/YYYY format.

Yes String 10 v1

parentPatents Parent Patent No JSON 

Object v1

inventionReportNumber

Automatically generated by the 

iEdison system for a new 

Invention Report after data has 

been submitted, checked for 

errors, and verified.

No String 100 v1

patentDocketNumber

The Patent Docket Number 

field is for 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 v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

64

Table 7-6: Patent Update API – patentRequest JSON Attributes

Request Parameter Description Required Data 

Type

Length Version

firstName First name of an inventor. Yes String 80 v1

lastName Last name of an inventor. Yes String 80 v1

middleInitial Middle initial of an inventor. No String 30 v1

fedEmployee

Is the inventor a federal 

employee? No boolean v1

Default: false.

fedAgency

If the inventor is a federal 

employee, what agency does 

the inventor work for? Refer to 

Section 11.1.8 Agency Mapping 

List for a list of valid 

abbreviations.

No String 80 v1

foreignFilings Patent Foreign Filing No JSON 

Object v1

countryName

The country name of the 

foreign filing. Refer to 11.1.9 

Country List for a list of valid 

country Name values.

Yes String 15 v1

status

The foreign filing status for the 

Patent. Refer to Section 11.1.2 

Patent Filing Status for a list of 

valid values.

Yes JSON 

Array

v1

filingDate

The date that the foreign 

Patent was issued. MM/DD/YYY 

format.

Yes String 10 v1

Table 7-6: Patent Update API – patentRequest JSON Attributes

Please send the following parameters for Binary Attachments along with the above Patent JSON Object. 

Request Parameter Description Required Data Type Length Version

confirmatoryLicense Document that provides the 

federal government a nonexclusive, non-transferable, 

irrevocable, paid-up right to 

practice the Invention or have 

the Invention practiced on its 

behalf for federal government 

purposes.

No Binary 

Attachmen

t

v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

65

Note: The allowed file types for Confirmatory License Document are (csv, gif, jpeg, jpg, png, pdf, docx, doc, tiff, tif, txt, xls, xlsx, 

ppt, pptx, odt, rtf.) Max File Size:25MB.

Note: The allowed file types for Government Support Clause document are (csv, gif, jpeg, jpg, png, pdf, docx, doc, tiff, tif, txt, xls, 

xlsx, ppt, pptx, odt, rtf.) Max File Size:25MB

7.2.3. Response Parameters

This section documents the response JSON objects, attributes, and types for a success or error 

response.

HTTP Status 200 (OK) 

Based on the request parameters, Create Patent API provides the below response parameters.

Table 7-7: Patent Update API – patentResponse JSON Attributes

Response Parameter Description Data 

Type

Version

id System generated sequence 

number used for ID of the Patent. Int v1

patentDocketNum

The Patent Docket Number field 

is for an internal reference 

number of the 

grantee/contractor organization 

to help track a reported 

Patent(s).

String v1

inventionReportNumber

The unique Invention Report 

Number that identifies the 

Invention record in iEdison the 

Patent is associated with.

String v1

issuedApplicationNumber The Patent number provident 

when the Patent is issued. String v1

issuedApplicationDate The date the Patent number was 

issued. String v1

Request Parameter Description Required Data Type Length Version

governmentSupportClause Document/statement 

acknowledging federal 

support of a subject Invention

that MUST be included in the 

specification of a U.S. Patent

application or a U.S. issued 

Patent.

No Binary 

Attachmen

t

v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

66

Table 7-7: Patent Update API – patentResponse JSON Attributes

Response Parameter Description Data 

Type

Version

pctAppNum

Patent Cooperation Treaty (PCT) 

number is used to uniquely 

identify a PCT type Patent 

application.

String v1

pctAppDate

This field is used for 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

This field is used for 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

This field is used for the filing 

date of the non-provisional 

Patent application with the U.S. 

Patent and Trademark Office 

(USPTO)

String v1

patentApplicationType

Patent Application Type of a 

record. Refer to Section 11.1.3 

Patent Application Types for a list 

of valid values.

String v1

patentReceiptDate Date the Patent was received by 

the government.

String v1

expireDate Estimated date of Patent 

expiration. 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 The Patent status. String v1

confLicenseReceiptDate Confirmatory License Receipt 

Date.

String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

67

Table 7-7: Patent Update API – patentResponse JSON Attributes

Response Parameter Description Data 

Type

Version

confLicenseRejectDate Date Confirmatory License is 

rejected by Government Agency. String v1

confLicenseRejectComment

Reason for Confirmatory License 

rejection shared with the 

organization.

String v1

confLicenseOutdated Used to indicate if the 

Confirmatory License is outdated. String v1

govtSuppClauseReceiptDate

The date the Federal Support 

Clause was received by the 

government.

String v1

govtSuppClauseRejectDate

Date Government Support Clause 

inclusion was rejected by the 

government.

String v1

govtSuppClauseRejectComment

Reason for Government Support 

Clause rejection displayed to 

grantee/contractor institution.

String v1

govtActionDate Government Action Date. String v1

domesticWaiverDecisionFlag Used to indicate Domestic 

Waiver decision. Boolean v1

domesticWaiverDecisionDate Domestic Waiver Decision Date. String v1

parentPatents Parent Patents list. JSON 

Object v1

inventionReportNumber The unique Invention Report 

Number for the parent Patent. String v1

patentDocketNumber

The Patent Docket Number 

field is for an internal 

reference number of the 

grantee/contractor 

organization to help track a 

reported Patent(s).

String v1

confirmatoryLicenseExcutionDate Confirmatory License date of 

execution for EPAS submission. String v1

abandonedReason The reason why a Patent was 

abandoned. String v1

extensionDays

Number of days Patent 

provisional application date has 

been extended.

Int v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

68

Table 7-7: Patent Update API – patentResponse JSON Attributes

Response Parameter Description Data 

Type

Version

usptoAppStatus USPTO application status of the 

Patent.

String v1

usptoAppStatusDate Date of USPTO application. String v1

usptoLastSyncDate Date of last sync with USPTO. String v1

assigned

Used to indicate if the Patent has 

been assigned to another 

organization.

Boolean v1

explanatoryNotes

Explanatory notes may 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.

Array 

[JSON 

Object]

v1

note

Explanatory notes may 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.

String v1

creatorName The full name of the user who 

entered the Explanatory Note. String v1

createdDate

The date when the user entered 

the Explanatory Note. 

MM/DD/YYYY format.

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

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.

String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

69

Table 7-7: Patent Update API – patentResponse JSON Attributes

Response Parameter Description Data 

Type

Version

creatorName The full name of the user who 

entered the Government Note. String v1

createdDate

The date when the user entered 

the Government Note. It is in 

MM/DD/YYYY format.

String v1

govSupClauseActions Government Support Clause 

Actions String v1

createdDate The created Date for the Patent 

record. String v1

updatedDate The last updated date for the 

Patent record String v1

Table 7-7: Patent Update API – patentResponse JSON Attributes

HTTP Status 400 (Bad Request) and HTTP Status 500 (Internal Server Error) 

When the system finds known errors related to validation or JSON formatting, it will return the 

following response in JSON format.

Table 7-8: Patent Update API Error 400 and 500 JSON Attribute List

Error Response JSON 

Attribute Name Description Data Type Version

responseCode Response Code String v1

message Response Message String v1

errors Errors JSON Object v1

code Error Code String v1

field

Error Field of the parameter 

that fails validation or cause 

the error.

String v1

message Error Message String v1

Table 7-8: Patent Update API Error 400 and 500 JSON Attribute List

HTTP Status 401 (Unauthorized) 

Table 7-9: Patent Update API Unauthorized JSON

Table 7 9: Patent Update API Unauthorized JSON

Unauthorized JSON Attribute 

Name

Description Data Type Version

message The message to indicate Access Denied. String v1

timestamp The time and date string when the 

access was denied.

String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

70

7.2.4. Request and Response Examples 

A sample request for the Patent Update REST API is shown below:

{

 "inventionReportNumber": "07654321-22-0103",

 "patentDocketNumber": "REST-PAT-0017",

 "patentStatus": "Institution Retains Rights",

 "patentTitle": "REST PAT 0017-updated",

 "patentApplicationType": "PROV",

 "provisionalPatentApplication": {

 "provisionalApplicationNumber": "64/999,910",

 "provisionalApplicationDate": "02/02/2022"

 },

 "inventors": [

 {

 "firstName": "John",

 "lastName": "Stewart",

 "fedEmployee": true,

 "middleInitial": "Q",

 "fedAgency": "NIST"

 },

 {

 "firstName": "Jane",

 "lastName": "Doe",

 "fedEmployee": false,

 "middleInitial": "",

 "fedAgency": ""

 },

 ],

 "foreignFilings": [

 {

 "countryName": "AFGHANISTAN",

 "status": "active",

 "filingDate": "02/02/2021"

 }

 ]

}

A sample response and error for the Patent Update REST API is shown below:

{

 "id": 338529126,

 "patentDocketNum": "REST-PAT-0017",

 "inventionReportNumber": "07654321-22-0103",
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

71

 "issuedApplicationNumber": "",

 "pctAppNum": "",

 "provisionalAppNum": "64/999,910",

 "provisionalAppDate": "02/02/2022",

 "nonProvisionalAppNum": "",

 "patentApplicationType": "PROV",

 "patentTitle": "REST PAT 0017-updated",

 "confLicenseRejectComment": "",

 "govtSuppClauseRejectComment": "",

 "parentPatents": [],

 "abandonedReason": "",

 "usptoAppStatus": "",

 "assigned": false,

 "patentStatus": "Institution Retains Rights",

 "explanatoryNotes": [],

 "governmentNotes": [],

 "govSupClauseActions": [],

 "inventors": [

 {

 "firstName": "John",

 "lastName": "Stewart",

 "fedEmployee": true,

 "middleInitial": "Q",

 "fedAgency": "NIST"

 },

 {

 "firstName": "Jane",

 "lastName": "Doe",

 "fedEmployee": false

 }

 ],

 "foreignFilings": [

 {

 "patentForeignFilingId": 12345,

 "countryName": "AFGHANISTAN",

 "status": "active",

 "filingDate": "02/02/2021"

 }

 ]

}

HTTP Status 400 (Bad Request) or 500 (Internal Server Error) 

{

 "responseCode": 400,

 "message": "Failed Validation",

 "errors": [
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

72

 {

 "code": "400",

 "field": "provAppNum",

 "message": "Provisional Application Number value is required."

 }

 ]

}

HTTP Status 401 (Unauthorized) 

{

 "message": "Access Denied",

 "timestamp": "2022-06-10T09:58:10.534055700"

}

7.3. Search Patent

Search conditions for Patent Search is based on AND operation with different Patent 

Fields in JSON Request. 

For Example, If the Patent search has Patent Docket Number and Primary Agency, the 

search results include all the searches that match both Patent Docket Number and 

Primary Agency.

7.3.1. Endpoint URI

Here’s an example of the v1 endpoint for the Search Patent resource.

POST /iedison/api/v1/patents/search

7.3.2. Request Parameters

The API POST request has the following elements:

• Headers: these are the request headers such as Accept or Content-Type. The Accept 

header parameter defines the expected response body format when the API returns 

the response. For example, you can define a response as JSON by modifying the Accept 

header. This Accept header is required in all requests. 

• Body: body contains the data which will be submitted as the post request. For example, 

when submitting a form, format data and file content are sent in the body of the 

request.

The table below provides the explanation of the search Patent POST request Header and Body 

parameters which are expected by iEdison API.
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

73

Table 7-10: Patent Search API Parameters

Request Parameters Description Data Type Version In

accept Setting to application/json String v1 header

patentSearchCriteria The Patent search criteria filters in JSON string. 

Table 7-10: Patent Search API Parameters

The table below shows the parameters that will be included in the JSON body only one time 

during the processing of Search Patents Request.

Table 7-11

Request Parameter 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. The Default = 20.

No Integer v1

offset Indicates the page index. Default offset 

starts with 0.

No Integer v1

inventionReportNumber Automatically generated by the iEdison 

system for a new 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. 

MM/DD/YYYY format.

No String 10 v1

inventionReportDateTo The To Date that the inventor disclosed 

the subject Invention in writing to the 

recipient institution. MM/DD/YYYY 

format.

No String 10 v1

inventionTitle The title of the Invention as it appears 

in the grantee/contractors employee’s 

Invention Report.

No String 255 v1

primaryAgency A Primary Agency must be designated 

for each Invention Report in iEdison.

Refer to Section 11.1.8 Agency 

Mapping List for a list of valid 

abbreviations.

No String 1 v1

titleElectionStatus The current status of the title to rights 

in the reported Invention. Refer to 

No Array 

[String]

50 v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

74

7.3.3. Response Parameters

Based on request parameters, Search Patent API provides below response parameters.

Table 7-11

Request Parameter Description Required Data Type Length Version

Section 11.1.11 Title Election Status for 

a list of valid values.

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 Patent Application Type of a record.

Refer to Section 11.1.3 Patent 

Application Types for a list of valid 

values.

No String 25 v1

patentStatus Used to identify the current status of a 

Patent. Refer to Section 11.1.7 Patent 

Status for a list of valid values.

No String 50 v1

patentDocketNumber The Patent Docket Number field is for 

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. 

MM/DD/YYYY format.

No String 10 v1

patentFilingDateTo The ‘up to’ search date against the PCT, 

Provisional, Non-Provisional Patent

application filing date. MM/DD/YYYY

format.

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 Inventor First Name. No String 50 v1

inventorLastName Inventor Last Name. No String 50 v1

lastUpdatedFrom The ‘start from’ search date against the 

Patent last updated date. MM/DD/YYYY 

format.

No String 10 v1

lastUpdatedTo The ‘up to’ search date against the 

Patent last updated date. MM/DD/YYYY 

format.

No String 10 v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

75

Table 7-11: Patent Search API – patentSearchCriteria JSON Attributes

Below are the PatentResponse Object attributes.

Table 7-13: Patent Search API – PatentResponse JSON Object Attributes

Response Parameter Description Data Type Version

id System generated sequence number used 

for ID of the Patent. Int v1

patentDocketNum

The Patent Docket Number field is for an 

internal reference number of the 

grantee/contractor organization to help 

track a reported Patent(s).

String v1

inventionReportNumber

The unique Invention Report Number that 

identifies the Invention record in iEdison 

the Patent is associated with.

String v1

issuedApplicationNumber The Patent number provided by USPTO 

when the Patent was 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

This field is used for the filing date of the 

Patent Cooperation Treaty (PCT) 

application.

String v1

Table 7-12: Patent Search API – patentSearchCriteria JSON Attributes

Response Parameter Description Data Type Version

totalRecords Total number of records for the 

search.

Number v1

limit Limit entered by a user while 

making the request i.e., total 

number of records the user wished 

to retrieve per page.

Number v1

offset Page index specified by a user. 

Default offset starts with 0 if user 

does not provide any offset in the 

request.

Number v1

patents A list of Patent response Objects. 

Table 7-14 below lists the JSON 

object attributes.

Object 

Array

v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

76

Table 7-13: Patent Search API – PatentResponse JSON Object Attributes

Response Parameter Description Data Type Version

provisionalAppNum

The unique identifier a provisional Patent 

application created upon filing at the 

USPTO.

String v1

provisionalAppDate

This field is used for 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

This field is used for the filing date of the 

non-provisional Patent application with 

the U.S. Patent and Trademark Office 

(USPTO)

String v1

patentApplicationType

Patent Application Type of a record. Refer 

to Section 11.1.3 Patent Application Types 

for a list of valid values.

String v1

patentReceiptDate Date Patent was received by the 

government.

String v1

expireDate Estimated date of Patent expiration. 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 The Patent status. String v1

confLicenseReceiptDate Confirmatory License Receipt Date. String v1

confLicenseRejectDate Date Confirmatory License is rejected by 

Government Agency. String v1

confLicenseRejectComment Reason for Confirmatory License rejection 

shared with the organization. String v1

confLicenseOutdated Used to indicate if the Confirmatory 

License is outdated. String v1

govtSuppClauseReceiptDate The date the Federal Support Clause was 

received by the government. String v1

govtSuppClauseRejectDate Date Government Support Clause 

inclusion was rejected by Government. String v1

govtSuppClauseRejectComment

Reason for Government Support Clause 

rejection displayed to grantee/contractor 

institution.

String v1

govtActionDate Government Action Date String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

77

Table 7-13: Patent Search API – PatentResponse JSON Object Attributes

Response Parameter Description Data Type Version

domesticWaiverDecisionFlag Used to indicate Domestic Waiver 

decision. Boolean v1

domesticWaiverDecisionDate Domestic Waiver Decision Date. String v1

parentPatents Parent Patents list. JSON 

Object v1

inventionReportNumber The unique Invention Report Number 

for the parent Patent. String v1

patentDocketNumber

The Patent Docket Number field is for 

an internal reference number of the 

grantee/contractor organization to 

help track a reported Patent(s).

String v1

executionDate Confirmatory license date of execution for 

EPAS submission. String v1

abandonedReason The reason why a Patent was abandoned. String v1

extensionDays Number of days the Patent provisional 

application date has been extended. Int v1

usptoAppStatus USPTO application status of the Patent. String v1

usptoAppStatusDate Date of USPTO application. String v1

usptoLastSyncDate Date of last sync with USPTO. String v1

assigned Used to indicate if the Patent has been 

assigned to another organization. Boolean v1

explanatoryNotes

Explanatory notes may 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.

Array 

[JSON 

Object]

v1

note

Explanatory notes may 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.

String v1

creatorName

The full name of the user who entered the 

Explanatory Note. String v1

createdDate The date when the user entered the 

Explanatory Note. MM/DD/YYYY format. String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

78

Table 7-13: Patent Search API – PatentResponse JSON Object Attributes

Response Parameter Description Data Type Version

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

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.

String v1

creatorName The full name of the user who entered the 

Government Note. String v1

createdDate The date when the user entered the 

Government Note. MM/DD/YYYY format. String v1

govSupClauseActions Government Support Clause Actions. String v1

Table 7-12: Patent Search API – PatentResponse JSON Object Attributes

7.3.4. Request and Response Examples 

A sample request for the Patent Search REST API is shown below:

{

"patentApplicationType": "DIV",

"patentDocketNumber": "1087.3A"

}

A sample response and error for the Patent Search REST API is shown below:

{

 "patents": [

 {

 "id": 62978,

 "patentDocketNum": "1087.3A",

 "inventionReportNumber": "07654321-01-0001",

 "patentNum": "6197595",

 "patentDate": "03/05/2001",

 "provisionalAppNum": "",

 "provisionalAppDate": "04/19/1999",

 "nonProvisionalAppNum": "09/294,700",
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

79

 "nonProvisionalAppDate": "04/19/1999",

 "applicationType": "DIV",

 "expireDate": "04/19/2019",

 "patentTitle": "Integrated Nucleic Acid Diagnostic Device",

 "confLicenseRejectComment": "",

 "confLicenseOutdated": false,

 "govtSuppClauseRejectDate": "05/14/2021",

 "govtSuppClauseRejectComment": "Government Agency that awarded grant is 

missing. Also, the language of the Government Support Clause is incorrect.",

 "oldPatentRule": true,

 "abandonedReason": "",

 "usptoAppStatus": "",

 "assigned": false,

 "patentStatus": "Institution Retains Rights",

 "explanatoryNotes": [],

 "governmentNotes": [],

 "userNotes": [],

 "govSupClauseActions": [

 {

 "id": 53038,

 "actionType": "R",

 "documentType": "SC",

 "actionDate": "12/31/1949",

 "reasonText": "Government Agency that awarded grant is missing. Also, the 

language of the Government Support Clause is incorrect."

 }

 ]

 }

 ],

 "totalRecords": 1,

 "limit": 100,

 "offset": 0

}

8.0. Utilization API Reference

8.1. Create Utilization

8.1.1. Endpoint URI

Here’s an example of the v1 endpoint for the Create Utilization resource.

POST /iedison/api/v1/utilizations/create
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

80

8.1.2. Request Parameters

The API POST request has the following elements:

• Headers: these are the request headers such as Accept or Content-Type. The Accept 

header parameter defines the expected response body format when the API returns 

the response. For example, you can define a response as JSON by modifying the Accept 

header. This Accept header is required in all requests. 

• Body: body contains the data which will be submitted as the post request. For example, 

when submitting a form, format data and file content are sent in the body of the 

request.

The table below provides the explanation of the Create Utilization POST request Header and 

Body parameters which are expected by iEdison API.

Table 8-1: Utilization Create API parameters

The table below shows the parameters that will be included in the JSON body during the 

processing of Create Utilization Request. The below parameters are included as JSON 

object in JSON body. The JSON object represents the metadata for the utilization that 

needs to be created.

Table 8 1: Utilization Create API parameters

Request Parameters Description Required Data Type Version In

accept Setting to application/json. Yes String v1 header

utilizationRequest The utilization request JSON content in string 

format contains the utilization attributes. Refer to

Table 8-2: Utilization Create API –

utilizationRequest JSON Attributes for details.

Yes String v1 formdata

Table 8-2: Utilization Create API – utilizationRequest JSON Attributes

Request JSON Attribute Name Description Required Data Type Length Version

inventionReportNumber The Invention Report number the 

utilization report is associated with.

Yes String 25 v1

reportingYear The year for which the utilization

report is being submitted.

Yes Integer v1

latestStageDev The latest stage of development of 

any product arising from this 

Invention. Refer to Section 11.1.1

Invention Development Stage for a 

list of latest valid values.

Yes String 30 v1

firstCommercialSaleYear Year product embodying the 

Invention was first sold (date of 

first commercial sale).

No Integer v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

81

Table 8-2: Utilization Create API – utilizationRequest JSON Attributes

Request JSON Attribute Name Description Required Data Type Length Version

totalIncome Total income from royalty or option 

agreements for the Invention.

No Number 

(float)

v1

manufacturingWaiver Used to indicate if a waiver for 

Manufacturing Requirement has 

been requested. Accepted values 

are 0 (for No) and 1 (for Yes).

Default: 0.

No Integer v1

manufacturingWaiverTotal Total number of manufacturing 

waivers obtained.

No Integer v1

domesticLicenseNumber Number of domestic manufacturing 

licenses.

No Integer

exclusiveLicensesOptions Number of exclusive licenses / 

option agreements for the 

Invention.

In the designated reporting period, 

how many exclusive licenses 

and/or options are active?

No Integer v1

nonExclusiveLicensesOptions Number of non-exclusive licenses / 

option agreements for the 

Invention.

In the designated reporting period, 

how many non-exclusive licenses 

and/or options are active?

No Integer v1

smallBusinessLicensesOptions Number of small business licenses / 

option agreements for the 

Invention.

How many licenses and/or options 

of any type to small businesses 

(<500 employees) are active in the 

designated reporting period?

No Integer v1

newUsJobs Approximate number of new U.S.-

based jobs created because of 

commercialization efforts during 

the reporting period.

No Integer v1

newUsCompanies Number of new U.S.-based 

companies created from the 

commercialization efforts during 

the reporting period. For DOE 

Invention only.

No Integer v1

utilizationDescription Describe how the development and 

commercialization of the subject 

Invention complies with any 

required U.S. manufacturing 

No String 1000 v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

82

Table 8-2: Utilization Create API – utilizationRequest JSON Attributes

Request JSON Attribute Name Description Required Data Type Length Version

requirements (e.g., U.S. Preference, 

a U.S. Competitive Clause, U.S. 

Manufacturing Plan, etc.) For DOE 

Invention only.

totalGrossSales Total Gross Sales for DOE Invention

only.

No Number v1

commercialProds FDA Approved Commercial 

products.

No JSON Array v1

commercialName The name of the FDA approved 

commercial product.

Yes String 80 v1

fdaApprovalNumber The number of the FDA approved 

commercial product.

No String 20 v1

fdaApprovalType The type of the FDA approved 

commercial product. Please refer 

to section 11.1.15 in Appendix for a 

list of acceptable utilization

Commercial Product Type values.

No String 15 v1

govtReviewStatus The status of the FDA approved 

commercial product. Please refer 

to section 11.1.16 in Appendix for a 

list of acceptable utilization

Government Review Status values.

No String 10 v1

publicInd The public announced indicator flag 

of the FDA approved commercial 

product. Please refer to section 

11.1.17 in Appendix for a list of 

acceptable utilization commercial 

product Public Announced values.

No String 3 v1

manufacturingCommProds The manufacturing commercial 

products made through the use of 

or Embodying the Subject 

Invention(s). Object attributes 

below.

No JSON Array v1

 productName The unique commercial product 

name.

Yes String 100 v1

 naicsCode The North American Industry 

Classification System (NAICS) code 

is used by Federal agencies in 

classifying business establishments.

No String 6 v1

 productLocation The manufacturing production 

location(s). Object attributes 

below.

No JSON Array v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

83

Table 8-2: Utilization Create API – utilizationRequest JSON Attributes

8.1.3. Response Parameters

This section documents the response JSON objects, attributes, and types for a success or error 

response.

HTTP Status 200 (OK) 

Based on the request parameters, Create Utilization API provides the below response 

parameters.

Table 8-2: Utilization Create API – utilizationRequest JSON Attributes

Request JSON Attribute Name Description Required Data Type Length Version

 country The manufacturing country for the 

location. Refer to 11.1.9 Country 

List for a list of valid country Name 

values.

Yes String 30 v1

 state The manufacturing state for the 

location for applicable country. 

Refer to Section 11.1.10 States List 

for a list of valid Code values.

No String 14 v1

 firstDate The first date of manufacturing. 

MM/DD/YYYY format.

Yes String 10 v1

 firstDateType The type for the first date of 

manufacturing. Please refer to for

a list of acceptable type values.

Yes String 8 v1

 productQuantity The total number of products at 

the manufacturing location.

Yes Integer v1

Table 8-3: Utilization Create API – utilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

inventionReportNumber Automatically generated by the iEdison 

system for a new Invention Report 

after data has been submitted, checked 

for errors, and verified.

String v1

granteeOrganizationName The name of the organization 

established at registration.

String v1

inventionTitle The title of the Invention as it appears 

in the grantee/contractors employee’s 

Invention Report.

String v1

primaryAgency A Primary Agency must be designated 

for each Invention Report in iEdison.

Refer to Section 11.1.8 Agency 

Mapping List for a list of valid 

abbreviations.

String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

84

Table 8-3: Utilization Create API – utilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

inventionReportDate The date the inventor discloses the 

subject Invention in writing to the 

recipient institution. MM/DD/YYYY 

format.

String v1

titleElectDate The Invention Elect Title Date. String v1

reportingYear The year for which the utilization 

report is being submitted.

Integer v1

latestStageDev The latest stage of development of any 

product arising from this Invention. 

Refer to Section 11.1.1 Invention 

Development Stage for a list of latest 

valid values.

String v1

firstCommercialSaleYear Year product embodying the Invention

was first sold (date of first commercial 

sale).

Integer v1

totalIncome Total income from royalty or option 

agreements for the Invention.

Integer v1

manufacturingWaiver Used to indicate if a waiver for 

Manufacturing Requirement has been 

requested. 0 (for No) and 1 (for Yes).

Integer v1

manufacturingWaiverTotal Total number of manufacturing waivers 

obtained.

Integer v1

exclusiveLicensesOptions Number of exclusive licenses / option 

agreements for the Invention.

Integer v1

nonExclusiveLicensesOptions Number of non-exclusive licenses / 

option agreements for the Invention.

Integer v1

smallBusinessLicensesOptions Number of small business licenses / 

option agreements for the Invention.

Integer v1

domesticLicenseNumber Total number of domestic 

manufacturing licensees.

Integer v1

newUsJobs Approximate number of new US-based 

jobs created because of 

commercialization efforts during the 

reporting period.

Integer

newUsCompanies Number of new US-based companies 

created from the commercialization 

efforts during the reporting period. For 

DOE Invention only.

Integer

utilizationDescription Describes how the development and 

commercialization of the subject 

Invention comply with any required 

U.S. manufacturing requirements (e.g., 

U.S. Preference, a U.S. Competitive 

String 1000
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

85

Table 8-3: Utilization Create API – utilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

Clause, U.S. Manufacturing Plan, etc.)

For DOE Invention only.

totalGrossSales Total Gross Sales for DOE Invention

only.

Number

commercialProds FDA Approved Commercial products. 

Object Attributes are below.

JSON Array v1

 commercialName The name of the FDA approved 

commercial product.

String v1

 fdaApprovalNumber The number of the FDA approved 

commercial product.

String v1

 fdaApprovalType The type of the FDA approved 

commercial product. Please refer to 

section 11.1.15 in Appendix for a list of 

acceptable utilization Commercial 

Product Type values.

String v1

 govtReviewStatus The status of the FDA approved 

commercial product. Please refer to 

section 11.1.16 in Appendix for a list of 

acceptable utilization Government 

Review Status values.

String v1

 publicInd The public announced indicator flag of 

the FDA approved commercial product. 

Please refer to section 11.1.17 in 

Appendix for a list of acceptable 

utilization commercial product Public 

Announced values.

String v1

manufacturingCommProds The manufacturing commercial 

products made through the use of 

Embodying the Subject Invention(s). 

JSON Object attributes below.

JSON Array v1

 productName The unique commercial product name. String v1

 naicsCode The North American Industry 

Classification System (NAICS) code is 

used by Federal agencies in classifying 

business establishments.

String v1

productLocation The manufacturing production 

location(s). JSON Object attributes 

below.

JSON Array v1

 country The manufacturing country for the 

location. Refer to 11.1.9 Country List 

for a list of valid country Name values.

String v1

 state The manufacturing state for the 

location for applicable country. Refer to 

String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

86

Table 8-3: Utilization Create API – utilizationResponse JSON Attributes

8.1.4. Request Examples

A sample request for the Utilization Create REST API is shown below:

{

 "inventionReportNumber": "07654321-22-0103",

 "reportingYear": 2010,

 "latestStageDev": "Commercialized",

 "firstCommercialSaleYear": 2009,

 "totalIncome": 3000,

 "manufacturingWaiver": 1,

 "manufacturingWaiverTotal": 5,

 "exclusiveLicensesOptions": 6,

 "domesticManufacturingLicenses": 7,

 "nonExclusiveLicensesOptions": 8,

 "smallBusinessLicensesOptions": 3,

 "totalGrossSales": 6500

}

A sample request for the Utilization Create REST API using the FDA Commercial Products.

{

"inventionReportNumber": "00490201-21-0001",

"reportingYear": 2020,

"latestStageDev": "Commercialized",

"firstCommercialSaleYear": 2020,

Table 8-3: Utilization Create API – utilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

Section 11.1.10 States List for a list of 

valid Code values.

 firstDate The first date of manufacturing. 

MM/DD/YYYY format.

String v1

 firstDateType The type for the first date of 

manufacturing. Please refer to list of 

acceptable type values.

String v1

 productQuantity The total number of products at the 

manufacturing location.

Integer v1

createdDate The created Date for the utilization

record.

String v1

updatedDate The last created Date for the utilization

record.

String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

87

"totalIncome": 1000,

"manufacturingWaiver": 1,

"manufacturingWaiverTotal": 3,

"exclusiveLicensesOptions": 4,

"domesticManufacturingLicenses": 5,

"nonExclusiveLicensesOptions": 2,

"smallBusinessLicensesOptions": 3,

"commercialProds": [{

"commercialName": "Test Prod1",

"fdaApprovalNumber": "1000001",

"publicInd": "Yes",

"govtReviewStatus": "Approved",

"fdaApprovalType": "Drug"

},

{

"commercialName": "Test Prod3",

"fdaApprovalNumber": "1000003",

"publicInd": "Yes",

"govtReviewStatus": "Approved",

"fdaApprovalType": "Medical Device"

}]

}

8.1.5. Response Examples

HTTP Status 200 (OK) 

A sample response and error for the Utilization Create REST API is shown below:

{

 "inventionReportNumber": "07654321-22-0103",

 "granteeOrganizationName": "DAN’S INSTITUTION",

 "inventionTitle": "REST – Create Invention108",

 "primaryAgency": "Army Research Laboratory – Army Research Office",

 "inventionReportDate": "01/31/2022",

 "titleElectDate": "06/10/2022",

 "reportingYear": 2010,

 "latestStageDev": "Commercialized",

 "firstCommercialSaleYear": 2009,

 "totalIncome": 3000.0,

 "manufacturingWaiver": 1,

 "manufacturingWaiverTotal": 5,

 "exclusiveLicensesOptions": 6,
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

88

 "domesticLicenseNumber": 0,

 "nonExclusiveLicensesOptions": 8,

 "smallBusinessLicensesOptions": 3,

 "totalGrossSales": 6500.0

}

 

HTTP Status 400 (Bad Request) or 500 (Internal Server Error) 

{

 "responseCode": 400,

 "message": "Invalid form-data content",

 "errors": [

 {

 "code": "400",

 "field": "reportingYear",

 "message": "Reporting Year (YYYY) * value isrequired."

 }

 ]

}

HTTP Status 400 (Bad Request) or 500 (Internal Server Error) 

{

 "message": "Access Denied",

 "timestamp": "2022-06-10T09:58:10.534055700"

}

8.2. Create Utilization V2

8.2.1. Endpoint URI

Here’s an example of the v2 endpoint for the Create Utilization resource.

POST /iedison/api/v2/utilizations/create

8.2.2. Request Parameters

The API POST request has the following elements:

• Headers: these are the request headers such as Accept or Content-Type. The Accept 

header parameter defines the expected response body format when the API returns 

the response. For example, you can define a response as JSON by modifying the Accept 

header. This Accept header is required in all requests. 

• Body: body contains the data which will be submitted as the post request. For example, 

when submitting a form, format data and file content are sent in the body of the 

request.
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

89

The table below provides the explanation of the create utilization POST request Header and 

Body parameters which are expected by the iEdison API.

Table 8-4: Utilization Create API parameters

The table below shows the parameters that will be included in the JSON body during the 

processing of Create Utilization Request. The below parameters are included as JSON 

object in JSON body. The JSON object represents the metadata for the utilization that 

needs to be created.

Table 8-4: Utilization Create API parameters

Request 

Parameters

Description Required Data 

Type

Version In

accept Setting to application/json. Yes String v2 header

utilizationRequest The utilization request JSON content in 

string format contains the utilization

attributes. Refer to Table 8-5: 

Utilization Create API –

utilizationRequest JSON Attributes for 

details.

Yes String v2 raw

Table 8-5: Utilization Create API – utilizationRequest JSON Attributes

Request JSON Attribute Name Description Required Data 

Type

Length Version

inventionReportNumber The Invention Report number the 

utilization report is associated with.

Yes String 25 v2

reportingYear The year for which the utilization

report is being submitted.

Yes Integer v2

latestStageDev The latest stage of development of 

any product arising from this 

Invention. Refer to Section 11.1.1

Invention Development Stage for a 

list of latest valid values.

Yes String 30 v2

firstCommercialSaleYear Year product embodying the 

Invention was first sold (date of 

first commercial sale).

This is required when 

latestStageDev has a value of 

“Commercialized” or “Licensed”.

Yes 

(Conditional

ly)

Integer v2

totalIncome Total income from royalty or option 

agreements for the Invention.

Yes 

(Conditional

ly)

Number 

(float)

v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

90

Table 8-5: Utilization Create API – utilizationRequest JSON Attributes

Request JSON Attribute Name Description Required Data 

Type

Length Version

This is required when 

latestStageDev has a value of 

“Commercialized” or “Licensed”.

exclusiveLicensesOptions Number of exclusive licenses / 

option agreements for the 

Invention.

In the designated reporting period, 

how many exclusive licenses 

and/or options are active?

This is required when 

latestStageDev has a value of 

“Commercialized” or “Licensed”.

Yes 

(Conditional

ly)

Integer v2

nonExclusiveLicensesOptions Number of non-exclusive licenses / 

option agreements for the 

Invention.

In the designated reporting period, 

how many non-exclusive licenses 

and/or options are active?

This is required when 

latestStageDev has a value of 

“Commercialized” or “Licensed”.

Yes 

(Conditional

ly)

Integer v2

smallBusinessLicensesOptions Number of small business licenses / 

option agreements for the 

Invention.

How many licenses and/or options 

of any type to small businesses 

(<500 employees) are active in the 

designated reporting period?

This is required when 

latestStageDev has a value of 

“Commercialized” or “Licensed”.

Yes 

(Conditional

ly)

Integer v2

IsUSManufacturingRequired1 Other than U.S. Preference (35 

U.S.C. 204), is the invention subject 

to any U.S. manufacturing 

requirements (e.g., U.S. 

Competitiveness provision, a U.S. 

Manufacturing DEC, etc.)?

Yes 

(Conditional

ly)

String 1 v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

91

Table 8-5: Utilization Create API – utilizationRequest JSON Attributes

Request JSON Attribute Name Description Required Data 

Type

Length Version

Accepted values are N (for No) and 

Y (for Yes).

This is required when 

latestStageDev has a value of 

“Commercialized” or “Licensed”.

IsUSManufacturingRequired2 1. If IsUSManufacturingRequired1

is N: In the designated reporting 

period do all grants to any person 

of the exclusive right to use or sell 

the subject invention in the United 

States require that any products 

embodying the subject invention or 

produced through the use of the 

subject invention will be 

manufactured substantially in the 

United States as required by 35 

U.S.C. 204? 

2. If IsUSManufacturingRequired1

is Y: In the designated reporting 

period, do all licenses include a 

requirement that any products 

embodying the subject invention or 

produced through the use of the 

subject invention will be 

manufactured substantially in the 

United States (including 

manufacturing requirements other 

than 35 U.S.C. 204)?

If latestStageDev is 

“Commercialized” or “Licensed” 

and isUSManufacturingRequired1

is “Y”, accepted value for this 

attribute can be “N” (for No), or “Y” 

(for Yes). 

If latestStageDev is 

“Commercialized” or “Licensed” 

and isUSManufacturingRequired1

is “N”, accepted value for this 

attribute can be “N” (for No), or “Y” 

Yes 

(Conditional

ly)

String 3 v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

92

Table 8-5: Utilization Create API – utilizationRequest JSON Attributes

Request JSON Attribute Name Description Required Data 

Type

Length Version

(for Yes), or “N/A” (for Not 

Applicable).

[See 11.1.21 and 11.1.22 for the 

questions logic]

IsUSManufacturingRequired3 1. If IsUSManufacturingRequired2

is N: In the designated reporting 

period are all products embodying 

the subject invention or produced 

through the use of the subject 

invention manufactured 

substantially in the United States 

for all grants to any person of the 

exclusive right to use or sell the 

subject invention in the United 

States as required by 35 U.S.C. 

204? 

2. If IsUSManufacturingRequired2

is Y: In the designated reporting 

period, are all products embodying 

the subject invention or produced 

through the use of the subject 

invention manufactured 

substantially in the United 

States(including manufacturing 

requirements other than 35 U.S.C. 

204)?

If latestStageDev is 

“Commercialized” or “Licensed” 

and isUSManufacturingRequired1

is “Y”, accepted value for this 

attribute can be “N” (for No), or “Y” 

(for Yes). 

If latestStageDev is 

“Commercialized” or “Licensed” 

and isUSManufacturingRequired1

is “N”, accepted value for this 

attribute can be “N” (for No), or “Y” 

(for Yes), or “N/A” (for Not 

Applicable).

Yes 

(Conditional

ly)

String 3 v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

93

Table 8-5: Utilization Create API – utilizationRequest JSON Attributes

Request JSON Attribute Name Description Required Data 

Type

Length Version

[See 11.1.21 and 11.1.22 for the 

questions logic]

notes General notes.

This is required when

commercializationPlanId has a 

value of 3 or 6.

Yes 

(Conditional

ly)

String 1000 v2

commercializationPlanId The commercialization plan for the 

invention.

What are your current 

commercialization plans for this 

invention?

This is required when 

latestStageDev has a value of “Not 

Licensed or Commercialized”.

Refer to Section 11.1.20 Utilization 

Commercialization Plan for a list of 

valid commercialization plans.

Yes 

(Conditional

ly)

Number v2

exclusiveLicensees The exclusive licensee names for 

the invention.

This is required when

exclusiveLicensesOptions has a 

value greater than 0.

Yes 

(Conditional

ly)

[String] v2

nonExclusiveLicensees The non-exclusive licensee names 

for the invention.

This is required when

nonExclusiveLicensesOptions has a 

value greater than 0.

Yes 

(Conditional

ly)

[String] v2

newUsJobs Approximate number of new U.S.-

based jobs created because of 

commercialization efforts during 

the reporting period. For DOE 

Invention only.

No Integer v2

newUsCompanies Number of new U.S.-based 

companies created from the 

commercialization efforts during 

the reporting period. For DOE 

Invention only.

No Integer v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

94

Table 8-5: Utilization Create API – utilizationRequest JSON Attributes

Request JSON Attribute Name Description Required Data 

Type

Length Version

manufacturingCommProds The manufacturing commercial 

products made through the use of 

or Embodying the Subject 

Invention(s). Object attributes 

below.

No JSON 

Array

v2

 productName The unique commercial product 

name.

Yes String 100 v2

 naicsCode The North American Industry 

Classification System (NAICS) code 

is used by Federal agencies in 

classifying business establishments.

For DOE invention only.

No String 6 v2

 licensees The licensees associated with the 

product.

No JSON 

Array

v2

 licenseeName The name of the licensee. The 

name must come from the 

exclusiveLicensees list, the

nonExclusiveLicensees list, or the 

institution name can be used if the 

institution itself is the licensee.

Yes String 255 v2

manufacturers The manufacturers for the 

manufacturing commercial 

product.

Yes JSON 

Array

v2

 manufacturerName The name of the manufacturer Yes String 255 v2

 productLocation The manufacturing production 

location(s). Object attributes 

below.

Yes JSON 

Array

v2

 country The manufacturing country for the 

location. Refer to 11.1.9 Country 

List for a list of valid country Name 

values.

No String 30 v2

 state The manufacturing state for the 

location for applicable country. 

Refer to Section 1111.1.10 States 

List for a list of valid Code values.

No String 14 v2

 firstDate The first date of manufacturing. 

MM/DD/YYYY format.

This is required when DOE is one of 

the funding agencies for the 

Yes 

(Conditional

ly)

String 10 v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

95

Table 8-5: Utilization Create API – utilizationRequest JSON Attributes

Table 8-5: Utilization Create API – utilizationRequest JSON Attributes

Request JSON Attribute Name Description Required Data 

Type

Length Version

Invention Report this utilization is 

associated with.

 firstDateType The type for the first date of 

manufacturing. Please refer to 

11.1.18 for a list of acceptable type 

values.

This is required when DOE is one of 

the funding agencies for the 

Invention Report this utilization is 

associated with.

Yes 

(Conditional

ly)

String 8 v2

 productQuantity The total number of products at 

the manufacturing location.

This is required when DOE is one of 

the funding agencies for the 

Invention Report this utilization is 

associated with.

Yes 

(Conditional

ly)

Integer v2

commercialProds FDA Approved Commercial 

products.

No JSON 

Array 

v2

commercialName The name of the FDA approved 

commercial product.

Yes String 80 v2

fdaApprovalNumber The number of the FDA approved 

commercial product.

No String 20 v2

fdaApprovalType The type of the FDA approved 

commercial product. Please refer 

to section 11.1.15 in Appendix for a 

list of acceptable utilization

Commercial Product Type values.

No String 15 v2

govtReviewStatus The status of the FDA approved 

commercial product. Please refer 

to section 11.1.16 in Appendix for a 

list of acceptable utilization

Government Review Status values.

No String 10 v2

publicInd The public announced indicator flag 

of the FDA approved commercial 

product. Please refer to section 

11.1.17 in Appendix for a list of 

acceptable utilization commercial 

product Public Announced values.

No String 3 v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

96

8.2.3. Response Parameters

This section documents the response JSON objects, attributes, and types for a success or error 

response.

HTTP Status 200 (OK) 

Based on the request parameters, Create Utilization API provides the below response 

parameters.

Table 8-6: Utilization Create API – utilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

inventionReportNumber Automatically generated by the iEdison 

system for a new Invention Report 

after data has been submitted, checked 

for errors, and verified.

String v2

granteeOrganizationName The name of the organization 

established at registration.

String v2

inventionTitle The title of the Invention as it appears 

in the grantee/contractors employee’s 

Invention Report.

String v2

primaryAgency A Primary Agency must be designated 

for each Invention Report in iEdison. 

Refer to Section 11.1.8 Agency 

Mapping List for a list of valid 

abbreviations.

String v2

inventionReportDate The date the inventor discloses the 

subject Invention in writing to the 

recipient institution. MM/DD/YYYY 

format.

String v2

titleElectDate The Invention Elect Title Date. String v2

reportingYear The year for which the utilization 

report is being submitted.

Integer v2

latestStageDev The latest stage of development of any 

product arising from this Invention. 

Refer to Section 11.1.1 Invention 

Development Stage for a list of latest 

valid values.

String v2

firstCommercialSaleYear Year product embodying the Invention

was first sold (date of first commercial 

sale).

Integer v2

totalIncome Total income from royalty or option 

agreements for the Invention.

Integer v2

exclusiveLicensesOptions Number of exclusive licenses / option 

agreements for the Invention.

Integer v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

97

Table 8-6: Utilization Create API – utilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

nonExclusiveLicensesOptions Number of non-exclusive licenses / 

option agreements for the Invention.

Integer v2

smallBusinessLicensesOptions Number of small business licenses / 

option agreements for the Invention.

Integer v2

IsUSManufacturingRequired1 Other than U.S. Preference (35 U.S.C. 

204), is the invention subject to any 

U.S. manufacturing requirements (e.g.,

U.S. Competitiveness provision, a U.S. 

Manufacturing DEC, etc.)?

N (for No) and Y (for Yes).

String v2

IsUSManufacturingRequired2 1. If IsUSManufacturingRequired1 is N: 

In the designated reporting period do 

all grants to any person of the exclusive 

right to use or sell the subject invention 

in the United States require that any 

products embodying the subject 

invention or produced through the use 

of the subject invention will be 

manufactured substantially in the 

United States as required by 35 U.S.C. 

204? 

2. If IsUSManufacturingRequired1 is Y:

In the designated reporting period, do 

all licenses include a requirement that 

any products embodying the subject 

invention or produced through the use 

of the subject invention will be 

manufactured substantially in the 

United States (including manufacturing 

requirements other than 35 U.S.C. 

204)?

If latestStageDev is “Commercialized” 

or “Licensed” and 

isUSManufacturingRequired1 is “Y”, the 

value for this attribute can be “N” (for 

No), or “Y” (for Yes). 

If latestStageDev is “Commercialized” 

or “Licensed” and 

isUSManufacturingRequired1 is “N”, 

String v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

98

Table 8-6: Utilization Create API – utilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

the value for this attribute can be “N” 

(for No), or “Y” (for Yes), or “N/A” (for 

Not Applicable).

[See 11.1.21 and 11.1.22 for the 

questions logic]

IsUSManufacturingRequired3 1. If IsUSManufacturingRequired2 is N: 

In the designated reporting period are 

all products embodying the subject 

invention or produced through the use 

of the subject invention manufactured 

substantially in the United States for all 

grants to any person of the exclusive 

right to use or sell the subject invention 

in the United States as required by 35 

U.S.C. 204? 

2. If IsUSManufacturingRequired2 is Y:

In the designated reporting period, are 

all products embodying the subject 

invention or produced through the use 

of the subject invention manufactured 

substantially in the United 

States(including manufacturing 

requirements other than 35 U.S.C. 

204)?

If latestStageDev is “Commercialized” 

or “Licensed” and 

isUSManufacturingRequired1 is “Y”, the 

value for this attribute can be “N” (for 

No), or “Y” (for Yes). 

If latestStageDev is “Commercialized” 

or “Licensed” and 

isUSManufacturingRequired1 is “N”, 

the value for this attribute can be “N” 

(for No), or “Y” (for Yes), or “N/A” (for 

Not Applicable).

[See 11.1.21 and 11.1.22 for the 

questions logic]

String v2

notes General notes. String v2

commercializationPlanId The commercialization plan for the 

invention.

Number v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

99

Table 8-6: Utilization Create API – utilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

What are your current 

commercialization plans for this 

invention?

Refer to 11.1.20 Utilization 

Commercialization Plan for a list of 

valid commercialization plans.

exclusiveLicensees The exclusive licensee names for the 

invention.

[String] v2

nonExclusiveLicensees The non-exclusive licensee names for 

the invention.

[String] v2

newUsJobs Approximate number of new U.S.-

based jobs created because of 

commercialization efforts during the 

reporting period. For DOE Invention

only.

Integer v2

newUsCompanies Number of new U.S.-based companies 

created from the commercialization 

efforts during the reporting period. For 

DOE Invention only.

Integer v2

manufacturingCommProds The manufacturing commercial 

products made through the use of or 

Embodying the Subject Invention(s). 

Object attributes below.

JSON Array v2

 productName The unique commercial product name. String v2

 naicsCode The North American Industry 

Classification System (NAICS) code is 

used by Federal agencies in classifying 

business establishments. For DOE 

invention only.

String v2

 licensees The licensees associated with the 

product.

JSON Array v2

 licenseeName The name of the licensee. The name 

must come from the exclusiveLicensees 

list, the nonExclusiveLicensees list, or 

the institution name can be used if the 

institution itself is the licensee.

String v2

manufacturers The manufacturers for the 

manufacturing commercial product.

JSON Array v2

 manufacturerName The name of the manufacturer String v2

productLocation The manufacturing production 

location(s). Object attributes below.

JSON Array v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

100

Table 8-6: Utilization Create API – utilizationResponse JSON Attributes

Table 8-6: Utilization Create API – utilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

country The manufacturing country for the 

location. Refer to 11.1.9 Country List 

for a list of valid country Name values.

String v2

state The manufacturing state for the 

location for applicable country. Refer to 

Section 11.1.10 States List for a list of 

valid Code values.

String v2

firstDate The first date of manufacturing.

MM/DD/YYYY format.

String v2

firstDateType The type for the first date of 

manufacturing. Please refer to 11.1.18

for a list of acceptable type values.

String v2

productQuantity The total number of products at the 

manufacturing location.

Integer v2

commercialProds FDA Approved Commercial products. 

Object Attributes are below.

JSON Array v2

commercialName The name of the FDA approved 

commercial product.

String v2

fdaApprovalNumber The number of the FDA approved 

commercial product.

String v2

fdaApprovalType The type of the FDA approved 

commercial product. Please refer to 

section 11.1.15 in Appendix for a list of 

acceptable utilization Commercial 

Product Type values.

String v2

govtReviewStatus The status of the FDA approved 

commercial product. Please refer to 

section 11.1.16 in Appendix for a list of 

acceptable utilization Government 

Review Status values.

String v2

publicInd The public announced indicator flag of 

the FDA approved commercial product. 

Please refer to section 11.1.17 in 

Appendix for a list of acceptable 

utilization commercial product Public 

Announced values.

String v2

createdDate The created Date for the utilization

record.

String v2

updatedDate The last created Date for the utilization 

record.

String v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

101

8.2.4. Request Examples

A sample request for the Utilization Create REST API is shown below:

{

 "inventionReportNumber": "8046501-22-0004",

 "reportingYear": 2023,

 "latestStageDev": "Commercialized",

 "firstCommercialSaleYear": 2023,

 "totalIncome": 50000.0,

 "exclusiveLicensesOptions": 2,

 "nonExclusiveLicensesOptions": 2,

 "smallBusinessLicensesOptions": 10,

 "isUSManufacturingRequired1": "Y",

 "isUSManufacturingRequired2": "N",

 "isUSManufacturingRequired3": "Y",

 "notes": "new utilization notes",

 "exclusiveLicensees": [

 "John Wick",

 "Peter Griffin"

 ],

 "nonExclusiveLicensees": [

 "John Wick",

 "James Doe"

 ],

 "newUsJobs": 100,

 "newUsCompanies": 500,

 "manufacturingCommProds": [

 {

 "productName": "widgets",

 "naicsCode": "ABC123",

 "licensees": [

 {

 "licenseeName": "John Wick",

 "manufacturers": [

 {

 "manufacturerName": "Intel",

 "productLocation": [

 {
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

102

 "country": "CHINA"

 },

 {

 "state": "MARYLAND",

 "country": "UNITED STATES"

 }

 ]

 },

 {

 "manufacturerName": "IBM",

 "productLocation": [

 {

 "state": "FLORIDA",

 "country": "UNITED STATES"

 }

 ]

 }

 ]

 },

 {

 "licenseeName": "James Doe",

 "manufacturers": [

 {

 "manufacturerName": "IBM",

 "productLocation": [

 {

 "state": "MARYLAND",

 "country": "UNITED STATES"

 }

 ]

 }

 ]

 }

 ]

 },

 {

 "productName": "gadgets",

 "licensees": [

 {
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

103

 "licenseeName": "STANFORD UNIVERSITY",

 "manufacturers": [

 {

 "manufacturerName": "Google",

 "productLocation": [

 {

 "state": "COLORADO",

 "country": "UNITED STATES"

 }

 ]

 }

 ]

 },

 {

 "licenseeName": "John Wick",

 "manufacturers": [

 {

 "manufacturerName": "Apple",

 "productLocation": [

 {

 "state": "TEXAS",

 "country": "UNITED STATES"

 }

 ]

 }

 ]

 }

 ]

 }

 ],

 "commercialProds": [

 {

 "commercialName": "nih prods",

 "fdaApprovalNumber": "1234",

 "publicInd": "Yes",

 "govtReviewStatus": "Approved",

 "fdaApprovalType": "Medical Device"

 }

 ]
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

104

} ]

}

8.2.5. Response Examples

HTTP Status 200 (OK) 

A sample response and error for the Utilization Create REST API is shown below:

{

 "inventionReportNumber": "8046501-22-0004",

 "granteeOrganizationName": "STANFORD UNIVERSITY",

 "inventionTitle": "Multiplexed in vivo DNA parsing and stitching",

 "primaryAgency": "National Institutes of Health",

 "inventionReportDate": "01/30/2022",

 "titleElectDate": "01/30/2022",

 "reportingYear": 2023,

 "latestStageDev": "Commercialized",

 "firstCommercialSaleYear": 2023,

 "totalIncome": 50000.0,

 "exclusiveLicensesOptions": 2,

 "nonExclusiveLicensesOptions": 2,

 "smallBusinessLicensesOptions": 10,

 "totalGrossSales": 0.0,

 "isUSManufacturingRequired1": "Y",

 "isUSManufacturingRequired2": "N",

 "isUSManufacturingRequired3": "Y",

 "notes": "new utilization notes",

 "exclusiveLicensees": [

 "John Wick",

 "Peter Griffin"

 ],

 "nonExclusiveLicensees": [

 "John Wick",

 "James Doe"

 ],

 "newUsJobs": 100,

 "newUsCompanies": 500,

 "manufacturingCommProds": [
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

105

 {

 "productName": "widgets",

 "naicsCode": "ABC123",

 "licensees": [

 {

 "licenseeName": "James Doe",

 "manufacturers": [

 {

 "manufacturerName": "IBM",

 "productLocation": [

 {

 "state": "MARYLAND",

 "country": "UNITED STATES"

 }

 ]

 }

 ]

 },

 {

 "licenseeName": "John Wick",

 "manufacturers": [

 {

 "manufacturerName": "Intel",

 "productLocation": [

 {

 "state": "",

 "country": "CHINA"

 },

 {

 "state": "MARYLAND",

 "country": "UNITED STATES"

 }

 ]

 },

 {

 "manufacturerName": "IBM",

 "productLocation": [

 {

 "state": "FLORIDA",

 "country": "UNITED STATES"

 }
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

106

 ]

 }

 ]

 }

 ]

 },

 {

 "productName": "gadgets",

 "licensees": [

 {

 "licenseeName": "John Wick",

 "manufacturers": [

 {

 "manufacturerName": "Apple",

 "productLocation": [

 {

 "state": "TEXAS",

 "country": "UNITED STATES"

 }

 ]

 }

 ]

 },

 {

 "licenseeName": "STANFORD UNIVERSITY",

 "manufacturers": [

 {

 "manufacturerName": "Google",

 "productLocation": [

 {

 "state": "COLORADO",

 "country": "UNITED STATES"

 }

 ]

 }

 ]

 }

 ]

 }

 ],

 "commercialProds": [
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

107

 {

 "commercialName": "nih prods",

 "fdaApprovalNumber": "1234",

 "publicInd": "Yes",

 "govtReviewStatus": "Approved",

 "fdaApprovalType": "Medical Device"

 }

 ],

 "createdDate": "08/11/2023"

}

 

HTTP Status 400 (Bad Request) or 500 (Internal Server Error) 

{

 "responseCode": 400,

 "message": "Invalid form-data content",

 "errors": [

 {

 "code": "400",

 "field": "reportingYear",

 "message": "Reporting Year (YYYY) * value isrequired."

 }

 ]

}

HTTP Status 400 (Bad Request) or 500 (Internal Server Error) 

{

 "message": "Access Denied",

 "timestamp": "2022-06-10T09:58:10.534055700"

}

8.3. Update Utilization

8.3.1. Endpoint URI

Here’s an example of the v1 endpoint for the Update Utilization resource.

POST /iedison/api/v1/utilizations/update

8.3.2. Request Parameters

The API POST request has the following elements:
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

108

• Headers: these are the request headers such as Accept or Content-Type. The Accept 

header parameter defines the expected response body format when the API returns 

the response. For example, you can define a response as JSON by modifying the Accept 

header. This Accept header is required in all requests. 

• Body: body contains the data which will be submitted as the post request. For example, 

when submitting a form, format data and file content are sent in the body of the 

request.

The table below provides the explanation of the update utilization POST request Header and 

Body parameters which are expected by iEdison API.

Table 8-7: Utilization Update API Parameters

Request Parameters Description Required Data Type Version In

accept Setting to application/json. Yes String v1 header

utilizationRequest The utilization request JSON content in string 

format contains the utilization attributes. Refer to 

Table 8-8: Utilization Create API –

utilizationRequest JSON Attributes for details.

Yes String v1 formdata

Table 8-7: Utilization Update API Parameters

The table below shows the parameters that will be included in the JSON body during the 

processing of Update Utilization Request. The below parameters are included as JSON object 

in JSON body. The JSON object represents the metadata of the Patent that needs to be 

updated.

Table 8-8: Utilization Update API – utilizationRequest JSON Attributes

Request JSON Attribute Name Description Required Data Type Length Version

inventionReportNumber The Invention report number the 

utilization report is associated with.

Yes String 25 v1

reportingYear The year for which the utilization 

report is being submitted.

Yes Integer v1

latestStageDev The latest stage of development of 

any product arising from this 

Invention. Refer to Section 11.1.1

Invention Development Stage for a 

list of latest valid values.

Yes String 30 v1

firstCommercialSaleYear Year product embodying the 

Invention was first sold (Date of 

first commercial sale).

No Integer v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

109

Table 8-8: Utilization Update API – utilizationRequest JSON Attributes

Request JSON Attribute Name Description Required Data Type Length Version

totalIncome Total income from royalty or option 

agreements for the Invention.

No Number 

(float)

v1

manufacturingWaiver Used to indicate if a waiver for 

Manufacturing Requirement has 

been requested. Accepted values 

are 0 (for No) and 1 (for Yes).

Default: 0.

No Integer v1

manufacturingWaiverTotal Total number of manufacturing 

waivers obtained.

No Integer v1

domesticLicenseNumber Number of domestic manufacturing 

licenses.

No Integer

exclusiveLicensesOptions Number of exclusive licenses / 

option agreements for the 

Invention.

In the designated reporting period, 

how many exclusive licenses 

and/or options are active?

No Integer v1

nonExclusiveLicensesOptions Number of non-exclusive licenses / 

option agreements for the 

Invention.

In the designated reporting period, 

how many non-exclusive licenses 

and/or options are active?

No Integer v1

smallBusinessLicensesOptions Number of small business licenses / 

option agreements for the 

Invention.

How many licenses and/or options 

of any type to small businesses 

(<500 employees) are active in the 

designated reporting period?

No Integer v1

newUsJobs Approximate number of new USbased jobs created because of 

commercialization efforts during 

the reporting period.

No Integer v1

newUsCompanies Number of new U.S.-based 

companies created from the 

commercialization efforts during 

the reporting period. For DOE 

Invention only.

No Integer v1

utilizationDescription Describes how the development 

and commercialization of the 

subject Invention comply with any 

required U.S. manufacturing 

No String 1000 v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

110

Table 8-8: Utilization Update API – utilizationRequest JSON Attributes

Request JSON Attribute Name Description Required Data Type Length Version

requirements (e.g., U.S. Preference, 

a U.S. Competitive Clause, U.S. 

Manufacturing Plan, etc.) For DOE 

Invention only.

totalGrossSales Total Gross Sales for DOE Invention

only.

No Number v1

commercialProds FDA Approved Commercial 

products.

No JSON Array v1

commercialName The name of the FDA approved 

commercial product.

Yes String 80 v1

fdaApprovalNumber The number of the FDA approved 

commercial product.

No String 20 v1

fdaApprovalType The type of the FDA approved 

commercial product. Please refer 

to section 11.1.15 in Appendix for a 

list of acceptable Utilization 

Commercial Product Type values.

No String 15 v1

govtReviewStatus The status of the FDA approved 

commercial product. Please refer 

to section 11.1.16 in Appendix for a 

list of acceptable Utilization 

Government Review Status values.

No String 10 v1

publicInd The public announced indicator flag 

of the FDA approved commercial 

product. Please refer to section 

11.1.17 in Appendix for a list of 

acceptable utilization commercial 

product Public Announced values.

No String 3 v1

manufacturingCommProds The manufacturing commercial 

products made through the use of 

or Embodying the Subject 

Invention(s). Object attributes 

below.

No JSON Array v1

 productName The unique commercial product 

name.

Yes String 100 v1

 naicsCode The North American Industry 

Classification System (NAICS) code 

is used by Federal agencies in 

classifying business establishments.

No String 6 v1

productLocation The manufacturing production 

location(s). Object attributes 

below.

No JSON Array v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

111

Table 8-8: Utilization Update API – utilizationRequest JSON Attributes

8.3.3. Response Parameters

HTTP Status 200 (OK) 

Based on the request parameters, Update Utilization API provides the below response 

parameters.

Table 8-8: Utilization Update API – utilizationRequest JSON Attributes

Request JSON Attribute Name Description Required Data Type Length Version

 country The manufacturing country for the 

location. Refer to 11.1.9 Country 

List for a list of valid country Name 

values.

Yes String 30 v1

 state The manufacturing state for the 

location for applicable country. 

Refer to Section 11.1.10 States List 

for a list of valid Code values.

No String 14 v1

 firstDate The first date of manufacturing. 

MM/DD/YYYY format.

Yes String 10 v1

 firstDateType The type for the first date of 

manufacturing. Please refer to 

11.1.18 for a list of acceptable type 

values.

Yes String 8 v1

 productQuantity The total number of products at 

the manufacturing location.

Yes Integer v1

Table 8-9: Utilization Update API – utilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

inventionReportNumber The Invention Report Number which 

the utilization record is associated with.

String v1

granteeOrganizationName The name of the organization 

established at registration.

String v1

inventionTitle The title of the Invention as it appears 

in the grantee/contractors employee’s 

Invention Report.

String v1

primaryAgency A Primary Agency must be designated 

for each Invention Report in iEdison.

Refer to Section 11.1.8 Agency 

Mapping List for a list of valid 

abbreviations.

String v1

inventionReportDate The date the inventor discloses the 

subject Invention in writing to the 

recipient institution. MM/DD/YYYY 

format.

String v1

titleElectDate The Invention Elect Title Date. String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

112

Table 8-9: Utilization Update API – utilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

reportingYear The year for which the utilization

report is being submitted.

Integer v1

latestStageDev The latest stage of development of any 

product arising from this Invention. 

Refer to Section 11.1.1 Invention 

Development Stage for a list of latest 

valid values.

String v1

firstCommercialSaleYear Year product embodying the Invention

was first sold (Date of first commercial 

sale).

Integer v1

totalIncome Total income from royalty or option 

agreements for the Invention.

Integer v1

manufacturingWaiver Used to indicate if a waiver for 

Manufacturing Requirement has been 

requested. 0 (for No) and 1 (for Yes).

Integer v1

manufacturingWaiverTotal Total number of manufacturing waivers 

obtained.

Integer v1

exclusiveLicensesOptions Number of exclusive licenses / option 

agreements for the Invention.

Integer v1

nonExclusiveLicensesOptions Number of non-exclusive licenses / 

option agreements for the Invention.

Integer v1

smallBusinessLicensesOptions Number of small business licenses / 

option agreements for the Invention.

Integer v1

domesticLicenseNumber Total number of domestic 

manufacturing licensees.

Integer v1

newUsJobs Approximate number of new US-based 

jobs created because of 

commercialization efforts during the 

reporting period.

Integer

newUsCompanies Number of new U.S.-based companies 

created from the commercialization 

efforts during the reporting period. For 

DOE Invention only.

Integer

utilizationDescription Describe how the development and 

commercialization of the subject 

Invention comply with any required 

U.S. manufacturing requirements (e.g., 

U.S. Preference, a U.S. Competitive 

Clause, U.S. Manufacturing Plan, etc.)

For DOE Invention only.

String 1000

totalGrossSales Total Gross Sales for DOE Invention

only.

Number
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

113

Table 8-9: Utilization Update API – utilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

commercialProds FDA Approved Commercial products. 

Object Attributes are below.

JSON Array v1

 commercialName The name of the FDA approved 

commercial product.

String v1

 fdaApprovalNumber The number of the FDA approved 

commercial product.

String v1

 fdaApprovalType The type of the FDA approved 

commercial product. Please refer to 

section 11.1.15 in Appendix for a list of 

acceptable Utilization Commercial 

Product Type values.

String v1

 govtReviewStatus The status of the FDA approved 

commercial product. Please refer to 

section 11.1.16 in Appendix for a list of 

acceptable Utilization Government 

Review Status values.

String v1

 publicInd The public announced indicator flag of 

the FDA approved commercial product. 

Please refer to section 11.1.17 in 

Appendix for a list of acceptable 

utilization commercial product Public 

Announced values.

String v1

manufacturingCommProds The manufacturing commercial 

products made through the use of or 

Embodying the Subject Invention(s). 

JSON Object attributes below.

JSON Array v1

 productName The unique commercial product name. String v1

 naicsCode The North American Industry 

Classification System (NAICS) code is 

used by Federal agencies in classifying 

business establishments.

String v1

productLocation The manufacturing production 

location(s). JSON Object attributes 

below.

JSON Array v1

 country The manufacturing country for the 

location. Refer to 11.1.9 Country List 

for a list of valid country Name values.

String v1

 state The manufacturing state for the 

location for applicable country. Refer to 

Section 11.1.10 States List for a list of 

valid Code values.

String v1

 firstDate The first date of manufacturing. 

MM/DD/YYYY format.

String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

114

Table 8-9: Utilization Update API – utilizationResponse JSON Attributes

8.3.4. Request Example

A sample request for the Patent Update REST API is shown below:

{

 "inventionReportNumber": "07654321-22-0103",

 "reportingYear": 2010,

 "latestStageDev": "Commercialized",

 "firstCommercialSaleYear": 2009,

 "totalIncome": 3100,

 "manufacturingWaiver": 1,

 "manufacturingWaiverTotal": 6,

 "exclusiveLicensesOptions": 6,

 "domesticManufacturingLicenses": 7,

 "nonExclusiveLicensesOptions": 8,

 "smallBusinessLicensesOptions": 3,

 "totalGrossSales": 6500

}

8.3.5. Response Examples

This section documents the response examples for success, error, and access denied requests.

HTTP Status 200 (OK) 

A sample response for the Utilization Update REST API is shown below:

{

 "inventionReportNumber": "07654321-22-0103",

 "granteeOrganizationName": "DAN'S INSTITUTION",

 "inventionTitle": "REST - Create Invention108",

Table 8-9: Utilization Update API – utilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

 firstDateType The type for the first date of 

manufacturing. Please refer to 11.1.18

for a list of acceptable type values.

String v1

 productQuantity The total number of products at the 

manufacturing location.

Integer v1

createdDate The created date for the utilization

record.

String v1

updatedDate The last updated date for the utilization 

record.

String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

115

 "primaryAgency": "Army Research Laboratory - Army Research Office",

 "inventionReportDate": "01/31/2022",

 "titleElectDate": "06/10/2022",

 "reportingYear": 2010,

 "latestStageDev": "Commercialized",

 "firstCommercialSaleYear": 2009,

 "totalIncome": 3100.0,

 "manufacturingWaiver": 1,

 "manufacturingWaiverTotal": 6,

 "exclusiveLicensesOptions": 6,

 "domesticLicenseNumber": 0,

 "nonExclusiveLicensesOptions": 8,

 "smallBusinessLicensesOptions": 3,

 "totalGrossSales": 6500.0,

 "newUsJobs": 0,

 "newUsCompanies": 0

}

HTTP Status 400 (Bad Request) or 500 (Internal Server Error) 

{

 "responseCode": 400,

 "message": "Invalid form-data content",

 "errors": [

 {

 "code": "400",

 "field": "reportingYear",

 "message": "Reporting Year (YYYY) * value isrequired."

 }

 ]

}

HTTP Status 401 (Unauthorized) 

{

 "message": "Access Denied",

 "timestamp": "2022-06-10T09:58:10.534055700"

}
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

116

8.4. Update Utilization V2

8.4.1. Endpoint URI

Here’s an example of the v2 endpoint for the Update Utilization resource.

POST /iedison/api/v2/utilizations/update

8.4.2. Request Parameters

The API POST request has the following elements:

• Headers: These are the request headers such as Accept or Content-Type. The Accept 

header parameter defines the expected response body format when the API returns 

the response. For example, you can define a response as JSON by modifying the Accept 

header. This Accept header is required in all requests. 

• Body: Body contains the data which will be submitted as the post request. For example, 

when submitting a form, format data and file content are sent in the body of the 

request.

The table below provides the explanation of the update utilization POST request Header and 

Body parameters which are expected by iEdison API.

Table 8-10: Utilization Update API Parameters

Request Parameters Description Required Data Type Version In

accept Setting to application/json. Yes String v2 header

utilizationRequest The utilization request JSON content in string 

format contains the utilization attributes. Refer to 

Table 8-11: Utilization Create API –

utilizationRequest JSON Attributes for details.

Yes String v2 raw

Table 8-10: Utilization Update API Parameters

The table below shows the parameters that will be included in the JSON body during the 

processing of Update Utilization Request. The below parameters are included as JSON object in 

JSON body. The JSON object represents the metadata of the Patent that needs to be updated.
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

117

Table 8-11: Utilization Update API – utilizationRequest JSON Attributes

Request JSON Attribute 

Name

Description Required Data 

Type

Length Version

inventionReportNumber The Invention Report number the 

utilization report is associated with.

Yes String 25 v2

reportingYear The year for which the utilization

report is being submitted.

Yes Integer v2

latestStageDev The latest stage of development of 

any product arising from this 

Invention. Refer to Section 11.1.1

Invention Development Stage for a 

list of latest valid values.

Yes String 30 v2

firstCommercialSaleYear Year product embodying the 

Invention was first sold (date of 

first commercial sale).

This is required when 

latestStageDev has a value of 

“Commercialized” or “Licensed”.

Yes 

(Conditionally)

Integer v2

totalIncome Total income from royalty or option 

agreements for the Invention.

This is required when 

latestStageDev has a value of 

“Commercialized” or “Licensed”.

Yes 

(Conditionally)

Number 

(float)

v2

exclusiveLicensesOptions Number of exclusive licenses / 

option agreements for the 

Invention.

In the designated reporting period, 

how many exclusive licenses 

and/or options are active?

This is required when 

latestStageDev has a value of 

“Commercialized” or “Licensed”.

Yes 

(Conditionally)

Integer v2

nonExclusiveLicensesOptions Number of non-exclusive licenses / 

option agreements for the 

Invention.

In the designated reporting period, 

how many non-exclusive licenses 

and/or options are active?

Yes 

(Conditionally)

Integer v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

118

Table 8-11: Utilization Update API – utilizationRequest JSON Attributes

Request JSON Attribute 

Name

Description Required Data 

Type

Length Version

This is required when 

latestStageDev has a value of 

“Commercialized” or “Licensed”.

smallBusinessLicensesOption

s

Number of small business licenses / 

option agreements for the 

Invention.

How many licenses and/or options 

of any type to small businesses 

(<500 employees) are active in the 

designated reporting period?

This is required when 

latestStageDev has a value of 

“Commercialized” or “Licensed”.

Yes 

(Conditionally)

Integer v2

IsUSManufacturingRequired1 Other than U.S. Preference (35 

U.S.C. 204), is the invention subject 

to any U.S. manufacturing 

requirements (e.g., U.S. 

Competitiveness provision, a U.S. 

Manufacturing DEC, etc.)?

Accepted values are N (for No) and 

Y (for Yes).

This is required when 

latestStageDev has a value of 

“Commercialized” or “Licensed”.

Yes 

(Conditionally)

String 1 v2

IsUSManufacturingRequired2 1. If IsUSManufacturingRequired1

is N: In the designated reporting 

period do all grants to any person 

of the exclusive right to use or sell 

the subject invention in the United 

States require that any products 

embodying the subject invention or 

produced through the use of the 

subject invention will be 

manufactured substantially in the 

United States as required by 35 

U.S.C. 204? 

2. If IsUSManufacturingRequired1

is Y: In the designated reporting 

Yes 

(Conditionally)

String 3 v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

119

Table 8-11: Utilization Update API – utilizationRequest JSON Attributes

Request JSON Attribute 

Name

Description Required Data 

Type

Length Version

period, do all licenses include a 

requirement that any products 

embodying the subject invention or 

produced through the use of the 

subject invention will be 

manufactured substantially in the 

United States (including 

manufacturing requirements other 

than 35 U.S.C. 204)?

If latestStageDev is 

“Commercialized” or “Licensed” 

and isUSManufacturingRequired1

is “Y”, accepted value for this 

attribute can be “N” (for No), or “Y” 

(for Yes). 

If latestStageDev is 

“Commercialized” or “Licensed” 

and isUSManufacturingRequired1

is “N”, accepted value for this 

attribute can be “N” (for No), or “Y” 

(for Yes), or “N/A” (for Not 

Applicable).

[See 11.1.21 and 11.1.22 for the 

questions logic]

IsUSManufacturingRequired3 1. If IsUSManufacturingRequired2

is N: In the designated reporting 

period are all products embodying 

the subject invention or produced 

through the use of the subject 

invention manufactured 

substantially in the United States 

for all grants to any person of the 

exclusive right to use or sell the 

subject invention in the United 

States as required by 35 U.S.C. 

204? 

2. If IsUSManufacturingRequired2

is Y: In the designated reporting 

period, are all products embodying 

the subject invention or produced 

Yes 

(Conditionally)

String 3 v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

120

Table 8-11: Utilization Update API – utilizationRequest JSON Attributes

Request JSON Attribute 

Name

Description Required Data 

Type

Length Version

through the use of the subject 

invention manufactured 

substantially in the United 

States(including manufacturing 

requirements other than 35 U.S.C. 

204)?

If latestStageDev is 

“Commercialized” or “Licensed” 

and isUSManufacturingRequired1

is “Y”, accepted value for this 

attribute can be “N” (for No), or “Y” 

(for Yes). 

If latestStageDev is 

“Commercialized” or “Licensed” 

and isUSManufacturingRequired1

is “N”, accepted value for this 

attribute can be “N” (for No), or “Y” 

(for Yes), or “N/A” (for Not 

Applicable).

[See 11.1.21 and 11.1.22 for the 

questions logic]

notes General notes.

This is required when 

commercializationPlanId has a 

value of 3 or 6.

Yes 

(Conditionally)

String 1000 v2

commercializationPlanId The commercialization plan for the 

invention.

What are your current 

commercialization plans for this 

invention?

This is required when 

latestStageDev has a value of “Not 

Licensed or Commercialized”.

Refer to 11.1.20 Utilization 

Commercialization Plan for a list of 

valid commercialization plans.

Yes 

(Conditionally)

Number v2

exclusiveLicensees The exclusive licensee names for 

the invention.

Yes 

(Conditionally)

[String] v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

121

Table 8-11: Utilization Update API – utilizationRequest JSON Attributes

Request JSON Attribute 

Name

Description Required Data 

Type

Length Version

This is required when

exclusiveLicensesOptions has a 

value greater than 0.

nonExclusiveLicensees The non-exclusive licensee names 

for the invention.

This is required when

nonExclusiveLicensesOptions has a 

value greater than 0.

Yes 

(Conditionally)

[String] v2

newUsJobs Approximate number of new U.S.-

based jobs created because of 

commercialization efforts during 

the reporting period. For DOE 

Invention only.

No Integer v2

newUsCompanies Number of new U.S.-based 

companies created from the 

commercialization efforts during 

the reporting period. For DOE 

Invention only.

No Integer v2

manufacturingCommProds The manufacturing commercial 

products made through the use of 

or Embodying the Subject 

Invention(s). Object attributes 

below.

No JSON 

Array

v2

 productName The unique commercial product 

name.

Yes String 100 v2

 naicsCode The North American Industry 

Classification System (NAICS) code 

is used by Federal agencies in 

classifying business establishments.

For DOE invention only.

No String 6 v2

licensees The licensees associated with the 

product.

No JSON 

Array

v2

 licenseeName The name of the licensee. The 

name must come from the 

exclusiveLicensees list, the 

nonExclusiveLicensees list, or the 

institution name can be used if the 

institution itself is the licensee.

Yes String 255 v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

122

Table 8-11: Utilization Update API – utilizationRequest JSON Attributes

Request JSON Attribute 

Name

Description Required Data 

Type

Length Version

manufacturers The manufacturers for the 

manufacturing commercial 

product.

Yes JSON 

Array

v2

 manufacturerName The name of the manufacturer Yes String 255 v2

productLocation The manufacturing production 

location(s). Object attributes 

below.

Yes JSON 

Array

v2

 country The manufacturing country for the 

location. Refer to 11.1.9 Country 

List for a list of valid country Name 

values.

No String 30 v2

 state The manufacturing state for the 

location for applicable country. 

Refer to Section 11.1.10 States List 

for a list of valid Code values.

No String 14 v2

 firstDate The first date of manufacturing. 

MM/DD/YYYY format.

This is required when DOE is one of 

the funding agencies for the 

Invention Report this utilization is 

associated with.

Yes 

(Conditionally)

String 10 v2

 firstDateType The type for the first date of 

manufacturing. Please refer to 

11.1.18 for a list of acceptable type 

values.

This is required when DOE is one of 

the funding agencies for the 

Invention Report this utilization is 

associated with.

Yes 

(Conditionally)

String 8 v2

 productQuantity The total number of products at 

the manufacturing location.

This is required when DOE is one of 

the funding agencies for the 

Invention Report this utilization is 

associated with.

Yes 

(Conditionally)

Integer v2

commercialProds FDA Approved Commercial 

products.

No JSON 

Array 

v2

commercialName The name of the FDA approved 

commercial product.

Yes String 80 v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

123

Table 8-11: Utilization Update API – utilizationRequest JSON Attributes

8.4.3. Response Parameters

HTTP Status 200 (OK) 

Based on the request parameters, Update Utilization API provides the below response 

parameters.

Table 8-11: Utilization Update API – utilizationRequest JSON Attributes

Request JSON Attribute 

Name

Description Required Data 

Type

Length Version

fdaApprovalNumber The number of the FDA approved 

commercial product.

No String 20 v2

fdaApprovalType The type of the FDA approved 

commercial product. Please refer 

to section 11.1.15 in Appendix for a 

list of acceptable utilization

Commercial Product Type values.

No String 15 v2

govtReviewStatus The status of the FDA approved 

commercial product. Please refer 

to section 11.1.16 in Appendix for a 

list of acceptable utilization

Government Review Status values.

No String 10 v2

publicInd The public announced indicator flag 

of the FDA approved commercial 

product. Please refer to section 

11.1.17 in Appendix for a list of 

acceptable utilization commercial 

product Public Announced values.

No String 3 v2

Table 8-12: Utilization Update API – utilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

inventionReportNumber Automatically generated by the iEdison 

system for a new Invention Report 

after data has been submitted, checked 

for errors, and ve rified.

String v2

granteeOrganizationName The name of the organization 

established at registration.

String v2

inventionTitle The title of the Invention as it appears 

in the grantee/contractors employee’s 

Invention Report.

String v2

primaryAgency A Primary Agency must be designated 

for each Invention Report in iEdison. 

Refer to Section 11.1.8 Agency 

Mapping List for a list of valid 

abbreviations.

String v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

124

Table 8-12: Utilization Update API – utilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

inventionReportDate The date the inventor discloses the 

subject Invention in writing to the 

recipient institution. MM/DD/YYYY 

format.

String v2

titleElectDate The Invention Elect Title Date. String v2

reportingYear The year for which the utilization 

report is being submitted.

Integer v2

latestStageDev The latest stage of development of any 

product arising from this Invention. 

Refer to Section 11.1.1 Invention 

Development Stage for a list of latest 

valid values.

String v2

firstCommercialSaleYear Year product embodying the Invention

was first sold (date of first commercial 

sale).

Integer v2

totalIncome Total income from royalty or option 

agreements for the Invention.

Integer v2

exclusiveLicensesOptions Number of exclusive licenses / option 

agreements for the Invention.

Integer v2

nonExclusiveLicensesOptions Number of non-exclusive licenses / 

option agreements for the Invention.

Integer v2

smallBusinessLicensesOptions Number of small business licenses / 

option agreements for the Invention.

Integer v2

IsUSManufacturingRequired1 Other than U.S. Preference (35 U.S.C. 

204), is the invention subject to any 

U.S. manufacturing requirements (e.g.,

U.S. Competitiveness provision, a U.S. 

Manufacturing DEC, etc.)?

N (for No) and Y (for Yes).

String v2

IsUSManufacturingRequired2 1. If IsUSManufacturingRequired1 is N: 

In the designated reporting period do 

all grants to any person of the exclusive 

right to use or sell the subject invention 

in the United States require that any 

products embodying the subject 

invention or produced through the use 

of the subject invention will be 

manufactured substantially in the 

United States as required by 35 U.S.C. 

204? 

String v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

125

Table 8-12: Utilization Update API – utilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

2. If IsUSManufacturingRequired1 is Y:

In the designated reporting period, do 

all licenses include a requirement that 

any products embodying the subject 

invention or produced through the use 

of the subject invention will be 

manufactured substantially in the 

United States (including manufacturing 

requirements other than 35 U.S.C. 

204)?

If latestStageDev is “Commercialized” 

or “Licensed” and 

isUSManufacturingRequired1 is “Y”, the 

value for this attribute can be “N” (for 

No), or “Y” (for Yes). 

If latestStageDev is “Commercialized” 

or “Licensed” and 

isUSManufacturingRequired1 is “N”, 

the value for this attribute can be “N” 

(for No), or “Y” (for Yes), or “N/A” (for 

Not Applicable).

[See 11.1.21 and 11.1.22 for the 

questions logic]

IsUSManufacturingRequired3 1. If IsUSManufacturingRequired2 is N: 

In the designated reporting period are 

all products embodying the subject 

invention or produced through the use 

of the subject invention manufactured 

substantially in the United States for all 

grants to any person of the exclusive 

right to use or sell the subject invention 

in the United States as required by 35 

U.S.C. 204? 

2. If IsUSManufacturingRequired2 is Y:

In the designated reporting period, are 

all products embodying the subject 

invention or produced through the use 

of the subject invention manufactured 

substantially in the United States

(including manufacturing requirements 

other than 35 U.S.C. 204)?

String v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

126

Table 8-12: Utilization Update API – utilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

If latestStageDev is “Commercialized” 

or “Licensed” and 

isUSManufacturingRequired1 is “Y”, the 

value for this attribute can be “N” (for 

No), or “Y” (for Yes). 

If latestStageDev is “Commercialized” 

or “Licensed” and 

isUSManufacturingRequired1 is “N”, 

the value for this attribute can be “N” 

(for No), or “Y” (for Yes), or “N/A” (for 

Not Applicable).

[See 11.1.21 and 11.1.22 for the 

questions logic]

notes General notes. String v2

commercializationPlanId The commercialization plan for the 

invention.

What are your current 

commercialization plans for this 

invention?

Refer to 11.1.20 Utilization 

Commercialization Plan for a list of 

valid commercialization plans.

Number v2

exclusiveLicensees The exclusive licensee names for the 

invention.

[String] v2

nonExclusiveLicensees The non-exclusive licensee names for 

the invention.

[String] v2

newUsJobs Approximate number of new U.S.-

based jobs created because of 

commercialization efforts during the 

reporting period. For DOE Invention

only.

Integer v2

newUsCompanies Number of new U.S.-based companies 

created from the commercialization 

efforts during the reporting period. For 

DOE Invention only.

Integer v2

manufacturingCommProds The manufacturing commercial 

products made through the use of or 

Embodying the Subject Invention(s). 

Object attributes below.

JSON Array v2

 productName The unique commercial product name. String v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

127

Table 8-12: Utilization Update API – utilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

 naicsCode The North American Industry 

Classification System (NAICS) code is 

used by federal agencies in classifying 

business establishments. For DOE 

invention only.

String v2

 fdaApprovalNumber The number of the FDA approved 

commercial product. For NIH Invention

only.

String v2

 fdaApprovalType The type of the FDA approved 

commercial product. Please refer to 

section 11.1.15 in Appendix for a list of 

acceptable utilization Commercial 

Product Type values. For NIH Invention

only.

String v2

 govtReviewStatus The status of the FDA approved 

commercial product. Please refer to 

section 11.1.16 in Appendix for a list of 

acceptable utilization Government 

Review Status values. For NIH Invention

only.

String v2

 publicInd The public announced indicator flag of 

the FDA approved commercial product. 

Please refer to section 11.1.17 in 

Appendix for a list of acceptable 

utilization commercial product Public 

Announced values. For NIH Invention

only.

String v2

 isNih Indicates whether product is an NIH 

product. For NIH invention only.

Accepted value is Y (for Yes).

String v2

licensees The licensees associated with the 

product.

JSON Array v2

licenseeName The name of the licensee. The name 

must come from the exclusiveLicensees 

list, the nonExclusiveLicensees list, or 

the institution name can be used if the 

institution itself is the licensee.

String v2

manufacturers The manufacturers for the 

manufacturing commercial product.

JSON Array v2

manufacturerName The name of the manufacturer String v2

productLocation The manufacturing production 

location(s). Object attributes below.

JSON Array v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

128

Table 8-12: Utilization Update API – utilizationResponse JSON Attributes

Table 8-12: Utilization Update API – utilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

 country The manufacturing country for the 

location. Refer to 11.1.9 Country List 

for a list of valid country Name values.

String v2

 state The manufacturing state for the 

location for applicable country. Refer to 

Section 11.1.10 States List for a list of 

valid Code values.

String v2

 firstDate The first date of manufacturing.

MM/DD/YYYY format.

String v2

 firstDateType The type for the first date of 

manufacturing. Please refer to 11.1.18

for a list of acceptable type values.

String v2

 productQuantity The total number of products at the 

manufacturing location.

Integer v2

commercialProds FDA Approved Commercial products. 

Object Attributes are below.

JSON Array v2

commercialName The name of the FDA approved 

commercial product.

String v2

fdaApprovalNumber The number of the FDA approved 

commercial product.

String v2

fdaApprovalType The type of the FDA approved 

commercial product. Please refer to 

section 11.1.15 in Appendix for a list of 

acceptable Utilization Commercial 

Product Type values.

String v2

govtReviewStatus The status of the FDA approved 

commercial product. Please refer to 

section 11.1.16 in Appendix for a list of 

acceptable Utilization Government 

Review Status values.

String v2

publicInd The public announced indicator flag of 

the FDA approved commercial product. 

Please refer to section 11.1.17 in 

Appendix for a list of acceptable 

utilization commercial product Public 

Announced values.

String v2

createdDate The created Date for the utilization 

record.

String v2

updatedDate The last created Date for the utilization 

record.

String v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

129

8.4.4. Request Example

A sample request for the Patent Update REST API is shown below:

{

 "inventionReportNumber": "8046501-22-0004",

 "reportingYear": 2023,

 "latestStageDev": "Commercialized",

 "firstCommercialSaleYear": 2023,

 "totalIncome": 50000.0,

 "exclusiveLicensesOptions": 2,

 "nonExclusiveLicensesOptions": 2,

 "smallBusinessLicensesOptions": 10,

 "isUSManufacturingRequired1": "Y",

 "isUSManufacturingRequired2": "N",

 "isUSManufacturingRequired3": "Y",

 "notes": "new utilization notes",

 "exclusiveLicensees": [

 "John Wick",

 "Peter Griffin"

 ],

 "nonExclusiveLicensees": [

 "John Wick",

 "James Doe"

 ],

 "newUsJobs": 100,

 "newUsCompanies": 500,

 "manufacturingCommProds": [

 {

 "productName": "motherboards",

 "naicsCode": "ABC123",

 "licensees": [

 {

 "licenseeName": "John Wick",

 "manufacturers": [

 {

 "manufacturerName": "Intel",

 "productLocation": [

 {

 "country": "CHINA"
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

130

 },

 {

 "state": "MARYLAND",

 "country": "UNITED STATES"

 }

 ]

 },

 {

 "manufacturerName": "IBM",

 "productLocation": [

 {

 "state": "FLORIDA",

 "country": "UNITED STATES"

 }

 ]

 }

 ]

 },

 {

 "licenseeName": "James Doe",

 "manufacturers": [

 {

 "manufacturerName": "IBM",

 "productLocation": [

 {

 "state": "MARYLAND",

 "country": "UNITED STATES"

 }

 ]

 }

 ]

 }

 ]

 },

 {

 "productName": "gadgets",

 "licensees": [

 {

 "licenseeName": "STANFORD UNIVERSITY",
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

131

 "manufacturers": [

 {

 "manufacturerName": "Google",

 "productLocation": [

 {

 "state": "COLORADO",

 "country": "UNITED STATES"

 }

 ]

 }

 ]

 },

 {

 "licenseeName": "John Wick",

 "manufacturers": [

 {

 "manufacturerName": "Apple",

 "productLocation": [

 {

 "state": "TEXAS",

 "country": "UNITED STATES"

 }

 ]

 }

 ]

 }

 ]

 }

 ],

 "commercialProds": [

 {

 "commercialName": "nih prods",

 "fdaApprovalNumber": "431",

 "publicInd": "Yes",

 "govtReviewStatus": "Pending",

 "fdaApprovalType": "Biologic"

 }

 ]

}
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

132

8.4.5. Response Examples

This section documents the response examples for success, error, and access denied requests.

HTTP Status 200 (OK) 

A sample response for the Utilization Update REST API is shown below:

{

 "inventionReportNumber": "8046501-22-0004",

 "granteeOrganizationName": "STANFORD UNIVERSITY",

 "inventionTitle": "Multiplexed in vivo DNA parsing and stitching",

 "primaryAgency": "National Institutes of Health",

 "inventionReportDate": "01/30/2022",

 "titleElectDate": "01/30/2022",

 "reportingYear": 2023,

 "latestStageDev": "Commercialized",

 "firstCommercialSaleYear": 2023,

 "totalIncome": 50000.0,

 "exclusiveLicensesOptions": 2,

 "nonExclusiveLicensesOptions": 2,

 "smallBusinessLicensesOptions": 10,

 "totalGrossSales": 0.0,

 "isUSManufacturingRequired1": "Y",

 "isUSManufacturingRequired2": "N",

 "isUSManufacturingRequired3": "Y",

 "notes": "new utilization notes",

 "exclusiveLicensees": [

 "John Wick",

 "Peter Griffin"

 ],

 "nonExclusiveLicensees": [

 "John Wick",

 "James Doe"

 ],

 "newUsJobs": 100,

 "newUsCompanies": 500,

 "manufacturingCommProds": [

 {

 "productName": "motherboards",

 "naicsCode": "ABC123",

 "licensees": [

 {
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

133

 "licenseeName": "James Doe",

 "manufacturers": [

 {

 "manufacturerName": "IBM",

 "productLocation": [

 {

 "state": "MARYLAND",

 "country": "UNITED STATES"

 }

 ]

 }

 ]

 },

 {

 "licenseeName": "John Wick",

 "manufacturers": [

 {

 "manufacturerName": "Intel",

 "productLocation": [

 {

 "state": "",

 "country": "CHINA"

 },

 {

 "state": "MARYLAND",

 "country": "UNITED STATES"

 }

 ]

 },

 {

 "manufacturerName": "IBM",

 "productLocation": [

 {

 "state": "FLORIDA",

 "country": "UNITED STATES"

 }

 ]

 }

 ]

 }

 ]
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

134

 },

 {

 "productName": "gadgets",

 "licensees": [

 {

 "licenseeName": "STANFORD UNIVERSITY",

 "manufacturers": [

 {

 "manufacturerName": "Google",

 "productLocation": [

 {

 "state": "COLORADO",

 "country": "UNITED STATES"

 }

 ]

 }

 ]

 },

 {

 "licenseeName": "John Wick",

 "manufacturers": [

 {

 "manufacturerName": "Apple",

 "productLocation": [

 {

 "state": "TEXAS",

 "country": "UNITED STATES"

 }

 ]

 }

 ]

 }

 ]

 }

 ],

 "commercialProds": [

 {

 "commercialName": "nih prods",

 "fdaApprovalNumber": "431",

 "publicInd": "Yes",

 "govtReviewStatus": "Pending",
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

135

 "fdaApprovalType": "Biologic"

 }

 ],

 "createdDate": "08/11/2023",

 "lastUpdatedDate": "08/11/2023"

}

HTTP Status 400 (Bad Request) or 500 (Internal Server Error) 

{

 "responseCode": 400,

 "message": "Invalid form-data content",

 "errors": [

 {

 "code": "400",

 "field": "reportingYear",

 "message": "Reporting Year (YYYY) * value isrequired."

 }

 ]

}

HTTP Status 401 (Unauthorized) 

{

 "message": "Access Denied",

 "timestamp": "2022-06-10T09:58:10.534055700"

}

8.5. Search Utilization

Search conditions for Utilization Records Search is based on the AND operation with 

different Utilization Records Fields in JSON Request. 

For Example, if the Utilization Records search has Invention Report Number and Invention

Report Year, the search results include all the searches that matches Invention Report 

Number and Invention Report Year.

8.5.1. Endpoint URI

Here's an example of the v1 endpoint for the Search Utilization resource.

POST /iedison/api/v1/utilizations/search
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

136

8.5.2. Request Parameters

The API POST request has the following elements:

• Headers: these are the request headers such as Accept or Content-Type. The Accept 

header parameter defines the expected response body format when the API returns 

the response. For example, you can define a response as JSON by modifying the Accept 

header. This Accept header is required in all requests. 

• Body: body contains the data which will be submitted as the post request. For example, 

when submitting a form, format data and file content are sent in the body of the 

request.

The table below provides the explanation of the search utilization POST request Header and 

Body parameters which are expected by iEdison API.

Table 8-13: Utilization Search API Parameters

Request Parameters Description Data Type Version In

accept Setting to application/json. String v1 header

utilizationSearchCriteria The search utilization criteria filters in JSON 

String format. 

String v1 formdata

Table 8-13: Utilization Search API Parameters

The table below shows the parameters that will be included in the JSON body only one time 

during the processing of Search Utilization Request.

Table 8-14: Utilization Search API – utilizationSearchCriteria JSON Attributes

Request Parameter Description Data Type Length Version

limit Total number of records to be retrieved 

per page. This field must be a number.

Max Value = 100. The Default = 20.

Integer v1

offset Indicates the page index. Default offset 

starts with 0.

Integer v1

inventionReportNumber The Invention Report Number filter to 

search for utilization.

String 25 v1

inventionDocketNumber An internal reference number of the 

grantee/contractor organization to help 

track a reported Invention(s).

String 30 v1

grantContractNumber The grant or contract number as 

specified by the agency. The format is 

defined by the agency.

String 50 v1

latestStageDev The latest stage of development of any 

product arising from this Invention. 

Refer to Section 11.1.1 Invention 

String 30 v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

137

Table 8-14: Utilization Search API – utilizationSearchCriteria JSON Attributes

8.5.3. Response Parameters

Based on request parameters, Search Utilization provides the below response 

parameters.

Table 8-14: Utilization Search API – utilizationSearchCriteria JSON Attributes

Request Parameter Description Data Type Length Version

Development Stage for a list of latest 

valid values.

primaryAgency A Primary Agency must be designated 

for each Invention Report in iEdison.

Refer to Section 11.1.8 Agency Mapping 

List for a list of valid abbreviations.

String 50 v1

granteeOrganizationName The name of the organization 

established at registration.

String 100 v1

titleElectionStatus The Title Election Status the institution’s 

decision regarding the election of title 

for this Invention. Refer to Section 

11.1.11 Title Election Status for a list of 

valid values.

Array 

[String]

50 v1

inventionTitle The title of the Invention as it appears in 

the grantee/contractor’s employee's 

Invention Report.

String 255

inventionReportDateFrom The From Date that the inventor 

disclosed the subject Invention in 

writing to the recipient institution. 

MM/DD/YYYY format.

String 10 v1

inventionReportDateTo The To Date that the inventor disclosed 

the subject Invention in writing to the 

recipient institution. MM/DD/YYYY 

format.

String 10 v1

fiscalYear The year for which the utilization report 

is being submitted.

Int 50 v1

commercialProductName The name of the product that was 

developed.

String 80 v1

fdaApprovalNumber FDA Approval Number. String 20 v1

fdaReportType FDA Report Type

lastUpdatedFrom The ‘start from’ search date against the 

utilization last updated date. 

MM/DD/YYYY format.

String 10 v1

lastUpdatedTo The ‘up to’ search date against the 

utilization last updated date. 

MM/DD/YYYY format.

String 10 v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

138

Table 8-15: Utilization Search API – utilizationSearchCriteria JSON Attributes

The following table contains the UtilizationResponse for the response list.

Table 8-15: Utilization Search API – utilizationSearchCriteria JSON Attributes

Response Parameter Description Data 

Type

Version

totalRecords Total number of records for the 

search.

Number v1

limit Limit entered by a user while making 

the request, i.e., the total number of 

records the user wished to retrieve 

per page

Integer v1

offset Page index specified by a user. 

Default offset starts with 0 if user 

does not provide any offset in the 

request.

Integer v1

utilizations A list of utilizations. Array 

[Utilizati

onRespo

nse]

Table 8-16: Utilization Search API – UtilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

inventionReportNumber The Invention Report Number the 

utilization record is associated with.

String v1

granteeOrganizationName The name of the organization 

established at registration.

String v1

inventionTitle The title of the Invention as it appears 

in the grantee/contractors employee's 

Invention Report.

String v1

primaryAgency A Primary Agency must be designated 

for each Invention Report in iEdison.

Refer to Section 11.1.8 Agency 

Mapping List for a list of valid 

abbreviations.

String v1

inventionReportDate The date the inventor disclosed the 

subject Invention in writing to the 

recipient institution. MM/DD/YYYY 

format.

String v1

titleElectDate The Invention Elect Title Date. String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

139

Table 8-16: Utilization Search API – UtilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

reportingYear The year for which the utilization

report is being submitted.

Integer v1

latestStageDev The latest stage of development of any 

product arising from this Invention. 

Refer to Section 11.1.1 Invention 

Development Stage for a list of latest 

valid values.

String v1

firstCommercialSaleYear Year product embodying the Invention

was first sold (date of first commercial 

sale).

Integer v1

totalIncome Total income from royalty or option 

agreements for the Invention.

Integer v1

manufacturingWaiver Used to indicate if a waiver for 

Manufacturing Requirement has been 

requested. 0 (for No) and 1 (for Yes).

Integer v1

manufacturingWaiverTotal Total number of manufacturing waivers 

obtained.

Integer v1

exclusiveLicensesOptions Number of exclusive licenses / option 

agreements for the Invention.

Integer v1

nonExclusiveLicensesOptions Number of non-exclusive licenses / 

option agreements for the Invention.

Integer v1

smallBusinessLicensesOptions Number of small business licenses / 

option agreements for the Invention.

Integer v1

domesticLicenseNumber Total number of domestic 

manufacturing licensees.

Integer v1

newUsJobs Approximate number of new U.S.-

based jobs created because of 

commercialization efforts during the 

reporting period.

Integer

newUsCompanies Number of new U.S.-based companies 

created from the commercialization 

efforts during the reporting period. For 

DOE Invention only.

Integer

utilizationDescription Describe how the development and 

commercialization of the subject 

Invention comply with any required 

U.S. manufacturing requirements (e.g., 

U.S. Preference, a U.S. Competitive 

Clause, U.S. Manufacturing Plan, etc.) 

For DOE Invention only.

String 1000

totalGrossSales Total Gross Sales for DOE Invention

only.

Number
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

140

Table 8-16: Utilization Search API – UtilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

commercialProds FDA Approved Commercial products. 

Object Attributes are below.

JSON Array v1

commercialName The name of the FDA approved 

commercial product.

String v1

fdaApprovalNumber The number of the FDA approved 

commercial product.

String v1

fdaApprovalType The type of the FDA approved 

commercial product. Please refer to 

section 11.1.15 in Appendix for a list of 

acceptable Utilization Commercial 

Product Type values.

String v1

govtReviewStatus The status of the FDA approved 

commercial product. Please refer to 

section 11.1.16 in Appendix for a list of 

acceptable Utilization Government 

Review Status values.

String v1

publicInd The public announced indicator flag of 

the FDA approved commercial product. 

Please refer to section 11.1.17 in 

Appendix for a list of acceptable 

utilization commercial product Public 

Announced values.

String v1

manufacturingCommProds The manufacturing commercial 

products made through the use of or 

Embodying the Subject Invention(s). 

JSON Object attributes below.

JSON Array v1

productName The unique commercial product name. String v1

naicsCode The North American Industry 

Classification System (NAICS) code is 

used by Federal agencies in classifying 

business establishments.

String v1

productLocation The manufacturing production 

location(s). JSON Object attributes 

below.

JSON Array v1

country The manufacturing country for the 

location. Please refer to 11.1.9 for a list 

of acceptable country values.

String v1

state The manufacturing state for the 

location for applicable country. Refer to 

Section 11.1.10 States List for a list of 

valid Code values.

String v1

firstDate The first date of manufacturing.

MM/DD/YYYY format.

String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

141

Table 8-16: Utilization Search API – UtilizationResponse JSON Attributes

8.5.4. Request Example

Below is a sample of the utilizationSearchCriteria string for the Search Utilization REST API.

• Search by inventionTitle and fiscalYear example

{

 "inventionTitle": "Free-space time-domain method for measuring thin film dielectric properties",

 "fiscalYear": 2001

}

• Search by grantContractNumber example

{

 "grantContractNumber": "SB222222B2222"

}

8.5.5. Response Example

This section documents the response examples for success, error, and access denied requests.

HTTP Status 200 (OK) 

A sample success response for the Utilization Search REST API is shown below:

{

 "utilizations": [

 {

 "inventionReportNumber": "07654321-22-0058",

 "granteeOrganizationName": "DAN'S INSTITUTION",

 "inventionTitle": "Test notification 311",

 "primaryAgency": "National Institute of Standards and Technology",

 "inventionReportDate": "04/18/2022",

 "reportingYear": 2011,

Table 8-16: Utilization Search API – UtilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

firstDateType The type for the first date of 

manufacturing. Please refer to 11.1.18

for a list of acceptable type values.

String v1

productQuantity The total number of products at the 

manufacturing location.

Integer v1

createdDate The created date of the utilization 

record. MM/DD/YYYY format.

String v1

updatedDate The updated date of the utilization 

record. MM/DD/YYYY format.

String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

142

 "latestStageDev": "Commercialized",

 "manufacturingWaiver": 0

 }

 ],

 "totalRecords": 1,

 "limit": 1,

 "offset": 0

}

HTTP Status 400 (Bad Request) or 500 (Internal Server Error) 

{

 "responseCode": 400,

 "message": "Invalid form-data content",

 "errors": [

 {

 "code": "400",

 "field": "utilizationSearchCriteria",

 "message": "There in one of more JSON field not vaild: 'fiscaldaYear'. Please verify the 

Rest parameters and submit request again."

 }

 ]

}

HTTPS 401 (Unauthorized) 

{

 "message": "Access Denied",

 "timestamp": "2022-06-10T09:58:10.534055700"

}

8.6. Search Utilization V2

Search conditions for Utilization Records Search is based on the AND operation with 

different Utilization Records Fields in JSON Request. 

For Example, if the Utilization Records search has Invention Report Number and Invention

Report Year, the search results include all the searches that matches Invention Report 

Number and Invention Report Year.

8.6.1. Endpoint URI

Here's an example of the v2 endpoint for the Search Utilization resource.

POST /iedison/api/v2/utilizations/search
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

143

8.6.2. Request Parameters

The API POST request has the following elements:

• Headers: These are the request headers such as Accept or Content-Type. The Accept 

header parameter defines the expected response body format when the API returns 

the response. For example, you can define a response as JSON by modifying the Accept 

header. This Accept header is required in all requests. 

• Body: Body contains the data which will be submitted as the post request. For example, 

when submitting a form, format data and file content are sent in the body of the 

request.

The table below provides the explanation of the search utilization POST request Header and 

Body parameters which are expected by iEdison API.

Table 8-17: Utilization Search API Parameters

Request Parameters Description Data Type Version In

accept Setting to application/json. String v2 header

utilizationSearchCriteria The search utilization criteria filters in JSON 

String format. 

String v2 raw

Table 8-17: Utilization Search API Parameters

The table below shows the parameters that will be included in the JSON body only one time 

during the processing of Search Utilization Request.

Table 8-18: Utilization Search API – utilizationSearchCriteria JSON Attributes

Request Parameter Description Data Type Length Version

limit Total number of records to be retrieved 

per page. This field must be a number.

Max Value = 100. The Default = 20.

Integer v2

offset Indicates the page index. Default offset 

starts with 0.

Integer v2

inventionReportNumber The Invention Report Number filter to 

search for utilization.

String 25 v2

inventionDocketNumber An internal reference number of the 

grantee/contractor organization to help 

track a reported Invention(s).

String 30 v2

grantContractNumber The grant or contract number as 

specified by the agency. The format is 

defined by the agency.

String 50 v2

latestStageDev The latest stage of development of any 

product arising from this Invention. 

Refer to Section 11.1.1 Invention 

String 30 v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

144

Table 8-18: Utilization Search API – utilizationSearchCriteria JSON Attributes

8.6.3. Response Parameters

Based on request parameters, Search Utilization provides the below response 

parameters.

Table 8-18: Utilization Search API – utilizationSearchCriteria JSON Attributes

Request Parameter Description Data Type Length Version

Development Stage for a list of latest 

valid values.

primaryAgency A Primary Agency must be designated 

for each Invention Report in iEdison. 

Refer to Section 11.1.8 Agency Mapping 

List for a list of valid abbreviations.

String 50 v2

granteeOrganizationName The name of the organization 

established at registration.

String 100 v2

titleElectionStatus The Title Election Status the institution’s 

decision regarding the election of title 

for this Invention. Refer to Section 

11.1.11 Title Election Status for a list of 

valid values.

Array 

[String]

50 v2

inventionTitle The title of the Invention as it appears in 

the grantee/contractors employee's 

Invention Report.

String 255 v2

inventionReportDateFrom The From Date that the inventor 

disclosed the subject Invention in 

writing to the recipient institution. 

MM/DD/YYYY format.

String 10 v2

inventionReportDateTo The To Date that the inventor disclosed 

the subject Invention in writing to the 

recipient institution. MM/DD/YYYY 

format.

String 10 v2

fiscalYear The year for which the utilization report 

is being submitted.

Int 50 v2

commercialProductName The name of the product that was 

developed.

String 80 v2

fdaApprovalNumber FDA Approval Number. String 20 v2

fdaReportType FDA Report Type v2

lastUpdatedFrom The ‘start from’ search date against the 

utilization last updated date. 

MM/DD/YYYY format.

String 10 v2

lastUpdatedTo The ‘up to’ search date against the 

utilization last updated date. 

MM/DD/YYYY format.

String 10 v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

145

Table 8-19: Utilization Search API – utilizationSearchCriteria JSON Attributes

The following table contains the UtilizationResponse for the response list.

Table 8-19: Utilization Search API – utilizationSearchCriteria JSON Attributes

Response Parameter Description Data 

Type

Version

totalRecords Total number of records for the 

search.

Number v2

limit Limit entered by a user while making 

the request, i.e., the total number of 

records the user wished to retrieve 

per page

Integer v2

offset Page index specified by a user. 

Default offset starts with 0 if user 

does not provide any offset in the 

request.

Integer v2

utilizations A list of utilizations. Array 

[Utilizati

onRespo

nse]

v2

Table 8-20: Utilization Search API – UtilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

inventionReportNumber Automatically generated by the iEdison 

system for a new Invention Report 

after data has been submitted, checked 

for errors, and verified.

String v2

granteeOrganizationName The name of the organization 

established at registration.

String v2

inventionTitle The title of the Invention as it appears 

in the grantee/contractors employee’s 

Invention Report.

String v2

primaryAgency A Primary Agency must be designated 

for each Invention Report in iEdison. 

Refer to Section 11.1.8 Agency 

Mapping List for a list of valid 

abbreviations.

String v2

inventionReportDate The date the inventor discloses the 

subject Invention in writing to the 

recipient institution. MM/DD/YYYY 

format.

String v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

146

Table 8-20: Utilization Search API – UtilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

titleElectDate The Invention Elect Title Date. String v2

reportingYear The year for which the utilization 

report is being submitted.

Integer v2

latestStageDev The latest stage of development of any 

product arising from this Invention. 

Refer to Section 11.1.1 Invention 

Development Stage for a list of latest 

valid values.

String v2

firstCommercialSaleYear Year product embodying the Invention

was first sold (date of first commercial 

sale).

Integer v2

totalIncome Total income from royalty or option 

agreements for the Invention.

Integer v2

exclusiveLicensesOptions Number of exclusive licenses / option 

agreements for the Invention.

Integer v2

nonExclusiveLicensesOptions Number of non-exclusive licenses / 

option agreements for the Invention.

Integer v2

smallBusinessLicensesOptions Number of small business licenses / 

option agreements for the Invention.

Integer v2

isUSManufacturingRequired1 Other than U.S. Preference (35 U.S.C. 

204), is the invention subject to any 

U.S. manufacturing requirements (e.g.,

U.S. Competitiveness provision, a U.S. 

Manufacturing DEC, etc.)?

N (for No) and Y (for Yes).

String v2

isUSManufacturingRequired2 1. If IsUSManufacturingRequired1 is N: 

In the designated reporting period do 

all grants to any person of the exclusive 

right to use or sell the subject invention 

in the United States require that any 

products embodying the subject 

invention or produced through the use 

of the subject invention will be 

manufactured substantially in the 

United States as required by 35 U.S.C. 

204? 

2. If IsUSManufacturingRequired1 is Y:

In the designated reporting period, do 

all licenses include a requirement that 

any products embodying the subject 

invention or produced through the use 

String v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

147

Table 8-20: Utilization Search API – UtilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

of the subject invention will be 

manufactured substantially in the 

United States (including manufacturing 

requirements other than 35 U.S.C. 

204)?

If latestStageDev is “Commercialized”

or “Licensed” and 

isUSManufacturingRequired1 is “Y”, the 

value for this attribute can be “N” (for 

No), or “Y” (for Yes). 

If latestStageDev is “Commercialized” 

or “Licensed” and 

isUSManufacturingRequired1 is “N”, 

the value for this attribute can be “N” 

(for No), or “Y” (for Yes), or “N/A” (for 

Not Applicable).

[See 11.1.21 and 11.1.22 for the 

questions logic]

isUSManufacturingRequired3 1. If IsUSManufacturingRequired2 is N: 

In the designated reporting period are 

all products embodying the subject 

invention or produced through the use 

of the subject invention manufactured 

substantially in the United States for all 

grants to any person of the exclusive 

right to use or sell the subject invention 

in the United States as required by 35 

U.S.C. 204? 

2. If IsUSManufacturingRequired2 is Y:

In the designated reporting period, are 

all products embodying the subject 

invention or produced through the use 

of the subject invention manufactured 

substantially in the United States

(including manufacturing requirements 

other than 35 U.S.C. 204)?

If latestStageDev is “Commercialized” 

or “Licensed” and 

isUSManufacturingRequired1 is “Y”, the 

String v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

148

Table 8-20: Utilization Search API – UtilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

value for this attribute can be “N” (for 

No), or “Y” (for Yes). 

If latestStageDev is “Commercialized” 

or “Licensed” and 

isUSManufacturingRequired1 is “N”, 

the value for this attribute can be “N” 

(for No), or “Y” (for Yes), or “N/A” (for 

Not Applicable).

[See See 11.1.21 and 11.1.22 for the 

questions logic]

notes General notes. String v2

commercializationPlanId The commercialization plan for the 

invention.

What are your current 

commercialization plans for this 

invention?

Refer to 11.1.20 Utilization 

Commercialization Plan for a list of 

valid commercialization plans.

Number v2

exclusiveLicensees The exclusive licensee names for the 

invention.

[String] v2

nonExclusiveLicensees The non-exclusive licensee names for 

the invention.

[String] v2

newUsJobs Approximate number of new U.S.-

based jobs created because of 

commercialization efforts during the 

reporting period. For DOE Invention

only.

Integer v2

newUsCompanies Number of new U.S.-based companies 

created from the commercialization 

efforts during the reporting period. For 

DOE Invention only.

Integer v2

utilizationDescription Describe how the development and 

commercialization of the subject 

Invention complies with any required 

U.S. manufacturing requirements (e.g., 

U.S. Preference, a U.S. Competitive 

Clause, U.S. Manufacturing Plan, etc.) 

For DOE Invention only.

String v2

manufacturingCommProds The manufacturing commercial 

products made through the use of or 

JSON Array v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

149

Table 8-20: Utilization Search API – UtilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

Embodying the Subject Invention(s). 

Object attributes below.

productName The unique commercial product name. String v2

naicsCode The North American Industry 

Classification System (NAICS) code is 

used by Federal agencies in classifying 

business establishments. For DOE 

invention only.

String v2

fdaApprovalNumber The number of the FDA approved 

commercial product. For NIH Invention

only.

String v2

fdaApprovalType The type of the FDA approved 

commercial product. Please refer to 

section 11.1.15 in Appendix for a list of 

acceptable utilization Commercial 

Product Type values. For NIH Invention

only.

String v2

govtReviewStatus The status of the FDA approved 

commercial product. Please refer to 

section 11.1.16 in Appendix for a list of 

acceptable utilization Government 

Review Status values. For NIH Invention

only.

String v2

publicInd The public announced indicator flag of 

the FDA approved commercial product. 

Please refer to section 11.1.17 in 

Appendix for a list of acceptable 

utilization commercial product Public 

Announced values. For NIH Invention

only.

String v2

isNih Indicates whether product is an NIH 

product. For NIH invention only.

Accepted value is Y (for Yes).

String v2

licensees The licensees associated with the 

product.

JSON Array v2

licenseeName The name of the licensee. The name 

must come from the exclusiveLicensees 

list, the nonExclusiveLicensees list, or 

the institution name can be used if the 

institution itself is the licensee.

String v2

Manufacturers The manufacturers for the 

manufacturing commercial product.

JSON Array v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

150

Table 8-20: Utilization Search API – UtilizationResponse JSON Attributes

Response JSON Attribute Name Description Data Type Version

 manufacturerName The name of the manufacturer String v2

productLocation The manufacturing production 

location(s). Object attributes below.

JSON Array v2

 country The manufacturing country for the 

location. Refer to 11.1.9 Country List 

for a list of valid country Name values.

String v2

 state The manufacturing state for the 

location for applicable country. Refer to 

Section 11.1.10 States List for a list of 

valid Code values.

String v2

 firstDate The first date of manufacturing. 

MM/DD/YYYY format.

String v2

 firstDateType The type for the first date of 

manufacturing. Please refer to 11.1.18

for a list of acceptable type values.

String v2

 productQuantity The total number of products at the 

manufacturing location.

Integer v2

commercialProds FDA Approved Commercial products. 

Object Attributes are below.

JSON Array v2

commercialName The name of the FDA approved 

commercial product.

String v2

fdaApprovalNumber The number of the FDA approved 

commercial product.

String v2

fdaApprovalType The type of the FDA approved 

commercial product. Please refer to 

section 11.1.15 in Appendix for a list of 

acceptable Utilization Commercial 

Product Type values.

String v2

govtReviewStatus The status of the FDA approved 

commercial product. Please refer to 

section 11.1.16 in Appendix for a list of 

acceptable Utilization Government 

Review Status values.

String v2

publicInd The public announced indicator flag of 

the FDA approved commercial product. 

Please refer to section 11.1.17 in 

Appendix for a list of acceptable 

utilization commercial product Public 

Announced values.

String v2

createdDate The created Date for the utilization 

record.

String v2

updatedDate The last created Date for the utilization 

record.

String v2
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

151

Table 8-20: Utilization Search API – UtilizationResponse JSON Attributes

8.6.4 Request Example

Below is a sample of the utilizationSearchCriteria string for the Search Utilization REST API.

• Search by inventionTitle and fiscalYear example

{

 "inventionTitle": "Free-space time-domain method for measuring thin film dielectric properties",

 "fiscalYear": 2001

}

• Search by grantContractNumber example

{

 "grantContractNumber": "SB222222B2222"

}

8.6.5 Response Example

This section documents the response examples for success, error, and access denied requests.

HTTP Status 200 (OK) 

A sample success response for the Utilization Search REST API is shown below:

{

 "utilizations": [

 {

 "inventionReportNumber": "8046501-22-0004",

 "granteeOrganizationName": "STANFORD UNIVERSITY",

 "inventionTitle": "Multiplexed in vivo DNA parsing and stitching",

 "primaryAgency": "National Institutes of Health",

 "inventionReportDate": "01/30/2022",

 "titleElectDate": "01/30/2022",

 "reportingYear": 2023,

 "latestStageDev": "Commercialized",

 "firstCommercialSaleYear": 2023,

 "totalIncome": 50000.0,

 "exclusiveLicensesOptions": 2,

 "nonExclusiveLicensesOptions": 2,

 "smallBusinessLicensesOptions": 10,

 "totalGrossSales": 0.0,

 "isUSManufacturingRequired1": "Y",

 "isUSManufacturingRequired2": "N",
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

152

 "isUSManufacturingRequired3": "Y",

 "notes": "new utilization notes",

 "exclusiveLicensees": [

 "John Wick",

 "Peter Griffin"

 ],

 "nonExclusiveLicensees": [

 "James Doe",

 "John Wick"

 ],

 "newUsJobs": 100,

 "newUsCompanies": 500,

 "manufacturingCommProds": [

 {

 "productName": "gadgets",

 "licensees": [

 {

 "licenseeName": "STANFORD UNIVERSITY",

 "manufacturers": [

 {

 "manufacturerName": "Google",

 "productLocation": [

 {

 "state": "COLORADO",

 "country": "UNITED STATES"

 }

 ]

 }

 ]

 },

 {

 "licenseeName": "John Wick",

 "manufacturers": [

 {

 "manufacturerName": "Apple",

 "productLocation": [

 {

 "state": "TEXAS",

 "country": "UNITED STATES"

 }

 ]
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

153

 }

 ]

 }

 ]

 },

 {

 "productName": "motherboards",

 "naicsCode": "ABC123",

 "licensees": [

 {

 "licenseeName": "James Doe",

 "manufacturers": [

 {

 "manufacturerName": "IBM",

 "productLocation": [

 {

 "state": "MARYLAND",

"country": "UNITED STATES"

 }

 ]

 }

 ]

 },

 {

 "licenseeName": "John Wick",

 "manufacturers": [

 {

 "manufacturerName": "Intel",

 "productLocation": [

 {

 "state": "MARYLAND",

"country": "UNITED STATES"

 },

 {

 "state": "",

 "country": "CHINA"

 }

 ]

 },

 {

 "manufacturerName": "IBM",
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

154

 "productLocation": [

 {

 "state": "FLORIDA",

 "country": "UNITED STATES"

 }

 ]

 }

 ]

 }

 ]

 }

 ],

 "commercialProds": [

 {

 "commercialName": "nih prods",

 "fdaApprovalNumber": "431",

 "publicInd": "Yes",

 "govtReviewStatus": "Pending",

 "fdaApprovalType": "Biologic"

 }

 ],

 "createdDate": "08/11/2023",

 "lastUpdatedDate": "08/11/2023"

 }

 ],

 "totalRecords": 1,

 "limit": 100,

 "offset": 0

}

HTTP Status 400 (Bad Request) or 500 (Internal Server Error) 

{

 "responseCode": 400,

 "message": "Invalid form-data content",

 "errors": [

 {

 "code": "400",

 "field": "utilizationSearchCriteria",

 "message": "There in one of more JSON field not 154ilen: ‘fiscaldaYear’. Please verify 

the Rest parameters and submit request again."

 }
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

155

 ]

}

HTTPS 401 (Unauthorized) 

{

 "message": "Access Denied",

 "timestamp": "2022-06-10T09:58:10.534055700"

}

9.0 Document API Reference

The document APIs provide ways to search for a list of disclosure document, Confirmatory License, 

Government Support Clause, and others document type from the Inventions and Patents; or download a 

specific document.

9.1 Search Document

Search condition for documents is the combination of attributes of the SearchDocumentCriteria JSON

object. System only will return documents which granted access permission to the user’s organization. 

9.1.1 Endpoint URI

Here’s an example of the v1 endpoint for the Search Documents resource.

POST /iedison/api/v1/documents/search

9.1.2 Request Parameters

The API POST request has the following elements:

• Headers: these are the request headers such as Accept or Content-Type. The Accept 

header parameter defines the expected response body format when the API returns 

the response. For example, you can define a response as JSON by modifying the Accept 

header. This Accept header is required in all requests. 

• Body: body contains the data which will be submitted as the post request. For example, 

when submitting a form, format data and file content are sent in the body of the 

request.

The table below provides the explanation of the search download document POST request 

Header and Body parameters which are expected by iEdison API.
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

156

The table below shows the parameters that will be included in the JSON body during the

processing of Document Search Request. The below parameters are included as JSON object in 

JSON body. The JSON object represents the metadata for the search criteria. The search will 

retrieve Invention documents only. If the JSON object contains Patent documents, then the 

search will retrieve Patent documents only.

Request Parameters Description Required Data 

Type

Version In

accept Setting to application/json. Yes String v1 header

documentSearchCriteria The documentSearchCriteria json 

objects containing fields to be 

used in the search. See table 

below.

Yes String v1 formdata

Table 8-21

Request Parameter Description Required Data 

Type

Length Version

inventionReportNumber Automatically generated by the 

iEdison system for a new 

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

patentDocketNumber The Patent Docket Number 

field is for an internal reference 

number of the 

grantee/contractor 

organization to help track a 

reported Patent(s).

No String 30 v1

primaryAgency A Primary Agency must be 

designated for each Invention 

Report in iEdison. Refer to 

Section 10.1.8 Agency Mapping 

List for a list of valid 

abbreviations.

No String 30 v1

granteeOrganizationName The name of the organization 

established at registration.

No String 100 v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

157

Table 8-21

Request Parameter Description Required Data 

Type

Length Version

titleElectionStatus The current status of the title 

to rights in the reported 

Invention. Refer to Section 

11.1.11 Title Election Status for 

a list of valid values.

No String 80 v1

inventionTitle The title of the Invention as it 

appears in the 

grantee/contractors 

employee’s Invention Report.

No String 255 v1

inventionReportDateFrom The From Date that the 

inventor disclosed in the 

subject Invention in writing to 

the recipient institution. 

MM/DD/YYYY format.

No String 10 v1

inventionReportDateTo The To Date that the inventor 

disclosed in the subject 

Invention in writing to the 

recipient institution. 

MM/DD/YYYY format.

No String 10 v1

patentFilingDateFrom The ‘starting from’ search date 

against the PCT, Provisional, 

Non-Provisional Patent 

application filing date. 

MM/DD/YYYY format.

No String 10 v1

patentFilingDateTo The ‘up to’ search date against 

the PCT, Provisional, NonProvisional Patent application 

filing date. MM/DD/YYYY 

format.

No String 10 v1

patentApplicationType Patent Application Type of a 

record. Refer to Section 11.1.3 

Patent Application Types for a 

list of valid values.

No String 25 v1

patentStatus Used to identify the current 

status of a Patent. Refer to 

Section 11.1.7 Patent Status for 

a list of valid values.

No String 50 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
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

158

Table 8-21

9.1.3 Response Parameters

This section documents the response JSON objects, attributes, and types for a success or error 

response.

HTTP Status 200 (OK) 

Based on the request parameters, Document Search API provides the below response 

parameters.

Table 8-21

Request Parameter Description Required Data 

Type

Length Version

grantContractNumber The grant or contract number 

as specified by the agency. The 

format is defined by the 

agency.

No String 50 v1

inventorFirstName First name of an inventor. No String 50 v1

inventorLastName Last name of an inventor. No String 50 v1

lastUpdatedFrom Search the "From Date" of the 

document last updated date,

MM/DD/YYYY format.

No String 10 v1

lastUpdatedTo Search the "To Date" of the 

document last updated date,

MM/DD/YYYY format.

No String 10 v1

lastUpdatedDate Document last updated date,

MM/DD/YYYY format.

No String 10 v1

limit Total number of records to be 

retrieved per page. This field 

must be a number Max Value = 

100. The Default = 20.

No Integer v1

offset Indicates the page index. 

Default offset starts with 0.

No Integer v1

Response Parameter Description Data Type Version

totalRecords Total number of records for 

the search.

Number v1

documentsList A list of document response 

Objects. Table 7-14 below lists

the JSON object attributes.

Object 

Array

v1

limit The limit used in the request Integer v1

offset The offset used in the request Integer v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

159

Below are the document response Object attributes.

9.1.4 Request and Response Examples 

A sample request for the Document Search REST API is shown below 

(documentSearchCriteria):

{

"inventionReportNumber": "7654321-22-0181"

}

A sample response and error for the Document Search REST API is shown below:

{

 "documentsList": [

 {

 "inventionReportNumber": "7654321-22-0181",

 "documentType": 6,

 "documentTypeName": "General",

 "documentID": 739268034,

 "fileName": "1408.txt",

 "documentCreateDate": "2022-10-28 10:26:32",

 "documentUpdateDate": "2022-11-02 11:20:58"

 },

Response Parameter Description Data Type Version

inventionReportNumber System generated sequence 

number used for ID of the 

Patent.

String v1

patentDocketNum The Patent Docket Number 

field is for an internal 

reference number of the 

grantee/contractor 

organization to help track a 

reported Patent(s).

String v1

documentType The unique identifier for 

document category types.

Number v1

documentTypeName The name of document 

category types.

String v1

documentID Unique identifier. String v1

fileName Name of the download file. String v1

documentCreateDate Date document was created. String v1

documentUpdateDate Last document update date. String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

160

 {

 "inventionReportNumber": "7654321-22-0181",

 "documentType": 9,

 "documentTypeName": "Invention Disclosure",

 "documentID": 739267910,

 "fileName": "1320_7654321-22-0181.txt",

 "documentCreateDate": "2022-10-18 20:22:41",

 "documentUpdateDate": "2022-11-02 11:20:58"

 },

 {

 "inventionReportNumber": "7654321-22-0181",

 "documentType": 6,

 "documentTypeName": "General",

 "documentID": 739268013,

 "fileName": "1717.txt",

 "documentCreateDate": "2022-10-26 16:04:18",

 "documentUpdateDate": "2022-11-02 11:20:58"

 },

 {

 "inventionReportNumber": "7654321-22-0181",

 "documentType": 20,

 "documentTypeName": "Publication",

 "documentID": 739268014,

 "fileName": "1361.txt",

 "documentCreateDate": "2022-10-26 16:05:30",

 "documentUpdateDate": "2022-11-02 11:20:58"

 }

 ],

 "totalRecords": 4

}

A sample request for the Document Search REST API is shown below:

inventionReportNumber + patentDocketNumber

{

"inventionReportNumber": "7654321-22-0181",

 "patentDocketNumber": "22-0181-01"

}

A sample response and error for the Document Search REST API is shown below:
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

161

{

 

"documentsList": [

 {

 "inventionReportNumber": "7654321-22-0181",

 "patentDocketNum": "22-0181-01",

 "documentType": 2,

 "documentTypeName": "Confirmatory License",

 "documentID": 739268015,

 "fileName": "confirmatorylicense338527583338529874.pdf",

 "documentCreateDate": "2022-10-26 16:12:15",

 "documentUpdateDate": "2022-11-02 17:15:16"

 },

 {

 "inventionReportNumber": "7654321-22-0181",

 "patentDocketNum": "22-0181-01",

 "documentType": 7,

 "documentTypeName": "Government Support Clause",

 "documentID": 739268016,

 "fileName": "Government Support Clause338529874.txt",

 "documentCreateDate": "2022-10-26 16:12:16",

 ""documentUpdateDate": "2022-11-02 11:20:58"

 },

 {

 "inventionReportNumber": "7654321-22-0181",

 "patentDocketNum": "22-0181-01",

 "documentType": 17,

 "documentTypeName": "Waiver",

 "documentID": 739268017,

 "fileName": "1307338529874.txt",

 "documentCreateDate": "2022-10-26 16:12:17",

 "documentUpdateDate": "2022-11-02 11:20:58"

 }

 ],

 "totalRecords": 3

}

9.2 Download Document

The Download Document API requires a document ID. This information is available by performing a 

document search which returns one or multiple records. Each returned document will have its

document ID.
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

162

9.2.1 Endpoint URI

Here’s an example of the v1 endpoint for the Download files.

POST /iedison/api/v1/documents/download

9.2.2 Request Parameters

The API POST request has the following elements:

• Headers: these are the request headers such as Accept or Content-Type. The Accept 

header parameter defines the expected response body format when the API returns 

the response. For example, you can define a response as JSON by modifying the Accept 

header. This Accept header is required in all requests. 

• Body: body contains the data which will be submitted as the post request. For example, 

when submitting a form, format data and file content are sent in the body of the 

request.

The table below provides the explanation of the download document file POST request Header 

and Body parameters which are expected by iEdison API.

The table below shows the parameters that will be included in the JSON body during the

processing of Document Search Request. The below parameters are included as a JSON object 

in JSON body. The JSON object represents the metadata for the search criteria. The search will 

retrieve Invention documents only. If the JSON object contains a Patent document, the search 

will retrieve Patent documents only.

9.2.3 Response Parameters

This section documents the response JSON objects, attributes, and types for a success or error 

response.

Request 

Parameters

Description Required Data 

Type

Version In

accept Setting to */* Yes String v1 header

document The document json objects 

containing fields to be used in the 

search download file. See table 

below.

Yes String v1 formdata

Request Parameter Description Required Data 

Type

Length Version

documentID Unique document identifier. Yes Number v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

163

HTTP Status 200 (OK) 

Based on the request parameters, the Document Search API provides the below response 

parameters.

9.2.4 Request and Response Examples 

A sample request for the Document Download REST API is shown below:

{

"documentID": 739268017

}

A sample response for the Document Download REST API is shown below:

The response header contains the filename in the content-disposition header attribute (see 

below image for example).

10.0 Notification API Reference

The notification APIs provide ways to search for a list of pending notifications. Search condition for 

notifications is the combination of attributes of the NotificationSearchCriteria JSON object. System only 

will return pending notifictions which granted access permission to the user’s organization. 

10.1 Endpoint URI

Here’s an example of the v1 endpoint for the Search Notifications resource.

POST /iedison/api/v1/notifications/search

Response Parameter Description Data Type Version

file The actual file document. Input stream v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

164

10.2 Request Parameters

The API POST request has the following elements:

• Headers: these are the request headers such as Accept or Content-Type. The Accept 

header parameter defines the expected response body format when the API returns 

the response. For example, you can define a response as JSON by modifying the Accept 

header. This Accept header is required in all requests. 

• Body: body contains the data which will be submitted as the post request. For example, 

when submitting a form, format data and file content are sent in the body of the 

request.

The table below provides the explanation of the search download document POST request 

Header and Body parameters which are expected by iEdison API.

The table below shows the parameters that will be included in the JSON body during the

processing of Document Search Request. The below parameters are included as JSON object in 

JSON body. The JSON object represents the metadata for the search criteria. 

Request Parameters Description Required Data 

Type

Version In

accept Setting to application/json. Yes String v1 header

notificationSearchCriteria The notificationSearchCriteria

json objects containing fields to 

be used in the search. See table 

below.

Yes String v1 formdata

Request Parameter Description Required Data 

Type

Length Version

inventionReportNumber Automatically generated by the 

iEdison system for a new 

Invention Report after data has 

been submitted, checked for 

errors, and verified.

No String 100 v1

patentDocketNumber The Patent Docket Number field 

is for an internal reference 

number of the 

grantee/contractor organization 

to help track a reported 

Patent(s).

No String 30 v1

messageNumber Search for the 

"MessageNumber" of a pending 

notification

No Integer 4 v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

165

10.3 Response Parameters

This section documents the response JSON objects, attributes, and types for a success or error 

response.

HTTP Status 200 (OK) 

Based on the request parameters, Document Search API provides the below response 

parameters.

Request Parameter Description Required Data 

Type

Length Version

fiscalYear Search for the "FiscalYear" of a 

pending notification in the 

format 4-digit "YYYY"

No Integer 4 v1

postedDateFrom Search the "From Date" of a 

notification posting date,

MM/DD/YYYY format.

No String 10 v1

postedDateTo Search the "To Date" of a

notification posting date,

MM/DD/YYYY format.

No String 10 v1

dueDateFrom Search the "From Date" of a 

notification due date,

MM/DD/YYYY format.

No String 10 v1

dueDateTo Search the "To Date" of a 

notification due date,

MM/DD/YYYY format.

No String 10 v1

limit Total number of records to be 

retrieved per page. This field 

must be a number Max Value = 

100. The Default = 20.

No Integer v1

offset Indicates the page index. Default 

offset starts with 0.

No Integer v1

Response Parameter Description Data Type Version

totalRecords Total number of records for 

the search.

Number v1

notificationsList A list of notification response 

Objects. Table below lists the 

JSON object attributes.

Object 

Array

v1

limit The limit used in the request Integer v1

offset The offset used in the request Integer v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

166

Below are the notification response Object attributes.

10.4 Request and Response Examples 

A sample request for the Notification Search REST API is shown below 

(notificationSearchCriteria):

{

 "inventionReportNumber": "7654321-0",

 "messageNumber": 310,

 "fiscalYear":2019

}

A sample response and error for the notification Search REST API is shown below:

{

 "notifications": [

Response Parameter Description Data Type Version

inventionReportNumber System generated sequence 

number used for ID of the 

Patent.

String v1

patentDocketNum The Patent Docket Number 

field is for an internal 

reference number of the 

grantee/contractor 

organization to help track a 

reported Patent(s).

String v1

messageNumber The Message Number of a 

notification

Number v1

messageDescription The Message Description of a 

notification

organization The recipient organization of a 

notification. It can be either 

be a federal agency of a grant 

contractor

String v1

fiscalYear The Fiscal Year of a 

notification.

Number V1

status The Status (Active/Inactive) of 

a notification.

String V1

postedDate Date when the notification

was posted.

String v1

dueDate The Due Date of a notification. String v1
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

167

 {

 "inventionReportNumber": "7654321-03-0010",

 "patentDocketNumber": "N/A",

 "messageNumber": 310,

 "messageDescription": "A utilization report must be submitted annually for 

every invention to which title has been elected. A utilization report for this invention 

was due on <DUE DATE>.",

 "organization": "DAN'S INSTITUTION",

 "fiscalYear": 2019,

 "status": "Active",

 "postedDate": "2020-12-31 19:05:01",

 "dueDate": "2019-12-31 19:00:00"

 },

 {

 "inventionReportNumber": "7654321-04-0039",

 "patentDocketNumber": "N/A",

 "messageNumber": 310,

 "messageDescription": "A utilization report must be submitted annually for 

every invention to which title has been elected. A utilization report for this invention 

was due on <DUE DATE>.",

 "organization": "DAN'S INSTITUTION",

 "fiscalYear": 2019,

 "status": "Active",

 "postedDate": "2020-12-31 19:05:01",

 "dueDate": "2019-12-31 19:00:00"

 },

 {

 "inventionReportNumber": "7654321-04-0023",

 "patentDocketNumber": "N/A",

 "messageNumber": 310,

 "messageDescription": "A utilization report must be submitted annually for 

every invention to which title has been elected. A utilization report for this invention 

was due on <DUE DATE>.",

 "organization": "DAN'S INSTITUTION",

 "fiscalYear": 2019,

 "status": "Active",

 "postedDate": "2022-04-03 02:00:13",

 "dueDate": "2019-12-31 19:00:00"

 },

 {

 "inventionReportNumber": "7654321-05-0064",
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

168

 "patentDocketNumber": "N/A",

 "messageNumber": 310,

 "messageDescription": "A utilization report must be submitted annually for 

every invention to which title has been elected. A utilization report for this invention 

was due on <DUE DATE>.",

 "organization": "DAN'S INSTITUTION",

 "fiscalYear": 2019,

 "status": "Active",

 "postedDate": "2022-09-08 22:00:03",

 "dueDate": "2019-12-31 19:00:00"

 }

 ],

 "totalRecords": 4,

 "limit": 100,

 "offset": 0

}

{

 "notifications": [

 {

 "inventionReportNumber": "7654321-03-0010",

 "patentDocketNumber": "N/A",

 "messageNumber": 310,

 "organization": "DAN'S INSTITUTION",

 "fiscalYear": 2019,

 "status": "Active",

 "postedDate": "2020-12-31 19:05:01",

 "dueDate": "2019-12-31 19:00:00"

 },

 {

 "inventionReportNumber": "7654321-04-0039",

 "patentDocketNumber": "N/A",

 "messageNumber": 310,

 "organization": "DAN'S INSTITUTION",

 "fiscalYear": 2019,

 "status": "Active",

 "postedDate": "2020-12-31 19:05:01",

 "dueDate": "2019-12-31 19:00:00"

 },

 {

 "inventionReportNumber": "7654321-04-0023",

 "patentDocketNumber": "N/A",

 "messageNumber": 310,
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

169

 "organization": "DAN'S INSTITUTION",

 "fiscalYear": 2019,

 "status": "Active",

 "postedDate": "2022-04-03 02:00:13",

 "dueDate": "2019-12-31 19:00:00"

 },

 {

 "inventionReportNumber": "7654321-05-0064",

 "patentDocketNumber": "N/A",

 "messageNumber": 310,

 "organization": "DAN'S INSTITUTION",

 "fiscalYear": 2019,

 "status": "Active",

 "postedDate": "2022-09-08 22:00:03",

 "dueDate": "2019-12-31 19:00:00"

 }

 ],

 "totalRecords": 4,

 "limit": 120,

 "offset": 0

}

11.0 Appendix

11.1 Mappings

11.1.1 Invention Development Stage

List of available Invention Development Stages

Value

Commercialized

Licensed

Not Licensed

11.1.2 Patent Filing Status

List of available Patent filing status

Value

Active

Expired
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

170

Abandoned

11.1.3 Patent Application Types

List of available Patent Application Types

Patent Application 

Type

Description Notes

CIP Continuation-In-Part Active Patent application type. 

This can be used in the Patent

create and update API requests.

CON Continuation Active Patent application type. 

This can be used in the Patent

create and update API requests.

CPA Continued Prosecution Application Non-Active Patent application 

type. This can NOT be used in 

the Patent create and update 

API requests.

DIV Divisional Active Patent application type. 

This can be used in the Patent

create and update API requests.

FWC File Wrapper Continuing Non-Active Patent application 

type. This can NOT be used in 

the Patent create and update 

API requests.

ORD Ordinary Utility Active Patent application type. 

This can be used in the Patent

create and update API requests.

PROV Provisional Active Patent application type. 

This can be used in the Patent

create and update API requests.

PVP Plant Variety Protection Active Patent application type. 

This can be used in the Patent

create and update API requests.

RCE Request for Continued Examination Non-Active Patent application 

type. This can NOT be used in 

the Patent create and update 

API requests.

PCT PCT Designating the US Active Patent application type. 

This can be used in the Patent

create and update API requests.

11.1.4 Award Type

List of the Invention funding agreement Award types
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

171

Value

Prime Award

Sub-Award

11.1.5 Agreement Types

List of available Agreement Types

11.1.6 Inventor US Federal Employee

Value

true

false

11.1.7 Patent Status

The iEdison Patent status list of value.

Value Notes

Transferred/Assigned This status value shall not be used in API request. 

Organization needs to use the UI to submit a 

Transfer Patent Request.

Voided This status value shall not be used in API request. 

Organization needs to use the UI to submit a Void 

Patent Request.

Expired This status value shall be used for the Patent 

Application Types of DIV, ORD, PVP, CIP, and CON

Abandoned/Intent to Abandon This value can be used for both organization and 

agency clients in the Patent request

Institution Retains Rights This value can be used for both organization and 

agency clients in the Patent request

11.1.8 Agency Mapping List

Click here to see list of all iEdison enrolled agencies. Be advised that you cannot use the API for agencies 

that have the following red notice "THIS AGENCY IS CURRENTLY INACTIVE IN IEDISON"

Value

Cooperative Agreement

Grant

Contract

ACT = DoE Specific

Other Funding Agreement
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

172

11.1.9 Country List

A list of valid country Names and FIPs Country Codes. 

Name FIPs Country Codes

AFGHANISTAN AF

ALBANIA AL

ALGERIA AG

ANDORRA AN

ANGOLA AO

ANGUILLA AV

ANTIGUA/BARBUD AC

ARGENTINA AR

ARMENIA AM

ARUBA AA

AUSTRALIA AS

AUSTRIA AU

AZERBAIJAN AJ

African Intellectual Property Organization OAPI

African Regional Intellectual Property Organization ARIPO

BAHAMAS BF

BAHRAIN BA

BANGLADESH BG

BARBADOS BB

BELARUS BO

BELGIUM BE

BELIZE BH

BENIN BN

BERMUDA BD

BHUTAN BT

BOLIVIA BL

BOSNIA/HERZEG BK

BOTSWANA BC

BRAZIL BR

BRITISH VI ISS VI

BRUNEI BX

BULGARIA BU

BURKINA UV

BURUNDI BY

CABO VERDE CV

CAMBODIA CB
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

173

Name FIPs Country Codes

CAMEROON CM

CANADA CA

CAYMAN ISLANDS CJ

CENTRAL AFR R CT

CHAD CD

CHILE CI

CHINA CH

COLOMBIA CO

COMOROS CN

CONGO CF

CONGO DEM REP CG

COSTA RICA CS

COTE D'IVOIRE IV

CROATIA HR

CUBA CU

CYPRUS CY

CZECH REPUBLIC EZ

DENMARK DA

DJIBOUTI DJ

DOMINICA DO

DOMINICAN REP DR

ECUADOR EC

EGYPT EG

EL SALVADOR ES

EQUATOR GUINEA EK

ERITREA ER

ESTONIA EN

ESWATINI WZ

ETHIOPIA ET

Eurasian Patent Organization EAPO

European Patent Organization EPO

FALKLAND ISS FX

FIJI FJ

FINLAND FI

FRANCE FR

FRENCH POLYNES FP

GABON GB

GAMBIA GA
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

174

Name FIPs Country Codes

GAZA STRIP GZ

GEORGIA GG

GERMANY GM

GHANA GH

GIBRALTAR GI

GREECE GR

GREENLAND GL

GRENADA GJ

GUATEMALA GT

GUERNSEY GK

GUINEA GV

GUINEA-BISSAU PU

GUYANA GY

HAITI HA

HONDURAS HO

HONG KONG HK

HUNGARY HU

ICELAND IC

INDIA IN

INDONESIA ID

IRAN IR

IRAQ IZ

IRELAND EI

ISRAEL IS

ITALY IT

JAMAICA JM

JAPAN JA

JERSEY JE

JORDAN JO

KAZAKHSTAN KZ

KENYA KE

KIRIBATI KR

KOREA PEO REP KN

KOREA REP OF KS

KOSOVO KV

KUWAIT KU

KYRGYZSTAN KG

LAOS LA
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

175

Name FIPs Country Codes

LATVIA LG

LEBANON LE

LESOTHO LT

LIBERIA LI

LIBYA LY

LIECHTENSTEIN LS

LITHUANIA LH

LUXEMBOURG LU

MACAU MC

MADAGASCAR MA

MALAWI MI

MALAYSIA MY

MALDIVES MV

MALI ML

MALTA MT

MAURITANIA MR

MAURITIUS MP

MEXICO MX

MOLDOVA MD

MONACO MN

MONGOLIA MG

MONTENEGRO MW

MONTSERRAT MH

MOROCCO MO

MOZAMBIQUE MZ

MYANMAR BM

NAMIBIA WA

NAURU NR

NEPAL NP

NETHERLANDS NL

NEW ZEALAND NZ

NICARAGUA NU

NIGER NG

NIGERIA NI

NORTH MACEDONIA MK

NORWAY NO

OMAN MU

PAKISTAN PK
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

176

Name FIPs Country Codes

PANAMA PM

PAPUA N GUINEA PP

PARAGUAY PA

PERU PE

PHILIPPINES RP

POLAND PL

PORTUGAL PO

Patent Office of the Cooperation Council for the Arab 

States of the Gulf GCCPO

QATAR QA

ROMANIA RO

RUSSIA RS

RWANDA RW

SAMOA WS

SAN MARINO SM

SAO TOME/PRINC TP

SAUDI ARABIA SA

SENEGAL SG

SERBIA SR

SEYCHELLES SE

SIERRA LEONE SL

SINGAPORE SN

SLOVAKIA LO

SLOVENIA SI

SOLOMON ISS BP

SOMALIA SO

SOUTH AFRICA SF

SOUTH SUDAN SS

SPAIN SP

SRI LANKA CE

ST HELENA SH

ST KITTS/NEVIS SC

ST LUCIA ST

ST VINCENT/GRN VC

SUDAN SU

SURINAME NS

SWEDEN SW

SWITZERLAND SZ
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

177

Name FIPs Country Codes

SYRIA SY

TAIWAN TW

TAJIKISTAN TI

TANZANIA U REP TZ

THAILAND TH

TIMOR-LESTE TT

TOGO TO

TONGA TN

TRINIDAD/TOBA TD

TUNISIA TS

TURKEY TU

TURKMENISTAN TX

TURKS/CAICOS I TK

TUVALU TV

UGANDA UG

UKRAINE UP

UNITED ARAB EM TC

UNITED KINGDOM UK

UNITED STATES US

URUGUAY UY

UZBEKISTAN UZ

VANUATU NH

VENEZUELA VE

VIETNAM VM

WEST BANK WE

YEMEN YM

YUGOSLAVIA YO

ZAMBIA ZA

ZIMBABWE ZI

11.1.10 States List

This is the state value use for contractorState in Invention and state in Utilization Manufacturing 

location. Find the valid ‘Code’ value for your requests.

Name Code

ALABAMA AL

ALASKA AK

ALBERTA AB

AMERICAN SAMOA AS
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

178

Name Code

AP0/FP0 EUROPE AE

AP0/FP0 OT PAC AP

AP0/FP0 S AMER AA

ARIZONA AZ

ARKANSAS AR

BAKER ISLAND FQ

BR. COLUMBIA BC

CALIFORNIA CA

COLORADO CO

CONNECTICUT CT

DELAWARE DE

DIST OF COL DC

FED MICRONESIA FM

FLORIDA FL

GEORGIA GA

GUAM GU

HAWAII HI

HOWARD ISLAND HQ

IDAHO ID

ILLINOIS IL

INDIANA IN

IOWA IA

JOHNSTON ATOLL JQ

KANSAS KS

KENTUCKY KY

KINGMAN REEF KQ

LOUISIANA LA

MAINE ME

MANITOBA MB

MARSHALL IS MH

MARYLAND MD

MASSACHUSETTS MA

MICHIGAN MI

MIDWAY ISLANDS MQ

MINNESOTA MN

MISSISSIPPI MS

MISSOURI MO

MONTANA MT

NAVASSA ISLAND BQ

NEBRASKA NE

NEVADA NV

NEW BRUNSWICK NB

NEW HAMPSHIRE NH
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

179

Name Code

NEW JERSEY NJ

NEW MEXICO NM

NEW YORK NY

NEWFOUNDLAND NL

NORTH CAROLINA NC

NORTH DAKOTA ND

NORTHN MARIANA MP

NOVA SCOTIA NS

NW TERRITORIES NT

OHIO OH

OKLAHOMA OK

ONTARIO ON

OREGON OR

PALAU PW

PALMYRA ATOLL LQ

PENNSYLVANIA PA

PR. EDWARD ISL PE

PUERTO RICO PR

QUEBEC PQ

QUEBEC QC

RHODE ISLAND RI

SASKATCHEWAN SK

SOUTH CAROLINA SC

SOUTH DAKOTA SD

TENNESSEE TN

TEXAS TX

TRUST TER PACF PS

US MINOR OUTLY UM

UTAH UT

VERMONT VT

VIRGIN ISLANDS VI

VIRGINIA VA

WAKE ISLAND WQ

WASHINGTON WA

WEST VIRGINIA WV

WISCONSIN WI

WYOMING WY

YUKON YT
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

180

11.1.11 Title Election Status

Indication of your institution's decision regarding the election of title for this Invention. The Draft, 

Voided, and Transferred status values shall not be used when submitting Invention Create or Update API 

requests.

Value Notes

Elect to Retain Title This can be used for both organization and agency 

clients in the create or update request.

Does Not Retain Title This can be used for both organization and agency 

clients in the Invention request. Once the Invention is 

saved with this status, organization client will no 

longer allow to modify the Invention metadata.

Designated as Unpatented Biological 

Material or Research Tool

This can be used for both organization and agency 

clients in the create or update request.

Under Evaluation Allow both organization and agency clients to use in 

the create or update request. 

Draft This status is used in response data only. This status 

value shall not be used in API create or update 

request.

Voided This status is used in response data only. This status 

value shall not be used in API request. The 

organization is required to use the UI to submit an 

Invention Void Request.

Transferred This status is use in response data only. This status 

value shall not be used in API request. The 

organization is required to use the UI to submit an 

Invention Transfer Request.

Government Takes Title (Award 

Terms)

If the invention is made by a private for-profit largesize organization that is funded by the DOE, and the 

DOE Waiver ID has not been given, the iEdison 

system will automatically set the status to "Not 

Waived." This value should not be used in the API 

request.

11.1.12 Invention Disposition

Decision of the agency as to how to proceed with the technology. This field will be auto-populated or set 

by the Primary Agency. It will be populated either automatically as "Barred" if a Patent is not filed within 

one year of the "Date of the First Publication/Sale/Public Use" or as "Void," "Transferred"/Assigned" 

after a request is granted. Otherwise, the Disposition Status will be set by the Primary Agency in 

response to the selection of "Does Not Retain Title."
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

181

Value Notes

Government Does Not Retain Rights Active status to allow for agency clients 

to use in the request only. Organization 

can only view this in response data.

Government Retains Rights Active status to allow for agency clients 

to use in the request only. Organization 

can only view this in response data.

Not Elect Title – Waive to Government Non-Active status for response data view 

only. This shall not be used in the request 

for create or update.

Not Elect Title – Waive to Third Party Non-Active status for response data view 

only. This shall not be used in the request 

for create or update.

Request for Inventor Waiver Non-Active status for response data view 

only. This shall not be used in the request 

for create or update.

Assignment Approved Non-Active status for response data view 

only. This shall not be used in the request 

for create or update.

Assignment Denied Non-Active status for response data view 

only. This shall not be used in the request 

for create or update.

Barred Active status to allow system to 

automatically set the Barred status. This 

status is used in response data only. This 

value shall not be used in API create or 

update request.

Voided Active status value. But it cannot be used 

in API create or update request. 

Organization needs to use UI to submit a 

Void request for the Invention. This will 

be set automatically when the Primary 

Agency approves the request.

Transferred Active status value. But it cannot be used 

in API create or update request.

Response data for Organization. This will 

be set automatically when the Primary 

Agency approves the request.

Note: Transferred status is for response data only. Updating an Invention to transfer status must go through Web 

Application Interface.

11.1.13 Utilization Reporting Year

The Utilization Reporting Year value is any 4 digits year which is the 5 years back from the Date 

Invention Reported to Organization up to current Calendar year. For example, if Invention Reported to 

Organization is 03/01/2016 and Calendar year is 2022. The following table contains the valid year.
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

182

*Note: Utilization Reporting year is temporarily disabled due to an upcoming Utilization questionnaire 

change. The iEdison support team will communicate with the grantee/contractor organizations and 

agencies when the new feature is ready.

Value

2011

2012

2013

2014

2015

2016

2017

2018

2019

2020

2021

2022

11.1.14 Year of First Commercial Sale

The Year of First Commercial Sale value is any 4 digits year which is the 5 years back from the Date 

Invention Reported to Organization up to current Calendar year. For example, if Invention Reported to 

Organization is 03/01/2016 and Calendar year is 2022. The following table contains the valid year.

Value

2011

2012

2013

2014

2015

2016

2017

2018

2019

2020

2021

2022

11.1.15 Utilization Commercial Product Type

Value

Biologic

Medical Device

Drug
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

183

11.1.16 Utilization Commercial Product Government Review Status

Value

Approved

Rejected

Pending

11.1.17 Utilization Public Announced

Value

Yes

No

11.1.18 Utilization Manufacturing Location First Date Type

Value

Actual

Expected

11.1.19 Invention Does Not Retain Title Reason

The 11.1.19 Invention Does Not Retain Title Reason values must be provided when the Title 

Election Status is set to "Does Not Retain Title".

Value

Low Commercial Potential

Non-Patentable (Not Novel)

Non-Patentable (Not Useful)

Non-Patentable (Obvious)

Did Not Yield Expected Results

Budget Limitation

Immature Market

Other

11.1.20 Utilization Commercialization Plan

Value Notes

1 Seeking additional funding to further develop this 

invention
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

184

Value Notes

2 Marketing and/or furthering development of this 

invention to attract commercial partners

3 Developing and/or using this invention for internal 

purposes only

4 Developing and/or preparing this invention with intent to 

commercialize ourselves

5 Making available for distribution and/or licensing for 

research purposes only

6 No current commercialization plan

11.1.21 Licensed Utilization Questions Logicsfor US Manufacturing

This appendix section shows the answer relationship between the fields latestStageDev, 

isUSManufacturingRequired1, and isUSManufacturingRequired2 when latestStageDev value has 

“Licensed” in the request.

11.1.22 Commercialized Utilization Questions Logics for US Manufacturing

This appendix section shows the answer relationship between the fields latestStageDev, 

isUSManufacturingRequired1, isUSManufacturingRequired2, and isUSManufacturingRequired3

when latestStageDev value has “Commercialized” in the request.
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

185

Sample Code Snippet to Consume APIs

The following code snippetshows how to connect to iEdison API and consume its services. Below is a 

sample Java code snippet to consume the iEdison Invention search API service.

Find below variables in the code snippet and replace them with your changes.

• INVENTIONS_SEARCH = Build and assign a request JSON string

• HOST_NAME = iEdison API URL (Ex. https://api-iedisonuat.nist.gov/)

• KEY_STORE.JKS = Location of a key store with imported certificate

• KEYSTORE_PASSWORD = Key Store password

String INVENTION_SEARCH = "{ \"inventionTitle\": \" \"}";

String VENDOR_API_URL = {HOST_NAME} + "/iedison/api/v1/inventions/search";

SSLContext scl = SslConfigurator.newInstance()

.keyStoreFile("{KEY_STORE.jks}")

.keyPassword("{KEYSTORE_PASSWORD}")

.securityProtocol("TLS")

.createSSLContext();

final Client client = ClientBuilder

.newBuilder()
Invention, Patent and Utilization (IPU) 

REST API Technical Specification 

186

.sslContext(scl)

.register(MultiPartFeature.class)

.build();

FormDataMultiPart formDataMultiPart = new FormDataMultiPart();

final FormDataMultiPart multipart = (FormDataMultiPart) 

formDataMultiPart.field("inventionSearchCriteria", INVENTION_SEARCH);

final WebTarget target = client.target(VENDOR_API_URL);

final Response response = target.request() 

.post(Entity.entity(multipart, multipart.getMediaType()));

assertEquals(response.getStatus(), 200);

formDataMultiPart.close();

multipart.close();

Below is a sample curl code snippet to consume the iEdison Invention search API service.

curl --key /home/lgt2/client-store.key.pem -E /home/lgt2/client-store.crt.pem -X POST -F 

'inventionSearchCriteria={"primaryAgency": "NIST","grantContractNumber": "T25252"}' https://apiiedisonuat.nist.gov/iedison/api/v1/inventions/search

Abbreviations

Acronym Description

IPU Invention, Patent, and Utilization

API Application Programming Interface

HTTP Hypertext Transfer Protocol

JSON JavaScript Object Notation

PKI Public Key Infrastructure

REST Representational state transfer

URI Uniform Resource Identifier