NIH System to S
ystem (S2S) “Client” Transactions Guide: SOAP
Version 5.11
Aug 2023
S2S Client Transactions Guide
Page
2
Table of Contents
Table of Contents..................................................................................................................... 2
Introduction ............................................................................................................................. 3
Background ......................................................................................................................... 3
Relationship to NIH eRA Commons system.......................................................................... 3
Business Process Operations .................................................................................................... 3
Security Considerations ........................................................................................................... 7
Transactions and Field Level Details ........................................................................................ 8
Validate Application ............................................................................................................ 8
Validate Component ............................................................................................................ 9
Grant Status Request .......................................................................................................... 11
Application Validation Messages Request........................................................................... 14
Person Information with UEI Request ................................................................................. 15
Person Information with Employment with UEI Request ..................................................... 17
Person Basic Information Request ...................................................................................... 19
Organization Information By UEI Request.......................................................................... 20
Prior Grant With UEI Request ............................................................................................ 21
FOA Information Request .................................................................................................. 23
Stem Cell Line Status Request ............................................................................................ 26
Credential Request ............................................................................................................. 26
SAM Org Info by UEI Request........................................................................................... 27
Generate Grant Image ........................................................................................................ 29
Generate Component Image ............................................................................................... 30
Generate Form Image......................................................................................................... 31
Generate Clinical Trials Form Image .................................................................................. 32
Process RFA PA Notice ..................................................................................................... 33
Regenerate Grant Image ..................................................................................................... 35
Appendices............................................................................................................................ 35
Appendix A: Attachment Meta Data Notes ......................................................................... 35
Appendix B: Sub Application ID Sample ............................................................................ 37
Appendix C: Testing Services............................................................................................. 38
Appendix D: Sample XML for Generate Form Image API:.................................................. 40
Appendix E: Sample XML for Generate Clinical Trials Form Image API: ........................... 42
Appendix F: Sample XML for FOA Information Request with package ID: ......................... 42
Appendix G: Sample XML for RFA PA Notice Request ..................................................... 43
Document History.................................................................................................................. 44
S2S Client Transactions Guide
Page
3
INTRODUCTION
Background
The System-to-System (S2S) interface provides the means for external systems to interact via
direct requests to the NIH eRA Exchange system to perform various business functions. These
business functions vary in purpose from obtaining Funding Opportunity Announcement (FOA)
information to querying the status of grant applications, retrieving validation error/warning
messages resulting from grant application processing, and verifying person information details.
All services are offered as standards based web services and published via WSDL, allowing
client stubs to be auto generated.
This document provides software developers with transaction level details for the eRA Exchange
System-to-System transactions. The aim is to supplement the WSDL definitions that themselves
provide structural layout and content level data typing information with field level content
descriptions. Also typical usage patterns are described. Brief details of the interaction processing
are provided along with details of the incoming request messages and outgoing responses.
The security considerations and requirements that ensure that response information is only
returned to requesters who are authorized to receive that information are also outlined.
In summary this guide is intended to assist external organizations with the creation and
processing of the transactions, their formatting and content, for the S2S exchanges currently
implemented and available for use. This document is a supplemental document from, and a
subset of, the formal internal NIH requirements documentation.
Relationship to NIH eRA Commons system
The NIH eRA Commons web site allows external users to enter and manage their profile
information and track grant applications in the Commons. The system-to-system web services
provide alternate means to get profile, status, and other information directly via system-to-system
transactions.
Business Process Operations
The following table shows the current business process operations supported.
Each operation is only permitted if all the security validations are passed (see following section
for detailed security handling). This includes transport level checking (valid certificate uniquely
identifying external party’s system); process level authorization checks, and valid association
between the requestor and the DUNS ID associated with the information exchange (permitted to
access that owner organizations information). The transactions are not constrained to only
information associated with eSubmission data, so information may have originated from
previous paper or online web entry processing. Each request is followed by a matching response
transaction, or an error transaction. Within response transactions the mandatory elements could
be present but as empty tags if no corresponding data is found in the database.
S2S Client Transactions Guide
Page
4
The operations available to external users are organized into three separate services:
• Submission Validation Service (SVS): Provides operations to validate a multi-project
application submission or a single project. SVS also provides operations to validate
specified components within a multi-project application submission against NIH business
rules.
• Submission Agency Data Service (SADS): Provides operations for retrieving NIH data
supporting electronic submissions.
• SIL: Provides operations to generate PDF images for Face Page, Budget, Grant Image
etc.
• RFA PA service : Provides operation for inserting the FOA information
S2S Client Transactions Guide
Page
5
Service Operation Description
Submission
Validation Service
(SVS)
Validate Application Validates an application against agency
business rules. Can be used run validations
pre-submission to Grants.gov
Submission
Validation Service
(SVS)
Validate Component Validates an application against agency
business rules. Currently only applies for
multi-project applications.
Submission Agency
Data Service
(SADS)
Application Status
Request
Request of grant application status.
Requestor provides the Grant application
reference number and must have permission
to access that organizations application.
Submission Agency
Data Service
(SADS)
Application
validation messages
request
Allows the receipt of agency validation error
and/or warning messages resulting from the
processing of an electronic grant application
submitted to Grants.gov. Request contains
either the Grants.gov tracking number or the
NIH accession number and requestor must
have permission to the application. The
response contains a list of agency error and/or
warning messages that resulted from
processing the grant application.
Submission Agency
Data Service
(SADS)
Person Information
Request
Request of Commons User Account
information based on the Account ID value;
returns person, degree, address and affiliation
information. Requestor must have permission
to access accounts for the associated
organization. Response contains information
supported by the transaction schema and on
file.
Submission Agency
Data Service
(SADS)
Person Information
with UEI Request
Request of Commons User Account
information based on the Account ID value;
returns person, degree, address, affiliation
information and UEI. Requestor must have
permission to access accounts for the
associated organization. Response contains
information supported by the transaction
schema and on file.
Submission Agency
Data Service
(SADS)
Organization
Information Request
Provide information regarding a specific
organization.
S2S Client Transactions Guide
Page
6
Submission Agency
Data Service
(SADS)
Organization
Information Request
By UEI
Provide information regarding a specific
organization by UEI
Submission Agency
Data Service
(SADS)
Previous Submission
Request
Provide information for a previous
submission that matches the current
submission.
Submission Agency
Data Service
(SADS)
Prior Grant Request Provide information for a prior grant that
matched the current submission.
Submission Agency
Data Service
(SADS)
Prior Grant with UEI
Request
Provide information for a prior grant with
UEI that matched the current submission.
Submission Agency
Data Service
(SADS)
FOA Information
Request
Provide information regarding a specific
opportunity.
Submission Agency
Data Service
(SADS)
Stem Cell Line
Status Request
Provide indicators whether identified stem
cell lines are valid.
Submission Agency
Data Service
(SADS)
Person Info with
Employment
Request
Request of Commons User Account
information based on the Account ID value;
returns person, degree, address, employments
and affiliation information. Requestor must
have permission to access accounts for the
associated organization. Response contains
information supported by the transaction
schema and on file.
Submission Agency
Data Service
(SADS)
Person Info with
Employment with
UEI Request
Request of Commons User Account
information based on the Account ID value;
returns person, degree, address, employments,
affiliation information, and UEI. Requestor
must have permission to access accounts for
the associated organization. Response
contains information supported by the
transaction schema and on file.
Submission Agency
Data Service
(SADS)
Credential Request
Request for Commons User ID based on the
last name and email address of a person.
Returns the list of User IDs that match the last
name and email in commons. Requestor must
have permission to access information for the
S2S Client Transactions Guide
Page
7
Security Considerations
Each request contains the UEI associated with the data requested. The UEI must be registered
and associated with the digital certificate used to make the request. When a mismatch occurs
between data requested and authorized, the failed attempt is recorded and may be construed as an
attempt to access un-authorized information. The partner is responsible for acquiring and setting
up their own digital certificate for use with SSL communications.
The submitting organization is given access to all applications, grants and person data within that
organization.
person whose credentials are being requested
for the associated organization.
Submission Agency
Data Service
(SADS)
SAM Org Info
Request
Request for SAM registration details.
Submission Agency
Data Service
(SADS)
SAM Org Info by
UEI Request
Request for SAM registration details by UEI
Submission Image
Service (SIL)
Generate Grant
Image
Generates Grant Image for Single and
Complex Grant Applications and expects the
PDF attachments being sent as Streams
Submission Image
Service (SIL)
Generate Component
Image
Generates Image for a component of a
Complex Grant Application and expects PDF
attachments being sent as Streams
Submission Image
Service (SIL)
Generate Form
Image
Generates Image for a Form of either a Single
or Complex Grant Application and expects
PDF attachments being sent as Streams
Submission Image
Service (SIL)
Generate Clinical
Trials Form Image
Generates Image for a filled in Clinical Trial
Forms PDF and expects PDF attachment
being sent as Streams
RFA PA service
(XCH)
Process Rfa Pa
Notice
Inserts the FOA information into
RFA_PA_NOTICES_T,
RFA_PA_ACTIVITIES_T,
RFA_PA_ICDS_T and
RFA_PA_COMPONENTS_T
Submission Agency
Data Service
(SADS)
Regenerate Grant
Image for LRP
application
Regenerates Grant Image for a LRP
application based on the Appl Id
S2S Client Transactions Guide
Page
8
However for calling SIL Operations, there is no restriction to use a different certificate for
different organization. The trading partner can register themselves in COMMONS, obtain a
certificate and register that certificate with eRA and assign necessary roles to access SIL
operations. AMS (account management services) application can be used for this purpose..
The following table summarizes the Roles necessary to access each of the services.
Service Name
Role
Role Context
Submission Validation
Service
SVS_APPLICANT_DATA_SERV
Institution
Submission Agency Data
Service
APPLICANT_RETRIEVAL_DATA_SERV
Institution
Submission Image Service
SERVICE_PROVIDER_ROLE
Global
Rfa Pa Service
APPLICANT_RFAPA_SERV
Global
Transactions and Field Level Details
Validate Application
VALIDATE APPLICATION REQUEST MESSAGE (incoming)
DESCRIPTION
The XML for the
submission
Meta data for attachments,
include document type,
page count and size
Note: See Appendix A:
Attachment Meta Data
Notes
each attachment referenced
in the Grant Application
XML
File name
Mime Type
File Location
Size in Bytes
Page Count
Number of Lines
validation to be under
Is Resizing Required
Is Encrypted Attachment
S2S Client Transactions Guide
Page
9
VALIDATE APPLICATION REQUEST MESSAGE (incoming)
DESCRIPTION
Is Password Protected
Is Secure
Pdf Error
Is XFA PDF
support XFA (XML Forms
Architecture) forms in PDF
VALIDATE APPLICATION RESPONSE MESSAGE (outgoing)
Data Element
Description
Validation Messages:
Messages repeated for each error/warning
Sub Application Group ID
This identifies Component Type, currently only
applicable for multi-project applications. (E.g.,
Overall, Core, Project, etc.)
Sub Application ID
This identifies Component Identifier, a unique
identifier for component types, currently only
applicable for multi-project applications.
Expected format: 3 digit unique number (unique
for the application) and the
SubApplicationGroupId (component type)
separated by a dash (E.g., 328-Core).
Note: See Appendix B: Sub Application ID
Sample
Message Rule Number
The rule number associated with the message
Message Severity
E (Error) or W (Warning)
Message Text
Validation message text
Message ID
A unique identifier for the message
Form Name
Form name where validation is applicable
Validate Component
VALIDATE COMPONENT REQUEST MESSAGE (incoming)
DESCRIPTION
The XML for the
submission
Meta data for attachments,
include document type,
page count and size
each attachment referenced
S2S Client Transactions Guide
Page
10
VALIDATE COMPONENT REQUEST MESSAGE (incoming)
DESCRIPTION
Note: See Appendix A:
Attachment Meta Data
Notes
XML
File name
Mime Type
File Location
Size in Bytes
Page Count
Number of Lines
validation to be under
Is Resizing Required
Is Encrypted Attachment
Is Password Protected
Is Secure
Pdf Error
Is XFA PDF
support XFA (XML Forms
Architecture) forms in PDF
Opportunity ID
VALIDATE COMPONENT RESPONSE MESSAGE (outgoing)
Data Element
Description
Validation Messages:
Messages repeated for each error/warning
Sub Application Group ID
This identifies Component Type, currently only
applicable for multi-project applications. (E.g.,
Overall, Core, Project, etc.)
S2S Client Transactions Guide
Page
11
VALIDATE COMPONENT RESPONSE MESSAGE (outgoing)
Data Element
Description
Validation Messages:
Messages repeated for each error/warning
Sub Application ID
This identifies Component Identifier, a unique
identifier for component types, currently only
applicable for multi-project applications.
Note: Though SVS will simply return the Sub
Application ID that is specified in the XML,
upon submission NIH expects the following
format: 3 digit unique number (unique for the
application) and the SubApplicationGroupId
(component type) separated by a dash (E.g., 328-
Core). See Appendix B: Sub Application ID
Sample
Message Rule Number
The rule number associated with the message
Message Severity
E (Error) or W (Warning)
Message Text
Validation message text
Message ID
A unique identifier for the message
Form Name
Form name where validation is applicable
Grant Status Request
APPLICATION STATUS REQUEST MESSAGE (incoming)
DESCRIPTION
(trackingNumber)
Grants.gov tracking number
of grant application (E.g.,
GRANT12345678)
(accessionNumber)
NIH Accession Number
(E.g., 1234567) that has
been reserved for the
application package
Project Title of grant
application
(grantNumber)
All components of the grant
number. Grant Number
must be supplied as a series
of components, some
required and some not. The
series of components shown
below comprise the full
grant number specification:
whole) is Optional.
However, if supplied,
certain components cannot
be blank. These are
indicated as such below.
First character of the grant
number.
S2S Client Transactions Guide
Page
12
APPLICATION STATUS REQUEST MESSAGE (incoming)
DESCRIPTION
Activity Code
Bytes 2-4 of the grant
number, i.e. “R01”
blank.
Administering PHS
Organization
Bytes 5-6 of the grant
number, i.e. “MH”
blank.
Bytes 7-12 of the grant
number, i.e. 000123
Year (supportYear)
Bytes 14-15 of the grant
number (immediately
following the dash)
Bytes 16-19 of the grant
number.
Notes:
This status request is designed to retrieve a single year of a data.
At least one identifier needs to be provided. The identifiers and their order of precedence are:
Accession Number
Tracking Number
Grant Number
Project Title
If more than one identifier is supplied, the first based on the precedence indicated above is used.
There is no consistency check within identifiers. The application identified must be one that was
previously electronically submitted by the trading partner for the submitting organization.
APPLICATION STATUS RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
E-Submission Status
(ESubmissionStatus)
A status code indicating the state of the message
in the electronic receipt process before functional
processing by NIH users.
o Grant application downloaded in the
exchange
o Grant application successfully validated
by the exchange
o Grant application failed format validation
o Grant application successfully loaded in
eRA database
S2S Client Transactions Guide
Page
13
APPLICATION STATUS RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
o Grant application failed content
validation
o E-application submission complete:
Application in process
E-Submission status date
(ESubmissionStatusDate)
Date of the latest E-Submission Status, above.
Grant status (grantStatus)
Grant application status post intake. This is the
offical grant status throughout the life cycle of
the application and grant
Grant status date (grantStatusDate)
Date of the latest Grant Status, above.
Grant Number (grantNumber)
All components of the grant number. The Grant
Number (E.g., 2R01MH000123-01S1) must be
supplied as a series of components. The series of
components shown below comprise the full grant
number specification. Please note that any or all
of these components may be blank, since the
assignment of grant number occurs after
application receipt, and might be at any stage of
completion when the status request is received.
Grant Number:
Application Type
(applicationTypeCode)
First character of the grant number, i.e. “2”
Grant Number:
Activity Code (activityCode)
Bytes 2-4 of the grant number, i.e. “R01”
Grant Number: Administering PHS
Organization (PHSOrgCode)
Bytes 5-6 of the grant number, i.e. “MH”
Grant Number: Serial Number
Bytes 7-12 of the grant number, i.e. 000123
Grant Number: Support Year
(supportYear)
Bytes 14-15 of the grant number (immediately
following the dash), i.e “01”
Grant Number: Suffix
Bytes 16-19 of the grant number, i.e. “S1”
Grant title (projectTitle)
Project title
Accession Number
(accessionNumber)
NIH internal key assigned before the grant
number
Submitter grant application identifier
Submitter internal id for the application
Application Receipt Date
(proposalReceiptDate)
Date the application was successfully received
by NIH.
SRO Contact
Scientific Review Administrator contact
information
SRO Name (name)
First, last name of Scientific Review
Administrator (SRO)
SRO Phone Number (phone)
Phone number for SRO contact
SRO E-Mail (email)
Email for SRO contact
S2S Client Transactions Guide
Page
14
APPLICATION STATUS RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
IRG Assignment (IRGAssignment)
Identifies Integrated Review Group (IRG) to
which application has been assigned. (E.g.,
ZNS1)
Study Section Meeting Date
Date on which review study section met / will
meet.
Study Section Meeting Location
Location of study section review meeting
Study Section Roster
List of members who serve on the assigned study
section.
Council Meeting Date
Identifies the council round assigned to this
application (year and month).
GMS Contact (GMSContact)
Grants Management Specialist contact
information
GMS Name (name)
Grants Management Specialist name
GMS Phone (phone)
Grants Management Specialist phone number
GMS E-Mail (email)
Grants Management Specialist Email
PO Contact (POContact)
Project Officical Contact information
PO Name (name)
Program Offical Name
PO Phone (phone)
Program Offical Phone Number
PO E-mail (email)
Program Offical Email
Advisory Council Meeting Date
Date of council meeting
Advisory Council Meeting Location
Location of council meeting
Application Validation Messages Request
APPLICATION VALIDATION MESSAGES REQUEST MESSAGE (incoming)
DESCRIPTION
(trackingNumber)
Grants.gov tracking number
of grant application (E.g.,
GRANT12345678)
(accessionNumber)
NIH Accession Number
that has been reserved for
the application package
(E.g., 1234567)
Notes:
At least one identifier needs to be provided. The identifiers and their order of precedence are:
Accession Number
Tracking Number
If more than one identifier is supplied, the first based on the precedence indicated above is used.
There is no consistency check within identifiers. The application identified must be one that was
previously electronically submitted by the trading partner for the submitting organization.
S2S Client Transactions Guide
Page
15
APPLICATION VALIDATION MESSAGES RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
Message Location (componentID,
formName)
Identifies component and form that generated
message. Currently only applicable for multi-
project applications. Will be empty for single
project applications. (E.g., 661-Core,
RR_OtherProjectInfo)
Message Severity (severity)
E (Error) or W (Warning)
Message Text (messageText)
Validation message text
Message Rule Number (ruleNum)
The rule number associated with the message
(E.g., 004.22.1)
Person Information with UEI Request
PERSON UEI INFORMATION REQUEST MESSAGE (incoming)
DESCRIPTION
(userID)
The COMMONS user id of
the person the information
is requested for
affiliated with the
organization for which the
information is requested. If
not, display the following
message: User {userId}is
not Authorized to access
this operation.
PERSON UEI INFORMATION RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
COMMONS User ID
(commonsUserId)
The person commons account id submitted in the
request
Affiliations (roles)
Role, system organization id and UEI for each
affiliation
S2S Client Transactions Guide
Page
16
PERSON UEI INFORMATION RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
Role type (role)
It will include 3 fields.
1. Role:
The code which indicates the role type in
the eRA database. If multiple roles are
associated with the provided Commons
User Id, the PI role will be returned if the
user has a PI role. (E.g., PI).
2. External org id:
Organization Identifier used in NIH
database (e.g., 123456)
3. UEI: Unique Entity Identifier
Person Name (personName)
Name as entered in Commons personal profile
Person Prefix Name (namePrefix)
From the profile
Person First Name (firstName)
From the profile
Person Middle Name (middleName)
From the profile
Person Last Name (lastName)
From the profile
Person Suffix Name (nameSuffix)
From the profile
Person employment address
(employmentAddress)
The address data group related to that affiliation
Line address 1 (lineAddress1)
From the profile
Line address 2 (lineAddress2)
From the profile
Line address 3 (lineAddress3)
From the profile
Line address 4 (lineAddress4)
From the profile
City (city)
City
State (state)
If country is Canada, will return Canadian
province code. For countries other than US and
Canada will be blank.
Postal Code (postalCode)
Equivalent to “zip code” in the eRA database.
Returns 9 digits (zip+four). If only 5 digits of zip
code are available, will pad with zeros (e.g.,
208171814, 265060000)
Country (countryCode)
This is the ISO-3166 country code (Alpha-3
format) (E.g., USA)
Contact Information (contact)
Phone, email, and fax contact information from
Commons personal profile
Phone number (phone)
Phone number
Fax Number (fax)
Fax number
E-mail address (email)
Email address
Preferred address code
(preferredAddressCode)
(true/false)
S2S Client Transactions Guide
Page
17
PERSON UEI INFORMATION RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
Degree (degree)
This is a repeating element of the degree and
degree text if degree is “other”.
Position Title (positionTitle)
Position title for this affiliation
List of prior awarded grants for that
person and that organization
(priorAwardedGrants)
This is a repeating element where each element
provides the full grant number with all
components including the amendments and multi
year awards. Subprojects are not included.
Application Type Code
(applicationTypeCode)
Grant Application Type Code
(E.g., 1 for New, 2 for Renewal, 3 for Revision,
4 for Extension, 5 for Non-competing
Continuation, 6 for Change of Organization
Status, 7 for Change of Grantee or Training
Institution, 8 for Non-Competing Continuation
Change of Institute or Division, 9 for Competing
Continuation Change of Institute or Division)
Activity Code (activityCode)
Grant activity code (E.g., R01)
PHS Organization (PHSOrgCode)
Awarding Institute code (E.g., MH)
Serial Number (serialNumber)
Grant serial number (E.g., 000123)
Support Year
Grant support year (E.g., 2)
Person Information with Employment with UEI Request
PERSON INFORMATION REQUEST MESSAGE (incoming)
DESCRIPTION
(userID)
The COMMONS user id of
the person the information
is requested for
affiliated with the
organization for which the
information is requested If
not, display the following
message: User {userID} is
not authorized to access this
operation
PERSON INFORMATION WITH EMPLOYMENT WITH UEI RESPONSE
MESSAGE (outgoing)
Data Element (Tag)
Description
COMMONS User ID
(commonsUserId)
The person commons account id submitted in the
request
Affiliations (roles)
Role, system organization id and UEI for each
affiliation
Organization UEI (uei)
Organization UEI provided in the request
S2S Client Transactions Guide
Page
18
PERSON INFORMATION WITH EMPLOYMENT WITH UEI RESPONSE
MESSAGE (outgoing)
Data Element (Tag)
Description
External Organization ID
(externalOrgId)
Organization Identifier used in NIH database
(e.g., 123456)
Role type (role)
The code which indicates the role type in the
eRA database. If multiple roles are associated
with the provided Commons User Id, the PI role
will be returned if the user has a PI role. (E.g.,
PI)
Person Name (personName)
Name as entered in Commons personal profile
Person Prefix Name (namePrefix)
From the profile
Person First Name (firstName)
From the profile
Person Middle Name (middleName)
From the profile
Person Last Name (lastName)
From the profile
Person Suffix Name (nameSuffix)
From the profile
Person employment address
(employmentAddress)
The address data group related to that affiliation
Line address 1 (lineAddress1)
From the profile
Line address 2 (lineAddress2)
From the profile
Line address 3 (lineAddress3)
From the profile
Line address 4 (lineAddress4)
From the profile
City (city)
City
State (state)
If country is Canada, will return Canadian
province code. For countries other than US and
Canada will be blank.
Postal Code (postalCode)
Equivalent to “zip code” in the eRA database.
Returns 9 digits (zip+four). If only 5 digits of zip
code are available, will pad with zeros (e.g.,
208171814, 265060000)
Country (countryCode)
This is the ISO-3166 country code (Alpha-3
format) (E.g., USA)
Contact Information (contact)
Phone, email, and fax contact information from
Commons personal profile
Phone number (phone)
Phone number
Fax Number (fax)
Fax number
E-mail address (email)
Email address
Preferred address code
(preferredAddressCode)
(true/false)
Degree (degree)
This is a repeating element of the degree and
degree text if degree is “other”.
List of prior awarded grants for that
person and that organization
(priorAwardedGrants)
This is a repeating element where each element
provides the full grant number with all
components including the amendments and multi
year awards. Subprojects are not included.
S2S Client Transactions Guide
Page
19
PERSON INFORMATION WITH EMPLOYMENT WITH UEI RESPONSE
MESSAGE (outgoing)
Data Element (Tag)
Description
Application Type Code
(applicationTypeCode)
Grant Application Type Code
(E.g., 1 for New, 2 for Renewal, 3 for Revision,
4 for Extension, 5 for Non-competing
Continuation, 6 for Change of Organization
Status, 7 for Change of Grantee or Training
Institution, 8 for Non-Competing Continuation
Change of Institute or Division, 9 for Competing
Continuation Change of Institute or Division)
Activity Code (activityCode)
Grant activity code (E.g., R01)
PHS Organization (PHSOrgCode)
Awarding Institute code (E.g., MH)
Serial Number (serialNumber)
Grant serial number (E.g., 000123)
Support Year
Grant support year (E.g., 2)
Person Basic Information Request
PERSON INFORMATION REQUEST MESSAGE (incoming)
DESCRIPTION
(userID)
The COMMONS user id of
the person the information
is requested for
PERSON INFORMATION WITH EMPLOYMENT WITH UEI RESPONSE
MESSAGE
Data Element (Tag)
Description
Person Name (personName)
Person Prefix Name (namePrefix)
From the profile
Person First Name (firstName)
From the profile
Person Middle Name (middleName)
From the profile
Person Last Name (lastName)
From the profile
Person Suffix Name (nameSuffix)
From the profile
Role type (role)
The code which indicates the role type in the
eRA database. If multiple roles are associated
with the provided Commons User Id, the PI role
will be returned if the user has a PI role. (E.g.,
PI)
Organization UEI (uei)
Organization UEI provided base on external_id
External Organization ID
(externalOrgId)
Organization Identifier used in NIH database
(e.g., 123456) which is based on user_id
S2S Client Transactions Guide
Page
20
Organization Information By UEI Request
ORGANIZATION INFORMATION REQUEST MESSAGE (incoming)
DESCRIPTION
(uei)
The identifier of the
organization about which
the information is
requested. This identifier is
the UEI.
certificate associated with
the caller
ORGANIZATION INFORMATION RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
External Organization ID
(externalOrgId)
Organization Identifier used in NIH database
(e.g., 123456)
Organizatin Name
(organizationName)
Name of the organization.
Organization EIN (ein)
EIN for the organization
Organization Address (address)
The profile address for the organization
Line address 1 (lineAddress1)
From the profile
Line address 2 (lineAddress2)
From the profile
Line address 3 (lineAddress3)
From the profile
Line address 4 (lineAddress4)
From the profile
City (city)
City
State (state)
If country is Canada, will return Canadian
province code. For countries other than US and
Canada will be blank.
Postal Code (postalCode)
Equivalent to “zip code” in the eRA database.
Returns 9 digits (zip+four). If only 5 digits of zip
code are available, will pad with zeros (e.g.,
208171814, 265060000)
Country (countryCode)
This is the ISO-3166 country code (Alpha-3
format) (E.g., USA)
Organization Status (status)
Indicates whether organization is ACTIVE (A)
or Closed (C)
Human Subject Assurance Number
(humanSubjectAssuranceNumber)
Human Subject Assurance Number (E.g.,
FWA00001234)
S2S Client Transactions Guide
Page
21
ORGANIZATION INFORMATION RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
Animal Welfare Assurance Number
Animal Welfare Assurance Number
If there is more than one Animal Welfare
Assurance Number associated with this
organization they will be returned as a list. For
example:
<AnimalWelfareAssuranceNumber>Assurance
number 1</AnimalWelfareAssuranceNumber>
<AnimalWelfareAssuranceNumber>Assurance
number 2</AnimalWelfareAssuranceNumber>
<AnimalWelfareAssuranceNumber>Assurance
number 3</AnimalWelfareAssuranceNumber>
NIH Policy Accepted Flag
(nihPolicyAcceptedFlag)
Flag indicating whether applicant organization
read and acknowledged NIH submission policy
statement or not(Y/N). A “Y” value is needed to
successfully submit an NIH application per
Submission Validation Service validation
000.44.
Data Element(Tag)
Description
uei
UEI for the organization
Prior Grant With UEI Request
PRIOR GRANT WITH UEI REQUEST MESSAGE (incoming)
DESCRIPTION
(federalID)
The federal identifier from
the SF 424 Form
serial number (e.g.
(applicationType)
The application type from
the SF 424 Form <Renewal,
Resubmission, Revision>
(projectStartDate)
The project start date from
the SF 424 Form.
Format <YYYY-MM-DD
or no data between tags>
(projectEndDate)
The project end date from
the SF 424 Form. Optional.
Format <YYYY-MM-DD
or no data between tags>
PRIOR GRANT WITH UEI RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
Accession Number
(accessionNum)
NIH internal key assigned before the grant number
S2S Client Transactions Guide
Page
22
PRIOR GRANT WITH UEI RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
Grant Status (grantStatus)
Grant application status post intake. This is the offical
grant status throughout the life cycle of the application
and grant (E.g., Awarded. Non-fellowships only)
Opportunity identifier
(rfapaNumber)
The opportunity under which the prior grant was
submitted.
Note: The Opportunity ID format stored in the NIH
database is slightly different than what appears in the
NIH Guide for Grants & Contracts or in Grants.gov.
For example: the database stores PA11-096 for FOA
PA-11-096 and NS13-006 for RFA-NS-13-006).
Activity Code (activityCode)
Activity code for the prior grant (E.g., R01)
Application Type
(applicationTypeCode)
The application type code for the prior grant
(E.g., 1 for New, 2 for Renewal, 3 for Revision, 4 for
Extension, 5 for Non-competing Continuation, 6 for
Change of Organization Status, 7 for Change of
Grantee or Training Institution, 8 for Non-Competing
Continuation Change of Institute or Division, 9 for
Competing Continuation Change of Institute or
Division)
Interim Funding
(interimFundingCode)
Indicator if the prior grant received interim funding.
Suffix Code (suffixCode)
Suffix code for the prior grant
Grant Title (projectTitle)
Project title for the prior grant
Application Receipt Date
(applReceiveDate)
Date the prior grant was successfully received by NIH
Project Start Date
(projectStartDate)
Prior grant start date
Project End Date
(projectEndDate)
Prior grant end date
Grant Number (grantNum)
Prior grant number (E.g., R44MD987654-03)
Support Year (supportYear)
Prior grant support year (E.g., 3)
UEI
UEI of the submitting organization for the prior grant
Award Doc Num
(awdDocNum)
Award document Id number
Budget Modular Indicator
(isBudgetModular)
An indicator if the prior grant has a modular budget
(true/false)
Summary Statement Indicator
(doesSummaryStatementExist)
An indicator if a summary statement has been
generated for the prior grant
Application Awarded Indicator
(isAppAwarded)
An indicator if the prior grant has been awarded
(true/false)
S2S Client Transactions Guide
Page
23
PRIOR GRANT WITH UEI RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
Application Verified Indicator
(isVerified)
An indicator if the prior grant has been verified
(true/false)
COMMONS User Id
(piCommonsID)
The Commons User Id of the PI on the prior grant
PI Last Name
(existingTransLastName)
The last name of the PI on the prior grant
SBIR STTR process
code(SBIRSTTRProcessCode)
Enumeration indicating the SBIR STTR process code.
Possible values:
Phase I
Phase II
Fast-Track
Direct Phase II
Phase IIA
Phase IIB
Commercialization Readiness Program
Full Opportunity Identifier
(fullRfaPaNumber)
The opportunity under which the prior grant was
submitted in full format.
FOA Information Request
FOA INFORMATION REQUEST MESSAGE (incoming)
DESCRIPTION
(rfapaNumber)
The opportunity for the
current submission
(e.g., RFA-NS-13-006, PA-
12-150)
Opportunity Identifier or
Package Id must be
The package ID is defined
in grants.gov. (e.g.,
PKG12345678)
Opportunity Identifier or
Package Id must be
(receiptDate)
Date the prior grant was or
will be successfully
received by NIH.
Format <YYYY-MM-DD>
default to current date.
FOA INFORMATION RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
Funding Opportunity
Number(fundingOpportunityNumber)
Full funding opportunity number returned from
grants.gov for a given package ID.
S2S Client Transactions Guide
Page
24
FOA INFORMATION RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
Activity Code (activityCode)
Activity code associated with opportunity
Combined activity codes (e.g., R21/R33) are
identified by the isCombinedMechanism flag.
When the isCombinedMechanism flag is true,
the first of the two activity codes would be listed
in this tag (e.g., R21 of R21/R33).
Administering PHS Organization
(phsOrgCode)
Institute/Center within Agency sponsoring
opportunity
Opt-out Flag (optOutCode)
A code that identifies if PAR or RFA would like
to opt out Limited Validation.
Note: This flag is not being used anymore.
Combined Mechanism Indicator
(isCombinedMechanism)
Indicator if opportunity uses combined
mechanism (true/false) E.g., R21/R33,
UH2/UH3
When true, the activity codes are listed in the
activityCode and combinedActivityCode tags.
Program Type (programTypeCode)
Program Type for opportunity (STTR, SBIR)
Direct Phase II (directPhaseII)
Indicator that FOA allows Direct Phase II
applications. (Y/N)
Opportunity Title (noticeTitle)
Title of opportunity
Notice Type (noticeTypeCode)
Notice Type for opportunity
‘P’ = PA (Program Announcement)
‘B’ = PAR (PA with special Receipt, Referral
and/or Review consideration
‘P’ = PAS (PA with Set-aside funds
‘R’ = RFA (Request For Applications)
Collaborative Type
(collaborativeTypeCode)
Collaborative Type for opportunity. Set to ‘01/
when the activity code is followed by the string
‘Collab’.
Council Round (councilMeetingDate)
Council round for opportunity (yyyymm)
Note: If a Council Round does not exist for the
requested FOA, the expected Council Round is
calculated based on the Proposal Receipt Date.
If omitted, the Council Round will be calculated
based on the current date.
Agency (agency)
Agency sponsoring opportunity (e.g., NIH)
AIDS Related Code
(aidsRelatedCode)
AIDS Related Code for opportunity (Y/N)
Multi-project indicator (isComplex)
Indicator for multi-project opportunity
(true/false)
S2S Client Transactions Guide
Page
25
FOA INFORMATION RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
Project Period Exception
(projectPeriodExceptionFlag)
Set to ‘Y’ if the FOA has been approved to allow
more than 5 budget periods. Set to ‘N’ otherwise.
Component Labels (component)
Agency defined labels used for expected
component types for an opportunity (applies to
multi-project submissions only)
E.g., Project, Core
Page Limits (pageLimit)
Page limits for research strategy (applies to
multi-project submissions only.)
Component Iterations
(minIterationNum, maxIterationNum)
Minimum and maximum number of iterations for
each expected component type (applies to multi-
project submissions only.) Note: limits may be
more restrictive than indicated in Grants.gov
opportunity schema.
projectCostExceptionFlag
When projectCostExceptionFlag is set to ‘Y’
then the direct cost limits must be followed as
stated in the FOA, not systematically validated
for the standard value for the activity code. For
example, R03 FOA that allows more than
$50,000 in direct costs per budget period.
pageLimitExceptionFlag
When pageLimitExceptionFlag is set to ‘Y’ then
the page limits for that attachment must be
followed as stated in the FOA, not systematically
validated for the standard value for the activity
code. For example, an R01 FOA that allows a
30 page research strategy instead of the standard
12 page limit.
projectPeriodExcepLT5YFlag
When projectPeriodExcepLT5Yflag is set to ‘Y’
then the project period may be greater than the
standard project period for the activity code. For
example, R21 FOA that allows more than 2
budget periods. This flag is applicable for
activity codes (R03, R21, R36, UH2) that require
project period less than 5 years whereas
projectPeriodExceptionFlag listed above is
applicable for activity codes (For example R01)
that require project period 5 years or more.
diversityFlag
When diversityFlag is set to ‘Y’ on the FOA,
then all senior key persons specified on the form
must provide a valid Commons Credential.
S2S Client Transactions Guide
Page
26
FOA INFORMATION RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
clinicalTrialCode
Indicates whether the FOA supports a clinical
trial etc. This is a string with possible values: N,
O, R and I.
N stands for ‘Not-Allowed’
O stands for Optional
R stands for Required
I stands for Required (Infrastructure)
Combined Activity Code
(combinedActivityCode)
Combined activity codes (e.g., R21/R33) are
identified by the isCombinedMechanism flag.
When the isCombinedMechanism flag is true,
the second of the two activity codes would be
listed in this tag (e.g., R33 of R21/R33).
Data Management Sharing Plan
(dmsPlan)
It is a set of codes to indicate the Data
Management Sharing Plan.
R stands Required
NA stands Not Allowed
RDS stands Required Data Sharing focus
Stem Cell Line Status Request
STEM CELL LINE STATUS REQUEST MESSAGE (incoming)
DESCRIPTION
List of proposed stem cell
lines (e.g., 0043)
STEM CELL LINE STATUS RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
Stem Cell Lines w/ indicators
(stemCellLine)
List of requested stem cell lines with indicator if
each is valid or not
Cell Line Code (stemCellLineCode)
Cell Line code (E.g., 0001)
Valid (valid)
Indicator of whether a cell line is valid or not
(true/false)
Credential Request
CREDENTIAL REQUEST MESSAGE (incoming)
DESCRIPTION
Last name of the person
whose Commons
Credentials are requested
S2S Client Transactions Guide
Page
27
CREDENTIAL REQUEST MESSAGE (incoming)
DESCRIPTION
Email of the person whose
Commons Credentials are
requested
CREDENTIAL RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
Commons User ID (credential)
List of commons user ids that match the
lastName and email in the request
SAM Org Info by UEI Request
SAM ORG INFO REQUEST MESSAGE (incoming)
DESCRIPTION
UEI of the organization
whose SAM registration
info is requested.
SAM ORG INFO RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
SAM Org registration details
(SAMOrgInfo)
This is a list of following information. Since an
organization can have multiple UEI’s this
method returns
samOrgsId
dunsID
dunsIDPlus4
cageCode
registerationExpirationDate
legalBusinessName
dbaName
companyDivision
divisionNumber
samCongressionalDistrict
entityUrl
entityStructure
stateOfIncorporation
countryOfIncorporation
businessTypeCounter
mailingAddressLine1
mailingAddressLine2
mailingAddressCity
mailingAddPostalCode
mailingAddZipCodePlus4
mailingAddressCountry
S2S Client Transactions Guide
Page
28
SAM ORG INFO RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
mailingAddStateOrProvince
govtBusPocFirstName
govtBusPocMiddleInitial
govtBusPocLastName
govtBusPocTitle
govtBusPocFaxUsOnly
elecBusPocFirstName
elecBusPocMiddleInital
elecBusPocLastName
electBusPocTitle
elecBusPocStAdd1
elecBusPocStAdd2
elecBusPocCity
elecBusPocZipPostalCode
elecBusPocZipPostalCodePlus4
elecBusPocCountryCode
elecBusPocStateOrProvince
elecBusPocUsPhone
elecBusPocUsPhoneExt
elecBusPocNonUsPhone
elecBusPocFaxUsOnly
elecBusPocEmail
domesticParentDunsNumber
domesticParentStAdd1
domesticParentStAdd2
domesticParentCity
domesticParentPostalCode
domesticParentCountryCode
domesticParentStateOrProv
domesticParentPhone
averageNumberOfEmployees
delinquentFederalDebtFlag
exclusionStatusFlag
lastMonthlyRunDate
softDeletedFlag
lastUpdId
lastUpdDate
registrationDate
samAddress1
samAddress2
samCity
samPostalCode
S2S Client Transactions Guide
Page
29
SAM ORG INFO RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
samProvinceOrState
samCountryCode
samZipCodePlus4
Data Element(Tag)
Description
SAM Org Info By UEI Response:
GetSAMOrgInfoByUEIResponse
uei
Generate Grant Image
GRANT IMAGE REQUEST MESSAGE (incoming)
DESCRIPTION
Grant Application as XML,
both Single and Complex
Grant application formats
are accepted
List: 0 to many
The value of “href” attribute
in corresponding
“FileLocation” sub element
in the “Attachment”
element in application
XML. Please refer
Appendix D for details of
an “Attachment” element in
the XML
href values in the
application XML
Actual PDF as Octet Stream
GRANT IMAGE RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
Image Content
Generated Image as Octet Stream
S2S Client Transactions Guide
Page
30
Generate Component Image
COMPONENT IMAGE REQUEST MESSAGE (incoming)
DESCRIPTION
XML for the Component
whose image is requested.
Metadata of the schema
associated with the complex
application FOA. It contains
the following sub fields.
Enumeration indicating
whether the project
associated with this
component is ‘Complex’,
‘Single’ or ‘Nonresearch’.
‘Complex’.
SchemaMetadata is a
type is expected and since
this API makes sense only
for ComplexApplication,
Meatadata of forms
contained in schema. This is
a list and at least one value
is expected. Each
formMetadata field contains
following sub fields.
Name of the form. Please
use name of the root
element in the form schema
as listed by Grants.gov
except version info.
lists the root element as
RR_SF424_2_0.
FormName is expected as
Namespace prefix used for
the elements for this form in
the xml
listed in schema. For
example, grants.gov schema
for R&R SF424 form lists
the namespace prefix as
Version of the form
List: 0 to many
The value of “href” attribute
in corresponding
“FileLocation” sub element
in the “Attachment”
element in application
XML. Please refer
Appendix D for details of
href values in the
component XML
S2S Client Transactions Guide
Page
31
COMPONENT IMAGE REQUEST MESSAGE (incoming)
DESCRIPTION
an “Attachment” element in
the XML
Actual PDF as Octet Stream
Name of the PI. PI name
usually appears in the
header.
COMPONENT IMAGE RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
impageContent
Generated Component Image as Octet Stream
Generate Form Image
FORM IMAGE REQUEST MESSAGE (incoming)
DESCRIPTION
Name of the form. Please
use name of the root
element in the form schema
as listed by Grants.gov
except version info.
lists the root element as
RR_SF424_2_0.
FormName is expected as
XML for the Form whose
image is requested.
Metadata of the schema
associated with the complex
application FOA. It contains
the following sub fields.
Enumeration indicating
whether the project
associated with this
component is ‘Complex’,
‘Single’ or ‘Nonresearch’.
‘Complex’.
SchemaMetadata is a
type is expected and since
this API makes sense only
for ComplexApplication,
Meatadata of forms
contained in schema. This is
a list and at least one value
is expected. Each
formMetadata field contains
following sub fields.
S2S Client Transactions Guide
Page
32
FORM IMAGE REQUEST MESSAGE (incoming)
DESCRIPTION
Name of the form. Please
use name of the root
element in the form schema
as listed by Grants.gov
except version info.
lists the root element as
RR_SF424_2_0.
FormName is expected as
Namespace prefix used for
the elements for this form in
the xml
listed in schema. For
example, grants.gov schema
for R&R SF424 form lists
the namespace prefix as
Version of the form
List: 0 to many
The value of “href” attribute
in corresponding
“FileLocation” sub element
in the “Attachment”
element in application
XML. Please refer
Appendix D for details of
an “Attachment” element in
the XML
href values in the
component XML
Actual PDF as Octet Stream
Name of the PI. PI name
usually appears in the
header.
FORM IMAGE RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
impageContent
Generated Form Image as Octet Stream
Generate Clinical Trials Form Image
FORM IMAGE REQUEST MESSAGE (incoming)
FIELD (Tag)
DESCRIPTION
VALIDATION
pdfattachment
1 pdf attachment with details
S2S Client Transactions Guide
Page
33
FORM IMAGE REQUEST MESSAGE (incoming)
FIELD (Tag)
DESCRIPTION
VALIDATION
reference
File name of the pdf
(PHSHumanSubjectsAndClinicalTrialsInfo-
V1.0.pdf, with filled-in data by user).
Please refer Appendix E for sample XML
for this call.
Content
Actual PDF as Octet Stream
Must be a valid PDF
document
FORM IMAGE RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
imageContent
Generated Clinical Trials Form Image as Octet
Stream
Process RFA PA Notice
RFA PA Notice REQUEST MESSAGE (incoming)
FIELD (Tag)
DESCRIPTION
VALIDATION
activityCode
A code that identifies the subcategory of
an extramural activity. It is used for auto
assignment of RFA Notice.
Activity code
should be valid
and be present in
Activity_codes_t
table
parentIndicator
A code that indicates whether this notice
is a parent. Valid values true or false
coIC
PHS Admin Org Code
IC should be
valid in
PHS_ORGS_T
RFAPANumber
This is used to uniquely identify RFA or
PA issues by IC.
RFAPANumber
cannot be empty
Notice Type code
cannot be empty
and it should start
with PA or PAR
or RFA
RFAPANumber
cannot be greater
than 10
primaryIC
The Primary IC that the RFA belongs to.
IC should be
valid in
PHS_ORGS_T
S2S Client Transactions Guide
Page
34
RFA PA Notice REQUEST MESSAGE (incoming)
FIELD (Tag)
DESCRIPTION
VALIDATION
receiptDate
The anticipated receipt date for responses
to an RFA or PA.
optOutIndicator
A code that identifies if PAR or RFA
would like to opt out Limited Validation.
clinicalTrialCode
Clinical trial code like N, O, R, I
expirationDate
The expiration date of RFA or PA.
openingDate
The date that RFA/PA notice is open.
FOATitle
The title given to the RFA/PA notice.
projectPeriodExceptionFlag
Flag indicating if FOA allows project
period to be longer than 5 years: 'Y' -
FOA allows project period be longer than
5 years; 'N' - does not allow
directPhaseTwoFlag
Flag indicating if FOA is an SBIR/STTR
direct phase 2;
'Y' - FOA is an SBIR/STTR in Direct
phase 2
'N' - FOA is an SBIR/STTR NOT in
Direct phase 2
standardDueDateFlag
Flag indicating if FOA uses standard
date: 'Y' - FOA uses standard date, 'N' -
FOA does not use standard date
graceDate
The date when FOA is still valid beyond
the expiration date.
ReviewCriteriaLabel
A unique number identifying the label set
projectCostExceptionFlag
Flag = Y to indicate Funding Opportunity
Announcement
allows Project Cost limit exception
Flag = N to indicate FOA does not allow
Project Cost limit exception
pageLimitExceptionFlag
Flag = Y to indicate Funding Opportunity
Announcement allows Project Cost limit
exception
Flag = N to indicate Funding Opportunity
Announcement does not allow Project
Cost limit exception
projectPeriodExcepLT5YFlag
Flag = 'Y' to indicate Funding
Opportunity Announcement Flag = 'Y' to
indicate Funding Opportunity
Announcement allows Project Period
Exception less than 5 years exception
Flag = 'N' to indicate Funding
Opportunity Announcement does not
S2S Client Transactions Guide
Page
35
RFA PA Notice REQUEST MESSAGE (incoming)
FIELD (Tag)
DESCRIPTION
VALIDATION
allow Project Period Exception less than
5 years exception
diversityFlag
Flag = 'Y' to indicate Parent Type 3
Diversity FOA, possible values are Y, N
and null
component
Components
should not be
duplicate
componentLabel
Label for the component
pageLimit
Maximum no of pages for the component
minIterationNum
Minimum no of times the component can
be present
maxIterationNum
Maximum no of times the component can
be present
RFA PA Notice RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
successful
Boolean stating if the RFA PA request
information is successfully persisted to DB
Regenerate Grant Image
Regenerate Grant Image REQUEST MESSAGE (incoming)
FIELD (Tag)
DESCRIPTION
VALIDATION
applId
ApplId Associated with an application
Regenerate Grant Image RESPONSE MESSAGE (outgoing)
Data Element (Tag)
Description
success
Boolean stating if the regenerate grant image
operation is successfully executed and a new
grant image is saved to DB
Appendices
Appendix A: Attachment Meta Data Notes
NIH uses ASPOSE pdf library to generate meta data for attachments
If the PDF size is 8.5 x 11 or 11 x 8.5 then we indicate resizing is not required.
--Attachment in xml file:
<PHS398_ResearchPlan_1_3:attFile>
S2S Client Transactions Guide
Page
36
<att:FileName>1-AddBioSketchA.pdf</att:FileName>
<att:MimeType>application/pdf</att:MimeType>
<att:FileLocation att:href="1-AddBioSketchA.pdf.81"/>
<glob:HashValue glob:hashAlgorithm="SHA-
1">yKdg68TocrfWwagB79Fn5bNm3yA=</glob:HashValue>
</PHS398_ResearchPlan_1_3:attFile>
--Sample of metadata
<typ:AttachmentMetaData>
<typ:FileName>1-AddBioSketchA.pdf</typ:FileName>
<typ:MimeType>application/pdf</typ:MimeType>
<typ:FileLocation>1-AddBioSketchA.pdf.81</typ:FileLocation>
<typ:SizeInBytes>8703</typ:SizeInBytes>
<typ:PageCount>1</typ:PageCount>
<typ:numberofLiness>40</typ:numberofLines>
<typ:isResizingRequired>false</typ:isResizingRequired>
<typ:isEncryptedAttachment>false</typ:isEncryptedAttachment>
<typ:ispasswordProtectedAttachment>false</typ:ispasswordProtectedAttachment>
<typ:isSecure>false</typ:isSecure>
<typ:pdfError>false</typ:pdfError>
<typ:isXfaPdf>false</typ:isXfaPdf>
</typ:AttachmentMetaData>
What are XFA forms and how they are different from AcroForms:
XFA stands for XML Forms Architecture (XFA) also known as LiveCycle forms
This link explains the differences well:
https://appligent.com/what-is-the-difference-between-
acroforms-and-xfa/
Relevant text from this link:
AcroForms are the original PDF forms technology, first introduced in 1998. AcroForms accept
input in both Forms Data Format (FDF) and XML Forms Data Format (xFDF). Many 3rd party
vendors support AcroForms.
Adobe’s acquisition of Accelio in 2003 brought that company’s XFA forms technology to
Adobe, where it is made available via Acrobat LiveCycle Designer. XFA forms are inherently
XML rather than PDF, and are incompatible with conventional PDF files. XFA forms “break”
Adobe’s Acrobat software, in the sense that Acrobat cannot be used to modify a LiveCycle
Designer-created document. XFA forms are not yet fully supported by third party PDF viewers’
vendors. Currently Adobe LiveCycle server software is required to process XFA forms in a
server environment.
How to determine if a PDF is an XFA form:
Open the document in Acrobat Reader of Acrobat Pro.
Select File->Properties from the menu.
In the ‘Description’ tab, look for PDF Producer in the ‘Advanced Group’.
S2S Client Transactions Guide
Page
37
It will be a version of ‘Adobe LiveCycle Designer’ if the PDF is an XFA form.
Appendix B: Sub Application ID Sample
--Sample XML snippet with sub application id
<Admin-Core:SubApplicationGroup xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:Admin-Core="http://apply.grants.gov/system/MetaMultiGrantApplication/Admin-
Core"
xsi:schemaLocation="http://apply.grants.gov/system/MetaMultiGrantApplication/Admin-
Core http://apply07.grants.gov/apply/opportunities/schemas/applicant/oppPA-60-999-
cidMULTI-PROJECT-PILOT/Admin-Core.xsd"><Admin-Core:SubApplicationGroupHeader>
<Admin-Core:SubApplicationGroupID>Admin-Core</Admin-Core:SubApplicationGroupID>
</Admin-Core:SubApplicationGroupHeader>
<Admin-Core:SubApplication>
<Admin-Core:SubApplicationHeader>
<Admin-Core:SubApplicationID>687-Admin-Core</Admin-Core:SubApplicationID>
</Admin-Core:SubApplicationHeader>
<Admin-Core:GrantApplication>
S2S Client Transactions Guide
Page
38
Appendix C: Testing Services
If you have a method of creating a client program to test the services, it is recommended to use
that for accessing and testing these services. Alternatively all the services listed in this document
can be tested using SOAP UI. You can follow these instructions on how to import a wsdl file
and test a service.
1. Create a new project in SOAP UI and select the wsdl file for which the project is being
created. If you are testing SADS service in UAT, you would use the URL:
https://services.external.uat.era.nih.gov/eraexchange/services/SubmissionAgencyDataSer
vice?wsdl
2. Click OK, SOAP UI will create the project and generate sample requests for all
operations supported by the service.
3. Open the request for the service method that needs to be tested and edit the request
supplying all necessary data
4. Make sure the end point, points to the correct service end point in appropriate
environment. For example for the service mentioned in step 1, the end point is
https://services.external.uat.era.nih.gov/eraexchange/services/SubmissionAgencyDataSer
vice
5. Set up the certificate: (assumption is that the certificate is already registered with eRA
and necessary roles have been added to the account that the certificate is mapped to)
a. Double click on the project and select WS-Security Configurations tab and select
Keystores sub tab
b. Add the java key store file associated with the certificate in this tab and provide
required credentials
c. Also configure SSL Keystore property in “request properties” window to point to
the same key store file used in 5b
d. Submit the request
6. Response window shall show the response from the service.
Additional instructions for testing SIL:
Since SIL deals with PDF attachments in the request and the response is a PDF stream, a few
more steps are involved:
1. To add attachment, please click on the Attachment… button at the bottom of the Request
window.
2. Choose the file that will be an attachment in the request. It will show up in the request
window.
3. Change the name to match “href” element for the corresponding element in the XML as
well as the “reference” element in the “attachments” section of the request.
4. Submit the request.
5. If the image is generated successfully, the response will show a reference to the file that
is downloaded.
6. To see the image, click the Attachments button at the bottom of the response window,
which will open the grant image in a pdf reader.
S2S Client Transactions Guide
Page
39
Sample XML:
Attachment element in XML:
<RR_SF424_2_0:SFLLLAttachment>
<att:FileName>SFLLLAttachment</att:FileName>
<att:MimeType>application/pdf</att:MimeType>
<att:FileLocation att:href="sflllattachment"/>
<glob:HashValue glob:hashAlgorithm="">MA==</glob:HashValue>
</RR_SF424_2_0:SFLLLAttachment>
Corresponding attachment stream map in the request:
<sub:attachments>
<sub:reference>sflllattachment</sub:reference>
<!--Optional:-->
<sub:content>cid:sflllattachment.pdf</sub:content>
</sub:attachments>
Response
<soap:Body>
<ImageResponse xmlns="http://era.nih.gov/submissionimageservice">
<imageContent>
<xop:Include href="cid:10a77a26-52c8-43fd-a6bb-37ec4e41696a-6@era.nih.gov"
xmlns:xop="http://www.w3.org/2004/08/xop/include"/>
</imageContent>
</ImageResponse>
</soap:Body>
Screenshot of SOAP UI showing, part of request, response, Attachments details (both for
request and response):
S2S Client Transactions Guide
Page
40
Appendix D: Sample XML for Generate Form Image API:
Sample XML and Attachment Info for generateFormImage API is listed below. Input for
component image is similar.
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:sub="http://era.nih.gov/submissionimageservice">
<soapenv:Header/>
<soapenv:Body>
<sub:FormWithAttachmentsRequest>
<sub:formName>RR_KeyPersonExpanded</sub:formName>
<sub:formXML><![CDATA[<RR_KeyPersonExpanded_2_0:RR_KeyPersonExpanded_2
_0
xmlns:RR_KeyPersonExpanded_2_0="http://apply.grants.gov/forms/RR_KeyPe
S2S Client Transactions Guide
Page
41
rsonExpanded_2_0-V2.0"
xmlns:att="http://apply.grants.gov/system/Attachments-V1.0"
xmlns:glob="http://apply.grants.gov/system/Global-V1.0"
xmlns:globLib="http://apply.grants.gov/system/GlobalLibrary-V2.0"
RR_KeyPersonExpanded_2_0:FormVersion="2.0">
<RR_KeyPersonExpanded_2_0:PDPI>
<RR_KeyPersonExpanded_2_0:Profile>
<RR_KeyPersonExpanded_2_0:Name>
<globLib:FirstName>Weerakoon Mudiyanselage</globLib:FirstName>
<globLib:MiddleName>Thushantha Harshi</globLib:MiddleName>
<globLib:LastName>Weerasinghe</globLib:LastName>
</RR_KeyPersonExpanded_2_0:Name>
<RR_KeyPersonExpanded_2_0:Address>
<globLib:Street1>FQUBED, INC.</globLib:Street1>
<globLib:Street2>6330 NANCY RIDGE DR, STE
107</globLib:Street2>
<globLib:City>SAN DIEGO</globLib:City>
<globLib:State>CA: California</globLib:State>
<globLib:ZipPostalCode>921213220</globLib:ZipPostalCode>
<globLib:Country>USA: UNITED STATES</globLib:Country>
</RR_KeyPersonExpanded_2_0:Address>
<RR_KeyPersonExpanded_2_0:Phone>858-677-
6733</RR_KeyPersonExpanded_2_0:Phone>
<RR_KeyPersonExpanded_2_0:Fax>858-677-
6737</RR_KeyPersonExpanded_2_0:Fax>
<RR_KeyPersonExpanded_2_0:Email>eRADev@mail.nih.gov</RR_KeyPersonExpan
ded_2_0:Email>
<RR_KeyPersonExpanded_2_0:OrganizationName>FQUBED,
INC.</RR_KeyPersonExpanded_2_0:OrganizationName>
<RR_KeyPersonExpanded_2_0:Credential>john.newsam</RR_KeyPersonExpanded
_2_0:Credential>
<RR_KeyPersonExpanded_2_0:ProjectRole>Other
(Specify)</RR_KeyPersonExpanded_2_0:ProjectRole>
<RR_KeyPersonExpanded_2_0:OtherProjectRoleCategory>Project
Lead</RR_KeyPersonExpanded_2_0:OtherProjectRoleCategory>
<RR_KeyPersonExpanded_2_0:DegreeType>DPHIL,DPH,MA,BA</RR_KeyPersonExpa
nded_2_0:DegreeType>
<RR_KeyPersonExpanded_2_0:BioSketchsAttached>
<RR_KeyPersonExpanded_2_0:BioSketchAttached>
<att:FileName>1-AddBioSketchA.pdf</att:FileName>
<att:MimeType>application/pdf</att:MimeType>
<att:FileLocation att:href="1-AddBioSketchA.pdf.42859" />
<glob:HashValue glob:hashAlgorithm="SHA-
1">WVHHJ/W0G6RzIs4UpZC44ejSuUw=</glob:HashValue>
</RR_KeyPersonExpanded_2_0:BioSketchAttached>
</RR_KeyPersonExpanded_2_0:BioSketchsAttached>
</RR_KeyPersonExpanded_2_0:Profile>
</RR_KeyPersonExpanded_2_0:PDPI>
S2S Client Transactions Guide
Page
42
</RR_KeyPersonExpanded_2_0:RR_KeyPersonExpanded_2_0>]]></sub:formXML>
<sub:schemaMetadata>
<sub:projectType>Complex</sub:projectType>
<!--1 or more repetitions:-->
<sub:formMetadata>
<sub:formName>RR_KeyPersonExpanded</sub:formName>
<sub:nameSpacePrefix>RR_KeyPersonExpanded_2_0</sub:nameSpacePrefix>
<sub:version>2.0</sub:version>
</sub:formMetadata>
</sub:schemaMetadata>
<!--Zero or more repetitions:-->
<sub:attachments>
<sub:reference>1-AddBioSketchA.pdf.42859</sub:reference>
<sub:content>cid:1-AddBioSketchA.pdf</sub:content>
</sub:attachments>
<sub:piName>TEST_PI</sub:piName>
</sub:FormWithAttachmentsRequest>
</soapenv:Body>
</soapenv:Envelope>
Appendix E: Sample XML for Generate Clinical Trials Form Image API:
Sample XML and Attachment Info for generateClinicalTrialsFormImage API is listed
below.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:sub="http://era.nih.gov/submissionimageservice">
<soapenv:Header/>
<soapenv:Body>
<sub:PdfWithAttachmentsRequest>
<sub:pdfattachment>
<sub:reference>Scenario1a_updated.pdf</sub:reference>
<sub:content>cid:Scenario1a_updated.pdf</sub:content>
</sub:pdfattachment>
</sub:PdfWithAttachmentsRequest>
</soapenv:Body>
</soapenv:Envelope>
Appendix F: Sample XML for FOA Information Request with package
ID:
S2S Client Transactions Guide
Page
43
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:typ="http://era.nih.gov/sads/types">
<soapenv:Header/>
<soapenv:Body>
<typ:GetFOAInfoRequest>
<typ:packageId>PKG00044588</typ:packageId>
</typ:GetFOAInfoRequest>
</soapenv:Body>
</soapenv:Envelope>
Appendix G: Sample XML for RFA PA Notice Request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ws="http://ws.eraexchange.nih.gov/" xmlns:typ="http://types.ws.eraexchange.nih.gov/">
<soapenv:Header/>
<soapenv:Body>
<ws:processRfaPaNoticeElement>
<typ:activityCode>U19</typ:activityCode>
<typ:parentIndicator>false</typ:parentIndicator>
<typ:RFAPANumber>PAR-19-276</typ:RFAPANumber>
<typ:transactionIndicator/>
<typ:primaryIC>NIA</typ:primaryIC>
<typ:receiptDate>2022-09-25T11:32:58Z</typ:receiptDate>
<typ:optOutIndicator>false</typ:optOutIndicator>
<typ:clinicalTrialCode>O</typ:clinicalTrialCode>
<typ:expirationDate>2022-09-26T11:32:58Z</typ:expirationDate>
<typ:openingDate>2019-12-25T11:32:58Z</typ:openingDate>
<typ:FOATitle>Complex Integrated Multi-Component Projects in Aging
Research (U19 Clinical Trial Optional)</typ:FOATitle>
<typ:projectPeriodExceptionFlag>false</typ:projectPeriodExceptionFlag>
<typ:directPhaseTwoFlag>false</typ:directPhaseTwoFlag>
<typ:standardDueDateFlag>true</typ:standardDueDateFlag>
<typ:graceDate>2022-10-30T11:32:58Z</typ:graceDate>
<typ:ReviewCriteriaLabel/>
<typ:component>
<typ:componentLabel>Overall</typ:componentLabel>
<typ:pageLimit>12</typ:pageLimit>
<typ:minIterationNum>1</typ:minIterationNum>
<typ:maxIterationNum>1</typ:maxIterationNum>
</typ:component>
<typ:component>
<typ:componentLabel>Admin Core</typ:componentLabel>
S2S Client Transactions Guide
Page
44
<typ:pageLimit>6</typ:pageLimit>
<typ:minIterationNum>1</typ:minIterationNum>
<typ:maxIterationNum>1</typ:maxIterationNum>
</typ:component>
<typ:component>
<typ:componentLabel>Core</typ:componentLabel>
<typ:pageLimit>6</typ:pageLimit>
<typ:minIterationNum/>
<typ:maxIterationNum>9</typ:maxIterationNum>
</typ:component>
<typ:component>
<typ:componentLabel>Project</typ:componentLabel>
<typ:pageLimit>12</typ:pageLimit>
<typ:minIterationNum>1</typ:minIterationNum>
<typ:maxIterationNum>9</typ:maxIterationNum>
</typ:component>
<typ:projectCostExceptionFlag>N</typ:projectCostExceptionFlag>
<typ:pageLimitExceptionFlag>N</typ:pageLimitExceptionFlag>
<typ:projectPeriodExcepLT5YFlag>N</typ:projectPeriodExcepLT5YFlag>
<typ:diversityFlag/>
</ws:processRfaPaNoticeElement>
</soapenv:Body>
</soapenv:Envelope>
Document History
Document Location
The NIH internal source document is located in ClearCase under
“External\eRAExchange\docs\6.deployment\user_guide\”.
Revision History
Version
Number
Revision
Date
Author
Summary of Changes
0.0
May-06
eRA Dev Team
Document creation
2.0
Jan-08
eRA Dev Team
Updates for migration to WSDL
3.0
Jan-12
eRA Dev Team (AD)
Updates for Complex Project
4.0
May-13
eRA Dev Team (KM)
Removed Person Info Update Request &
Degree Code Lookup Values.
Updates Input/Outputs for Complex Project.
4.0.1
May-13
eRA Team (SC)
Provided additional context (tag names,
improved descriptions, examples, samples)
S2S Client Transactions Guide
Page
45
4.0.2
Dec-13
eRA Team (SC)
Removed ‘DRAFT’ watermark and updated
logo. Updated Get FOA Information request
to include Project Period Exception
indicator. Clarified that the SVS service is
not yet available.
4.0.3
Jan-13
eRA Team (SC)
Updated Get FOA Information request to
include Direct Phase II indicator.
4.0.4
Jan-15
eRA Team
Updated SVS and SADS service details,
added details for SIL
4.0.5
Mar-17
eRA Team
Updated SADS service details.
4.0.6
July-15
eRA Team
Updated combined activity code
information for tags:
isCombinedMechanism, activityCode, and
combinedActivityCode.
4.0.7
Oct-15
eRA Team
Updated FOA Response to reflect diversity
flag and other exception flags.
4.0.8
Nov-15
eRA Team
Updated Submission Image Generation
Service details to reflect the changes to
remove Submission Identifier and
isNIHApp
4.0.9
May-16
eRA Team
Added two new SADS API getCredential
and getSAMOrgInfo
4.2
Jan-17
eRATeam
Added 2 new API for Submission Image
Generation Service. These API are
generateComponentImage and
generateFormImage.
A new flag ‘clinicalTrialFlag’ has been
added to getFOAInfo response.
4.3
Feb-17
eRATeam
Added 2 new elements to
AttachmentMetadata for
SubmissionValidationService methods
4.4
Aug-17
eRATeam
Removed the following methods from the
SADS service:
• Non research Amendment Types
request
• Non research Amendment Forms
request
• Non research Grant Details request
Removed the flag
isSBIRSTTRPhaseIIBAwarded from Prior
Grant Response and added SBIR STTR
Process code which is an enumeration
FOAInformation Response:
S2S Client Transactions Guide
Page
46
Removed the clinicialTrialFlag and added
ClinicalTrialCode
4.5
July-18
eRATeam
Updated Organization Information
response. A new flag
nihPolicyAcceptedFlag has been added to
the response
4.6
Aug-18
eRATeam
Updated new API
(generateClinicalTrialsFormImage) for
Submission Image Generation Service.
4.7
Sep-18
eRATeam
Update the existing API getFOAInfo for
SubmissionAgencyDataService
4.8
July-20
eRATeam
Added RFA PA Notice service
4.9
Nov-20
eRATeam
Updated the existing API getPersonInfo for
SubmissionAgencyDataService to add
personId and OrcId to the response
5.0
Apr-21
eRATeam
Updated the description for opt-Out Flag in
FOA INFORMATION RESPONSE
MESSAGE
5.1
Jun-21
eRATeam
Added new operation regenerateGrantImage
to Submission Agency Data Services
(SADS)
5.2
Aug-21
eRATeam
Added new operation
getSAMOrgInfoByUEI to Submission
Agency Data Services(SADS)
5.3
Aug-21
eRATeam
Added new operation
getOrganizationInfoByUEI to Submission
Agency Data Services(SADS)
5.4
Sep-21
eRATeam
Added
getPersonInfoWithEmploymentWithUEI
operation to SADS
5.5
Sep-21
eRATeam
Added getPersonInfoWithUEI operation to
SADS
5.6
Sep-21
eRATeam
Added getPriorGrantInfoWithUEI operation
to SADS
5.7
May-22
eRATeam
Added full rfa pa number to
getPriorGrantInfo and
getPriorGrantInfoWithUEI
5.8
May-22
eRATeam
Remove getPreviousSubmissionInfo which
is not present in external
5.9
Aug-22
eRATeam
Add getPersonBasicInfo in external
5.10
Aug-22
eRATeam
Add dmsPlan in response of getFOAInfo
external
5.11
Aug-23
eRATeam
Removed external ws operations
getOrganizationInfo, getPersonInfo,
S2S Client Transactions Guide
Page
47
getPersonInfoWithEmployment,
getPriorGrantInfo, getSAMOrgInfo