NONCONFIDENTIAL // EXTERNAL

G-Invoicing

System Interface 

Specifications - Pull

A Guide to extracting, packaging, and transmitting GT&C,

Order and Performance data from G-Invoicing

General Terms and Conditions (GT&C),

Orders and Performance

Version 7.2.1

June 2023
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

2

NONCONFIDENTIAL // EXTERNAL

Table of Contents

1 Introduction................................................................................................................................ 3

1.1 Purpose ............................................................................................................................... 3

1.2 Scope................................................................................................................................... 3

1.3 References .......................................................................................................................... 3

2 Assumptions/Constraints ......................................................................................................... 4

2.1 Assumptions....................................................................................................................... 4

2.2 Constraints.......................................................................................................................... 4

3 Interface Mechanism ................................................................................................................. 4

3.1 Physical Interface ............................................................................................................... 4

3.2 Protocol............................................................................................................................... 4

3.3 Supported Environments................................................................................................. 14

4 Interface Specification ............................................................................................................ 14

4.1 Processing Logic.............................................................................................................. 14

4.2 Business Rules................................................................................................................. 15

4.3 File Naming Convention .................................................................................................. 15

4.4 Interface Timing................................................................................................................ 15

4.5 Retransmissions............................................................................................................... 16

4.6 Interface Data Details ....................................................................................................... 16

5 Error Specifications................................................................................................................. 20

6 Security..................................................................................................................................... 20

7 Interface Integrity..................................................................................................................... 21

7.1 TWAI .................................................................................................................................. 21

7.2 Communication Channel ................................................................................................. 21

8 Revision History ...................................................................................................................... 22

Appendix A: Messaging Protocol & Data Encapsulation............................................................ 25

1 G-Invoicing Message Encapsulation ..................................................................................... 25

1.1 HTTP Request .....................................................................................................................................................25

1.2 HTTP Response ...................................................................................................................................................25

2 Call Detail ................................................................................................................................. 26

3 Document List.......................................................................................................................... 26

4 Error.......................................................................................................................................... 27
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

3

NONCONFIDENTIAL // EXTERNAL

1 Introduction

1.1 Purpose

This artifact defines the interface specification to define the transmission of General Terms & 

Conditions (GT&C), Order and Performance data from the G-Invoicing application to Federal 

Program Agency systems. It serves as an agreement between G-Invoicing, agencies with 

interfacing systems, their software provider development teams and Bureau of the Fiscal 

Service business owners, upon which the system-to-system interface will be based.

1.2 Scope

This artifact defines the G-Invoicing specifications to extract, package and transmit GT&C, 

Order and Performance data and the communication channel that carries these messages. The 

focus is on the specifications that must be mutually agreed upon by G-Invoicing and agencies 

with interfacing systems. The G-Invoicing team owns the maintenance of this document.

1.3 References

The artifacts listed below support the current Production release of this specification and may be 

downloaded from the provided location. Artifacts that support future enhancements and 

releases of this specification can be made available upon request.

1.3.1 The Federal Intragovernmental Data Standards (FIDS) for GT&C, Order and 

Performance Data Elements

https://www.fiscal.treasury.gov/fsservices/gov/acctg/g_invoice/g_invoice_home.htm

1.3.2 System Mapping and Validation Rules (SM&VR) for GT&C and Order, explains how 

each data element in the FIDS maps to G-Invoicing and the validation rules enforced for 

each change in status.

https://www.fiscal.treasury.gov/fsservices/gov/acctg/g_invoice/g_invoice_home.htm

Note: There is no SM&VR document for Performance data because there are not 

multiple, complex status scenarios to support. Validation rules appear in the 

Performance FIDS.

1.3.3 XML Schema Documentation

• GTC.xsd (payload)

• Documents Summary.xsd

• Error.xsd 

The following schemas are used for Orders and Performance:

• Order_Documents Summary.xsd

• Order_Error.xsd 

• Order.xsd (payload)

• Performance.xsd (payload)

https://www.fiscal.treasury.gov/data/
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

4

NONCONFIDENTIAL // EXTERNAL

2 Assumptions/Constraints

2.1 Assumptions

1. While this artifact represents an agreement by G-Invoicing, Federal Program Agencies 

and their software providers, it does not imply a release schedule or project plan. 

Those topics are described by other artifacts for the respective projects and are not 

referenced here.

2. The interface is limited to the transmission of GT&C, Order and Performance data 

outbound from G-Invoicing to agencies with interfacing systems. Additional data types 

are not included in this interface at this time.

2.2 Constraints

1. This interface will be delivered via web services, access governed by the Treasury 

Web Application Infrastructure (TWAI), as per agreement between FRB St Louis, the 

Department of the Treasury Bureau of the Fiscal Service and Defense Logistics 

Agency (DLA) Transaction Services, and is consistent with the Bureau of the Fiscal 

Service’s desire to move towards delivering system-to-system interfaces via web 

services.

a. Similar operating agreements may be made with other agencies, as-needed.

2. Messages will be sent over the internet utilizing the HTTPS protocol.

3. The Bureau of the Fiscal Service reference data XML Schemas will be published by 

the Enterprise Data Architecture group at https://www.fiscal.treasury.gov/data/. These 

schemas will be used to format the payload portion of the data transmission.

a. XML namespaces may vary with each new schema version

3 Interface Mechanism

3.1 Physical Interface

The G-Invoicing to agency system interface will communicate using HTTPS with 2-way TLS 

(Transport Layer Security) using a client certificate through the TWAI. The TWAI will employ a 

web service proxy to serve as a focal route for incoming web service requests so that the web 

service provider is only configured to receive requests from a single point of origination. The 

web service response is routed back on the same stream to the initial requestor.

3.2 Protocol

The G-Invoicing to agency system interface will employ a push/pull model utilizing REST 

Services with an XML payload.

All services below are referenced via URLs in the following format. 

https://host-name:port/base-path/resource-path

3.2.1 Host names:

Production: ws.igt.fiscal.treasury.gov

Quality Assurance Current: qa.ws.igt.fiscal.treasury.gov 

Quality Assurance Future: qaf.ws.igt.fiscal.treasury.gov
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

5

NONCONFIDENTIAL // EXTERNAL

Functional Test: ft.ws.igt.fiscal.treasury.gov

3.2.2 Base Path: /ginv

3.2.3 Resource: /services

Note: G-Invoicing supports a one-to-many relationship between a Partner ID and a 

System ID whereby one Partner created and managed within a single agency account 

can represent multiple Systems spread across many agency accounts. Policy requires 

that at least one System ID must be created and managed in each agency account to 

push data. The Partner ID must be assigned a client certificate to access G-Invoicing.

3.2.3.1 Resource: GT&C List

Component Detail / Description

Path /ginv/services/v1_0/gtc/ (for single ALC per partner v2.1 XML schema) 

/ginv/services/v2_0/gtc/ (for 1-to-many ALCs per partner v3.0 XMLschema) 

Method GET 

Description Returns a list of all GT&Cs from the System that the User is authorized to access.

Example GET /ginv/services/v1_0/gtc?status=REC,CLZ 

GET /ginv/services/v2_0/gtc?status=REC,CLZ

GET /ginv/services/v1_0/gtc?agencyLocationCode=17000001,17000002,17000003 

&lastModifiedDateTime=2020-06-17T13:30:00.000-04:00

Host: ws.igt.fiscal.treasury.gov

Accept: application/xml 

Accept Encoding: gzip, deflate 

Connection: Keep-Alive

Parameters

Name: agencyLocationCode

Description: Limits results to GT&Cs which contains at least one of the passed ALCs. 

In: query

Type: Comma separated array of strings 

Required: false

Name: status

Description: Limits results of GT&Cs associated with one of the passed status types. 

In: query

Type: Comma separated array of strings, enumeration

Values: “REC” (Open For Orders), “CLZ” (Closed), “PND” (Pending Approval), “REJ” (Rejected). 

Required: false

Name: lastModifiedDateTime

Description: Limits results to GT&Cs updated since the passed date/time. 

In: query

Type: dateTime; Format: YYYY-MM-DDThh:mm:ss.SSS+|-00:00

All time should be specified in local time zone with time zone offset from UTC in hours 

and minutes ahead (+) or behind (-) UTC.

Required: false
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

6

NONCONFIDENTIAL // EXTERNAL

Component Detail / Description

Name: SystemID 

Description: Identifies the system that is exchanging data with G-Invoicing. 

In: header

Type: string [100] 

Required: true

Name: Agency-Tracking-Identifier

Description: Unique identifier from agency system, optionally supplied in the request. 

In: header

Type: string [50] 

Required: false

Consumes N/A

Produces

Status Code: 200

Description: Successful call returns Call Detail and a list of GT&Cs. 

Content Type: application/xml

Schema(s): Call Detail, Document List

3.2.3.2 Resource: Single GT&C by ID

Component Detail / Description

Path /ginv/services/v1_0/gtc/<id> (to pull single GT&C for v2.1 XML schema) 

or ginv/services/v2_0/gtc/<id> (to pull single GT&C for v3.0 XML schema)

Method GET 

Description Returns an individual GT&C referenced by the passed unique RequestType / 

RequestTypeID combination.

Example GET /ginv/services/v1_0/gtc/A1610-017-021-012345 

GET /ginv/services/v2_0/gtc/A2006-017-021-123456 

Host: ws.igt.fiscal.treasury.gov

Accept: application/xml 

Accept Encoding: gzip, deflate 

Connection: Keep-Alive

Parameters

Name: id

Description: A Unique ID referencing an individual GT&C. 

In: path (required)

Type: string [20] 

Required: true

Name: SystemID 

Description: Identifies the system that is exchanging data with G-Invoicing. 

In: header

Type: string [100] 

Required: true
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

7

NONCONFIDENTIAL // EXTERNAL

Component Detail / Description

Name: Agency-Tracking-Identifier

Description: Unique identifier from agency system, optionally supplied in the request. 

In: header

Type: string [50] 

Required: false

Consumes N/A

Produces

Status Code: 200

Description: Successful call returns Call Detail and an individual GT&C. 

Content Type: application/xml

Schema(s): Call Detail, GT&C

3.2.3.3 Resource: Single Attachment by ID

Component Detail / Description

Path /ginv/services/v1_0/attachment/<id> (for GT&C attachment)

/ginv/services/v1_0/order/attachment/<id> (for Order attachment)

/ginv/services/v1_0/order/performance/attachment/<id> (for Performance attachment)

Method GET 

Description Returns an individual Attachment referenced by the passed unique ID.

Example GET /ginv/services/v1_0/attachment/987654321

GET /ginv/services/v1_0/order/attachment/987654321

GET /ginv/services/v1_0/order/performance/attachment/987654321 

Host: ws.igt.fiscal.treasury.gov

Accept: application/xml 

Accept Encoding: gzip, deflate 

Connection: Keep-Alive

Parameters

Name: id

Description: A Unique ID referencing an individual Attachment. 

In: path

Type: string [30] 

Required: true

Name: SystemID 

Description: Identifies the system that is exchanging data with G-Invoicing. 

In: header

Type: string [100] 

Required: true

Name: Agency-Tracking-Identifier

Description: Unique identifier from agency system, optionally supplied in the request. 

In: header

Type: string [50] 

Required: false

Consumes N/A
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

8

NONCONFIDENTIAL // EXTERNAL

Component Detail / Description

Produces

Status Code: 200

Description: Successful call returns the binary content of the Attachment file. 

Content Type: application/octet-stream

Schema(s): file

3.2.3.4 Resource: Orders List

Component Detail / Description

Path Ginv/services/v1_0/order (to pull list of Orders for v2.2 of the XML schema) 

or Ginv/services/v2_0/order> (to pull list of Orders for v2.3 of the XML schema)

Note: The v2.3 Order_Document_Summary.xsd uses the same format as the v3.0 

Document_Summary.xsd for GT&Cs, which supports 1-to-many ALCs per partner. 

ALCs for an Order will only occupy the first occurrence of AgencyLocationCode.

Method GET 

Description Returns a list of all Orders from the System that the User is authorized to access. The 

keys necessary to obtain detailed Order data are obtained by pulling the Orders List.

Example GET /ginv/services/v1_0/order?lastModifiedDateTime=2017-05-09T17:30:00.000-04:00 

GET /ginv/services/v2_0/order?lastModifiedDateTime=2021-03-08T19:20:00.000-04:00 

Host: ws.igt.fiscal.treasury.gov

Accept: application/xml 

Accept Encoding: gzip, deflate 

Connection: Keep-Alive

Parameters

Name: agencyLocationCode

Description: Limits results to Orders associated with one of the passed ALCs. 

In: query

Type: Comma separated array of strings 

Required: false

Name: status

Description: Limits results of Orders associated with one of the passed status types. 

In: query

Type: Comma separated array of strings, enumeration

v1_0 Values: “PRA” (Pending Requesting Approval) or “P1A” (Pending Partner 1 

Approval), “SSA” (Share with Servicing) or “SP2” (Shared with Partner 2), “PSA” 

(Pending Servicing Approval) or “P2A” (Pending Partner 2 Approval), “REC” 

(Open), “DR” (Draft - when Order Mod>0), “REJ” (Rejected), “CLZ” (Closed)

v2_0 Values: “P1A” (Pending Partner 1 Approval), “SP2” (Shared with Partner 2), 

“P2A” (Pending Partner 2 Approval), “REC” (Open), “DR” (Draft - when Order 

Mod>0), “REJ” (Rejected), “CLZ” (Closed) 

Required: false

Name: lastModifiedDateTime

Description: Limits results to Orders updated since the passed date/time. 

In: query

Type: dateTime; Format: YYYY-MM-DDThh:mm:ss.SSS+|-00:00

All time should be specified in local time zone with time zone offset from UTC in hours 

and minutes ahead (+) or behind (-) UTC.

Required: false
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

9

NONCONFIDENTIAL // EXTERNAL

Component Detail / Description

Name: SystemID 

Description: Identifies the system that is exchanging data with G-Invoicing. 

In: header

Type: string [100] 

Required: true

Name: Agency-Tracking-Identifier

Description: Unique identifier from agency system, optionally supplied in the request. 

In: header

Type: string [50] 

Required: false

Consumes N/A

Produces

Status Code: 200

Description: Successful call returns Call Detail and a list of Orders. 

Content Type: application/xml

Schema(s): Call Detail, Document List

3.2.3.5 Resource: Single Order by ID

Component Detail / Description

Path Ginv/services/v1_0/order/<id> (to pull Orders for v2.2 of the XML schema) 

or Ginv/services/v2_0/order/<id> (to pull Orders for v2.3 of the XMLschema)

Method GET 

Description Returns an individual Order referenced by the passed unique identifier for an individual 

Order. Identifiers to Attachments related to an Order (i.e., Attachment IDs) are obtained 

by pulling the Single Order by ID.

Example GET /ginv/services/v1_0/order/O1705-123-234-000146 

or GET /ginv/services/v2_0/order/O2005-123-234-000146 

Host: ws.igt.fiscal.treasury.gov

Accept: application/xml 

Accept Encoding: gzip, deflate 

Connection: Keep-Alive

Parameters

Name: id

Description: A Unique ID referencing an individual Order. 

In: path (required)

Type: string [20] 

Required: true

Name: modNbr

Description: Allow a system to pull specific modification of an Order

Paths: order

In: query

Type: numeric [10] 

Required: false
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

10

NONCONFIDENTIAL // EXTERNAL

Name: SystemID 

Description: Identifies the system that is exchanging data with G-Invoicing. 

In: header

Type: string [100] 

Required: true
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

11

NONCONFIDENTIAL // EXTERNAL

Component Detail / Description

Name: Agency-Tracking-Identifier

Description: Unique identifier from agency system, optionally supplied in the request. 

In: header

Type: string [50] 

Required: false

Consumes N/A

Produces

Status Code: 200

Description: Successful call returns Call Detail and an individual Order. 

Content Type: application/xml

Schema(s): Call Detail, Order

3.2.3.6 Resource: Performance List

Component Detail / Description

Path /ginv/services/v1_0/order/performance

Method GET 

Description Returns a list of all Performance transactions from the System that the User is authorized 

to access, based on Order permissions.

Example GET /ginv/services/v1_0/order/performance?lastModifiedDateTime=2017-05- 

09T17:30:00.000-04:00?agencyLocationCode=12010001

Host: ws.igt.fiscal.treasury.gov

Accept: application/xml 

Accept Encoding: gzip, deflate 

Connection: Keep-Alive

Parameters

Name: agencyLocationCode

Description: Limits results to Performance transactions related to Orders containing one 

of the passed ALCs.

In: query

Type: Comma separated array of strings 

Required: false

Name: lastModifiedDateTime

Description: Limits results to Performance transactions created since the passed 

date/time.

In: query

Type: dateTime (ISO 8601) 

Required: false

Name: SystemID 

Description: Identifies the system that is exchanging data with G-Invoicing. 

In: header

Type: string [100] 

Required: true
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

12

NONCONFIDENTIAL // EXTERNAL

Component Detail / Description

Name: status

Description: Limits results of Performance associated with one of the passedStatus 

values.

In: query

Type: Comma separated array of strings, enumeration 

Values: All values in Performance FIDS are supported 

Required: false

Name: orderNumber

Description: Limits results to Performance associated with a single Order 

In: query

Type: string [20] 

Required: false

Name: Agency-Tracking-Identifier

Description: Unique identifier from agency system, optionally supplied in the request. 

In: header

Type: string [50] 

Required: false

Consumes N/A

Produces

Status Code: 200

Description: Successful call returns Call Detail and a list of Performance transactions. 

Content Type: application/xml

Schema(s): Call Detail, Document List

Note: Settlement Status and lastModifiedDateTime are initially set by G-Invoicing when 

Performance is reported. The values of both will change if/as settlement occurs.

3.2.3.7 Resource: Single Performance by ID

Component Detail / Description

Path Ginv/services/v1_0/order/performance/{id}

Method GET 

Description Returns an individual Performance transaction referenced by the passed unique identifier 

for an individual Performance transaction.

Example GET /ginv/services/v1_0/order/performance/P1805-123-234-000456 

Host: ws.igt.fiscal.treasury.gov

Accept: application/xml 

Accept Encoding: gzip, deflate 

Connection: Keep-Alive

Parameters

Name: id

Description: A Unique ID referencing an individual Performance transaction. 

In: path (required)

Type: string [20] 

Required: true
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

13

NONCONFIDENTIAL // EXTERNAL

Component Detail / Description

Name: SystemID 

Description: Identifies the system that is exchanging data with G-Invoicing. 

In: header

Type: string [100] 

Required: true

Name: Agency-Tracking-Identifier

Description: Unique identifier from agency system, optionally supplied in the request. 

In: header

Type: string [50] 

Required: false

Consumes N/A

Produces

Status Code: 200

Description: Successful call returns an individual Performance transaction. 

Content Type: application/xml

Schema: Performance 

3.2.4 Common Headers

3.2.4.1 Accept Header

Component Detail / Description

Name Accept 

Value application/xml

Description Indicates the service client expects content in XML format. No other format is currently 

supported.

3.2.4.2 Accept-Encoding

Component Detail / Description

Name Accept-Encoding

Value gzip, deflate

Description Allows the service client to indicate it supports compressing the response payload using 

gzip compression.

3.2.4.3 Connection Header

Component Detail / Description

Name Connection

Value keep-alive

Description Indicates the service client wants to use HTTP keep-alive to more efficiently make 

multiple requests.
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

14

NONCONFIDENTIAL // EXTERNAL

3.3 Supported Environments

The G-Invoicing application operates within the Treasury Web Application Infrastructure (TWAI) 

environments. Interface testing will take place in G-Invoicing’s Functional Test and Quality 

Assurance environments. G-Invoicing operates both Production and Contingency environments.

Fail-over by G-Invoicing from Production to Contingency environments will be transparent.

Table 1: Supported Environments

G-Invoicing TWAI Use

Functional Test (FT) Future view of Production (new release) – will be used on a limited 

basis for interface testing.

Quality Assurance - Current (QAC) Current view of Production environment – used for agency testing.

Quality Assurance - Future (QAF) Future view of Production (new release) – used for UAT.

Production Production

4 Interface Specification

4.1 Processing Logic

4.1.1 Agencies with interfacing systems will make a web service call to G-Invoicing to request 

new or modified GT&C, Order or Performance information. The credentials for the 

agency systems are verified by the TWAI. Certificate-based authentication is performed 

against TWAI policies. Web service requests for G-Invoicing data require a United 

States Department of the Treasury issued certificate.

4.1.2 Validate the parameters that are passed in the request depending on the data being 

requested (e.g., Document List, Single Document, Single Attachment) as stated in 

Section 3.2 of this document. The parameters to be passed are either required, 

optional, and/or conditional depending on the request.

4.1.3 G-Invoicing will retrieve the requested data.

4.1.4 The data is formatted into an XML document per the XML schema(s) referenced in

Appendix A of this document.

4.1.5 G-Invoicing transmits the data to the agency system.

4.1.6 If errors are encountered at any time while processing the request, G-Invoicing will 

capture that data and respond back to the agency partner with the error details.
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

15

NONCONFIDENTIAL // EXTERNAL

4.2 Business Rules

4.2.1 System requests for GT&C, Order and Attachment data will be fulfilled with data as it 

exists when the request is answered.

Note: This statement covers any previous or historical states that a document would 

have been in prior to its current state. G-Invoicing will not provide a document history 

(i.e., multiple versions of the same document) or deleted attachments.

4.2.2 The agency system must be granted permissions (aka, user role) to view the type of 

data being requested.

4.2.3 The agency system must be assigned to Organizational Group(s) containing the ALC(s) 

for which the data is being requested.

4.2.3.1 An agency system only requires access to one side of an agreement (Requesting 

or Servicing) not both to view all data associated with the agreement, including 

attachments. The agency system will be properly authorized to ensure it is valid 

for the type of request being submitted.

4.2.3.2 Users granted data access to an Order will be allowed to access Performance 

related to that Order (assuming they are assigned a role to view Performance).

4.2.4 GT&C and Order document requests submitted with a Status parameter of “Delete” will 

not be fulfilled.

Note: There are no restrictions on pulling deleted Performance records.

4.2.5 GT&C document requests submitted with a Status parameter of “Draft” (DR) will 

not be fulfilled.

4.2.6 Order document requests submitted with a Status parameter of “Draft” (DR) will only 

return Orders with Modification Number > 0.

4.2.7 GT&C and Order requests for Document Types submitted without a Status parameter 

will return documents in all statuses, except where noted above.

4.2.8 Character entity references ampersand (&) and less than (<) are escaped on output to 

XML. The escape sequence for ampersand is & and the escape sequence for less 

than is <.

4.3 File Naming Convention

N/A

4.4 Interface Timing

The web service is available 24 hours per day, 7 days per week. G-Invoicing has a daily 

scheduled outage for maintenance as noted below.

3:45 AM - 4:15 AM EST (Monday through Saturday)

11:00 AM - 11:30 AM EST (Sunday)

Agency systems are in full control of the frequency and the timing of this interface.
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

16

NONCONFIDENTIAL // EXTERNAL

4.5 Retransmissions

Retransmissions are not needed because the G-Invoicing web services provide for 

synchronous operation in that the agencies with interfacing systems will be waiting for the 

response from G-Invoicing before continuing.

Should the web service connection somehow fail in the middle of a series of client 

requests to G-Invoicing (e.g., multiple document requests, multiple attachment requests) 

the client (i.e., interfacing agency system) is responsible for continuing the requests when 

services are restored.

4.6 Interface Data Details

The information below documents the data sent for the methods available on the web 

service. For more details, refer to the XML schemas for the service in Appendix A.

4.6.1 Business – Data Elements

The business data for GT&C and Orders may be accessed on the Bureau of the Fiscal

Service G-Invoicing website.

The data elements in Table 2 will be returned with each single GT&C, Order or 

Performance request where the requested document contains one or more attachments. 

This data describes each attachment and provides the means (i.e., URL) for a 

subsequent request to retrieve the attachment(s).

Table 2: Attachment Summary Data Elements

Familiar Name XML Tag Definition Constraints Optionality

Attachment File 

Name 

<FileName> The actual name of the 

attachment file. 

String [1, 32] Maximum 

length = 132 String UTF8 

Required 

Attachment File 

Alias

<FileNameAlias> Descriptive name for an 

attachment. Different from 

the name assigned to the 

file itself. 

String [0,132] Maximum 

length = 132 String UTF8 

Optional 

Attachment ID <AttachmentID> Unique identifier for an 

attachment. 

Integer 

Maximum length = 30 

Required 

Attachment 

Updated By 

<FullName> The username or partner 

(Buyer or Seller) that 

uploaded the attachment. 

String [0,100] Maximum 

length = 100 String UTF8 

Required 

Attachment Date 

Time

<UploadDateTime> The date and time the file 

was uploaded into GInvoicing. 

DateTime Format: YYYY-MMDDThh:mm:ss.SSS+|- 00:00 

All time should be specified in 

local time zone with time zone 

offset from UTC in hours and 

minutes ahead (+) or behind 

(-) UTC.

Required 

File Size <FileSize> The size of the attachment 

expressed in kilobytes 

(kB). Note: Small files may 

be expressed as 0 kB. 

Integer 

Minimum length = 1 

Maximum length = 8 

Required 
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

17

NONCONFIDENTIAL // EXTERNAL

Familiar Name XML Tag Definition Constraints Optionality

Document URL <URL> The URL that will be used 

in a subsequent request by 

the agency system to 

retrieve the attachment. 

String [0, 4000] 

Maximum length = 4000 

String UTF-8 

Required 

4.6.2 Response – Data elements

The data elements below in Table 3 will be returned in the body of every response 

generated by G-Invoicing. The data elements contained in Table 4 will be returned when 

requesting a list of new or modified documents from G-Invoicing.

Table 3: Call Detail Response Data Elements

Familiar Name XML Tag Definition Constraints Optionality

Agency Partner ID <PartnerID> Identifies the intended 

recipient of the 

transmission. 

String [100] 

Minimum length = 0 

Maximum length = 100 

String UTF-8 

Required 

Agency System ID <SystemID> Identifies the system that is 

exchanging data with GInvoicing. 

String [100] 

Minimum length = 1 

Maximum length = 100 

String UTF-8 

Required 

Agency Tracking 

Identifier 

<RequestID> Unique identifier, optionally 

supplied in the request and 

echoed back in the 

response. 

String [50] 

Minimum length = 0 

Maximum length = 50 

String UTF-8 

Optional 

G-Invoicing 

Tracking Identifier 

<GINVTrackingID> Unique tracking identifier, 

generated by G-Invoicing. 

String [50] 

Minimum length = 1 

Maximum length = 50 

String UTF-8 

Required 

Environment <Environment> Describes the environment 

in which the system 

interface resides. 

String [30] 

Minimum length = 0 

Maximum length = 30 

String UTF-8 

Values: “Production”, “Quality 

Assurance”, “Functional Test”. 

Required 

Request Type <RequestType> Type of request that was 

submitted to G-Invoicing by 

the agency system. 

String [30] 

Minimum length = 0 

Maximum length = 30 

String UTF-8 

Values: “GTC List”, “Order List”, 

“Performance List”, “Single 

GTC”, “Single Order”, “Single 

Performance”, “Single 

Attachment”. 

Note: Values are derived from 

the service being accessed. 

Required 

Record Count <RecordCount> The total number of 

records in the payload. 

Integer 

Minimum length = 1 

Maximum length = 8 

Required 
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

18

NONCONFIDENTIAL // EXTERNAL

Table 4: Document List Data Elements

Familiar 

Name

XML Tag Definition Constraints Optionality

Requesting 

Agency 

Location 

Code(s) 

GT&C/Orders: 

<RequestingAgencyLoc 

ations/AgencyLocation

Code> 

Performance: 

<RequestingAgencyLoc 

ationCode>

Unique identifier(s) for 

a federal agency 

buying goods and/or 

services. 

GT&Cs: 1-to-many 

ALCs per side. 

Orders: Only one ALC 

for per side, each 

appearing in array. 

Performance: ALCs 

are not (yet) returned 

in arrays. 

String [0-9]{8} (i.e., Digits 0 to 9. 

Length must be eight digits.) 

String UTF-8. 

Min=1. no Max 

Required 

Servicing 

Agency 

Location 

Code(s) 

GT&C/Orders: 

<ServicingAgencyLocati 

ons/AgencyLocationCo

de> 

Performance: 

<ServicingAgencyLocati 

onCode>

String [0-9]{8} (i.e., Digits 0 to 9. 

Length must be eight digits.) 

String UTF-8. 

Min=1. no Max 

Required 

Document 

Type

<DocumentType> Describes the 

document type (e.g., 

GT&C, Order, 

Performance) that was 

requested. 

String [30] 

Minimum length = 0 

Maximum length = 30 

String UTF-8 

Values: “GTC”, “Performance” 

For Orders the DocumentType is 

being utilized to indicate an In-flight 

Order.

There are 5 different DocumentType 

values: 

APIOrder: In-flight Order = No 

UIOrder: In-flight Order = No 

UIOrderIFO: In-flight Order = Yes 

UIOrderUpload: In-flight Order = No 

UIOrderUploadIFO: In-flight Order = 

Yes 

Required 

Manual Entry 

Indicator 

<Manual EntryIndicator> Indicates whether the 

document was 

introduced by a user or 

a system. 

String 

Enumeration: “Y” (Yes), “N” (No) 

“N” indicates System generated 

“Y” indicates User generated 

Required 

Document ID <DocumentNumber> Unique identifier for a 

document. 

String [20] Minimum 

length = 0 

Maximum length = 20 

String UTF-8 [A-Z, 0-9, -] 

(i.e., upper case alpha characters, 

digits 0-9, and dashes.) 

Required 

Modification 

Number 

<ModificationNumber> Unique identifier 

assigned to a GT&C or 

Order document that 

has been modified form 

the original. 

Integer 

Maximum length = 10 

Conditional

Status <Status> The current status of 

the GT&C or Order 

document. 

See Federal Intragovernmental 

Data Standards (FIDS). 

Conditional
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

19

NONCONFIDENTIAL // EXTERNAL

Last Modified 

Date/Time

<LastModifiedDateTime

>

The date/time the 

document was last 

updated.

DateTime

Format: YYYY-MMDDThh:mm:ss.SSS+|-00:00

All time should be specified in local 

time zone with time zone offset from 

UTC in hours and minutes ahead (+) 

or behind (-) UTC.

Required

Document 

URL

<URL> The URL that will be 

used in a subsequent 

request by the agency 

system to retrieve the 

document.

String [4000] 

Minimum length = 0

Maximumlength = 4000 

String UTF-8

Required
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

20

NONCONFIDENTIAL // EXTERNAL

5 Error Specifications

Standard web service faults are generated for exceptions that can cause the request to not be 

processed. If the agency system cannot be authenticated or authorized, then a fault is returned. 

If the requested resource is unavailable then a fault will be thrown. All services may return the 

following HTTP status codes along with variable error message text describing the error(s) in 

the response.

Error ID HTTP Status Code Example

1 400 – Bad Request 

ValidationFailedException 

Note: Message text included 

in the <ErrorDesc> element 

will vary depending on the 

error condition.

<ns0:ErrorDetail> 

<ns0:ErrorDesc>ValidationFailedException message = Requesting agency Point Of Contact 

Full Name is required.</ns0:ErrorDesc> 

<ns0:ErrorTitle>400 ValidationFailedException</ns0:ErrorTitle> 

<ns0:RequestDateTime>2018-05-24T15:43:27.578-04:00</ns0:RequestDateTime> 

<ns0:RequestTypeIdentifier>Order Create</ns0:RequestTypeIdentifier> 

<ns0:Status>400</ns0:Status> 

</ns0:ErrorDetail> 

2 403 – Unauthorized 

AccessDeniedException 

Note: Message text included 

in the <ErrorDesc> element 

will vary depending on the 

error condition.

<ns0:ErrorDetail> 

<ns0:ErrorDesc>AccessDeniedException message = User is not authorized to the 

system.</ns0:ErrorDesc> 

<ns0:ErrorTitle>403 AccessDeniedException</ns0:ErrorTitle> 

<ns0:RequestDateTime>2018-05-23T08:33:04.426-04:00</ns0:RequestDateTime> 

<ns0:RequestTypeIdentifier>Order Create</ns0:RequestTypeIdentifier> 

<ns0:Status>403</ns0:Status> 

</ns0:ErrorDetail> 

</Ginv_Error> 

3 500 – Internal Server 

Error 

ServerException 

Note: Message text included 

in the <ErrorDesc> element 

will vary depending on the 

error condition.

<ns0:ErrorDetail> 

<ns0:ErrorDesc>ServerException message = Multiple users found.</ns0:ErrorDesc> 

<ns0:ErrorTitle>500 ServerException</ns0:ErrorTitle> 

<ns0:RequestDateTime>2018-05-23T08:29:07.566-04:00</ns0:RequestDateTime> 

<ns0:RequestTypeIdentifier>Order Create</ns0:RequestTypeIdentifier> 

<ns0:Status>500</ns0:Status> 

</ns0:ErrorDetail> 

6 Security

The TWAI will accept web service traffic, perform certificate-based authentication against 

security policies, and route the requests to G-Invoicing. Separate certificates are needed for test 

and production environments.

No Personal Identifying Information (PII) is being transported by this system interface. There is 

no risk that this interface or the included functions will allow additional access to G-Invoicing 

data.

The Department of Defense has rated information contained in G-Invoicing as Mission 

Assurance Category III. The MAC III rating is for systems handling information that is necessary 

to conduct day-to-day business, but does not materially affect support to deployed or 

contingency forces in the short-term. The consequences of loss of integrity or availability can be 

tolerated or overcome without significant impacts on mission effectiveness or operational 

readiness. The consequences could include the delay or degradation of services or 

commodities enabling routine activities. Mission Assurance Category III systems require 

protective measures, techniques or procedures generally commensurate with commercial best 

practices.
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

21

NONCONFIDENTIAL // EXTERNAL

7 Interface Integrity

7.1 TWAI

TWAI security infrastructure, policies and procedures guarantee that only authenticated and 

authorized entities are permitted access to the G-Invoicing application and its assets. Virus 

detection, intrusion detection, and network and infrastructure monitoring software and hardware 

are provided by and operated in the TWAI.

7.2 Communication Channel

Adhere to the Guidelines for protecting sensitive data during electronic dissemination across 

networks as stated in the NIST Special Publication (SP) 800-52 (rev 1), Selection, 

Configuration, and Use of Transport Layer Security (TLS) Implementations.

Meet security requirements for NIST Special Publication (SP) 800-53 (rev 4), Recommended 

Security Controls for Federal Information Systems, and other applicable guidance, such as 

Treasury Directive Publication (TDP) 85-01.
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

22

NONCONFIDENTIAL // EXTERNAL

8 Revision History

Vers. 

Num.

Date of 

Change

G-Inv 

Rel. Change/Revision Description Page/Section Affected

0.1 09/22/16 2.1 Initial Draft All

0.2 01/05/17 2.1 Updates after meeting with GEX group All

0.3 02/02/17 2.1 3.2 Protocol information added, updates to all sections. All

0.4 02/06/17 2.1 Updates after peer review. All

0.5 02/23/17 2.1 Added XML schema documentation. 4.6, 5, Appendix A

0.6 02/28/17 2.1 Added sample XML. Appendix A

0.7 03/03/17 2.1 Updates after internal review. All

0.8 03/07/17 2.1 Updates after peer review. All

0.9 03/10/17 2.1 Updates after final internal review. All

0.10 03/29/17 2.1 Updates after Fiscal Service review. 4.1.1, 5, 4.6.1, A

1.0 03/29/17 2.1 Baseline All

1.1 04/24/17 2.1 Data element edits from D.O.D. BIO. 4.6.1

Appendix A

1.2 04/26/17 2.1 Omit “Draft” and “Delete” statuses. 3.2.3.1

4.2

4.6.1

1.3 05/19/17 2.1 Drop enumeration from Status element, added 

Environment element values.

Updated data elements that were “Optional” with min 

required char of 1 to 0.

Error Detail in Error schema is 1:Many

4.6.1

4.6.1

Appendix A

1.4 05/26/17 2.1 Updated schema versions to 2.0 

Data element edits.

Added 400 HTTP error code.

Schema updates

1.3.3

4.6.1

5

Appendix A

1.5 06/05/17 2.1 Changed PartnerID and SystemID elements from Integer to 

String.

Error schema changed to Ginv_Error.

4.6.1

Appendix A

1.6 06/19/17 2.1 Removed Attachment List Summary 1.3.3, 3.2.3,

4.1.2, 4.6.1,

Appendix A

1.7 06/20/17 2.2 Added Order to specification. All

2.0 07/06/17 2.2 Prepped for Fiscal Service approval. All

2.0.1 07/13/17 2.2 Raised SystemID, PartnerID to 100 chars. 

Added 2nd approval for GT&C

3.2.3, 4.6.1

Appendix A 

2.0.2 08/08/17 2.2 Removed GT&C and Order data tables. 4.6.1, 4.6.2

2.0.3 09/07/17 2.2 Added HTTP Error Code Table 5

2.0.4 10/25/17 2.2 Added min and max length to Record Count data element. 

Added Attachment Summary table.

Table 3

4.6.1

2.0.5 11/08/17 2.2 GINV-1295, GINV-1326

Updated schema reference info. 

Enumerated StatusCode values,

Made approval fields optional, corrected document

inconsistencies.

Appendix A 

1.3.2

Appendix A 

Table 2, Table 3
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

23

NONCONFIDENTIAL // EXTERNAL

2.0.6 12/12/17 2.2 Updated schema and XML information. Appendix A

2.0.7 01/19/18 2.2 Updates based on data standards. All

2.0.8 02/01/18 2.2 Updated schema and XML information Appendix A

2.0.9 02/28/18 2.2 Removed /gtc from Attachment URL 3.2.3.3

2.0.10 03/14/18 2.2 Removed Attachment from examples provided for 

Document Type.

Added business rule for status “PRA”

Table 4

4.2.6

2.0.11 04/11/18 2.2 1) Added character entity reference codes business rule.

(2) Updated date/time format. (3) Updated FileSize to

reflect kB.

(1) 4.2.7

(2) All

(3) Table 2

2.0.12 04/30/18 2.2 Add ‘Single Attachment’ to Request Types Table 3

2.0.13 05/21/18 2.2 GINV-1787 move Org Ref data to Header level in XSD Appendix A

2.0.14 5/30/18 2.2 Updated HTTP error status codes 5

2.0.15 6/6/18 2.2 Updated Resource information 3.2.3

3.0 6/8/18 2.2 Baseline All

3.0.1 6/27/18 2.2 Updated Header Appendix A

3.1 7/31/18 2.3 Added Performance transaction All

3.2 8/6/18 2.3 Updated following internal review All

3.3 8/28/18 2.3 Following Treasury review: (1) updated Partner/System

note, (2) removed GTC and Order XML samples

3.2.3

Appendix A

4.0 9/4/18 2.3 Approved – see GINV-1933 N/A

4.0.1 10/12/18 2.3 Deleted attachments are excluded. Order access =

Performance access.

4.2.1-3

4.0.2 10/24/18 2.3 Perf IDs obtained via Single Order by ID resource ... (No 

longer true)

3.2.3, 4.2.3.2 Table

4

4.1 12/20/18 2.3 Numerous changes in reaction to Dec 4-6 Perf mtgs. Added

Performance List.

All

4.2 12/24/18 2.3 Updates after internal review 4.2.1, Table 4

4.3 1/9/19 2.3 Better aligned schemas to FIDS.

Updated Treasury system owner name. 

Extend Order services for Performance.

1.3.3, 3.2.3.3,

3.2.3.6-7

4.4 2/13/19 2.3 Allow agencies to pull Orders in draft status if Mod > 0 so

they know Orders are not open.

4.2.4 – 4.2.9

5.0 2/25/19 2.3 Baseline for Performance Txn All

5.0.1 3/19/19 n/a Removed extra requirement to disallow pull of GT&Cs in

pending status. This matches code.

4.2.7

5.0.2 3/22/19 n/a Corrected spec to match code ... Manual Entry Indicator ‘Y’ 

indicates manual entry.

Table 4

5.1 4/15/19 2.3 +1 

(TBD)

Added settlement parameters to Pull Performance List 3.2.3.6

5.2 4/16/19 2.3 +1 

(TBD)

Removed comments after internal review.

Added explanation of how Settlement is audited. 

Distributed for Settlement approval.

3.2.3.6

6.0 4/29/19 2.3 +1

(TBD)

Baselined for Settlement History

6.1 6/12/19 2.3 +1 

(TBD)

Changed ‘settlementStatus’ to ‘status’ for Performance 

List. Added note to 4.2.4

3.2.3.6

4.2.4
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

24

NONCONFIDENTIAL // EXTERNAL

6.1.1 8/29/19 N/A Clarified policy requiring at least one System ID per

Partner ID.

3.2.3

v6.1.2 3/20/20 N/A XML namespaces may vary w/ schema version 2.2.3a

v6.2 6/12/20 r4.0 Single GT&C resource supports v 1_0 and 2_0 3.2.3.2

v6.2.1 6/17/20 r4.0 GT&C List resource supports v 1_0 and 2_0 3.2.3.1, Table 4

v6.3 6/23/20 r4.0 1. As of r2.2, G-Invoicing does not send empty tags.

2. SystemID is now required.

Appendix A 

Every resource

v6.4 12/03/20 r4.0 Removed DAG reference as System Ids are now assigned 

to Org Groups 

P1A or PRA Orders will be returned in the Order list when 

Mod>=0

4.2.3

v7.0 5/21/20 r4.1 New version to support Seller Facilitated Orders. Three

statuses have changed.

3.2.3.4, 4.2.7

v7.0.1 5/29/20 r4.1 Order List resource must support v 2_0 3.2.3.4

v7.1 12/03/20 r4.1 Clarified Order List status parameters for v 1_0 & v 2_0 3.2.3.4

v7.1.1 1/12/2021 r4.0 Clarification on change introduced in r4.0: Document 

Summary List now includes ALCs in arrays for GT&Cs and 

Orders, but not (yet) for Performance.

Table 4

v7.1.2 2/23/2021 r4.0 Removed reference to TWAI architecture diagram, which 

is not publicly available

7.1

7.2 10/12/22 5.0 Added info on Order DocumentType for the Order List 

pull

Table 4

7.2.1 06/29/23 5.2 Added modNbr to Order detail pull parameter 3.2.3.5
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

25

NONCONFIDENTIAL // EXTERNAL

Appendix A: Messaging Protocol & Data Encapsulation

1 G-Invoicing Message Encapsulation

Transmissions into and out of G-Invoicing will utilize RESTful web-services over the 

internet with an XML payload. The HTTP Request and Response will have the structure 

depicted in diagrams in 1.1 and 1.2 below.

1.1 HTTP Request

The HTTP Request will have an empty Body when the Header contains a “GET” command. 

When the Request contains a “PUT” command the Body will contain an XML payload.

1.2 HTTP Response

Call Detail data will be returned in every response generated by G-Invoicing with the 

exception of the individual attachment download. Call Detail contains metadata about the 

Request/Response. The Call Detail data will be part of the HTTP Body and precede any 

data included in the response that satisfies the initial request.
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

26

NONCONFIDENTIAL // EXTERNAL

2 Call Detail

3 Document List

Call Detail Sample XML

<?xml version="1.0" encoding="UTF-8"?>

<!--Sample XML file generated by XMLSpy v2017 sp2 (x64) (http://www.altova.com)-->

<cmn:Call_Detail xmlns:cmn="urn:us:gov:treasury" 

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 

xsi:schemaLocation="urn:us:gov:treasury:ginv:gtc GTC.xsd">

<cmn:RecordCount>50</cmn:RecordCount>

<cmn:RequestID>277655239</cmn:RequestID>

<cmn:GINVTrackingID>3357822214</cmn:GINVTrackingID>

<cmn:PartnerID>1789</cmn:PartnerID>

<cmn:Environment>Production</cmn:Environment>

<cmn:RequestType>Single GTC</cmn:RequestType>

<cmn:SystemID>789</cmn:SystemID>

</cmn:Call_Detail>

Document List Sample XML

<?xml version="1.0" encoding="UTF-8"?>

<!--Sample XML file generated by XMLSpy v2017 sp2 (x64) (http://www.altova.com)-->

<cmn:DocumentList xmlns:cmn="urn:us:gov:treasury" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 

xsi:schemaLocation="urn:us:gov:treasury:ginv:documents Documents_Summary.xsd">

<cmn:Document>

<cmn:DocumentNumber>A1610-017-017-000170</cmn:DocumentNumber>

<cmn:Status>REC</cmn:Status>

<cmn:LastModifiedDateTime>2017-08-28T14:05:37.534-04:00</cmn:LastModifiedDateTime>

<cmn:URL>https://host-name:port/base-path/resource-path</cmn:URL>

<cmn:RequestingAgencyLocationCode>00005023</cmn:RequestingAgencyLocationCode>

<cmn:ServicingAgencyLocationCode>00005197</cmn:ServicingAgencyLocationCode>

<cmn:DocumentType>GTC</cmn:DocumentType>

<cmn:ModificationNumber/>

<cmn:ManualEntryIndicator>Y</cmn:ManualEntryIndicator>

</cmn:Document>

</cmn:DocumentList>
G-Invoicing System Interface Specifications – Pull GT&C, Order and Performance

Version 7.2.1 – June 2023

27

NONCONFIDENTIAL // EXTERNAL

4 Error

Error Sample XML

<?xml version="1.0" encoding="UTF-8"?>

<!--Sample XML file generated by XMLSpy v2017 sp2 (x64) (http://www.altova.com)-->

<cmn:ErrorDetail xmlns:cmn="urn:us:gov:treasury" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 

xsi:schemaLocation="urn:us:gov:treasury:ginv:error Error.xsd">

<cmn:ErrorDesc>Unknown GTC ID provided. Correct and resubmit.</cmn:ErrorDesc>

<cmn:ErrorTitle>400 Unknown GTC ID</cmn:ErrorTitle>

<cmn:RequestDateTime>2017-08-28T14:05:37.534-04:00</cmn:RequestDateTime>

<cmn:AgencyLocationCodes>00008501,00008502</cmn:AgencyLocationCodes>

<cmn:RequestTypeIdentifier/>

<cmn:Status>PND</cmn:Status>

</cmn:ErrorDetail>