Version 2.4 G-Invoicing – Pull Organization API 03/14/2024

1

NONCONFIDENTIAL // EXTERNAL

G-Invoicing – Pull Organization API

Description/

Purpose

This specification describes how to call the application programming interface 

(API) to extract Organizational (org) Groups and related data from G-Invoicing.

Org Groups are used to control access to documents, ALCs and TAS-BETCs

(through TAS Filters). Each Schedule on an Order or 7600EZ Invoice must be 

assigned two valid TAS-BETCs.

Status Codes

Common HTTP Status Codes:

• 200 – Okay 

• 400 – Bad request

• 403 – Forbidden

• 500 – Internal server error

Organization 

Summary

This service provides organizational data in JavaScript Object Notation (JSON) format to an 

external agency partner. Multiple resources are available to pull organizational groups and related 

information, each described below, and each result in its own format. Data involved in Resources 1 

and 2 are defined in the Organizational FIDS. TAS-BETC data involved in Resource 3 is defined in 

the Order FIDS. 

Note: Only an authorized Partner ID (and accompanying System ID) will elicit a response from GInvoicing. See the System Integration Guide or G-Invoicing Playbook for information on how to 

partner with G-Invoicing, or contact us at IGT@fiscal.treasury.gov

Entity Relationships

The diagram below depicts the relationships between organizational entities (e.g., Group, ALC, 

TAS Filter), G-Invoicing document types (e.g., GT&C, Order, 7600EZ Invoice) and reference data 

(TAS-BETC) obtained from Fiscal Service’s Shared Accounting Module (SAM).
Version 2.4 G-Invoicing – Pull Organization API 03/14/2024

2

NONCONFIDENTIAL // EXTERNAL

Each Order/7600EZ Invoice must reference a GT&C, two ALCs (requesting and servicing) and two 

TAS-BETCs (requesting and servicing) for each Schedule in the Order or 7600EZ Invoice. The Pull 

Org resources described below provide all the valid choices for Group, ALC and TAS-BETC under 

a GT&C. 

Resources

1. Get Groups for a GT&C

This endpoint allows systems to extract all the organizational Groups that can be associated with an 

Order/7600EZ Invoice under the requested GT&C. Aside from the eligible Groups, the returned 

data set also includes eligible ALC(s) and TAS Filter(s), both on the requesting and servicing sides 

of the requested GT&C. The resulting JSON is in a flattened format, suitable for populating a dropdown list of Groups that may be chosen for assignment to an Order or 7600EZ Invoice under the 

requested GT&C.

Note: Order Manager or 7600EZ Manager role is not required to call this resource but is required 

to create an Order.

HTTP method: GET

Path: /ginv/services/v1_0/groups/forGtc/{gtcNbr}/

Request:

Parameters

Name: systemId

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

In: header

Type: string [100]

Required: true

Name: gtcNbr

Description: Limits the results to the requested General Terms and 

Conditions agreement and any related Groups that will support an 

Order/7600EZ Invoice under that GT&C

In: path

Type: string [20]

Required: true

Name: buySellIndicator (R=requesting, S=servicing)

Description: Limits the results to requesting or servicing Groups based on the 

System ID's access via the Requesting or Servicing Order Manager or 

7600EZ Invoice roles

In: query

Type: string [1]

Required: false
Version 2.4 G-Invoicing – Pull Organization API 03/14/2024

3

NONCONFIDENTIAL // EXTERNAL

Example

GET /ginv/services/v1_0/groups/forGtc/A2006-123-234-000345

Business Rules:

There are rules governing the relationships between a GT&C and its Orders or 7600EZ 

Invoices, and data referenced from those Orders or 7600EZ Invoices. These rules are applied to 

the JSON data set included with the API response:

1. Requesting and Servicing Groups are managed separately, following the same rules.

2. A valid org Group must be selected for each partner (buyer and seller) on the Order or 

7600EZ Invoice.

3. Only active org Groups may be assigned to the Order or 7600EZ Invoice, thus are included 

in the response.

4. At a minimum, the Group associated with the GT&C may always be used for the Order or 

7600EZ Invoice.

5. Only org Groups containing at least one of the ALCs assigned to the GT&C are included in 

the response.

6. When the Document Inheritance Indicator is ‘N’ (no), descendants of the org Group 

associated with the GT&C may not be used for the Order or 7600EZ Invoice (unless they 

qualify as a Subordinate Group. (See next rule).

7. Additional “subordinate” Groups may be assigned to a GT&C, and Orders or 7600EZ 

Invoices may be created in these “subordinate” Groups.

8. The optional buySellIndicator parameter may be used to limit the groups returned to those 

that the client System ID could use to create an Order or 7600EZ Invoice. If the client’s 

System ID is assigned to the uppermost group in the organization (for the Order 

Manager/7600EZ Manager role) then this parameter need not be specified.

a. If not specified, all eligible groups are returned for both sides of the Order or 

7600EZ Invoice. 

b. If specified as ‘R’, G-Invoicing will limit the returned groups on the requesting side 

of the Order/7600EZ Invoice based on the System IDs group assignments for the 

Requesting Order/7600EZ Manager roles.

c. If specified as ‘S’, G-Invoicing will limit the returned groups on the servicing side of 

the Order based on the System IDs group assignments for the Servicing 

Order/7600EZ Manager roles.
Version 2.4 G-Invoicing – Pull Organization API 03/14/2024

4

NONCONFIDENTIAL // EXTERNAL

2. Get Groups in an Agency Account

This endpoint allows systems to extract detail data describing all organizational Groups within the 

Agency Account for the requested System ID. The resulting JSON is in a hierarchical format, 

suitable for simulating the organizational tree in G-Invoicing.

HTTP method: GET

Path: /ginv/services/v1_0/groups/

Request:

Parameters

Name: systemId

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

provides necessary linkage to the requested Agency Account

In: header

Type: string [100]

Required: true

Name: accountId

Description: Identifies the Agency Account which data will be provided

In: query

Type: string [100]

Required: false

Name: showInactive

Description: Expands the returned data set to include inactive Groups; 

Otherwise only active Groups are returned

In: query

Type: string [1]

Required: false

Example

GET /ginv/services/v1_0/groups/?accountId=508749&showInactive=N

Business Rules:

1. This service will return all Groups within the Agency Account in which the System ID 

resides, which may span multiple organizational hierarchies within that agency account.

a. This is true when the accountId is not passed.

2. The parent-child relationships between org Groups can be used to recreate the hierarchy for 

an agency account in G-Invoicing, but cannot by itself be used to predict which Groups can 

view and manage Orders, Performance, or 7600EZs under that GT&C agreement. The Get 

Groups for a GT&C resource (above) should be used for that purpose.
Version 2.4 G-Invoicing – Pull Organization API 03/14/2024

5

NONCONFIDENTIAL // EXTERNAL

3. Get TAS-BETCs for a Group

This endpoint allows systems to extract detail data describing all valid combinations of TAS and 

BETC for an Order created within a specific org Group. The resulting JSON is in a flattened format, 

suitable for populating a drop-down list of TAS-BETC choices.

HTTP method: GET

Path: /ginv/services/v1_0/groups/{groupId}/tasBetcs

Request:

Parameters

Name: systemId

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

In: header

Type: string [100]

Required: true

Name: groupId

Description: Limits the results to the requested org Group 

In: path

Type: string [36]

Required: true

Name: buySellIndicator (R=requesting, S=servicing)

Description: Limits the results to requesting or servicing TAS-BETCs 

In: query

Type: string [1]

Required: true

Example

GET /ginv/services/v1_0/groups/c266353b-c46f-4606-9438-

3bf1b6a1ff1d/tasBetcs?buySellIndicator=R

Business Rules:

1. This service will return all requesting or servicing TAS-BETC combinations that are valid 

for the specified org Group. 

2. There are two sides to every Order (requesting and servicing). In some cases (e.g., seller 

facilitated Order) one partner can supply TAS-BETCs for both sides. In these situations, 

this resource can be called twice, once for buySellIndicator ‘R’ (requesting) and again for 

buySellIndicator ‘S’ (servicing.

a. When buySellIndicator = ‘R’, G-Invoicing will provide valid debit BETCs from 

the Shared Accounting Module (i.e., isCredit = ‘0’).

b. When buySellIndicator = ‘S’, G-Invoicing will provide valid credit BETCs from 

the Shared Accounting Module (i.e., isCredit = ‘1’).
Version 2.4 G-Invoicing – Pull Organization API 03/14/2024

6

NONCONFIDENTIAL // EXTERNAL

4. Get Agency Accounts

This endpoint allows systems to extract a list of active Agency Accounts from G-Invoicing. The 

resulting JSON will be a list of all Agency Accounts within the environment unless the system 

passes the optional lastModifiedDateTime parameter to reduce the changes to a specified date/time. 

This endpoint will relate G-Invoicing’s Account IDs to their Agency Names. 

HTTP method: GET

Path: /ginv/services/v1_0/groups/accounts

Request:

Parameter

Name: lastModifiedDateTime

Description: Limits results to Agency Accounts that have been updated since the 

passed date/time. 

In: query

Type: dateTime

Format: YYYY-MM-DDThh:mm:ss.SSSZ or YYYY-MMDDThh:mm:ss.SSS+|-00:00

• Can be formatted in Zulu (UTC) or with a time zone offset. All 

responses in JSON will be returned in Zulu (UTC).

Required: false

Example

GET /ginv/services/v1_0/groups/accounts?lastModifiedDateTime=2023-07-

20T16:32:44.591Z

Business Rule:

1. The lastModifiedDateTime is incremented when the Agency Account updates their 

Organizational Group structure within G-Invoicing. This will be updated when an Account 

Admin either updates an existing group, adds a new group, or deletes an existing group. 

Updates to a group may include any or all the following actions: Adding/removing ALC(s), 

TAS filters, updating the Group Name or Description, or changing the status of the group.

2. Only active Agency Accounts are returned in the response.
Version 2.4 G-Invoicing – Pull Organization API 03/14/2024

7

NONCONFIDENTIAL // EXTERNAL

5. Get ALCs assigned to Agency Accounts

This endpoint allows systems to extract a list of Agency Location Codes (ALCs) that are assigned 

to Agency Accounts from G-Invoicing. The resulting JSON will be a list of all (A=Active or IInactive) ALCs within the environment unless the system passes the optional accountId query 

parameter to reduce the ALCs returned to that specific Agency Account. 

HTTP method: GET

Path: /ginv/services/v1_0/groups/alc

Request:

Parameter

Name: accountId

Description: Limits results to an Agency Account 

In: query

Type: string [38]

Required: false

Example

GET /ginv/services/v1_0/groups/alc?accountId=263195

Business Rule:

1. Only ALCs assigned to an Agency Account will be returned.

2. Active and Inactive ALCs will be returned if they’re assigned to an Agency Account.

a. Inactive ALCs may not be used to generate new documents.

3. ALC Name, Agency Name, and Agency Id are not managed in G-Invoicing, but flow from 

the Treasury system CARS/SAM. If the ALC Name needs to be updated it may be 

requested to be updated in that system and that data will flow into G-Invoicing.

4. Account Id is system generated within G-Invoicing and has no logic associated to it. It is 

stored as an integer, if passing the optional query string parameter with leading zeros they 

will be ignored.

5. Account Name is the agency specified Agency Name in G-Invoicing. 
Version 2.4 G-Invoicing – Pull Organization API 03/14/2024

8

NONCONFIDENTIAL // EXTERNAL

Responses

Bad Request

Content Type: application/json

Status Code: 400

Description: Request could not be processed, returned with a message text 

containing the problem encountered (in the response).

Schema: errors

Example

{

"callDetail": {

"environment": "TEST",

"recordCount": "1"

},

"errors": [

{

"code": "400",

"message": "Group not found"

}

]

}

Note: The recordCount represents a count of all objects in the body of the response, 

whether the body contains errors (see above), Groups or TAS-BETCs (see below). 

Forbidden (aka, unauthorized request)

Content Type: application/json

Status Code: 403

Description: System ID included in the request was not found or not authorized

Schema: errors

Internal Server Error

Content Type: application/json

Status Code: 500

Description: An unexpected error was encountered.

Schema: errors

Okay (aka, success)

Content Type: application/json

Status Code: 200

Description: Organizational request was successfully processed with a response 

containing the organizational Groups matching the criteria.

Schema: Organization
Version 2.4 G-Invoicing – Pull Organization API 03/14/2024

9

NONCONFIDENTIAL // EXTERNAL

Example of a Successful Resource: 1 (Get Groups for GT&C) Response

{

 "callDetail": {

 "environment": "DEVF",

 "recordCount": "3"

 },

 "requestingGroups": [

 {

 "id": "b94bf5b5-40be-4f84-9dcf-0df76cca56cb",

 "name": "Test Group 1",

 "description": "Test Parent Description",

 "createDate": "2020-02-07T18:57:31.393Z",

 "lastUpdateDateTime": "2020-02-07T18:57:31.393Z",

 "status": "A",

 "alcCodes": [

 "00002050"

 ],

 "tasFilters": [

 {

 "aid": "000",

 "ata": "000",

 "sub": "000",

 "main": "000 "

 }

 ]

 },

 {

 "id": "34e4a8e1-5998-481b-8596-b0200797b57b",

 "name": "TestGroup 2",

 "description": "Test Description",

 "createDate": "2020-01-13T16:07:56.244Z",

 "lastUpdateDateTime": "2020-02-07T18:56:00.576Z",

 "status": "A",

 "alcCodes": [

 "00002050",

 "00002049"

 ],

 "tasFilters": [

 {

 "aid": "000"

 }

 ]

 }

 ],

 "servicingGroups": [

 {

 "id": "34e4a8e1-5998-481b-8596-b0200797b57b",

 "name": "TestGroup 2",

 "description": "Test Description",

 "createDate": "2020-01-13T16:07:56.244Z",

 "lastUpdateDateTime": "2020-02-07T18:56:00.576Z",

 "status": "A",
Version 2.4 G-Invoicing – Pull Organization API 03/14/2024

10

NONCONFIDENTIAL // EXTERNAL

 "alcCodes": [

 "00002050",

 "00002049"

 ],

 "tasFilters": [

 {

 "aid": "000"

 }

 ]

 }

 ]

}

Example of a Successful Resource: 2 (Get Groups in Agency Account) Response

{

 "callDetail": {

 "environment": "TEST",

 "recordCount": "3"

 },

"groups": [

{

"id": "34e4a8e1-5998-481b-8596-b0200797b57b",

"name": "TestGroup",

"description": "Test Description",

"children": [

{

"id": "1ab8c6ba-bbb7-4ccc-bebd-74fc2efce001",

"name": "TestChildGroup",

"description": "Test Child Description",

"status": "A",

"createDate": "2020-02-07T18:56:42.892Z",

"parentId": "34e4a8e1-5998-481b-8596-b0200797b57b",

"alcCodes": [

"00002049"

],

"tasFilters": [

{

"aid": "014",

"ata": "020",

"sub": "001",

"main": "1199"

}

]

},

{

"id": "e6a9e3b3-ba67-44f9-b4f8-fe2ac170a8b6",

"name": "TestChild2Group",

"description": "Test Child2 Description",

"status": "I",

"createDate": "2020-02-07T18:58:06.375Z",

"deactiveDate": "2020-02-08T13:28:16.273Z",

"lastUpdateDateTime": "2020-02-08T13:28:16.273Z",

"parentId": "34e4a8e1-5998-481b-8596-b0200797b57b",
Version 2.4 G-Invoicing – Pull Organization API 03/14/2024

11

NONCONFIDENTIAL // EXTERNAL

"alcCodes": [

"00002050"

],

"tasFilters": [

{

"aid": "014"

},

{

"aid": "020",

"ata": "014"

}

]

}

],

"status": "A",

"createDate": "2020-02-07T18:56:42.892Z",

"lastUpdateDateTime": "2020-02-08T13:28:16.273Z",

"alcCodes": [

"00002050",

"00002049"

]

}

]

}

Example of a Successful Resource: 3 (Get TAS-BETCs for a Group) Response

{

 "callDetail": {

 "environment": "TEST",

 "recordCount": "3"

 },

 "tasBetcs": [

 {

 "subLevelPrefixCd": "06",

 "agencyId": "000",

 "allocTransferAgcyId": "015",

 "availabilityTypeCd": "A",

 "beginningPeriodAvail": "2011",

 "endingPeriodAvail": "2015",

 "mainAcctCd": "0110",

 "subAccountCd": "000",

 "busEventTypeCd": "DISB"

 },

 {

 "subLevelPrefixCd": "06",

 "agencyId": "000",

 "allocTransferAgcyId": "015",

 "availabilityTypeCd": "A",

 "beginningPeriodAvail": "2011",

 "endingPeriodAvail": "2015",

 "mainAcctCd": "0110",

 "subAccountCd": "000",
Version 2.4 G-Invoicing – Pull Organization API 03/14/2024

12

NONCONFIDENTIAL // EXTERNAL

 "busEventTypeCd": "DISNGF"

 },

 {

 "subLevelPrefixCd": "06",

 "agencyId": "000",

 "allocTransferAgcyId": "015",

 "availabilityTypeCd": "A",

 "beginningPeriodAvail": "2011",

 "endingPeriodAvail": "2015",

 "mainAcctCd": "0110",

 "subAccountCd": "000",

 "busEventTypeCd": "DISGF"

 }

 ]

}

Example of a Successful Resource 4: (Get Agency Accounts) Response

{

 "callDetail": {

 "environment": "Test",

 "recordCount": "4"

 },

 "accounts": [

 {

 "accountId": 508749,

 "accountName": "Account 1",

 "lastModifiedDateTime": "2022-06-05 16:49:50.756"

 },

 {

 "accountId": 424941,

 "accountName": " Account 2",

 "lastModifiedDateTime": "2021-05-30 15:36:55.093"

 },

 {

 "accountId": 121617114,

 "accountName": " Account 3",

 "lastModifiedDateTime": "2023-06-01 07:44:00.206"

 },

 {

 "accountId": 498192,

 "accountName": " Account 4",

 "lastModifiedDateTime": "2019-06-07 14:38:28.955"

 }

 ]

}
Version 2.4 G-Invoicing – Pull Organization API 03/14/2024

13

NONCONFIDENTIAL // EXTERNAL

Example of a Successful Resource 5: (Get ALCs Assigned to Agency Accounts) 

Response

{

 "callDetail": {

 "environment": "Test",

 "recordCount": "2"

 },

 "alcs": [

 {

 "alcCode": "20180304",

 "alcName": "Department of the Treasury - BUREAU OF THE FISCAL SVC",

 "agencyId": "020",

 "agencyName": "Department of the Treasury",

 "accountId": 263195,

 "accountName": "Department of the Treasury – Fiscal Services,

 "status": "A"

 },

 {

 "alcCode": "20740001",

 "alcName": "DEPT OF THE TREASURY - OFFICE OF THRIFT SUPERVISION",

 "agencyId": "020",

 "agencyName": "Department of the Treasury",

 "accountId": 264553195,

 "accountName": "Department of the Treasury",

 "status": "I"

 }

 ]

}
Version 2.4 G-Invoicing – Pull Organization API 03/14/2024

14

NONCONFIDENTIAL // EXTERNAL

Appendix A: Revision History

Doc.

Vers.

API 

Vers.

Date of 

Change

G-Inv 

Rel. Change/Revision Description Page/Section Affected

0.1 2/14/20 Initial draft for internal review. All

0.2 2/20/20 Updated schemas to handle timestamps in compliant way Example and 

Appendix B

0.3 2/21/20 Updated after internal review, prior to distributing to Treasury pp. 2-4

1.0 1_0 2/28/20 Published version after review with ERP Vendors No change

1.1 4/9/20 4.0 1. API will not be available until release 4.0 (not 3.3)

2. Dropped accountId and accountName because they add no value

JSON schema 

and sample

1.2 6/5/20 4.0 1. Renamed from Organizational Groups to Organizational Data 

2. Get Groups for Order parameter Group replaced by GT&C Nbr

3. New resource to pull eligible TAS-BETCs

Resource 1

Resource 3

1.3 6/11/20 4.0 Made adjustments following internal review. Resource 1

Resource 3

1.4 6/22/20 4.0 Folded in JSON schemas and samples Resource 1-3

1.5 6/22/20 4.0 Differentiated path names for resources 1 and 3. Draft version for 

first distribution to vendors and agencies.

Resource 1, 3

2.0 6/25/20 4.0 Prepped version 2.0 for publishing. No material change.

2.0.1 8/31/20 4.0 Clarified that Order Manager role is required to create Orders. Resource 1

2.1 11/9/20 4.1 1. Added rules 5-7 to Resource 1.

2. Corrected hyperlink to Org FIDS.

Resource 1

Summary

2.2 12/16/20 4.1 Added optional buySellIndicator parameter to Resource 1 Resource 1

2.3 06/08/23 5.2 Added 7600EZ Invoice to indicate that the Resources may be used 

for that document as well. Added a new Resource 4 that is used to 

pull Agency Accounts. Update Resource 2, which now allows an 

optional accountId parameter. Included JSON sample for Resource 4

All – f7600EZ

Resource 2

Resource 4

JSON Sample

2.4 1_0 3/14/2024 7.0 Added new endpoint to allow systems to pull ALCs assigned to 

Agency Accounts

Removed Appendix A for JSON schema examples. Please see 

OpenAPI specs on the G-Invoicing resource page for the schema 

examples.

Resource 5

End of Specification