TREASURY SBU/CUI // EXTERNAL

Do Not Pay Portal API Agency 

Implementation Guide

June 2024
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

2

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

Version History

Version Date Author(s) Description of Version / Change

2.0 9-17-2018 Jason Noah, Gary Timmons, Steve 

Burbank

First Published Version

2.1 2-21-2019 Jason Noah, Gary Timmons, Steve 

Burbank

Minor wording changes

2.2 4-30-2019 Andy Walter Added valid API criteria combinations

2.3 6-3-2019 Andy Walter Added definitions for Source Content Description 

and Search Criteria

2.4 6-6-2019 Andy Walter Added new fields for TOP Debt Check and latest 

death data sources

2.5 7-2-2019 Jason Noah Updated examples and wording for Outcome 

processing

2.6 8-18-2019 Andy Walter Added First Name and Last Name to SAM 

Entity Registration data source. Added Business 

Name to TOP Debt Check data source.

2.7 10-9-2019 Steve Burbank Updated Certificate Generation Instructions

2.8 10-9-2019 Jason Noah Updated multi-data source instructions

2.8 12-10-2019 Jason Noah Fixed typo relating to maximum page size (no 

minor version rolled)

2.9 7-10-2020 Jason Noah Updated search restriction section to highlight 

allowed characters

3.0 1-20-2021 Steve Burbank Updated JSON API Overview section to include 

multiple calls per search

3.1 3-1-2021 Jason Noah Added notes re: server-time zone and name search 

formatting

3.2 5-27-2021 Steve Burbank Added IRS data source Automatic Revocation of 

Exemption List, notes regarding calling multiple 

child response object fields, and a section on DNP 

API service availability

3.3 9-10-2021 Steve Burbank Updated SAM Exclusions data source to include 

UEI, added section on multiple searches per API 

call. Corresponds to DNP Portal R7.4.

3.4 9-20-2021 Bum Yong Kim Reformatted document to fit standardization of 

other DNP guides.
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

3

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

Version Date Author(s) Description of Version / Change

3.5 12-7-2021 Steve Burbank Updated SAM Entity Registration Records data 

source to include UEI. Corresponds to DNP 

Portal R7.5.

3.6 4/20/2022 Steve Burbank Updated Guide to remove DUNS and DUNS Plus 

4 references due to GSA transition to UEI. 

Corresponds to DNP Portal R7.7.

3.7 6/17/2022 Steve Burbank Added IRS Publication 78 data source to coincide 

with Portal R7.10.

3.8 12/10/2022 Steve Burbank Updated OFAC country code response field to 

coincide with updates made with R7.11.

3.9 6/24/2023 Steve Burbank Added IRS Form 990-N data source to coincide 

with Portal R8.4.0.

4.0 8/18/2023 Jason Noah, Steve Burbank Updated guide to reflect change from GET to 

POST method. Corresponds with Portal R8.5.1

4.1 11/23/2023 Steve Burbank, Amina KopicOsmanovicUpdated guide to reflect DMF-Full 

implementation and Appendix B

4.2 6/3/2024 Steve Burbank, Amina KopicOsmanovicUpdated guide to correct death data source date 

formats (DOB, DOD, as-of date). Updated 

possible values for DMF Full list status code and 

list status code descriptions. Updated logo. 

Cleaning up format.
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

4

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

Table of Contents

DOCUMENT PURPOSE ..........................................................................................................................................9

WEB SERVICE OVERVIEW...................................................................................................................................9

Service Availability.......................................................................................................................................9

QAF Environment Availability.....................................................................................................................9

SECURITY CONSIDERATIONS.............................................................................................................................9

Access Groups and Data Sources..................................................................................................................9

Server Certificates.........................................................................................................................................9

REST OVERVIEW..................................................................................................................................................10

JSON API OVERVIEW ..........................................................................................................................................10

SERVICE VERSIONING STRATEGY..................................................................................................................13

PAGINATION.........................................................................................................................................................14

Search Methodology ...................................................................................................................................15

SEARCH FIELD RESTRICTIONS ........................................................................................................................16

INCLUDED/EXCLUDED RESOURCES...............................................................................................................17

SEARCHING MULTIPLE RESOURCES AT ONCE............................................................................................18

SEARCH CRITERIA ..............................................................................................................................................20

SEARCHING MULTIPLE ENTITIES WITH A SINGLE API CALL ..................................................................20

SERVICE CATALOG.............................................................................................................................................20

Ping.......................................................................................................................20

Usage...........................................................................................................................................................21

SEARCH AND RESPONSE INFORMATION BY AVAILABLE DATA SOURCE ...........................................21

AMERICAN INFOSOURCE DEATH DATA – OBITUARY (AIS-OBIT) ..........................................................22

AIS OBIT Search Fields – Definitions.......................................................................................................22

AIS OBIT Search Fields – Technical Information .....................................................................................22

AIS OBIT Response Fields – Definitions...................................................................................................23

AIS OBIT Response Fields – Technical Information .................................................................................23

AIS OBIT Usage.........................................................................................................................................24

AMERICAN INFOSOURCE DEATH DATA – PROBATE (AIS-PROB)............................................................25

AIS PROB Search Fields – Definitions......................................................................................................25

AIS PROB Search Fields – Technical Information ....................................................................................25

AIS PROB Response Fields – Definitions..................................................................................................26

AIS PROB Response Fields – Technical Information................................................................................26

AIS PROB Usage........................................................................................................................................27

AUTOMATIC REVOCATION OF EXEMPTION LIST (ARL)............................................................................28

ARL Search Fields – Definitions................................................................................................................28
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

5

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

ARL Search Fields – Technical Information ..............................................................................................28

ARL Response Fields – Definitions............................................................................................................29

ARL Response Fields – Technical Information..........................................................................................29

ARL Usage..................................................................................................................................................31

CREDIT ALERT SYSTEM (CAIVRS) ..................................................................................................................32

CAIVRS Search Fields – Definitions .........................................................................................................32

CAIVRS Search Fields – Technical Information........................................................................................32

CAIVRS Response Fields – Definitions.....................................................................................................33

CAIVRS Response Fields – Technical Information ...................................................................................33

CAIVRS Usage ...........................................................................................................................................35

DEATH MASTER FILE-FULL (DMF-FULL).......................................................................................................36

DMF-Full Search Fields – Definitions........................................................................................................36

DMF-Full Search Fields – Technical Information......................................................................................36

DMF-Full Response Fields – Definitions...................................................................................................37

DMF-Full Response Fields – Technical Information .................................................................................37

DMF-Full Usage .........................................................................................................................................38

DEPARTMENT OF DEFENSE DEATH DATA (DOD) .......................................................................................39

DOD Search Fields – Definitions ...............................................................................................................39

DOD Search Fields – Technical Information..............................................................................................39

DOD Response Fields – Definitions...........................................................................................................40

DOD Response Fields – Technical Information .........................................................................................40

DOD Usage.................................................................................................................................................41

DEPARTMENT OF STATE DEATH DATA (DOS).............................................................................................42

DOS Search Fields – Definitions................................................................................................................42

DOS Search Fields – Technical Information ..............................................................................................42

DOS Response Fields – Definitions............................................................................................................43

DOS Response Fields – Technical Information..........................................................................................43

DOS Usage..................................................................................................................................................44

FORM 990-N (e-Postcard).......................................................................................................................................45

Form 990-N Search Fields – Definitions....................................................................................................45

Form 990-N Search Fields – Technical Information ..................................................................................45

Form 990-N Response Fields – Definitions................................................................................................46

Form 990-N Response Fields – Technical Information..............................................................................47

Form 990-N Usage......................................................................................................................................48

LIST OF EXCLUDED INDIVIDUALS & ENTITIES (LEIE) – PUBLIC AND RESTRICTED..........................50

LEIE Search Fields - Definitions................................................................................................................50
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

6

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

LEIE Search Fields – Technical Information..............................................................................................50

LEIE Response Fields – Definitions...........................................................................................................51

LEIE Response Fields – Technical Information .........................................................................................52

LEIE Usage.................................................................................................................................................53

OFFICE OF FOREIGN ASSETS CONTROL (OFAC)..........................................................................................54

OFAC Search Fields - Definitions..............................................................................................................54

OFAC Search Fields – Technical Information............................................................................................54

OFAC Response Fields...............................................................................................................................55

OFAC Main Object Response Fields - Definitions.....................................................................................55

OFAC Main Object Response Fields – Technical Information ..................................................................56

OFAC Main Object Response Fields – Usage............................................................................................56

OFAC Address Child Object Response Fields – Definitions .....................................................................57

OFAC Address Child Object Response Fields – Technical Information....................................................57

OFAC Address Child Object Response Fields – Usage .............................................................................58

OFAC Alternate ID Child Object Response Fields – Definitions ..............................................................59

OFAC Alternate ID Child Object Response Fields – Technical Information.............................................59

OFAC Alternate ID Child Object Response Fields – Usage ......................................................................60

OFAC Date of Birth Child Object Response Fields – Definitions .............................................................61

OFAC Date of Birth Child Object Response Fields – Technical Information............................................61

OFAC Date of Birth Child Object Response Fields – Usage .....................................................................61

OFAC Place of Birth Child Object Response Fields – Definitions ............................................................62

OFAC Place of Birth Child Object Response Fields – Technical Information...........................................62

OFAC Place of Birth Child Object Response Fields – Usage ....................................................................62

OFAC Citizenship Child Object Response Fields – Definitions................................................................63

OFAC Citizenship Child Object Response Fields – Technical Information...............................................63

OFAC Citizenship Child Object Response Fields – Usage ........................................................................63

OFAC Nationality Child Object Response Fields – Definitions.................................................................64

OFAC Nationality Child Object Response Fields – Technical Information...............................................64

OFAC Nationality Child Object Response Fields – Usage.........................................................................64

OFAC Program Child Object Response Fields – Definitions.....................................................................65

OFAC Program Child Object Response Fields – Technical Information...................................................65

OFAC Program Child Object Response Fields – Usage.............................................................................65

PUBLICATION 78 DATA (PUB 78)......................................................................................................................66

PUB 78 Search Fields - Definitions............................................................................................................66

PUB 78 Search Fields – Technical Information .........................................................................................66

PUB 78 Main Object Response Fields - Definitions ..................................................................................67
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

7

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

PUB 78 Main Object Response Fields – Technical Information................................................................67

PUB 78 Response Fields – Usage...............................................................................................................68

SYSTEM FOR AWARD MANAGEMENT (SAM) ENTITY REGISTRATION RECORDS ..............................69

SAM Entity Registration Search Fields – Definitions................................................................................69

SAM Entity Registration Search Fields – Technical Information ..............................................................69

SAM Entity Registration Response Fields..................................................................................................70

SAM Entity Registration Main Object Response Fields – Definitions.......................................................70

SAM Entity Registration Main Object Response Fields – Technical Information.....................................72

SAM Entity Main Object Response Fields – Usage ...................................................................................75

SAM Entity Registration Organization Code Child Object Response Fields – Definitions.......................76

SAM Entity Registration Organization Code Child Object Response Fields – Technical Information .....76

SAM Entity Registration Organization Code Child Object Response Fields – Usage ...............................76

SAM Entity Registration Business Code Child Object Response Fields – Definitions..............................78

SAM Entity Registration Business Code Child Object Response Fields – Technical Information............78

SAM Entity Registration Business Code Child Object Response Fields – Usage......................................78

SAM Entity Registration Disaster Response Child Object Response Fields – Definitions........................80

SAM Entity Registration Disaster Response Child Object Response Fields – Technical Information ......80

SAM Entity Registration Disaster Response Child Object Response Fields – Usage................................80

SAM Entity Registration NAICS Child Object Response Fields – Definitions.........................................82

SAM Entity Registration NAICS Child Object Response Fields – Technical Information .......................82

SAM Entity Registration NAICS Child Object Response Fields – Usage .................................................83

SAM Entity Registration Product Service Code Child Object Response Fields – Definitions...................85

SAM Entity Registration Product Service Code Child Object Response Fields – Technical Info .............85

SAM Entity Registration Product Service Code Child Object Response Fields – Usage...........................86

SAM Entity Registration Federal Supply Classification Child Object Response Fields – Definitions......88

SAM Entity Registration Federal Supply Classification Child Object Response Fields – Tech Info ........88

SAM Entity Registration Federal Supply Classification Child Object Response Fields – Usage ..............89

SAM Entity Registration SBA Code Child Object Response Fields – Definitions....................................91

SAM Entity Registration SBA Code Child Object Response Fields – Technical Information ..................91

SAM Entity Registration SBA Code Child Object Response Fields – Usage ............................................92

SAM Entity Registration Address Information Child Object Response Fields – Definitions....................94

SAM Entity Registration Address Information Child Object Response Fields – Technical Info...............94

SAM Entity Registration Address Information Child Object Response Fields – Usage ............................95

SYSTEM FOR AWARD MANAGEMENT (SAM) EXCLUSION RECORDS – PUB AND RES .........97

SAM Exclusion Search Fields – Definitions ..............................................................................................97

SAM Exclusion Search Fields – Technical Information.............................................................................97
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

8

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SAM Exclusion Response Fields – Definitions..........................................................................................98

SAM Exclusion Response Fields – Technical Information ........................................................................99

SAM Exclusion Records Usage................................................................................................................100

TREASURY OFFSET PROGRAM (TOP) DEBT CHECK .................................................................................101

TOP Debt Check Search Fields – Definitions...........................................................................................101

TOP Debt Check Search Fields – Technical Information.........................................................................101

TOP Debt Check Response Fields – Definitions......................................................................................102

TOP Debt Check Response Fields – Technical Information ....................................................................103

TOP Debt Check Usage ............................................................................................................................105

Match Outcome Transmittal .....................................................................................................................107

Match Outcome Transmittal Fields – Definitions.....................................................................................107

Match Outcome Transmittal Fields – Technical Information...................................................................108

Match Outcome Transmittal Fields – Usage.............................................................................................110

APPENDIX A........................................................................................................................................................111

JSON API examples..................................................................................................................................111

Sparse Fieldsets.........................................................................................................................................111

Pagination .................................................................................................................................................113

Error Objects.............................................................................................................................................114

APPENDIX B ........................................................................................................................................................115

Certificate Request and Generation Instructions.......................................................................................115

APPENDIX C ........................................................................................................................................................116

List of Acronyms ......................................................................................................................................116
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

9

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

DOCUMENT PURPOSE

The Do Not Pay (DNP) Portal Application Program Interface (API) Implementation Guide is intended to 

offer agencies and programs a comprehensive set of technical specifications and requirements for initiating 

search requests for matches against approved data sources. This guide should give business owners the 

ability to talk through decisions with the technical team, and it should give the technical team the necessary 

information to develop the requests and work with appropriate responses. However, the guide is not 

expected to eliminate the need for technical and business conversations with the DNP API implementation 

team.

WEB SERVICE OVERVIEW

For the purpose of this document, a Web Service is defined as any machine-to-machine interaction that 

takes place over a network, typically using the Hypertext Transfer Protocol (HTTP) used on the web. It is 

commonly referred to as an API, and two types include Simple Object Access Protocol (SOAP) and 

REpresentational State Transfer (REST). REST is the type of API offered by DNP.

Service Availability

The DNP API is designed to be available on a 24 x 7 basis. If the API receives a call when the service is 

unavailable, you will receive the following message with http status code 503:

QAF Environment Availability

Quality Assurance testing will be completed against the DNP QA Future environment. Please note that this 

environment is turned down daily (including weekends) from 9PM – 5AM Central Time.

SECURITY CONSIDERATIONS

Access Groups and Data Sources

Access to the DNP Web Service and associated data sources is administered through Agency Access 

Groups and Treasury issued security certificates. Only those data sources approved for use by these Access 

Groups will be available to a given Access Group.

Server Certificates

Agencies are required to use supported X.509 certificates to interface with DNP’s Web Service. A 

certificate is presented to the DNP Web Service whenever connections to the service are initiated. This 

document provides instructions on how to download and export backup certificates generated by the U.S. 

Treasury’s Operational Certificate Authority (TOCA) to your local PC. It does not provide instructions on 

{"errors": [{

 "detail": "The system is currently unavailable",

 "title": "Service Unavailable",

 "status": "503"

}]}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

10

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

how to install SSL certificates on your agency’s servers. Instructions regarding certificate retrieval can be 

found in Appendix B of this document.

REST OVERVIEW

REST is an acronym that stands for REpresentational State Transfer. It defines the interface and 

conventions used between a web service provider and service consumers/clients. It uses the already 

familiar URL, HTTP Header, and Method standards to convey meaning to web service calls. The 

established HTTP verbs: GET, POST, UPDATE, and DELETE are used to represent action on a service, 

and the URL contents are used to represent data structures. For example, using a web GET request on the 

following service URL: http://fakeservice/V1/user would result in data returned to the client for every user 

in the system, whereas the URL: http://fakeservice/V1/user/12345 would only return data related to the 

user with ID 12345. If a client made a POST submission to the URL: http://fakeservice/V1/user the 

service would be expecting the client to provide content within the message body relating to the creation of 

a new user object. In addition, a service can use the HTTP accept/content-type header to specify the type 

of content it is configured to receive and produce. 

Note: The DNP API will only be using the GET and POST verbs, and will produce content of type: 

application/vnd.api+json which is specific to the JSON API standard. 

Any POST calls done by a client should also be done with the application/vnd.api+json content type. This is a general 

description of REST, please note that in the DNP API searches that would normally be done with GET calls are done via 

POST and a jsonapi formatted message body.

JSON API OVERVIEW

JavaScript Object Notation Application Program Interface (JSON API) is a specification for web 

service APIs that is built upon the REST standard and JSON data format. This is a strict set of shared 

conventions which give service clients a large amount of flexibility in the requests they make and 

responses they receive. Full details can be found at: http://jsonapi.org.

The specification defines several aspects of web service communication:

• Content type – JSON API uses the content type: application/vnd.api+json.

• Format of message content – JSON API defines the top-level elements: data, errors, and meta

contained in request/response data. If the errors element is present the data and meta elements 

cannot be present, and vice versa. The DNP API will always return a meta element in every (nonerror) request as it contains information like transaction ID.

• Including Child Object Response Fields – some data sources include certain match detail fields 

(response fields) that are contained within relational objects. Those data sources that contain 

relational data will call out those child object response fields in their usage sections. To call more 

than one set of child object response fields, the request message should include the attribute 

“include”:”childResponseObject1,childResponseObject2,etc”

• Uniform Resource Identifier (URI) – the URI is constructed by an agency to reference specific 

request data via the API. Each data source has unique data elements and response fields. These 
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

11

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

particular response fields have a URI that must be included in the request message.

• Data Return Sizes – the server can define maximum amounts of data to be returned in each 

request. If the total data payload exceeds this size the server will provide pagination links and meta

information to retrieve the rest of the data. The DNP API specifies a count of 250 as the maximum 

result size returned for any particular search, and this is enforced at the resource level. A single 

search involving three different resources could theoretically return 750 rows maximum, or 250 

rows per resource.

• Sparse Fieldsets – a client can specify which fields they wish to retrieve on a given resource. 

o For example, making a POST request to the URL: http://fakeservice/V1/user with 

attributes “fields[user]”:”firstName,lastName” would retrieve details for all users but 

only the firstName and lastName fields of each user would be returned. This allows 

individual clients to retrieve only the data pertinent to them, and can potentially reduce 

bandwidth/resource usage.

• Sorting – a client can specify the order in which data will be sorted when it is retrieved.

o For example, making a POST request to the URL: http://fakeservice/V1/user with attributes

“sort[user]”:”lastName” would return all user records to the client sorted ascending by the 

last name. Sending the POST request with this URL: http://fakeservice/V1/user with 

attributes “sort[user]”:”-lastName” would return all user records to the client sorted 

descending by the last name.

• Filtering – a client can specify which fields should be used to filter the data to be retrieved. 

o For example, making a POST request to the URL: http://fakeservice/V1/user with attributes

“filter[user.lastName]”:”Smith” would retrieve all user records with the last name of 

‘Smith.’

• Pagination – a client can specify which pagination settings they prefer to be applied to their data.

o For example, making a POST request to the URL: http://fakeservice/V1/user with attributes

“page[size]”:”10”,”page[number]”:”1” would return all user records to the client, but 

would only return 10 records at a time and would contain records 1-10 as the user requested 

the first page number. The content of the response would also contain metadata to retrieve 

the remaining data. 

o The client must specify both the page size and page number parameters when making the 

request. If the client specifies a value above 250 (the DNP API maximum retrieval size per 

resource), then the value will be adjusted to 250 and the pagination fields will reflect this.

• Combination – all of these attributes can be combined into a single request. 

o This URL: http://fakeservice/V1/user with attributes

“fields[user]”:”firstName,lastName”,”sort[user]”:”firstName”,”filter[user.lastName]”:”

Smith”,”page[size]”:”10”,”page[number]”:”1” would return only the firstName and 

lastName fields of any users with the last name of ‘Smith’, the results would be sorted by 

first name, only up to 10 results would be retrieved at a time, and the first page of data 

would be returned in the response.
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

12

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

JSON API also defines strict rules for the formatting of any message body returned from a request. 

The jsonapi.org page is a good reference for these rules, but the DNP API has some specifics to 

consider:

• Whenever pagination is used, there are additional variables provided in the meta section of the 

message. See the pagination section below for more details.

• Every request the DNP API responds to will contain a ‘transaction-id’ in the meta element of the 

message body. This will be a unique value for each search and should be used in subsequent 

requests tied to the original search. 

o For example, Outcome data based on a prior search should always be sent with the 

transaction-id of the original search, and this data should be provided in the meta section 

of the response.

• If a client needs the DNP API to echo their own unique transaction id the attribute ‘clienttransaction-id’ should be sent. If a client sends a request with a client-transaction-id field, it will be 

sent back in the message reply in the meta section of the message body.

• When a POST request is received from a client (a request to create a resource) it is NOT expected 

that a client will provide an ID for the JSON API message content. Additionally, a JSON API 

message may not be returned, depending on the nature of the request. 

o For example, a status code of 201 or 202 returned from a POST request indicates that the 

server successfully received and processed the request but the resulting content is not 

available to the client. In these situations a response message will still be provided, but 

will largely be empty, other than a ‘transaction-id’ and ‘client-transaction-id’ (if one was 

provided).

• The fields ‘remote-user’ and ‘remote-user-location’ can be provided to the DNP API for each client 

request. These correspond to the unique id of the user in the origin system as well as that user’s 

location. If provided these will be logged in association with each transaction.

• When errors are returned from the API both the http status code and the status code returned in the 

“errors” portion of the response message will either be a 400 or 500. An error code of 400 typically 

means that something was invalid in the request (bad parameters, etc.) and an error code of 500 

typically means that something is failing within the API (internal connectivity, etc.).

• When API responses are returned to the client, there is a field in the meta section of the response 

called ‘server-timezone’ that contains the timezone in which the API/data store are running. 

Possible values include EST (eastern timezone) and UTC (coordinated universal time).
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

13

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SERVICE VERSIONING STRATEGY

The DNP API contains a version number (e.g., V1) at the base of its URL endpoints. This is provided to 

ensure that if future changes are introduced which would cause a conflict for existing clients, older API 

versions can be maintained for compatibility. The DNP API uses what is known as an additive versioning 

strategy. This means that the only conditions under which a new API version will be created are:

• An existing resource type is removed or renamed. In the previous examples, renaming the ‘user’ 

resource to ‘system_user’ or removing it altogether would result in a new service version. The 

older version would continue to support the original ‘user’ resource.

• An existing resource has one of its fields removed or renamed. In the previous examples, renaming 

the ‘lastName’ field to ‘last_name’ or removing it altogether would result in a new service version. 

The older version would keep the original ‘lastName’ field.

• The URL structure changes. In the previous examples, changing the URL from: 

http://fakeservice/V1/user to http://fakeservice/V1/system_user would result in a new service 

version (and change the V1 to V2). The older version would continue using the /user endpoint.

• Changes to required HTTP headers. If an existing web endpoint has a new required header added 

(e.g., content-type, accepts) or changed, a new service version would be created. The older version 

would continue to support the original headers.

Equally important, changes which will NOT result in a new service version are:

• A new resource type is added. In the case of the DNP API, if a new data source was added to the 

API and a client was granted access, that client’s queries could now potentially contain a new 

resource type. This will not result in a new service version, and it would be expected that the client 

not fail because of this new resource.

• A new field is added to an existing resource. In the previous examples if the field ‘middleName’ 

was added to the ‘user’ resource a new service version would not be created. It would be expected 

that the client not fail because of this new field.

• New additions are made to the URL/endpoints of the existing service. In the previous examples, if 

the API was changed to now support the URL: http://fakeservice/V1/organization in addition to the 

existing URL: http://fakeservice/V1/user, a new service version would not be created. It would be 

expected that the client not fail because of this new URL.

• Changes to URLs not related to application functionality. For example, if an infrastructure change 

required that the URL: http://fakeservice/V1/ be changed to: http://differentfakeservice/V1/, this 

would not necessarily result in a new service version. It is presumed that in this type of situation a 

temporary redirect or joint deployment may be used.

In general, anything that is added to the DNP API will likely not result in a new service version, whereas 

changes to existing resources and functionality would likely necessitate a new version.

New versions would increment the base version in the service endpoints (e.g., V1 would change to V2).
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

14

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

PAGINATION

When data source searches are performed against the DNP API, there are default pagination limits applied 

of 250 records per data source. Therefore, if a client performs a single search against 2 data sources, the 

maximum rows which could be returned are 500, or 250 rows for each data source. As previously 

mentioned, a client can specify its own pagination values for page size/number in the request, but this value 

will be changed to 250 if a greater value is requested. If the results of a search are paginated, the following 

fields will be added to the response.

Note: total-count will always be returned in the meta section, regardless of pagination.

• JSON API allows for an optional top-level element called ‘links’ to be present in a response. 

However, all DNP API searches are done via POST requests so these will not be present in the 

response. Instead, the pagination fields below can be used for this purpose.

• The top-level meta element will contain the following elements, used to aid in client processing:

o page-size – this contains the number of records returned for each page

o current-page – this contains the current page of data

o total-count – this contains the total number of records for all pages of data

o total-pages – this contains the total number of pages, based on the page-size and total-count 

elements

See the example below. The sample data used to produce this contains 1005 total records, and 

this is the first response containing the data from page 1, and the page size is specified as 25. 

Note that the same five links are always provided even though the previous/first/self links contain 

the same values.

{

 "data": [ data would go here...

 ],

 "meta": {

 "page-size": “25”,

 "current-page": “1”,

 "total-count": “1005”,

 "total-pages": “41”

 }

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

15

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

Search Methodology

Within the API searches are done via a POST method that contains the following jsonapi-compliant 

message:

Where the queryParameter/queryValue entries represent query parameters that would normally be 

presented in the URL. For example, a GET URL that looks like this:

http://server/services/V1/datasource?filter[businessName]=ShoeMart

Would be represented by a POST request with a body that looks like this:

Literally any query parameter normally sent in a normal query string would be included in the attributes

json element, without the ? and & separators.

{

"data":[

 {

 "type":"datasourceSearch",

 "attributes":

 {

 “filter[businessName]”:”ShoeMart”

 }

 }

 ]

}

{

"data":[

 {

 "type":"datasourceSearch",

 "attributes":

 {

 “queryParameter1”:”queryValue1”,

 “queryParameter2”:”queryValue2”,

 “queryParameter3”:”queryValue3”

 }

 }

 ]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

16

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SEARCH FIELD RESTRICTIONS

Only certain fields can be used to search data sources through the DNP API. The specifics of which fields 

can be used on which data sources are defined in the next section of this document.

If a multi-data source search is executed and the correct fields are not provided for a particular data source, 

it will be dropped from the request. Certain fields, like firstName and lastName, are allowed to be used in 

data source searches but must be provided together. Certain fields must be provided if a corresponding 

field is provided, like UEI if EFT Indicator is provided. A client can choose to search a single data source 

(e.g., /datasource/dmf), a subset of allowed data sources (e.g., /datasource/dmf,ofac), or all allowed data 

sources (e.g., /datasource) in a single search. Examples are given for each data source below.

In addition, there is validation/rejection that can occur based on characters used in a search. The only 

characters allowed in URL search fields are:

• Lower case letters a-z

• Upper case letters A-Z

• Numbers 0-9

• Whitespace

• Additional allowed characters:

o ‘

o (

o )

o [

o ]

o .

o :

o &

o ,

o _

o -

o @

o $

o !

o ?

o /

NOTE: Commas should only be used in search fields to separate individual entities you wish to query. For example, 

you should not use commas before suffixes as in the example below: 

“filter[aisObituary.firstName]”:”John, Jr”,”filter[aisObituary.lastName]”:”Doe”

The system will interpret this as a search for aisObituary matches against both John and Jr. 
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

17

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

INCLUDED/EXCLUDED RESOURCES

When data source searches are performed against the DNP API, there is a possibility that not all data 

sources can be searched with the criteria provided. For example, if an agency has access to both the DMF 

and OFAC data sources and performs a single search against these data sources using an SSN/EIN/TIN, 

then only DMF can be searched since OFAC does not have SSN/EIN/TIN. There are two JSON data 

arrays returned in the “meta” section of the response called “includedResources” and “excludedResources.” 

In the above example, includedResources would contain a single entry for DMF and excludedResources 

would contain a single entry for OFAC. See the example below for reference.

{

 "data": [...data would be included here...],

 "meta": {

 "transaction-id": “12345”,

 "total-count": “0”,

 "excludedResources": ["ofac"],

 "includedResources": ["dmf"]

 }

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

18

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SEARCHING MULTIPLE RESOURCES AT ONCE

It is possible to search more than one data source in a single request. Consider the following examples of 

request URLs and how they apply search criteria. Assume that the client making the request has access to 

the DMF, OFAC, and CAIVRS data sources (see data source definitions in the document below).

The example below will search all of the client’s data sources using a TIN of 123456789. OFAC cannot be 

searched by TIN and will therefore be skipped, but DMF and CAIVRS will be searched.

URL: http://server/services/V1/datasource

The example below will search all of the client’s data sources using a First Name field of John and a Last 

Name field of Doe. CAIVRS cannot be searched by First/Last Name and will be skipped, but DMF and 

OFAC will be searched.

URL: http://server/services/V1/datasource

POST Body:

{

"data":[

 {

 "type":"datasourceSearch",

 "attributes":

 {

 “filter[tin]”:”123456789”

 }

 }

 ]

}

POST Body:

{

"data":[

 {

 "type":"datasourceSearch",

 "attributes":

 {

 “filter[firstName]”:”John”,

 “filter[firstName]”:”Doe” 

 }

 }

 ]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

19

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

In the example below all 3 data sources will be searched. The CAIVRS and DMF searches will use the 

TIN parameter and the OFAC search will use First/Last Name. Note that DMF can be searched by either 

TIN or First/Last Name, but TIN will give a more conclusive match so it is used

URL: http://server/services/V1/datasource

The example below will search only the DMF and CAIVRS data sources using a TIN of 123456789. 

Subsets of data sources can be used in this way

URL: http://server/services/V1/datasource/dmf,caivrs

POST Body:

{

"data":[

 {

 "type":"datasourceSearch",

 "attributes":

 {

 “filter[firstName]”:”John”,

 “filter[firstName]”:”Doe”,

 “filter[tin]”:”123456789”

 }

 }

 ]

}

POST Body:

{

"data":[

 {

 "type":"datasourceSearch",

 "attributes":

 {

 “filter[firstName]”:”John”,

 “filter[firstName]”:”Doe”,

 “filter[tin]”:”123456789”

 }

 }

 ]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

20

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

In summary, if no data sources are included in the request URL then all of the available data sources will 

be searched, if the proper search fields are provided. A client can also include 1 or many data sources in 

the URL path to limit the scope of the search.

SEARCH CRITERIA

When data source searches are performed an additional field will be returned in the response called 

“searchCriteria” which identifies exactly which search field was used to match the record. The possible 

values for this field are: SSN/EIN/TIN, NAME, UEI, EFT INDICATOR, BUSINESS NAME.

Note also that when searches are done on fields like First Name/Last Name/Business Name no preformatting should be applied to the name values. For example, if a client is searching for a Business Name 

match on “Bank of Washington,” this value should be passed to the API “as is” rather than applying 

formatting like “BANKOFWASHINGTON,” “BANKWASHINGTON,” or “WASHINGTONBANKOF.” 

Applying formatting before the search lowers the odds of a positive match.

SEARCHING MULTIPLE ENTITIES WITH A SINGLE API CALL

It is possible to search for multiple entities using a single API call. Appropriate DNP legal review must be 

completed in order to allow your access group to search multiple entities with a single call. This access 

will be defined at the access group and data source level. Guidelines and examples regarding multipleentity API calls are provided below:

• Separate searched entities using commas. Multiple entities must include an equal number of 

searched parameters (e.g., five first names must be accompanied by five last names).

o Sample Request: “filter[firstName]”:”Barton,Adam”,”filter[lastName]”:”Halifax,Boyer”

• Searched entities cannot include commas in their names when including suffixes, titles, etc. The 

API will interpret these as distinct entities which will likely result in a failed call.

o Example: “filter[firstName]”:”Barton,Adam”,”filter[lastName]”:”Halifax,Jr,Boyer,EsqWeb”

SERVICE CATALOG

Ping

The ping service is designed for a client to call as a health check of the DNP API. There are no required 

arguments, and the response will be a JSON API message with an empty “data” element and a meta value 

called “ping-response.” A value of “false” in this field indicates that the API is not in a valid state to 

process requests, and a value of “true” indicates normal availability. There is also a “release” field which 

indicates the release version of the API being accessed. This is a value managed and communicated by the 

DNP technical team.
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

21

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

Usage

URI /ping

Access Requirements none

Sample Response {

 "data": [],

 "meta": {

 "ping-response": “true”

 “release”: “5.6”

 }

}

SEARCH AND RESPONSE INFORMATION BY AVAILABLE DATA SOURCE

While all data sources offered by DNP are covered in this document, not all data sources are used by most 

agencies or programs.

Please refer to the sections referencing the data sources approved for your agency/program API 

implementation.

All data source queries will return the searchCriteria used in the search. This will display as a string value 

(e.g., TIN) in the response.

Note: You may see “Private,” or “PRIV” in some data values in the tables below. This is the same as “Restricted” data 

sources.
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

22

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

AMERICAN INFOSOURCE DEATH DATA – OBITUARY (AIS-OBIT)

☐ Your agency is approved to access this data source.

American InfoSource Death Data - Obituary (AIS-OBIT) contains death information sourced using 

obituary records obtained from funeral homes and newspapers.

AIS OBIT Search Fields – Definitions

Data Element Definition

TIN The Social Security Number of the deceased individual.

First Name First name of the deceased individual.

Last Name Last name of the deceased individual.

AIS OBIT Search Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

TIN tin Character 9 Yes

First Name firstName Character 50 Yes

Both first name 

and last name 

must be sent in 

the request.

Last Name lastName Character 50 Yes

Both first name 

and last name 

must be sent in 

the request.
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

23

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

AIS OBIT Response Fields – Definitions

Data Element Definition

TIN The Social Security Number of the deceased individual.

Name Name of deceased individual.

Death Date Date of death as provided by AIS (YYYY-MM-DD).

Birth Date Date of birth provided by AIS (YYYY-MM-DD).

Address Line 1 Street Address Line one of the deceased individual's last residence address.

Address Line 2 Street Address Line two of the deceased individual's last residence address.

City City of the deceased individual's last residence address.

State State of the deceased individual's last residence address.

Postal Code Postal Code of the deceased individual's last residence address.

As-of Date The date that the data source resource was last updated.

AIS OBIT Response Fields – Technical Information

Data 

Element API Field Name

Data 

Type Length Value / Format Nullable Notes

TIN tin Character 9 No

Name name Character 200 Yes

Death Date deathDate Character 10 Format:

YYYY-MM-DD Yes

Birth Date birthDate Character 10 Format:

YYYY-MM-DD Yes

Address Line 

1

addressLine1 Character 150 No

Address Line 

2

addressLine2 Character 150 No

City city Character 50 No

State stateCode Character 2 No

ZIP postalCode Character 10 No

Source Sys 

Type Code 

Description

srcSysTypeCdDesc Character 20 AIS-OBIT No

As-of Date asOfDate Date 10 MM/DD/YYYY No
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

24

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

AIS OBIT Usage

URI /datasource (multi-resource search)

/datasource/aisObituary

Access 

Requirements Client’s Access Group must have access to aisObituary datasource

Sample Response {

"data": [

{

 "attributes": {

 "srcSysTypeCdDesc": "AIS-OBIT",

 "city": "STATEN ISLAND",

 "searchCriteria": "SSN/EIN/TIN",

 "postalCode": "51035",

 "name": "DIRINA HAWA WAYE",

 "tin": "078238529",

 "deathDate": "2005-03-30",

 "addressLine1": "5654 HARDESTY STREET",

 "stateCode": "IN",

 "asOfDate": "05/11/2021",

 "birthDate": "1900-10-20"

 },

 "id": "2879225329",

 "type": "aisObituary" }]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

25

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

AMERICAN INFOSOURCE DEATH DATA – PROBATE (AIS-PROB)

☐ Your agency is approved to access this data source.

American InfoSource Death Data - Probate (AIS-PROB) contains death information sourced using U.S. 

probate court records.

AIS PROB Search Fields – Definitions

Data Element Definition

TIN The Social Security Number of the deceased individual.

First Name First name of the deceased individual.

Last Name Last name of the deceased individual.

AIS PROB Search Fields – Technical Information

Data

Element API Field Name DataType Length Value / Format Nullable Notes

TIN tin Character 9 Yes

First Name firstName Character 50 Yes

Both first name 

and last name 

must be sent in 

the request.

Last Name lastName Character 50 Yes

Both first name 

and last name 

must be sent in 

the request.
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

26

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

AIS PROB Response Fields – Definitions

Data Element Definition

TIN The Social Security Number of the deceased individual.

Name Name of deceased individual.

Death Date Date of death as provided by AIS (YYYY-MM-DD).

Birth Date Date of birth provided by AIS (YYYY-MM-DD).

Address Line 1 Street Address Line one of the deceased individual's last residence address.

Address Line 2 Street Address Line two of the deceased individual's last residence address.

City City of the deceased individual's last residence address.

State State of the deceased individual's last residence address.

ZIP ZIP of the deceased individual's last residence address.

As-of Date The date that the data source resource was last updated.

AIS PROB Response Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

TIN tin Character 9 No

Name name Character 200 Yes

Death Date deathDate Character 10 Format:

YYYY-MM-DD Yes

Birth Date birthDate Character 10 Format:

YYYY-MM-DD Yes

Address Line 

1

addressLine1 Character 150 No

Address Line 

2

addressLine2 Character 150 No

City city Character 50 No

State stateCode Character 2 No

ZIP postalCode Character 10 No

Source Sys 

Type Code 

Description

srcSysTypeCdDesc Character 20 AIS-PROB No

As-of Date asOfDate Date 10 MM/DD/YYYY No
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

27

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

AIS PROB Usage

URI /datasource (multi-resource search)

/datasource/aisProbate

Access Requirements Client’s Access Group must have access to aisProbate datasource

Sample Response

 {

"data": [

{

"attributes": {

 "srcSysTypeCdDesc": "AIS-PROB",

 "city": "KERRVILLE",

 "searchCriteria": "SSN/EIN/TIN",

 "postalCode": "18513",

 "name": "ADAM BOYER",

 "tin": "896903212",

 "addressLine1": "95 FOUNTAIN ST",

 "stateCode": "CO",

 "asOfDate": "05/11/2021"

 },

 "id": "2879283070",

 "type": "aisProbate" }

]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

28

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

AUTOMATIC REVOCATION OF EXEMPTION LIST (ARL)

☐ Your agency is approved to access this data source.

The Internal Revenue Service (IRS) Automatic Revocation of Exemption List data source (ARL) provides 

information regarding tax-exempt status revocation when an organization does not file required Form 990-

series returns or notices annually for three consecutive years.

ARL Search Fields – Definitions

Data Element Definition

TIN

The EIN, or Employer Identification Number, is also known as a federal Tax 

Identification Number (TIN) and is used to identify a business or nonprofit entity. An 

EIN is a unique 9-digit number, similar to a Social Security Number for an individual.

Business Name The primary name by which the organization is listed in IRS records.

ARL Search Fields – Technical Information

Data Element API Field Name Data 

Type Length Value / Format Nullable Notes

TIN tin Character 9 No

Business Name businessName Character 200 No
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

29

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

ARL Response Fields – Definitions

Data Element Definition

TIN

The EIN, or Employer Identification Number, is also known as a federal Tax 

Identification Number (TIN) and is used to identify a business or nonprofit entity. An 

EIN is a unique 9-digit number, similar to a Social Security Number for an individual.

Name The primary name by which the organization is listed in IRS records.

Business Name The primary name by which the organization is listed in IRS records.

Also Known As Any other name the organization uses.

Address Line 1 The organization’s last known STREET address.

City Name The city in which the organization’s last known mailing address is located.

State Code The state in which the organization’s last known mailing address is located.

Postal Code The zip code in which the organization's last known mailing address is located.

Country Code The country in which the organization’s last known mailing address is located.

Exemption Type The code associated with the section of the Internal Revenue Code that describes the 

type of organization.

Exemption Type 

Description The section of the Internal Revenue Code that describes the type of organization.

Revocation Date The effective date that the organization’s federal tax exemption was automatically 

revoked for not filing a Form 990-series return or notice for three consecutive years.

Revocation Date Text

Text format of the effective date that the organization’s federal tax exemption was 

automatically revoked for not filing a Form 990-series return or notice for three 

consecutive years.

Revocation Posting Date The date on which the IRS posted notice of the organization’s automatic revocation on 

IRS.gov.

Revocation Posting Date 

Text

Text format of the date on which the IRS posted notice of the organization’s automatic 

revocation on IRS.gov.

Exemption 

Reinstatement Date

The organization’s effective date of tax exemption, determined by the IRS after the 

organization’s exemption was automatically revoked and the organization applied for 

reinstatement of exemption.

Exemption 

Reinstatement Date Text

The organization’s effective date of tax exemption, determined by the IRS after the 

organization’s exemption was automatically revoked and the organization applied for 

reinstatement of exemption.

As-of Date The date that the data source resource was last updated.

ARL Response Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

TIN tin Character 9 No

Name name Character 200 No

Business 

Name businessName Character 200 No

Also Known As alsoKnownAs Character 256 Yes

Address Line 1 addressLine1 Character 150 No

City Name cityName Character 50 No

State Code stateCode Character 2 No

Postal Code postalCode Character 15 No
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

30

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

Country Code countryCode Character 3 No

Exemption 

Type searchExemptionType Character 256 No

Exemption 

Type 

Description

searchExemptionTypeDesc Character 256 Yes

Revocation 

Date searchRevocationDt Date 10 YYYY-MM-DD No

Revocation 

Date Text searchRevocationDateTxt Character 11 DD-MMM-YYYY No

Revocation 

Posting Date searchRevocationPostingDt Date 10 YYYY-MM-DD No

Revocation 

Posting Date 

Text

searchRevocationPostingDateTxt Character 11 DD-MMM-YYYY No

Exemption 

Reinstatement 

Date

searchExemptionReinstatementDt Date 10 YYYY-MM-DD Yes

Exemption 

Reinstatement 

Date Text

searchExemptionReinstatementDateTxt Character 11 DD-MMM-YYYY Yes

Source Sys 

Type Code 

Description

srcSysTypeCdDesc Character 20 ARL No

As-of Date asOfDate Date 10 MM/DD/YYYY No
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

31

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

ARL Usage

URI /datasource (multi-resource search)

/datasource/arl

Access Requirements Client’s Access Group must have access to arl datasource

Sample Response

{

"data": [

{

 "attributes": {

 "srcSysTypeCdDesc": "ARL",

 "city": "TOWNSVILLE",

 "postalCode": "12345",

 "businessName": "ACME",

 "tin": "123456789",

 "revocationDate": "01/01/2000",

 "addressLine1": "LINE 1",

 "addressLine2": "LINE 2",

 "stateCode": "MO",

 "reinstatementDate": "01/01/1900"

 },

 "id": "987654321",

 "type": "arl"

 }]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

32

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

CREDIT ALERT SYSTEM (CAIVRS)

☐ Your agency is approved to access this data source.

Credit Alert System data source (CAIVRS) is a database created by the federal government to track people 

who have defaulted on any federal debts or obligations, have had claims paid on direct or guaranteed 

federal loans, have a federal lien, judgment or a federal loan that is currently in default or foreclosure, or 

have had a claim paid by a reporting agency.

DNP receives delinquency data from only the following federal agencies:

• Department of Housing and Urban Development (HUD),

• Department of Veterans Affairs (VA),

• Department of Agriculture (USDA),

• Small Business Administration (SBA),

• Department of Justice (DOJ).

o The DOJ sends three additional data fields that are not present in the other sources.

CAIVRS Search Fields – Definitions

Data Element Definition

TIN

The Social Security Number (SSN), Employer Identification Number (EIN) or Taxpayer 

Identification Number (TIN) of the borrower on a delinquent or defaulted federal 

direct loan or federally-guaranteed loan.

CAIVRS Search Fields – Technical Information

Data Element API Field 

Name Data Type Length Value / Format Nullable Notes 

TIN tin Character 9 No
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

33

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

CAIVRS Response Fields – Definitions

Data Element Definition

TIN

The Social Security Number (SSN), Employer Identification Number (EIN) or Taxpayer 

Identification Number (TIN) of the borrower on a delinquent or defaulted federal direct 

loan or federally-guaranteed loan.

Tax ID Type Short description of the Borrower's Tax ID type used in the CAIVRS record (SSN, EIN, 

TIN).

Agency A text description of the reporting agency. For example, FHA Title 1; Department 

of Veterans Affairs.

Case Type A text description of the Case Type Code. For example, Lien; Default.

Case Number A reference number issued by the reporting agency for the delinquent or defaulted 

federal direct loan or federally-guaranteed loan.

Collection Code A reference number for distinguishing collection district (example: TXW).

Collection Description Collection district description. For example, TXW=Western District of Texas.

Phone Number Phone number of the distinguishing collection district.

Source Content 

Description An abbreviated description of the data source.

As-of Date The date that the data source resource was last updated.

CAIVRS Response Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

TIN tin Character 9 No

Tax ID Type taxIdType Character 4

Values:

SSN, EIN, TIN Yes

Agency agencyName Character 256

Values:

-FHA Title 1

-Department of

Veterans Affairs

-USDA-Rural Housing

-Small Business

Administration

-Department of

Justice – Combined

-HUD Generic Debt

-USDA Rural

Development Debt

Yes

Case Type caseType Character 256

Values:

-Claim

-Default

-Foreclosure

-Lien Judgement

Yes
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

34

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

Case Number caseNumber Character 9 Yes

Collection

Code collectionCode Character 5

Example Values:

-TXW

-NCW

Yes Dept. of Justice 

(DOJ) only

Collection 

Description collectionDescription Character 100

Example Values:

-Western District of

Texas

-Western District of

North Carolina

Yes Dept. of Justice 

(DOJ) only

Phone 

Number phoneNumber Character 20 Example Value: 9135551212 Yes Dept. of Justice (DOJ) only

Source Sys 

Type Code 

Description

srcSysTypeCdDesc Character 20 CAIVRS No

As-of Date asOfDate Date 10 MM/DD/YYYY No
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

35

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

CAIVRS Usage

URI /datasource (multi-resource search)

/datasource/caivrs

Access 

Requirements Client’s Access Group must have access to caivrs datasource

Sample Response

{

 "data": [

{

 "attributes": {

 "caseNumber": "987654321",

 "tin": "123456789",

 "taxIdType": "TIN",

 "agencyName": "ABC",

 "collectionCode": "Sample Code",

 "collectionDescription": "Test Description",

 "phoneNumber": "555-555-5555",

 "caseType": "DEFAULT",

 "srcSysTypeCdDesc": "CAIVRS"

 },

 "id": "822223256",

 "type": "caivrs"

 }]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

36

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

DEATH MASTER FILE-FULL (DMF-FULL)

☐ Your agency is approved to access this data source.

The Death Master File-Full (DMF-Full) is a data source containing records of deaths reported to the Social 

Security Administration (SSA). The deaths reported to SSA come from many sources, including family 

members, funeral homes, financial institutions, postal authorities, state information, and other federal 

agencies. Does contain vital death records from states.

DMF-Full Search Fields – Definitions

Data Element Definition

TIN The Social Security Number of the deceased individual.

First Name First name of the deceased individual.

Last Name Last name of the deceased individual.

DMF-Full Search Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

TIN tin Character 9 Yes

First Name firstName Character 15 Yes

Both first name 

and last name 

must be sent in 

the request.

Last Name lastName Character 20 Yes

Both first name 

and last name 

must be sent in 

the request.
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

37

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

DMF-Full Response Fields – Definitions

Data Element Definition

TIN The Social Security Number of the deceased individual.

Name Name of deceased individual.

Death Date Date of death as provided by SSA (YYYY-MM-DD).

Birth Date Date of birth provided by SSA (YYYY-MM-DD).

Verify or Proof A one-character code which indicates that a death has been Verified (V) or that a death 

certificate has been observed (Proof (P)).

Source Content 

Description An abbreviated description of the data source.

As-of Date The date that the data source resource was last updated.

DMF-Full Response Fields – Technical Information

Data 

Element API Field Name Data 

Type Length Value / Format Nullable Notes

TIN tin Character 9 No

Name name Character 200

Format: first name 

middle name last 

name

Yes

Death Date deathDate Character 10 Format: YYYY-MM-DD Yes

Birth Date birthDate Character 10 Format: YYYY-MM-DD Yes

Verify or 

Proof verifyOrProof Character 30 Values: V, P, N/A Yes

V= VERIFIED -

BY FAMILY 

MEMBER OR 

FUNERAL 

HOME

P= PROOF -

DEATH 

CERTIFICATE

N/A= NO 

VERIFICATION 

HAS 

OCCURRED

Source Sys 

Type Code 

Description

srcSysTypeCdDesc Character 20 DMF No

As-of Date asOfDate Date 10 MM/DD/YYYY No
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

38

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

DMF-Full Usage

URI /datasource (multi-resource search)

/datasource/dmf

Access Requirements Client’s Access Group must have access to dmf datasource

Sample Response

{

 "data": [

"attributes": {

 "srcSysTypeCdDesc": "DMF",

 "searchCriteria": "SSN/EIN/TIN",

 "name": "ROSEMARIE KIRCHNER",

 "tin": "193182907",

 "deathDate": "2004-04-21",

 "asOfDate": "05/23/2024",

 "birthDate": "1938-11-27",

 "verifyOrProof": "V"

 },

 "id": "2884019137",

 "type": "dmf" 

}

]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

39

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

DEPARTMENT OF DEFENSE DEATH DATA (DOD)

☐ Your agency is approved to access this data source.

The Department of Defense death data source (DOD) contains information on active-duty United States

military and Reserves regarding confirmed or presumed deaths.

DOD Search Fields – Definitions

Data Element Definition

TIN The Social Security Number of the deceased individual.

First Name First name of the deceased individual.

Last Name Last name of the deceased individual.

DOD Search Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

TIN tin Character 9 Yes

First Name firstName Character 256 Yes

Both first name 

and last name 

must be sent in 

the request.

Last Name lastName Character 256 Yes

Both first name 

and last name 

must be sent in 

the request.
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

40

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

DOD Response Fields – Definitions

Data Element Definition

TIN The Social Security Number of the deceased individual.

Name Name of deceased individual.

Death Date Date of death as provided by DoD (YYYY-MM-DD).

Birth Date Date of birth provided by DoD (YYYY-MM-DD).

As-of Date The date that the data source resource was last updated.

DOD Response Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

TIN tin Character 9 No

Name name Character 200

Format: first name 

middle name last 

name

Yes

Death Date deathDate Character 10 Format: YYYY-MM-DD Yes

Birth Date birthDate Character 10 Format: YYYY-MM-DD Yes

Source Sys 

Type Code 

Description

srcSysTypeCdDesc Character 20 DOD No

As-of Date asOfDate Date 10 MM/DD/YYYY No
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

41

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

DOD Usage

URI /datasource (multi-resource search)

/datasource/dod

Access Requirements Client’s Access Group must have access to dod datasource

Sample Response

 {

"data": [

{

 "attributes": {

 "srcSysTypeCdDesc": "DOD",

 "searchCriteria": "SSN/EIN/TIN",

 "name": "ADAM BOYER",

 "tin": "896903212",

 "deathDate": "2018-08-01",

 "asOfDate": "04/26/2023",

 "birthDate": "1990-10-26"

 },

 "id": "2879334956",

 "type": "dod"

}

]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

42

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

DEPARTMENT OF STATE DEATH DATA (DOS)

☐ Your agency is approved to access this data source.

Department of State death data source (DOS) contains records of American Citizens who are deceased or 

presumed deceased while abroad, as reported by U.S. embassies or consulates upon its receipt of a foreign 

death certificate or finding of death by a local competent authority.

DOS Search Fields – Definitions

Data Element Definition

TIN The Social Security Number of the deceased individual.

First Name First name of the deceased individual.

Last Name Last name of the deceased individual.

DOS Search Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

TIN tin Character 9 Yes

First Name firstName Character 256 Yes

Both first name 

and last name 

must be sent in 

the request.

Last Name lastName Character 256 Yes

Both first name 

and last name 

must be sent in 

the request.
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

43

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

DOS Response Fields – Definitions

Data Element Definition

TIN The Social Security Number of the deceased individual.

Name Name of deceased individual.

Death Date Date of death as provided by DOS (YYYY-MM-DD).

Birth Date Date of birth provided by DOS (YYYY-MM-DD).

As-of Date The date that the data source resource was last updated.

DOS Response Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

TIN tin Character 9 No

Name name Character 200

Format: first name 

middle name last 

name

Yes

Death Date deathDate Character 10 Format: YYYY-MM-DD Yes

Birth Date birthDate Character 10 Format: YYYY-MM-DD Yes

Source Sys 

Type Code 

Description

srcSysTypeCdDesc Character 20 DOS No

As-of Date asOfDate Date 10 MM/DD/YYYY No
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

44

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

DOS Usage

URI /datasource (multi-resource search)

/datasource/dos

Access Requirements Client’s Access Group must have access to dos datasource

Sample Response

{

"data": [

{

 "attributes": {

 "srcSysTypeCdDesc": "DOS",

 "searchCriteria": "SSN/EIN/TIN",

 "name": "BOYER ADAM",

 "tin": "896903212",

 "deathDate": "2018-08-01",

 "asOfDate": "04/25/2023",

 "birthDate": "1990-10-26"

 },

 "id": "2879179641",

 "type": "dos"

}

]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

45

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

FORM 990-N (e-Postcard)

☐ Your agency is approved to access this data source.

The Internal Revenue Service (IRS) Form 990-N (e-Postcard) data source is an annual electronic notice 

most small tax-exempt organizations (annual gross receipts normally $50,000 or less) are eligible to file.

Form 990-N Search Fields – Definitions

Data Element Definition

TIN

The EIN, or Employer Identification Number, is also known as a federal Tax 

Identification Number (TIN) and is used to identify a business or nonprofit entity. An 

EIN is a unique 9-digit number, similar to a Social Security Number for an individual.

Business Name The primary name by which the organization is listed in IRS records.

Form 990-N Search Fields – Technical Information

Data Element API Field Name Data 

Type Length Value / Format Nullable Notes

TIN tin Character 9 No

Business Name businessName Character 200 No
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

46

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

Form 990-N Response Fields – Definitions

Data Element Definition

TIN

The EIN, or Employer Identification Number, is also known as a federal Tax 

Identification Number (TIN) and is used to identify a business or nonprofit entity. An 

EIN is a unique 9-digit number, similar to a Social Security Number for an individual.

Name The primary name by which the organization is listed in IRS records.

Business Name The primary name by which the organization is listed in IRS records.

Receipt Under Allowance The amount the organization’s gross receipts are equal to or less than.

Tax Period Begin Date The tax period begin date for the organization’s exemption.

Tax Period End Date The tax period end date that the organization’s exemption runs through.

Tax Year The tax period year that the organization’s exemption runs through.

Mailing Address Line 1 The street address for the organization’s last known mailing address.

Mailing City The city in which the organization’s last known mailing address is located.

Mailing State The state in which the organization’s last known mailing address is located.

Mailing Zip The zip code in which the organization's last known mailing address is located.

Mailing Country The country in which the organization’s last known mailing address is located.

Officer Name Name of the organization’s Principal Officer.

Officer Address line 1 Street address of the organization’s Principal Officer.

Officer City The city in which the organization’s Principal Officer’s last known mailing address is 

located.

Officer State Code The State in which the organization’s Principal Officer’s last known mailing address is 

located.

Officer Zip The zip code of the organization's last known mailing address.

Organization Has 

Terminated Indicates whether or not the organization’s exempt status has terminated.

Tax ID Type Indicates the TIN type of the organization (EIN/SSN/TIN).

Company URL The URL address of the organization as it appears in the original data source.

Source System Type 

Code The name of the data source returned.

Source System Type 

Code Description The full name of the data source returned.

Party Type Code The type of entity (Individual, Group, Unknown).

As-of Date The date that the data source resource was last updated.
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

47

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

Form 990-N Response Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

TIN tin Character 9 No

Name name Character 200 No

Business 

Name businessName Character 200 No

Receipt 

Under 

Allowance

receiptUnderAllowance Character 5 50000 No

Tax Period 

Begin Date taxPeriodBeginDate Date 10 YYYY-MM-DD No Date

Tax Period 

End Date taxPeriodEndDate Date 10 YYYY-MM-DD No Date

Tax Year taxYear Character 256 No

Mailing 

Address Line 

1

mailingAddrLine1 Character 150 No

Mailing City mailingCity Character 50 No

Mailing State mailingState Character 2 No

Mailing Zip mailingZip Character 15 No

Mailing 

Country mailingCountry Character 3 No

Officer Name officerName Character 60 Yes

Officer 

Address Line 

1

officerAddressLine1 Character 150 Yes

Officer City officerCity Character 50 Yes

Officer State 

Code officerStateCd Character 50 Yes

Officer Zip officerPostalCd Character 15 Yes

Organization 

Has 

Terminated

terminated Character 256 No

Tax ID Type taxIdType Character 4 No

Company 

URL companyUrl Character 200 Yes

Source 

System Type 

Code

srcSysTypeCd Character 40 990-N No
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

48

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

Source 

System Type 

Code 

Description

srcSysTypeCdDesc Character 500 990-N No

Party Type 

Code type Character 4 I, G, U No

As-of Date asOfDate Date 10 YYYY-MM-DD No Date

Form 990-N Usage

URI

/datasource (multi-resource search)

/datasource/form990n

Access Requirements Client’s Access Group must have access to 990n data source

Sample Response

{

 "data": [

{

 "attributes": {

 "receiptUnderAllowance": "50000",

 "searchCriteria": "SSN/EIN/TIN",

 "businessName": "SUGME",

 "taxPeriodEndDate": "12/31/2017",

 "companyUrl": "WWW.SUGME.ORG",

 "type": "U",

 "mailingZip": "04280",

 "officerAddressLine1": "108 MIDDLE ROAD",

 "officerCity": "SABATTUS",

 "officerPostalCd": "04280",

 "taxYear": "2017",

 "mailingCountry": "USA",

 "tin": "010534473",

 "mailingAddrLine1": "108 MIDDLE ROAD",

 "mailingState": "ME",

 "terminated": "NO",

 "srcSysTypeCdDesc": "990-N",

 "mailingCity": "SABATTUS",

 "srcSysTypeCd": "990-N",

 "name": "SUGME",

 "officerName": "DAVID GILBERT",
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

49

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

 "officerStateCd": "ME",

 "taxPeriodBeginDate": "01/01/2017",

 "officerCountryCd": "USA",

 "taxIdType": "EIN",

 "asOfDate": "05/29/2023"

 },

 "id": "1747892250",

 "type": "form990n"

 }]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

50

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

LIST OF EXCLUDED INDIVIDUALS & ENTITIES (LEIE) – PUBLIC AND 

RESTRICTED

☐ Your agency is approved to access this data source.

The List of Excluded Individuals & Entities Public and Restricted data sources (LEIE) provide information 

regarding individuals and entities currently excluded from participation in Medicare, Medicaid, and all 

other federal health care programs. Individuals and entities who have been reinstated are removed from the 

LEIE. The Restricted version of LEIE includes excluded entity TIN information as well as up to five 

exclusion types.

LEIE is owned and administered by the Department of Health and Human Services (HHS) Office of the 

Inspector General (OIG).

LEIE Search Fields - Definitions

Data Element Definition

TIN Taxpayer Identification Number. SSN/EIN/TIN of the individual on the exclusions list.

First Name First name of the individual on the exclusions list.

Last Name Last name of the individual on the exclusions list.

Business Name The name of the entity on the exclusions list.

As-of Date The date that the data source resource was last updated.

LEIE Search Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

TIN tin Character 9 Yes

TIN can be used only 

for the Restricted

version of LEIE. TIN 

is not available in the 

Public version of 

LEIE.

First Name firstName Character 15 Yes

Both first name and 

last name must be 

sent in the request.

Last Name lastName Character 20 Yes

Both first name and 

last name must be 

sent in the request.

Business 

Name businessName Character 30 Yes

As-of Date asOfDate Date 10 MM/DD/YYYY No
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

51

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

LEIE Response Fields – Definitions

Data Element Definition

TIN Taxpayer Identification Number. SSN/EIN/TIN of the individual or entity on the excluded 

list.

Name Full Name of entity.

General The entity's basic type of medical practice or position.

Specialty The entity's medical specialization.

Exclusion Program Social Security Act Exclusion Authorities (example: 1128(a)(1)).

Exclusion Description Long description of Exclusion Program. (example: Conviction of program-related crimes. 

Minimum Period: 5 years).

Exclusion Date The date of the entity's exclusion.

Birth Date The date of birth of the entity being excluded (if applicable).

National Provider 

Identifier

A unique 10-digit identification number issued to health care providers in the United 

States by the Centers for Medicare and Medicaid Services (CMS).

Waiver Date The date the entity's exclusion status was waived.

Waiver State The state in which the entity's exclusion status was waived.

Address Line 1 Line 1 of the street address of the entity being excluded.

Address Line 2 Line 2 of the street address of the entity being excluded.

City The city for the entity being excluded.

State The state for the entity being excluded.

ZIP The ZIP code for the entity being excluded.

Country The country for the entity being excluded.

Source Content 

Description An abbreviated description of the data source.

As-of Date The date that the data source resource was last updated.
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

52

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

LEIE Response Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

TIN tin Character 9 No

TIN can be used only 

for the Restricted 

version of LEIE. TIN 

is not available in the 

Public version of 

LEIE.

Name name Character 200 Yes

General general Character 20 Yes

Specialty specialty Character 20 Yes

Exclusion 

Program exclusionCode Character 30 Yes

Exclusion 

Description exclusionDescription Character 3800 Yes

Exclusion Date exclusionDate Character 10 MM/DD/YYYY Yes

Birth Date birthDate Character 10 MM/DD/YYYY Yes

National 

Provider 

Identifier

providerIdentifier Character 10 Yes

Waiver Date waiverDate Character 8 YYYYMMDD Yes

Waiver State waiverState Character 2 Yes

Address addressLine1 Character 30 Yes

Address addressLine2 Character 30 Yes

City city Character 20 Yes

State stateCode Character 2 Yes

ZIP postalCode Character 5 Yes

Country countryCode Character 3 Yes

Source Sys 

Type Code 

Description

srcSysTypeCdDesc Character 20 LEIE-PRIV or LEIEPUB No

As-of Date asOfDate Date 10 MM/DD/YYYY No
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

53

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

LEIE Usage

Note that in the examples below only [leiePrivate] is used, but you would substitute this with [leiePublic], 

if applicable.

URI /datasource (multi-resource search)

/datasource/leiePrivate

Access 

Requirements Client’s Access Group must have access to leiePublic or leiePrivate datasource

Sample 

Response

{

"data": [

{

 "attributes": {

 "general": "Sample Profession",

 "exclusionCode": "123456",

 "exclusionDate": 01/01/2001,

 "city": "Metropolis",

 "countryCode": "US",

 "postalCode": "12345",

 "tin": "123456789",

 "specialty": "Sample Data",

 "name": "JOHN DOE",

 "addressLine1": "418 2nd Street",

 "addressLine2": "Suite B",

 "stateCode": "NC",

 "exclusionDescription": "Sample exclusion",

 "birthDate": 01/01/1950,

 "srcSysTypeCdDesc": "LEIE-PRIV"

 },

 "id": "10045016",

 "type": "leiePrivate"

 }]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

54

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

OFFICE OF FOREIGN ASSETS CONTROL (OFAC)

☐ Your agency is approved to access this data source.

The Office of Foreign Assets Control data source (OFAC) of the U.S. Treasury administers and enforces 

economic and trade sanctions based on U.S. foreign policy and national security goals against targeted 

foreign states, organizations, and individuals. The OFAC data source also contains individuals, groups, 

and entities, such as terrorists and narcotics traffickers, designated under programs that are not country

specific. Collectively, such individuals and companies are called "Specially Designated Nationals" or 

"SDNs." Their assets are blocked, and U.S. persons are generally prohibited from doing business with 

them.

OFAC Search Fields - Definitions

Data Element Definition

First Name First name of the individual SDN on the list.

Last Name Last name of the individual SDN on the list.

Business Name Business Name of Specially Designated National (SDN). This can be a business name or 

even the name of a vessel.

OFAC Search Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

First Name firstName Character 15 Yes

Both first name and 

last name must be 

sent in the request.

Last Name lastName Character 20 Yes

Both first name and 

last name must be 

sent in the request.

Business 

Name businessName Character 200 Yes
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

55

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

OFAC Response Fields

Important Note: Unlike most of the other data sources, certain OFAC match detail fields (response fields) are contained within 

relational objects, so requesting response fields is a little different for this data source.

For the Main object below, you may still declare which associated data element(s) you’d like in the response. However, all other 

sections below represent child objects. You may choose which child objects you’d like in the response, but you must get all of the 

available data elements within a selected child object in each response.

See the OFAC Usage sections for instructions on how to structure your request for the main object and child objects.

Performance on child object responses will be less robust than for the main object; excluding child objects from response requests is 

recommended if the data is not needed.

OFAC Main Object Response Fields - Definitions

Data Element Definition

Title

Position of the SDN (Specially Designated National) on the OFAC listing based upon 

citizenship, country, etc. Examples include Dr. and Director General. May be blank if SDN 

is not an individual.

Name Name of Specially Designated National (SDN). This can be a person's name, business 

name or even the name of a vessel.

Type Sanctions type: The only two valid values currently are I and B.

Type Description Description of Sanctions type code: The only two valid values currently are Individual 

and Business.

Remarks

Text field for additional information concerning the SDN. Examples could include aliases, 

passport information position information such as "Secretary General" or "Military 

Leader", known organizations they are linked to, “all offices worldwide”, and any other 

narrative information about a sanctioned party.

Source Content 

Description An abbreviated description of the data source.

As-of Date The date that the data source resource was last updated.
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

56

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

OFAC Main Object Response Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

Title title Character 200 Yes

Name name Character 200 Yes

Type type Character 1

Valid values:

- I

- B

Yes

Type 

Description typeDescription Character 256

Valid values:

- Individual

- Business Yes

Remarks remarks Character 1000 Yes

Source Sys 

Type Code 

Description

srcSysTypeCdDesc Character 20 OFAC No

As-of Date asOfDate Date 10 MM/DD/YYYY No

OFAC Main Object Response Fields – Usage

The information below highlights usage when retrieving the primary OFAC fields.

URI /datasource (multi-resource search)

/datasource/ofac

Access 

Requirements Client’s Access Group must have access to ofac datasource

Sample 

Response

{

"data": [{

 "attributes": {

 "name": "JOHN DOE",

 "typeDescription": "INDIVIDUAL",

 "type": "I",

 "title": "TITLE",

 "srcSysTypeCdDesc": "OFAC"

 },

 "id": "100957123",

 "type": "ofac"

}]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

57

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

OFAC Address Child Object Response Fields – Definitions

Data Element Definition

Address Street Address Line 1 of the Specially Designated National.

Address 2 Second line of Street Address of the Specially Designated National.

Address 3 Third line of Street Address of the Specially Designated National.

City City of the Specially Designated National.

State State/Province of the Specially Designated National.

Postal Code Postal Code of the Specially Designated National. This can be either a US Zip code or 

international postal code.

Country Country of the Specially Designated National.

OFAC Address Child Object Response Fields – Technical Information

Data Element API Field Name Data Type Length Value / Format Nullable Notes

Address addressLine1 Character 150 Yes

Address 2 addressLine2 Character 150 Yes

Address 3 addressLine3 Character 150 Yes

City city Character 50 Yes

State stateCode Character 2 Yes

Postal Code postalCode Character 15 Yes

Country country Character 50 Yes
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

58

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

OFAC Address Child Object Response Fields – Usage

The information below uses the examples from the main object and includes the additional information for 

the address child object. Note that although the include value is “address,” in the return data it is contained 

in the “addresses” element, as it can return more than one object per search.

URI include=address

Access 

Requirements Client’s Access Group must have access to ofac datasource

Sample 

Response

{

"data": [

{

 "attributes": {

 "addresses": [{

 "city": "KANSAS CITY",

 "countryCode": "USA",

 "postalCode": "12345",

 "addressLine1": "ATTN - BB",

 "addressLine2": "LOCATION TT98",

 "addressLine3": "123 2nd St",

 "stateCode": "MO"

 }],

 "name": "JOHN DOE",

 "typeDescription": "INDIVIDUAL",

 "type": "I",

 "title": "Test Title"

 },

 "id": "100957123",

 "type": "ofac"

}]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

59

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

OFAC Alternate ID Child Object Response Fields – Definitions

Data Element Definition

Country Country of Issue. Name of country that issued the ID/Registration document.

ID Type Type of ID/Registration. Possible values include Passport, Cedula, and Driver’s License 

Number.

ID Number Number that appears on the ID/Registration document.

Issue Date Issue Date of the ID/Registration document.

Expiration Date Expiration Date of the ID/Registration document.

OFAC Alternate ID Child Object Response Fields – Technical Information

Data

Element API Field Name DataType Length Value / Format Nullable Notes

Country countryCode Character 5 Yes

ID Type idType Character 50

Valid values:

Passport

Cedula

Driver’s License

Number

Yes

ID Number idNumber Character 40 Yes

Issue Date issueDate Character 10 DD MON YYYY 

example: 14 JUN 2018 Yes

Expiration 

Date expirationDate Character 10 DD MON YYYY example: 14 JUN 2018 Yes
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

60

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

OFAC Alternate ID Child Object Response Fields – Usage

The information below uses the examples from the main object and includes the additional information for 

the identification child object. Note that although the include value is “alternateId,” in the return data it is 

contained in the “alternateIds” element, as it can return more than one object per search.

URI include=alternateId

Access 

Requirement Client’s Access Group must have access to OFAC datasource.

Sample 

Response

{

"data": [

{

 "attributes": {

 "alternateIds": [{

 "countryCode": "US",

 "idType": "PASSPORT",

 "idNumber": "12345",

 "issueDate": "01/01/2012",

 "expirationDate": "01/01/2017"

 }],

 "name": "JOHN DOE",

 "typeDescription": "INDIVIDUAL",

 "type": "I",

 "title": "Test Title"

 },

 "id": "100957123",

 "type": "ofac"

}]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

61

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

OFAC Date of Birth Child Object Response Fields – Definitions

Data Element Definition

Date of Birth Date of Birth for SDN.

OFAC Date of Birth Child Object Response Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

Date of Birth alternateBirthDate Date 10 MM/DD/YYYY Yes

OFAC Date of Birth Child Object Response Fields – Usage

The information below uses the examples from the main object and includes the additional information for 

the date of birth child object. Note that although the include value is “birthdate,” in the return data it is 

contained in the “birthDates” element, as it can return more than one object per search.

URI include=birthdate

Access 

Requirements Client’s Access Group must have access to ofac datasource

Sample 

Response

{

"data": [

{

 "attributes": {

 "birthDates": [{

 "alternateBirthDate": "01/01/1975"

 }],

 "name": "JOHN DOE",

 "typeDescription": "INDIVIDUAL",

 "type": "I",

 "title": "Test Title"

 },

 "id": "100957123",

 "type": "ofac"

}]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

62

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

OFAC Place of Birth Child Object Response Fields – Definitions

Data Element Definition

Place of Birth Birth place location country information for a Specially Designated National.

OFAC Place of Birth Child Object Response Fields – Technical Information

Data

Element API Field Name DataType Length Value / Format Nullable Notes

Place of Birth birthPlace Character 250 Yes

OFAC Place of Birth Child Object Response Fields – Usage

The information below uses the examples from the main object and includes the additional information for 

the place of birth child object. Note that although the include value is “birthplace,” in the return data it is 

contained in the “birthPlaces” element, as it can return more than one object per search.

URI include=birthplace

Access 

Requirements Client’s Access Group must have access to ofac datasource.

Sample 

Response

{

"data": [

{

 "attributes": {

 "birthPlaces": [{

 "placeOfBirth": "ORLANDO, FL"

 }],

 "name": "JOHN DOE",

 "typeDescription": "INDIVIDUAL",

 "type": "I",

 "title": "Test Title"

 },

 "id": "100957123",

 "type": "ofac"

}]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

63

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

OFAC Citizenship Child Object Response Fields – Definitions

Data Element Definition

Citizenship Country of citizenship for a Specially Designated National.

OFAC Citizenship Child Object Response Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

Citizenship country Character 250 Yes

OFAC Citizenship Child Object Response Fields – Usage

The information below uses the examples from the main object and includes the additional information for 

the citizenship child object. Note that although the include value is “citizenship,” in the return data it is 

contained in the “citizenships” element, as it can return more than one object per search.

URI include=citizenship

Access 

Requirements

Client’s Access Group must have access to ofac datasource

Sample 

Response

{

"data": [

{

 "attributes": {

 "citizenships": [{

 "country": "UNITED STATES"

 }],

 "name": "JOHN DOE",

 "typeDescription": "INDIVIDUAL",

 "type": "I",

 "title": "Test Title"

 },

 "id": "100957123",

 "type": "ofac"

}]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

64

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

OFAC Nationality Child Object Response Fields – Definitions

Data Element Definition

Nationality Country of residence for a Specially Designated National.

OFAC Nationality Child Object Response Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

Nationality nationality Character 250 Yes

OFAC Nationality Child Object Response Fields – Usage

The information below uses the examples from the main object and includes the additional information for 

the nationality child object. Note that although the include value is “nationality,” in the return data it is 

contained in the “nationalities” element, as it can return more than one object per search.

URI include=nationality

Access 

Requirements Client’s Access Group must have access to ofac datasource

Sample 

Response

{

"data": [

{

 "attributes": {

 "nationalities": [{

 "nationality": "UNITED STATES"

 }],

 "name": "JOHN DOE",

 "typeDescription": "INDIVIDUAL",

 "type": "I",

 "title": "Test Title"

 },

 "id": "100957123",

 "type": "ofac"

}]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

65

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

OFAC Program Child Object Response Fields – Definitions

Data Element Definition

Program

Sanctions Program Name. It is a Specially Designated Nationals focus area. It indicates 

the sanctions program pursuant to which the person has been blocked, designated, or 

identified. Sample programs include: 561LIST, CUBA, DPRK (North Korea Sanctions 

Regulations), IRAN, JADE, NPWMD (Weapons of Mass Destruction Proliferators 

Sanctions Regulations), and SYRIA.

OFAC Program Child Object Response Fields – Technical Information

Data

Element API Field Name DataType Length Value / Format Nullable Notes

Program program Character 50 Yes

OFAC Program Child Object Response Fields – Usage

The information below uses the examples from the main object and includes the additional information for 

the program child object. Note that although the include value is “program,” in the return data it is 

contained in the “programs” element, as it can return more than one object per search.

URI include=program

Access 

Requirements Client’s Access Group must have access to ofac datasource

Sample 

Response

{

"data": [

{

 "attributes": {

 "programs": [{

 "program": "JADE"

 }],

 "name": "JOHN DOE",

 "typeDescription": "INDIVIDUAL",

 "type": "I",

 "title": "Test Title"

 },

 "id": "100957123",

 "type": "ofac"

}]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

66

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

PUBLICATION 78 DATA (PUB 78)

☐ Your agency is approved to access this data source.

The Internal Revenue Service Publication 78 data source (PUB 78) is a list of organizations eligible to 

receive tax-deductible charitable contributions. Note: If an organization uses a “doing business as” name, it 

is not listed in the file. Only the business name registered with the IRS is in the listing.

PUB 78 Search Fields - Definitions

Data Element Definition

TIN Tax Identification Number of the entity included on the list

First Name First name of the individual on the list.

Last Name Last name of the individual on the list.

Business Name Business Name of the entity

PUB 78 Search Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

TIN tin Character 9 YES

First Name firstName Character 15 Yes

Both first name and 

last name must be 

sent in the request.

Last Name lastName Character 20 Yes

Both first name and 

last name must be 

sent in the request.

Business 

Name businessName Character 200 Yes
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

67

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

PUB 78 Main Object Response Fields - Definitions

Data Element Definition

Country The two-character code of the country in which the entity exists.

City Name The name of the city in which the entity exists.

Business Name The registered business name of the entity.

Type The type of business of the registered entity.

Deductibility Code The type of organization and use of contribution.

TIN The Tax Identification Number of the registered entity.

Name The name of the registered entity.

State Code The state in which the entity is based.

Tax ID Type Indicates whether the TIN is an SSN, EIN, or TIN.

As-of Date The date that the data source resource was last updated.

PUB 78 Main Object Response Fields – Technical Information

Data Element API Field Name Data 

Type Length Value / Format Nullable Notes

Country country Character 3 Yes

City Name cityName Character 50 Yes

Business Name businessName Character 200 Yes

Type type Character 1 Yes

Deductibility Code deductibilityCode Character 256 Yes

TIN tin Character 9 Yes

Name name Character 200 Yes

State Code stateCode Character 2 Yes

Tax ID Type taxIdType Character 4 Yes

As-of Date asOfDate Date 10 MM/DD/YYYY No
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

68

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

PUB 78 Response Fields – Usage

The information below highlights usage when retrieving the primary PUB 78 fields.

URI /datasource (multi-resource search)

/datasource/pub78

Access 

Requirements Client’s Access Group must have access to PUB78 data source.

Sample 

Response

 {

"data": [

{

 "attributes": {

 "country": "US",

 "srcSysTypeCdDesc": "PUB 78",

 "searchCriteria": "SSN/EIN/TIN",

 "businessName": "ECYC INC.",

 "type": "U",

 "srcSysTypeCd": "PUB78",

 "cityName": "RAHWAY",

 "deductibilityCode": "PC",

 "tin": "223340530",

 "name": "ECYC INC.",

 "stateCode": "NJ",

 "taxIdType": "EIN",

 "asOfDate": "06/13/2022"

 },

 "id": "841850615",

 "type": "pub78"

 }]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

69

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SYSTEM FOR AWARD MANAGEMENT (SAM) ENTITY REGISTRATION

RECORDS

☐ Your agency is approved to access this data source.

System for Award Management (SAM) Entity Registration Records data source (formerly known as 

Central Contractor Registration - CCR) is the primary registrant database for the U.S. Federal Government. 

SAM Entity Registration Records collects, validates, stores, and disseminates data in support of agency 

acquisition.

SAM Entity Registration Search Fields – Definitions

Data Element Definition

TIN Taxpayer Identification Number. SSN/EIN/TIN of the individual or entity on the entity 

registration list.

First Name The First Name of the individual on the entity registration list.

Last Name The Last Name of the individual on the entity registration list.

UEI (Unique Entity 

Identifier)

A twelve-character alpha-numeric identifier assigned to registered entities by the 

General Services Administration (GSA) for use within the System of Award Management 

(SAM).

Electronic Funds 

Transfer (EFT) Indicator

A four-character suffix to the unique entity identifier. The suffix is assigned at the 

discretion of the commercial, nonprofit, or Government entity to establish additional 

System for Award Management records for identifying alternative EFT accounts for the 

same entity. Used to identify alternative EFT accounts for the same entity at the same 

physical location.

Business Name The name of the entity on the registration list.

SAM Entity Registration Search Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

TIN tin Character 9 Yes

First Name firstName Character 75 Yes

Both first name and 

last name must be 

sent in the request.

Last Name lastName Character 50 Yes

Both first name and 

last name must be 

sent in the request.

UEI (Unique 

Entity 

Identifier)

uei Character 12 Yes

Electronic 

Funds 

Transfer (EFT) 

Indicator

eftIndicator Character 4 Yes

Since EFT Indicator is 

an extension of UEI, 

EFT Indicator cannot 

be entered as a 

search criterion 

unless UEI is also 

entered.

Business 

Name businessName Character 30 Yes
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

70

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SAM Entity Registration Response Fields

Important Note: Unlike most of the other data sources, certain SAM Entity Registration match detail fields (Response Fields) are 

contained within relational objects, so requesting response fields is a little different for this data source.

For the Main object below, you may still declare which associated data element(s) you’d like in the response. However, all other 

sections below represent child objects. You may choose which child objects you’d like in the response, but you must get all of the 

available data elements within a selected child object in each response.

See the SAM Entity Registration Usage sections for instructions on how to structure your request for the main object and child 

objects.

Performance on child object responses will be less robust than for the main object; excluding child objects from response requests is 

recommended if the data is not needed.

SAM Entity Registration Main Object Response Fields – Definitions

Data Element Definition

Registration Status Current status of the registration. It is the SAM Extract Code field in the monthly SAM 

Entity file. Values are Active and Expired.

CAGE/NCAGE

The Commercial And Government Entity (CAGE) Code is a five-character ID number 

used extensively within the U.S. federal government, assigned by the Department of 

Defense’s Defense Logistics Agency (DLA). The CAGE code provides a standardized 

method of identifying a given facility at a specific location. CAGE codes for entities 

located outside the United States are called NATO Commercial and Government Entity 

(NCAGE) codes. NCAGE codes are assigned internationally as part of the NATO 

Codification System (NCS), and are required for all foreign entities or the registration 

will be considered incomplete.

Legal Business Name Registered Legal Business Name.

DBA Doing Business As (DBA). The commonly used other name, such as a franchise, licensee 

name, or an acronym. This name must be different from the Legal Business Name.

Division Name Company Division Name. If you do business or are identified as a division of a larger 

company.

Division Number Company Division Number. If a number identifier commonly distinguishes your division.

Company URL Corporate URL. Entity's web page URL.

UEI (Unique Entity 

Identifier)

A twelve-character alpha-numeric identifier assigned to registered entities by the General 

Services Administration (GSA) for use within the System of Award Management (SAM).

Electronic Funds Transfer 

(EFT) Indicator

A four-character suffix to the unique entity identifier. The suffix is assigned at the 

discretion of the commercial, nonprofit, or Government entity to establish additional 

System for Award Management records for identifying alternative EFT accounts for the 

same entity. Used to identify alternative EFT accounts for the same entity at the same 

physical location.

DoDAAC

The Department of Defense Activity Address Code (DoDAAC) is a six position code that 

uniquely identifies a Department of Defense unit, activity, or organization that has the 

authority to requisition, contract for, receive, have custody of, issue, or ship DoD assets, 

or fund/pay bills for materials and/or services.

TIN Taxpayer Identification Number. SSN/EIN/TIN of the individual or entity on the entity 

registration list.

Financial Institution The name of the bank to use for EFT/banking purposes.

ABA Routing Number American Banking Routing ID is a financial institution's nine-digit routing transit number 

assigned by the American Banking Association (ABA).

Account Number Account number to which EFT payments are deposited. If an award is received, the 

Federal Government will use this information to process the payment.

Account Type Account Type: C=Checking or S=Savings
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

71

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

Data Element Definition

Activation Date The date on which the SAM Entity Registration Record was activated.

Authorization Date The date the registered entity authorized the use of the financial information included in 

the SAM Registration Record related to the acquisition of Government goods or services.

Initial Registration Date The date on which the entity was first registered with SAM.

Fiscal Year End Close 

Date

The date on which the entity ends their fiscal year; this is the same day/month every 

year for a given entity.

Last Updated Date The date on which the SAM Entity Registration Record was last updated.

Physical Street Address 1 D&B Registration Physical Street Address 1

Physical Street Address 2 D&B Registration Physical Street Address 2

Physical City D&B Registration Physical City

Physical State D&B Registration Physical State

Physical Foreign Province D&B Registration Physical Foreign Province

Physical ZIP Code D&B Registration Physical ZIP Code

Physical Country D&B Registration Physical Country

Mailing Name

Mailing Name. Full name: First, Middle, and Last. Comes from the Government Business 

Point of Contact name fields.

Mailing Street Address 1 Mailing Street Address 1 (If unable to receive mail at physical address.)

Mailing Street Address 2 Mailing Street Address 2 (If unable to receive mail at physical address.)

Mailing City Mailing City (If unable to receive mail at physical address.)

Mailing State Mailing State (If unable to receive mail at physical address.)

Mailing Foreign Province Mailing Foreign Province (If unable to receive mail at physical address.)

Mailing Zip Code Mailing Zip Code (If unable to receive mail at physical address.)

Mailing Country Mailing Country (If unable to receive mail at physical address.)

Business Start Date Date the entity was formed or established.

Business Termination 

Date The date when the entity's registration expires.

Delinquent Federal Debt

Delinquent Federal Debt. Values: Y and N. Yes/No flag (whether entity has a delinquent 

federal debt. A non-entry [-] indicates that this registrant has not yet been verified with

Treasury. Foreign registrations are not verified.

Source Content 

Description An abbreviated description of the data source.

As-of Date The date that the data source resource was last updated.
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

72

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SAM Entity Registration Main Object Response Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

Registration 

Status registrationStatus Character 1

Valid Values:

- Active

- Expired

Yes

CAGE/NCAGE cageCode Character 5 Yes

Legal 

Business

Name

name Character 120 Yes

DBA dba Character 120 Yes

Division Name divisionName Character 60 Yes

Division 

Number divisionNumber Character 10 Yes

Company 

URL companyUrl Character 200 Yes

UEI (Unique 

Entity 

Identifier)

uei Character 12 Yes

Electronic 

Funds 

Transfer 

(EFT) 

Indicator

eftIndicator Character 4 Yes

Since EFT Indicator 

is an extension of 

UEI, EFT Indicator 

cannot be entered 

as a search 

criterion unless UEI 

is also entered.

DoDAAC dodaac Character 9 Yes

TIN tin Character 9 No

Financial 

Institution financialInstitute Character 60 Yes

ABA Routing 

Number abaRoutingNumber Character 9 Yes

Account 

Number accountNumber Character 30 Yes

Account Type accountType Character 1 Yes

Activation 

Date activationDate Character 10 MM/DD/YYYY Yes

Authorization 

Date authorizationDate Character 10 MM/DD/YYYY Yes
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

73

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

Initial 

Registration 

Date

initialRegistrationDate Character 10 MM/DD/YYYY Yes

Fiscal Year 

End Close 

Date

fiscalYearEndCloseDate Character 6 MMM DD Yes

Last Updated 

Date lastUpdateDate Character 10 MM/DD/YYYY Yes

Physical 

Street 

Address 1

physicalStreetAddress 

Line1 Character 150 Yes

Physical 

Street 

Address 2

physicalStreetAddress 

Line2 Character 150 Yes

Physical City physicalCity Character 40 Yes

Physical State physicalStateCode Character 2 Yes

Physical 

Foreign 

Province

physicalForeignProvince Character 55 Yes

Physical ZIP 

Code physicalPostalCode Character 15 Yes

Physical 

Country physicalCountryCode Character 3 Yes

Mailing Name mailName Character 256 Yes

Mailing Street 

Address 1 mailAddressLine1 Character 150 Yes

Mailing Street 

Address 2 mailAddressLine2 Character 150 Yes

Mailing City mailCity Character 40 Yes

Mailing State mailStateCode Character 2 Yes

Mailing 

Foreign 

Province

mailForeignProvince Character 55 Yes

Mailing Zip 

Code mailPostalCode Character 15 Yes

Mailing 

Country mailCountryCode Character 3 Yes
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

74

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

Business Start 

Date businessStartDate Character 10 MM/DD/YYYY Yes

Business 

Termination 

Date

businessTerminationDate Character 10 MM/DD/YYYY Yes

Delinquent 

Federal Debt delinquentFederalDebtFlag Character 5

Valid Values: Y 

and N Yes

Source Sys 

Type Code 

Description

srcSysTypeCdDesc Character 20 SAM-ENT No

As-of Date asOfDate Date 10 MM/DD/YYYY No
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

75

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SAM Entity Main Object Response Fields – Usage

The information below highlights usage when retrieving the primary SAM Entity fields.

URI /datasource (multi-resource search)

/datasource/samEnt 

Access 

Requirements Client’s Access Group must have access to samEnt datasource

Sample Response

{

"data": [

{

 "attributes": {

 "registrationStatus": "ACTIVE",

 "businessStartDate": "04/06/1993",

 "cageCode": "8XN89",

 "companyUrl": "www.johnsshoes.com",

 " eftIndicator ": "5432",

 "mailForeignProvince": "ON",

 "physicalStreetAddressLine1": "221 BAKER ST",

 "physicalStreetAddressLine2": "SUITE B",

 "businessTerminationDate": "04/06/2017",

 "physicalStateCode": "ON",

 "physicalCountryCode": "CAN",

 "tin": "123456789",

 "mailCity": "ONTARIO",

 "physicalForeignProvince": "ON",

 "mailStateCode": "ON",

 "dba": "JOHNS SHOES EXPRESS",

 "abaRoutingNumber": "123",

 "delinquentFederalDebtFlag": "A",

 "accountType": "C",

 "mailCountryCode": "CAN",

 "accountNumber": "84357",

 "mailPostalCode": "64002",

 "physicalCity": "ONTARIO",

 "name": "JOHNS SHOES",

 "physicalPostalCode": "64002",

 "mailAddressLine1": "221 BAKER ST",

 "mailAddressLine2": "SUITE B",

 "uei": "987654321",

 "financialInstitute": "INSTITUTE",

 "srcSysTypeCdDesc": "SAM-ENT"

 },

 "id": "908712671",

 "type": "samEnt"

}]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

76

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SAM Entity Registration Organization Code Child Object Response Fields –

Definitions

Data Element Definition

Organization Code

The structure of the entity as defined by the IRS. Example values include 2J-Sole 

Proprietorship, 2L-Corporate Entity (Not Tax Exempt), CY-Country - Foreign 

Government, and X6-International Organization.

SAM Entity Registration Organization Code Child Object Response Fields –

Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

Organization 

Code organizationCodeDescription Character 200

SAM Entity Registration Organization Code Child Object Response Fields – Usage

The information below uses the examples from the main object and includes the additional information for 

the organization code (orgType) child object. Note that although the include value is “orgType,” in the 

return data it is contained in the “orgTypes” element, as it can return more than one object per search.

URI

/datasource (multi-resource search)

/datasource/samEnt

Access 

Requirements Client’s Access Group must have access to samEnt datasource

Sample Response

{

"data": [

{

 "attributes": {

 "registrationStatus": "ACTIVE",

 "businessStartDate": "04/06/1993",

 "cageCode": "8XN89",

 "companyUrl": "www.johnsshoes.com",

 " eftIndicator ": "5432",

 "mailForeignProvince": "ON",

 "physicalStreetAddressLine1": "221 BAKER ST",

 "physicalStreetAddressLine2": "SUITE B",

 "businessTerminationDate": "04/06/2017",

 "physicalStateCode": "ON",

 "physicalCountryCode": "CAN",

 "tin": "123456789",
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

77

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

 "mailCity": "ONTARIO",

 "physicalForeignProvince": "ON",

 "mailStateCode": "ON",

 "dba": "JOHNS SHOES EXPRESS",

 "abaRoutingNumber": "123",

 "delinquentFederalDebtFlag": "A",

 "accountType": "C",

 "mailCountryCode": "CAN",

 "accountNumber": "84357",

 "mailPostalCode": "64002", "orgTypes":

 [{"organizationCodeDescription": "2L - CORPORATE ENTITY (NOT TAX EXEMPT)"}],

 "physicalCity": "ONTARIO",

 "name": "JOHNS SHOES",

 "physicalPostalCode": "64002",

 "mailAddressLine1": "221 BAKER ST",

 "mailAddressLine2": "SUITE B",

 "uei": "987654321",

 "financialInstitute": "BANK"

 },

 "id": "908712671",

 "type": "samEnt"

}]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

78

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SAM Entity Registration Business Code Child Object Response Fields –

Definitions

Data Element Definition

Business Code 

Description

Translation of a 2-digit SBA Business Type code into a textual description of the code. 

Examples include: 20: Foreign Owned and Located, A3: Labor Surplus Area Firm, A2: 

Woman Owned Business, 23: Minority Owned Business, etc.

SAM Entity Registration Business Code Child Object Response Fields – Technical 

Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

Business 

Code 

Description

businessCodeDescription Character 256

SAM Entity Registration Business Code Child Object Response Fields – Usage

The information below uses the examples from the main object and includes the additional information for 

the business code (businessType) child object. Note that although the include value is “businessType,” in 

the return data it is contained in the “businessTypes” element, as it can return more than one object per 

search

URI /datasource (multi-resource search)

/datasource/samEnt

Access 

Requirements Client’s Access Group must have access to samEnt datasource

Sample 

Response

{

"data": [

{

 "attributes": {

 "registrationStatus": "ACTIVE",

 "businessStartDate": "04/06/1993",

 "cageCode": "8XN89",

 "companyUrl": "www.johnsshoes.com",

 " eftIndicator ": "5432",

 "mailForeignProvince": "ON",

 "physicalStreetAddressLine1": "221 BAKER ST",

 "physicalStreetAddressLine2": "SUITE B",

 "businessTerminationDate": "04/06/2017",

 "physicalStateCode": "ON",

 "physicalCountryCode": "CAN",

 "tin": "123456789",
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

79

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

 "mailCity": "ONTARIO",

 "physicalForeignProvince": "ON",

 "mailStateCode": "ON",

 "dba": "JOHNS SHOES EXPRESS",

 "abaRoutingNumber": "123",

 "delinquentFederalDebtFlag": "A",

 "accountType": "C",

 "mailCountryCode": "CAN",

 "accountNumber": "84357",

 "mailPostalCode": "64002", " businessTypes":

 [{"businessCodeDescription": "20: Foreign Owned and Located"}],

 "physicalCity": "ONTARIO",

 "name": "JOHNS SHOES",

 "physicalPostalCode": "64002",

 "mailAddressLine1": "221 BAKER ST",

 "mailAddressLine2": "SUITE B", "uei": "987654321",

 "financialInstitute": "BANK"

 },

 "id": "908712671",

 "type": "samEnt"

}]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

80

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SAM Entity Registration Disaster Response Child Object Response Fields –

Definitions

Data Element Definition

Display Description Textual description of the Area Served or the services rendered for the Disaster 

Response Registry. Example value is "Geographic Area Served.”

Display Value The state, city, county, or MSA where the service was rendered. Examples: "Any AreaAny Area" and "State - North Carolina."

SAM Entity Registration Disaster Response Child Object Response Fields –

Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

Display 

Description displayDescription Character 256

Currently always 

returns "Geographic 

Areas Served"

Display Value displayValue Character 256

SAM Entity Registration Disaster Response Child Object Response Fields – Usage

The information below uses the examples from the main object and includes the additional information for 

the disaster response child object. Note that although the include value is “disasterResponse,” in the return 

data it is contained in the “disasterResponses” element, as it can return more than one object per search.

URI /datasource (multi-resource search)

/datasource/samEnt 

Access 

Requirements Client’s Access Group must have access to samEnt datasource

Sample 

Response

{

"data": [

{

 "attributes": {

 "registrationStatus": "ACTIVE",

 "businessStartDate": "04/06/1993",

 "cageCode": "8XN89",

 "companyUrl": "www.johnsshoes.com",

 " eftIndicator ": "5432",

 "mailForeignProvince": "ON",

 "physicalStreetAddressLine1": "221 BAKER ST",

 "physicalStreetAddressLine2": "SUITE B",

 "businessTerminationDate": "04/06/2017",

 "physicalStateCode": "ON",

 "physicalCountryCode": "CAN",

 "tin": "123456789",
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

81

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

 "mailCity": "ONTARIO",

 "physicalForeignProvince": "ON",

 "mailStateCode": "ON",

 "dba": "JOHNS SHOES EXPRESS",

 "abaRoutingNumber": "123",

 "delinquentFederalDebtFlag": "D",

 "accountType": "C",

 "mailCountryCode": "CAN",

 "accountNumber": "84357",

 "mailPostalCode": "64002",

 " disasterResponses": [

 {"displayDescription": "SAMPLE DESCRIPTION", "displayValue": "SAMPLE VALUE"}

 ],

 "physicalCity": "ONTARIO",

 "name": "JOHNS SHOES",

 "physicalPostalCode": "64002",

 "mailAddressLine1": "221 BAKER ST",

 "mailAddressLine2": "SUITE B",

 "uei": "987654321",

 "financialInstitute": "BANK"

 },

 "id": "908712671",

 "type": "samEnt"

}]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

82

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SAM Entity Registration NAICS Child Object Response Fields – Definitions

Data Element Definition

Emerging Small Business 

Indicator

Any small business concern whose size is no greater than 50 percent of the numerical 

size standard applicable to the Standard Industrial Classification ( SIC ) code assigned 

to a contracting opportunity.

NAICS Code North American Industry Classification System (NAICS) Codes. A method for classifying 

business establishments.

NAICS Description Expanded definition of NAICS Code.

Small Business Indicator Certified as a Small Business by the Small Business Administration.

SAM Entity Registration NAICS Child Object Response Fields – Technical 

Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

Emerging 

Small 

Business 

Indicator

emergingSmallBusinessIndicator Character 1

Valid Values: Y 

and N

NAICS Code naicsCode Character 6

NAICS 

Description naicsDescription Character 256

Small 

Business 

Indicator

smallBusinessIndicator Character 1

Valid Values: Y 

and N
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

83

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SAM Entity Registration NAICS Child Object Response Fields – Usage

The information below uses the examples from the main object and includes the additional information for 

the (naics child) object. Note that although the include value is “naicsDetail,” in the return data it is 

contained in the “naicsDetails” element, as it can return more than one object per search.

URI /datasource (multi-resource search)

/datasource/samEnt

Access

Requirements Client’s Access Group must have access to samEnt datasource

Sample Response

{

"data": [

{

 "attributes": {

 "registrationStatus": "ACTIVE",

 "businessStartDate": "04/06/1993",

 "cageCode": "8XN89",

 "companyUrl": "www.johnsshoes.com",

 "eftIndicator": "5432",

 "mailForeignProvince": "ON",

 "physicalStreetAddressLine1": "221 BAKER ST",

 "physicalStreetAddressLine2": "SUITE B",

 "businessTerminationDate": "04/06/2017",

 "physicalStateCode": "ON",

 "physicalCountryCode": "CAN",

 "naicsDetails": [

 {

 "emergingSmallBusinessIndicator": "I",

 "naicsDescription": "SEARCH, DETECTION, NAVIGATION, GUIDANCE, AERONAUTICAL, 

AND NAUTICAL SYSTEM AND INSTRUMENT MANUFACTURING",

 "smallBusinessIndicator": "N",

 "naicsCode": "334511"

 }

 ],

 "tin": "123456789",

 "mailCity": "ONTARIO",

 "physicalForeignProvince": "ON",

 "mailStateCode": "ON",

 "dba": "JOHNS SHOES EXPRESS",

 "abaRoutingNumber": "123",
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

84

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

 "delinquentFederalDebtFlag": "A",

 "accountType": "C",

 "mailCountryCode": "CAN",

 "accountNumber": "84357",

 "mailPostalCode": "64002",

 "physicalCity": "ONTARIO",

 "name": "JOHNS SHOES",

 "physicalPostalCode": "64002",

 "mailAddressLine1": "221 BAKER ST",

 "mailAddressLine2": "SUITE B",

 "uei": "987654321",

 "financialInstitute": "BANK"

 },

 "id": "908712671",

 "type": "samEnt"

}]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

85

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SAM Entity Registration Product Service Code Child Object Response Fields –

Definitions

Data Element Definition

Product Service Code

Four-character, and alpha-numeric codes. Product service codes are used by the United 

States government to describe the products, services, and research and development 

purchased by the government.

Product Service Code 

Description Textual description of Product Service Code. Explains the meaning of the 4-digit code.

SAM Entity Registration Product Service Code Child Object Response Fields –

Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

Product

Service Code pscCode Character 4

Example Values:

-AP31 - R&D- Natural

Resource: Mineral

(Basic

Research)

-Q524 - MedicalThoracic

-S203 - HousekeepingFood

-K010 - Modification of 

Equipment- Weapons

-L052 - Technical

RepresentativeMeasuring

Tools

A full list of codes can 

be found in the Federal 

Procurement Data 

System Product and 

Service Codes Manual.

 

Product

Service Code

Description

pscDescription Character 256
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

86

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SAM Entity Registration Product Service Code Child Object Response Fields –

Usage

The information below uses the examples from the main object and includes the additional information for 

the product service code (pscDetails) child object. Note that although the include value is “pscDetail” in 

the return data it is contained in the “pscDetails” element, as it can return more than one object per search.

URI /datasource (multi-resource search)

/datasource/samEnt

Access

Requirements Client’s Access Group must have access to samEnt datasource

Sample Response

{

"data": [

{

 "attributes": {

 "registrationStatus": "ACTIVE",

 "businessStartDate": "04/06/1993",

 "cageCode": "8XN89",

 "companyUrl": "www.johnsshoes.com",

 "eftIndicator": "5432",

 "mailForeignProvince": "ON",

 "physicalStreetAddressLine1": "221 BAKER ST",

 "physicalStreetAddressLine2": "SUITE B",

 "businessTerminationDate": "04/06/2017",

 "physicalStateCode": "ON",

 "physicalCountryCode": "CAN",

 "pscDetails": [

 {

 "pscCode": "-Q524 - Medical- Thoracic",

 "pscDescription": "SAMPLE DESCRIPTION",

 }

 ],

 "tin": "123456789",

 "mailCity": "ONTARIO",

 "physicalForeignProvince": "ON",

 "mailStateCode": "ON",

 "dba": "JOHNS SHOES EXPRESS",

 "abaRoutingNumber": "123",

 "delinquentFederalDebtFlag": "D",
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

87

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

 "accountType": "C",

 "mailCountryCode": "CAN",

 "accountNumber": "84357",

 "mailPostalCode": "64002",

 "physicalCity": "ONTARIO",

 "name": "JOHNS SHOES",

 "physicalPostalCode": "64002",

 "mailAddressLine1": "221 BAKER ST",

 "mailAddressLine2": "SUITE B",

 "uei": "987654321",

 "financialInstitute": "BANK"

 },

 "id": "908712671",

 "type": "samEnt"

}]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

88

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SAM Entity Registration Federal Supply Classification Child Object Response 

Fields – Definitions

Data Element Definition

Federal Supply 

Classification Code

Federal Supply Classification Code: A subset of Product Service Code. Federal Supply 

Class (FSC) codes are used to group products into logical families for management 

purposes. They are four-digit fields.

Federal Supply 

Classification Description

Textual description of Federal Supply Classification Code. Explains the meaning of the 

four-digit FSC.

SAM Entity Registration Federal Supply Classification Child Object Response 

Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

Federal

Supply

Classification

Code

fscCode Character 4

Example Values: 6520 

- Dental

Instruments,

Equipment, and

Supplies

7644 - Digital Maps,

Charts and Geodetic

Products

8915 - Fruits and

Vegetables

1345 - Land Mines

5530 - Plywood and

Veneer

Federal

Supply

Classification

Description

fscDescription Character 256
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

89

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SAM Entity Registration Federal Supply Classification Child Object Response 

Fields – Usage

The information below uses the examples from the main object and includes the additional information for 

the federal supply classification (fscDetails) child object. Note that although the include value is 

“fscDetail,” in the return data it is contained in the “fscDetails” element, as it can return more than one 

object per search.

URI /datasource (multi-resource search)

/datasource/samEnt

Access

Requirements Client’s Access Group must have access to samEnt datasource

Sample Response

{

"data": [

{

 "attributes": {

 "registrationStatus": "ACTIVE",

 "businessStartDate": "04/06/1993",

 "cageCode": "8XN89",

 "companyUrl": "www.johnsshoes.com",

 "eftIndicator": "5432",

 "mailForeignProvince": "ON",

 "physicalStreetAddressLine1": "221 BAKER ST",

 "physicalStreetAddressLine2": "SUITE B",

 "businessTerminationDate": "04/06/2017",

 "physicalStateCode": "ON",

 "physicalCountryCode": "CAN",
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

90

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

 "fscDetails": [

 {

 "fscCode": "6520 - Dental Instruments, Equipment, and Supplies", 

"fscDescription": "SAMPLE DESCRIPTION",

 }

 ],

 "tin": "123456789",

 "mailCity": "ONTARIO",

 "physicalForeignProvince": "ON",

 "mailStateCode": "ON",

 "dba": "JOHNS SHOES EXPRESS",

 "abaRoutingNumber": "123",

 "delinquentFederalDebtFlag": "A",

 "accountType": "C",

 "mailCountryCode": "CAN",

 "accountNumber": "84357",

 "mailPostalCode": "64002",

 "physicalCity": "ONTARIO",

 "name": "JOHNS SHOES",

 "physicalPostalCode": "64002",

 "mailAddressLine1": "221 BAKER ST",

 "mailAddressLine2": "SUITE B",

 "uei": "987654321",

 "financialInstitute": "BANK"

 },

 "id": "908712671",

 "type": "samEnt"

}]
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

91

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SAM Entity Registration SBA Code Child Object Response Fields – Definitions

Data Element Definition

SBA Code Small Business Administration Code. Examples include: A4, A6, JT, XX.

SBA Description Textual description of the SBA Code.

SAM Entity Registration SBA Code Child Object Response Fields – Technical 

Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

SBA Code sbaCode Character 2

Example Values:

A4 - SBA Certified

Small Disadvantaged

Business

A6 - SBA Certified 8(a)

Program Participant

JT - SBA Certified 8(a)

Joint Venture

XX - SBA Certified Hub 

Zone Firm

A full list of codes can 

be found in the SAM 

Functional Data 

Dictionary.

SBA

Description sbaDescription Character 256

Examples include: 

A4=SBA Certified

Small Disadvantaged 

Business, A6=SBA

Certified 8A Program

Participant, JT=SBA

Certified 8A Joint

Venture, XX=SBA

Certified Hub Zone

Firm
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

92

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SAM Entity Registration SBA Code Child Object Response Fields – Usage

The information below uses the examples from the main object and includes the additional information for 

the federal SBA code (smallBusiness) child object. Note that although the include value is 

“smallBusiness,” in the return data it is contained in the “smallBusinesses” element, as it can return more 

than one object per search.

URI

/datasource (multi-resource search)

/datasource/samEnt 

Access

Requirements

Client’s Access Group must have access to samEnt datasource

Sample 

Response

{

"data": [

{

 "attributes": {

 "registrationStatus": "ACTIVE",

 "businessStartDate": "04/06/1993",

 "cageCode": "8XN89",

 "companyUrl": "www.johnsshoes.com",

 "eftIndicator": "5432",

 "mailForeignProvince": "ON",

 "physicalStreetAddressLine1": "221 BAKER ST",

 "physicalStreetAddressLine2": "SUITE B",

 "businessTerminationDate": "04/06/2017",

 "physicalStateCode": "ON",

 "physicalCountryCode": "CAN",

 "smallBusinesses": [

 {

 "sbaCode": "A4 - SBA Certified Small Disadvantaged Business", "sbaDescription": 

"SAMPLE DESCRIPTION",

 }

 ],
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

93

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

 "tin": "123456789",

 "mailCity": "ONTARIO",

 "physicalForeignProvince": "ON",

 "mailStateCode": "ON",

 "dba": "JOHNS SHOES EXPRESS",

 "abaRoutingNumber": "123",

 "delinquentFederalDebtFlag": "A",

 "accountType": "C",

 "mailCountryCode": "CAN",

 "accountNumber": "84357",

 "mailPostalCode": "64002",

 "physicalCity": "ONTARIO",

 "name": "JOHNS SHOES",

 "physicalPostalCode": "64002",

 "mailAddressLine1": "221 BAKER ST",

 "mailAddressLine2": "SUITE B",

 "uei": "987654321",

 "financialInstitute": "BANK"

 },

 "id": "908712671",

 "type": "samEnt"

}]
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

94

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SAM Entity Registration Address Information Child Object Response Fields –

Definitions

Data Element Definition

Name Point of Contact name.

Address 1 The first line of the address.

Address 2 The second line of the address.

Address Type Code Indicates which address type is captured.

City City

State State

Fax Fax Number

Foreign Province

Foreign Province; If outside the United States, this would be the Province of the foreign 

country.

Country Country

US Phone US Phone Number

ZIP Postal ZIP Code

SAM Entity Registration Address Information Child Object Response Fields –

Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

Name name Character 200

Address 1 addressLine1 Character 150

Address 2 addressLine2 Character 150

Address Type 

Code addressTypeCode Character 2

Values:

X5 - Alternate

Exclusion Address

X6 - D&B Address

X7 - DoDAAC Address

DM - Domestic Parent

Address

GL - Global Parent

Address

HQ - Headquarters

Parent Address

IR - IRS/TIN Address

FE - Mailing Address

OA - Other Address

PA - Physical Address

X8 - POC Address

B3 - Previous Business

Address

X9 - Primary Exclusion

Address

RI - Remittance

Address
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

95

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

City city Character 40 

State stateCode Character 2

Fax fax Character 13

Foreign 

Province

foreignProvince Character 55

Country countryCode Character 3

US Phone usPhone Character 16

ZIP postalCode Character 15

SAM Entity Registration Address Information Child Object Response Fields –

Usage

The information below uses the examples from the main object and includes the additional information for 

the address information (address) child object. Note that although the include value is “address,” in the 

return data it is contained in the “addresses” element, as it can return more than one object per search.

URI /datasource (multi-resource search)

/datasource/samEnt

Access

Requirements Client’s Access Group must have access to samEnt datasource

Sample Response

{

"data": [

{

 "attributes": {

 "eftIndicator": "5432",

 "mailForeignProvince": "ON",

 "physicalStreetAddressLine1": "221 BAKER ST",

 "physicalStreetAddressLine2": "SUITE B",

 "businessTerminationDate": "04/06/2017",

 "physicalStateCode": "ON",

 "physicalCountryCode": "CAN",

 "tin": "123456789",

 "mailCity": "ONTARIO",

 "physicalForeignProvince": "ON",

 "mailStateCode": "ON",

 "dba": "JOHNS SHOES EXPRESS",

 "abaRoutingNumber": "123",

 "delinquentFederalDebtFlag": "D",

 "accountType": "C",
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

96

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

 "mailCountryCode": "CAN",

 "accountNumber": "84357",

 "mailPostalCode": "64002",

 "physicalCity": "ONTARIO",

 "name": "JOHNS SHOES",

 "physicalPostalCode": "64002",

 "mailAddressLine1": "221 BAKER ST",

 "mailAddressLine2": "SUITE B",

 "uei": "987654321",

 "financialInstitute": "BANK"

 },

 "id": "908712671",

 "type": "samEnt"

}]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

97

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SYSTEM FOR AWARD MANAGEMENT (SAM) EXCLUSION RECORDS – PUBLIC AND 

RESTRICTED

☐ Your agency is approved to access this data source.

System for Award Management (SAM) Exclusion Records data source – Public and Restricted contains a 

list of individuals and firms excluded by federal government agencies from receiving new federal contracts. 

The Restricted version of this data source contains TIN information.

The SAM Exclusion list replaced General Services Administration’s (GSA’s) Excluded Parties List System 

(EPLS), which discontinued in 2012. References to EPLS remain in the DNP database, which you may 

note when reviewing certain sections of this document.

SAM Exclusion Search Fields – Definitions

Data Element Definition

TIN Taxpayer Identification Number. SSN/EIN/TIN of the individual on the exclusions list. 

Only searchable on the Sam Exclusion Restricted data source.

UEI (Unique Entity 

Identifier)

A twelve-character alpha-numeric identifier assigned to registered entities by the 

General Services Administration (GSA) for use within the System of Award Management 

(SAM).

First Name First name of the individual on the exclusions list.

Last Name Last name of the individual on the exclusions list.

Business Name The name of the business/entity on the exclusions list.

SAM Exclusion Search Fields – Technical Information

Data Element API Field Name Data 

Type Length Value / Format Nullable Notes

TIN tin Character 9 Yes

TIN can be used 

only for the 

Restricted version 

of SAM Exclusion. 

TIN is not 

available in the 

Public version of 

SAM Exclusion.

UEI uei Character 12 Yes

First Name firstName Character 50 Yes

Both first name 

and last name 

must be sent in 

the request.

Last Name lastName Character 50 Yes

Both first name 

and last name 

must be sent in 

the request.

Business Name businessName Character 200 Yes
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

98

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SAM Exclusion Response Fields – Definitions

Data Element Definition

Name Full name of individual or entity on the exclusions list.

TIN Taxpayer Identification Number. SSN/EIN/TIN of the individual on the exclusions list.

Address Line 1 Street Address Line 1 of the individual or entity on the exclusions list.

Address Line 2 Street Address Line 2 of the individual or entity on the exclusions list.

City City of the individual or entity on the exclusions list.

State State of the individual or entity on the exclusions list.

ZIP ZIP Code of the individual or entity on the exclusions list.

Country Country of the individual or entity on the exclusions list.

SAM Number

The internal number used by SAM to identify exclusion records. Since only Firm 

exclusion records are required to have a UEI Number, SAM needed a way to uniquely 

track exclusion records of other Classification Types.

Cage Code

Commercial And Government Entity (CAGE) Code is a five-character ID number used 

extensively within the U.S. federal government, assigned by the Department of 

Defense’s Defense Logistics Agency (DLA). The CAGE code provides a standardized 

method of identifying a given facility at a specific location.

Exclusion Code Identifies if the exclusion is Reciprocal, Nonprocurement or Procurement.

Exclusion Type

Identifies the exclusion type that the exclusion falls under. Exclusion type is the 

successor to the CT code identifying the exclusion reason. Exclusion Type is a 

simplified, easier to understand way of identifying exclusion reasons. The types are 

generally “Prohibition/Restriction”, "Voluntary Exclusion", or “Ineligible.” In some 

cases, the type may indicate “Proceedings Pending” or “Proceedings Completed.”

Exclusion Description This field provides the agency performing the exclusion space to enter additional 

information as necessary, often an explanation on why the entity is being excluded.

Classification Classification Type: Individual, Firm, Vessel, or Special Entity Designation

Create Date Identifies when the data was first entered into SAM Exclusions.

Action Date The date that the exclusion became active.

Termination Date Identifies the date that the exclusion is/was to be terminated. If "indefinite" is in this 

field, there is no set date that the exclusion will terminate.

Agency The name of the agency that assigned the exclusion to the entity or individual.

UEI

A twelve-character alpha numeric identifier assigned to registered entities by the 

General Services Administration (GSA) for use within the System of Award Management 

(SAM).

Agency UEI UEI of the agency that registered the exclusion.

NPI

National Provider Identifier. The NPI replaced the UPIN as the unique number used to 

identify health care providers other than by SSNs. The Centers for Medicaid & Medicare 

Services first began assigning NPIs in 2006, and providers were required to use NPIs 

as of mid-2008.

As-of Date The date that the data source resource was last updated.
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

99

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SAM Exclusion Response Fields – Technical Information

Data Element API Field Name Data Type Length Value / Format Nullable Notes

Name name Character 200 Yes

TIN tin Character 9 No

Only available 

in SAM 

Exclusion 

Restricted. Not 

available in 

SAM Exclusion 

Public.

Address Line 1 addressLine1 Character 150 No

Address Line 2 addressLine2 Character 150 No

City city Character 50 No

State stateCode Character 2 No

ZIP postalCode Character 10 No

Country countryCode Character 3 No

SAM Number samNumber Character 9 No

Cage Code cageCode 5 No

Only available 

in SAM 

Exclusion

Restricted. Not 

available in 

SAM Exclusion 

Public.

Exclusion 

Program exclusionCode Character 50 No

Exclusion Type exclusionType Character 50 No

Exclusion 

Description exclusionDescription Character 256 No

Classification classification Character 256 No

Create Date createDate Character 10 MM/DD/YYYY No

Action Date actionDate Character 10 MM/DD/YYYY No

Termination 

Date terminationDate Character 10

MM/DD/YYYY 

May also contain 

the value 

"INDEF."

No

Agency agency Character 256 No

UEI uei Character 12 Yes

Agency UEI agencyUei Character 12 Yes

NPI npi Character 100 No

Source Sys 

Type Code 

Description

srcSysTypeCdDesc Character 20 SAM-EXCL-RES No

As-of Date asOfDate Date 10 MM/DD/YYYY No
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

100

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

SAM Exclusion Records Usage

In the usage of the DNP API, the long names samExPub and samExRes are used for SAM Exclusion 

records (Public and Restricted, respectively).

The examples below are all using samExRes, but the usage is the same for samExPub.

URI /datasource (multi-resource search)

/datasource/samExRes

Access 

Requirements Client’s Access Group must have access to samExRes or samExPub

Sample Response

{

"data": [

{

 "attributes": {

 "tin": "987654321",

 "name": "JOHN DOE",

 "exclusionCode": "RECIPROCAL",

 "exclusionType": "PROHIBITION/RESTRICTION",

 "exclusionDescription": "SAMPLE DESCRIPTION",

 "agency": "HEALTH AND HUMAN SERVICES, DEPARTMENT OF",

 "addressLine1": "123 2ND ST",

 "addressLine2": "SUITE B",

 "city": "KANSAS CITY",

 "stateCode": "MO",

 "postalCode": "64001",

 "countryCode": "US",

 "cageCode": "7SXB4",

 "classification": "INDIVIDUAL",

 "terminationDate": "INDEF.",

 "uei": "UEI3AE221107",

 "agencyUei": "AGUEI55A1107",

 

 "samNumber": "AA427A1",

 "actionDate": "11/20/2005",

 "createDate": "04/19/2007",

 "npi": "123456789",

 "srcSysTypeCdDesc": "SAM-EXCL-RES"

 },

 "id": "661971351",

 "type": "samExRes"

}]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

101

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

TREASURY OFFSET PROGRAM (TOP) DEBT CHECK

☐ Your agency is approved to access this data source.

The Treasury Offset Program (TOP) Debt Check data source is a centralized offset program, administered 

by the U.S. Treasury’s Bureau of the Fiscal Service (Fiscal Service) Disbursing and Debt Management 

(DDM). TOP collects past-due (delinquent) debts (for example, child support payments) that people owe to 

state and federal agencies.

Fiscal Service disburses federal payments, such as federal tax refunds for agencies making federal 

payments (known as "payment agencies"), such as the Internal Revenue Service. "Creditor agencies," such 

as the Department of Education submit delinquent debts to Fiscal Service for collection and inclusion in 

TOP, TOP matches people and businesses who owe delinquent debts with money that federal agencies are 

paying (for example, a tax refund). To the extent allowed by law, when a match happens, TOP withholds 

(offsets) money to pay the delinquent debt.

TOP Debt Check is a Restricted data source.

TOP Debt Check Search Fields – Definitions

Data Element Definition

TIN Debtor TIN refers to the TIN (SSN for individual, EIN for business or entity) of debtor.

First Name First name of the individual debtor.

Last Name Last name of the individual debtor.

Business Name Name of business or entity debtor.

TOP Debt Check Search Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

TIN tin Character 9 Yes

First Name firstName Character 35 Yes

Both first name and 

last name must be 

sent in the request.

Last Name lastName Character 35 Yes

Both first name and 

last name must be 

sent in the request.

Business 

Name businessName Character 200 Yes
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

102

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

TOP Debt Check Response Fields – Definitions

Data Element Definition

Debtor TIN Debtor TIN refers to the TIN (SSN for individual, EIN for business or entity) of debtor.

Debtor Name Name of Debtor.

Individual Business 

Indicator An identifier that classifies the debtor as either an individual ("I" or a business "B").

Debtor Street Address 

Line 1 Address line one of debtor's residence/location.

Debtor Street Address 

Line 2 Address line two of debtor's residence/location.

Debtor City City of debtor's residence/location.

Debtor State State of debtor's residence/location.

Debtor ZIP ZIP code of debtor's residence/location.

Debtor Country Country of debtor's residence/location.

Debt Number Agency Debt Number or Agency Account Number— the unique account number used to 

identify the debt account owed by an individual or business to the creditor agency.

Date of Delinquent Debt Date of delinquency for a specific record.

Debt Type

Code for type of debt assigned by TOP. Examples include:

1-Child Support - AFDC

6-Federal Agency Debt

17-IRS-17

CD-Corporate Debt

OS-Other State Debt

UT-Unemployment Compensation Tax Debts

Debt Type Description Text description of the debt type. See above for example descriptions.

Debt Agency Site Name Creditor agency (origin of debt).

Debt Agency Site 

Contact Name Main contact at creditor agency.

Debt Agency Site 

Address Line 1 Address line one of creditor agency.

Debt Agency Site 

Address Line 2 Address line two of creditor agency.

Debt Agency Site City City of creditor agency.

Debt Agency Site State State of creditor agency.

Debt Agency Site ZIP ZIP code of creditor agency.

Debt Agency Phone 

Number Main phone number at creditor agency.

Debt Agency Phone 

Extension Main phone number extension at creditor agency.

Debt Agency National 

Phone Number Respective national collection office phone number of creditor agency.

Debt Agency National 

Phone Extension Respective national collection office phone number extension of creditor agency.

As-of Date The date that the data source resource was last updated.
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

103

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

TOP Debt Check Response Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

Debtor TIN tin Character 9 No

Debtor 

Name name Character 200 Yes

Individual 

Business 

Indicator

individualBusinessIndicator Character 1 Values: I or B Yes

Debtor 

Street

Address 

Line 1

debtorAddressLine1 Character 30 Yes

Debtor 

Street

Address 

Line 2

debtorAddressLine2 Character 30 Yes

Debtor City debtorCity Character 25 Yes

Debtor State debtorStateCode Character 2 Yes

Debtor ZIP debtorPostalCode Character 9 Yes

Debtor 

Country debtorCountryCode Character 3 Yes

Debt 

Number debtNumber Character 18 Yes

Date of 

Delinquent 

Debt

delinquentDebtDate Character 10 Format: 

MM/DD/YYYY Yes

Debt Type debtType Character 2

Example Values:

1-Child Support -

AFDC

6-Federal Agency 

Debt

17-IRS-17

CD-Corporate Debt

OS-Other State 

Debt

UT-Unemployment

Compensation Tax

Debts

Yes

Debt Type 

Description debtTypeDescription Character 256 Yes
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

104

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

Debt 

Agency Site 

Name

debtAgencySiteName Character 35 Yes

Debt 

Agency Site 

Contact 

Name

debtAgencySiteContactName Character 35 Yes

Debt 

Agency Site 

Address 

Line 1

debtAgencySiteAddressLine1 Character 35 Yes

Debt 

Agency Site 

Address 

Line 2

debtAgencySiteAddressLine2 Character 35 Yes

Debt 

Agency Site 

City

debtAgencySiteCity Character 25 Yes

Debt 

Agency Site 

State

debtAgencySiteStateCode Character 2 Yes

Debt 

Agency Site 

ZIP

debtAgencySitePostalCode Character 9 Yes

Debt 

Agency 

Phone 

Number

debtAgencyPhoneNumber Character 10 Yes

Debt 

Agency 

Phone 

Extension

debtAgencyPhoneExtension Character 4 Yes

Debt 

Agency

National 

Phone 

Number

debtAgencyNationalPhoneNumber Character 25 Yes

Debt 

Agency 

National 

Phone 

Extension

debtAgencyNationalPhoneExtension Character 4 Yes

Source Sys 

Type Code 

Description

srcSysTypeCdDesc Character 20 DBCK No
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

105

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

As-of Date asOfDate Date 10 MM/DD/YYYY No

TOP Debt Check Usage

URI /datasource (multi-resource search)

/datasource/dbck

Access

Requirements Client’s Access Group must have access to the Top Debt Check (dbck) datasource

Sample Response

{

"data": [

{

 "attributes": {

 "tin": "732904154",

 "name": "JOHN DOE",

 "debtType": "01",

 "debtNumber": "1122334455",

 "debtTypeDescription": "SAMPLE DESCRIPTION",

 "individualBusinessIndicator": "I",

 "delinquentDebtDate": "10/16/2010",

 "debtTypeDescription": "CHILD SUPPORT - AFDC",

 "debtorAddressLine1": "123 2nd St",

 "debtorAddressLine2": "Suite A",

 "debtorCity": "KANSAS CITY",

 "debtorStateCode": "MO",

 "debtorPostalCode": "64001",

 "debtorCountryCode": "US",

 "debtAgencyPhoneNumber": "555-555-5555",

 "debtAgencyPhoneExtension": "7",

 "debtAgencyNationalPhoneNumber": "888-888-8888",

 "debtAgencyNationalPhoneExtension": "200",

 "debtAgencySiteContactName": "SAMPLE CONTACT",

 "debtAgencySitePostalCode": "64001",

 "debtAgencySiteCity": "KANSAS CITY"

 "debtAgencySiteStateCode": "MO",

 "debtAgencySiteAddressLine1": "815 BEAKER ST",

 "debtAgencySiteAddressLine2": "SUITE 201",

 "debtAgencySiteName": "SAMPLE DEBT AGENCY",
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

106

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

 "srcSysTypeCdDesc": "DBCK"

 },

 "id": "10442391",

 "type": "dbck"

 }]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

107

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

Match Outcome Transmittal

Match outcomes help DNP and agencies easily measure prevented improper payment of federal dollars to 

entities and individuals whose match status renders them ineligible to receive those dollars. The match 

outcome transmittal can occur any time after the match data is received by the agency. Match outcome 

transmittal fields will link the original search results returned to the agency to the outcome achieved by the 

search. This service accepts POST requests, and it requires the client to provide information from the 

original search. Note that this service requires the client to provide a “transaction-id” field in the meta 

section of the message.

This should be the transaction id from the original search which relates to the Outcome being provided. 

Please see the sample message below for more details.

Match Outcome Transmittal Fields – Definitions

Data Element Definition

Matching Data Source This is a one-to-many list of data sources that were the source of the original match returned to 

the agency. Found in the original response transmittal as “type.” This is an optional field.

Matching Party ID This is a one-to-many list of party ids that were the source of the original match returned to the 

agency. Found in the original response transmittal as “id.” This is an optional field.

Dollars Saved Flag

A “YES” or “NO” statement that declares whether the match associated with the outcome 

transmittal resulted in a decision not to disburse federal dollars. (YES = match resulted in not 

disbursing federal dollars) This is a required field, value must be either “YES” or “NO”.

Dollars Saved Amount The dollar amount of federal dollars not disbursed due to the match. This is an optional field. 

Note that this is a text field.

Payment Frequency

The frequency of payment of the declared Dollar Amount; useful in calculating total dollars saved 

when the amount would have been disbursed more than once, if the entity searched had been 

paid. Response options: Annual; Contract/Award Total; Daily; Monthly; One-time; Other. This is 

an optional field.

Payee Category

The type of payee the entity searched represents. Response options: Allotment, Annuity, Benefit, 

Child Support, Education, Fee, Insurance, Miscellaneous, Refund, Salary, Thrift, Travel, Vendor. 

This is an optional field.

No Saving Reason

The reason a match to a data source did not result in disqualifying the searched entity from 

payment. Response Options: Business reason to pay, Data source is not applicable to payee, Data 

source match is not the actual payee, Services performed - must pay, Other. This is an optional 

field.

Comments This is a free-form entry field (alpha-numeric), should the agency wish to explain any of the 

answers above, or make a note about the match outcome. This is an optional field.
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

108

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

Match Outcome Transmittal Fields – Technical Information

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

Matching 

Data Sources data sources Array of Strings 255

Possible values:

aisObituary

aisProbate

caivrs

dbck

dmf

dod

dos

ofac

samExPub

samExRes

leiePublic

leiePrivate

samEnt

Yes

Matching 

Party ID recordIds Array ofStrings 255 Yes

Dollars Saved 

Flag dollarsSaved Character 5

Valid values: “YES” or 

“NO” No

Dollars Saved

Amount dollarAmountSaved Character 20

Text field but it must 

contain a valid 

number. Decimal

values are allowed

Yes

Payment 

Frequency paymentFrequency Character 255

Valid values:

Annual

Contract/Award Total

Daily

Monthly

One-time Other

Yes

If value other 

than those listed 

is sent, an error 

will be returned. 

The Comments 

field can be 

used to explain 

the "Other" 

value.

Payee 

Category payeeCategory Character 255

Valid Values:

Allotment

Annuity

Benefit

Child Support

Education

Fee

Insurance

Miscellaneous

Refund

Salary

Thrift

Travel

Vendor

Yes

If value other 

than those listed 

is sent, an error 

will be returned. 

The Comments 

field can be 

used to explain 

the "Other" 

value.
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

109

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

Data 

Element API Field Name Data Type Length Value / Format Nullable Notes

No Saving 

Reason noSavingsReason Character 255

Values:

Business reason to pay 

Data source is not 

applicable to payee 

Data source match is 

not the actual payee 

Services performed -

must pay Other

Yes

If value other 

than those listed 

is sent, an error 

will be returned. 

The Comments 

field can be 

used to explain 

the "Other" 

value.

Comments comments Character 255 Yes
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

110

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

Match Outcome Transmittal Fields – Usage

This service accepts POST requests. There is only a single service endpoint used to receive Outcome 

messages. The response from a successful request will be a 201 status code and message with an empty 

“data” element. If an error is produced the response code will be either 400 or 500 and the “error” element 

will contain these details. Note that the sample message below contains the meta section as that is how a 

client will relay the original transaction id.

URI /outcome

Access 

Requirements Client’s Access Group must have access to at least one datasource

Sample Requests /outcome

Sample Message

 {

 "data": [{

 "attributes": {

 "noSavingsReason": "Services performed - must pay",

 "comments": "Sample comments for testing",

 "payeeCategory": "Benefit",

 "dollarAmountSaved": “1001”,

 "dollarsSaved": “YES”,

 "paymentFrequency": "Annual",

 "data sources": [

 "dmf",

 "ofac"

 ],

 "recordIds": [

 "12345",

 "6789"

 ]

 },

 "type": "outcome"

 }],

 "meta": {"transaction-id": "123456789"}

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

111

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

APPENDIX A

JSON API examples

The jsonapi.org site includes several fictional examples based on article/author data. Below are some of 

the examples using Do Not Pay standards for URI and message body formatting. Note that the standard 

date format used in the DNP API is MM/DD/YYYY unless specifically stated otherwise. The examples 

have been altered to reflect this.

Sparse Fieldsets

The DNP API supports the following example for include statements:

POST /articles “include”:”author”

However note that in this example, the included object (author) would not have its own type/id attribute, 

and therefore no ‘relationship’ or ‘included’ element or would be provided as it is in the response to this 

example:

{

 "data": [{

 "type": "articles",

 "id": "1",

 "attributes": {

 "title": "JSON API paints my bikeshed!",

 "body": "The shortest article. Ever.",

 "created": "05/22/2015",

 "updated": "05/22/2015"

 },

 "relationships": {

 "author": {

 "data": {"id": "42", "type": "people"}

 }

 }

 }],

 "included": [

 {

 "type": "people",

 "id": "42",

 "attributes": {

 "name": "John",
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

112

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

 "age": 80,

 "gender": "male"

 }

 }

 ]

}

Also note that the above example could have the parent resource of the included object in [] brackets if 

that’s preferred, as shown below:

POST /articles “include[article]”:”author”

The fields parameter used with Sparse fieldsets is supported exactly as the examples show:

POST /articles “include”:”author”, “fields[articles]”:”title,body”, “fields[people]”:”name”

In the example above, the only fields returned for the articles object would be title and body, and only 

name would be returned for the people object.
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

113

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

Pagination

Client-provided pagination parameters can only be provided using page[number] and page[size], and the 

resulting data looks the same as the jsonapi.org examples, with an added description element 

accompanying each link. In addition, when pagination is used the elements total-pages, total-count, pagesize, and current-page will be present in the meta section. The example request:

POST /articles “page[number]”:”3”,”page[size]”:”1”

Would therefore result in the following response:

{

 "meta": {

 "total-pages": “13”

 "total-count": “13”

 "page-size": “1”

 "current-page": “3”

 },

 "data": [

 {

 "type": "articles",

 "id": "3",

 "attributes": {

 "title": "JSON API paints my bikeshed!",

 "body": "The shortest article. Ever.",

 "created": "05/22/2015",

 "updated": "05/22/2015"

 }

 }

 }

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

114

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

Error Objects

The only error elements currently supported by the DNP API are status, title, and detail. In 

nonproduction environments there may be additional information returned in the ‘meta’ element nested 

within ‘errors.’ The first name error example provided from jsonapi.org would look like this:

In certain situations multiple errors may be returned. As noted in the JSON API section of the document 

above, errors will always be returned with an HTTP status code of 400 or 500 with only the ‘errors’ 

element in the document.

{

 "errors": [

 {

 "status": "422",

 "title": "Invalid Attribute",

 "detail": "First name must contain at least three characters."

 }

 ]

}
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

115

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

APPENDIX B

Certificate Request and Generation Instructions

In order to establish and test the connection to DNP’s QA and Production API application servers, the 

appropriate web server certificates are required. The DNP API Technical Project Management Team 

will request these certificates from the Treasury Operational Certificate Authority (TOCA) – one for 

QA environment testing and one for Production.

A representative from the API Technical Project Management Team will provide you with a reference 

number and an authorization code – one set for each certificate to be issued (QA and Production). Once 

you have obtained these codes, use the following links to navigate to the U.S. Treasury Operational 

Certification Authority certificate generation sites:

DEV(QA/non-Prod): https://api-preprod.fiscal.treasury.gov/ap/acc/exp/v1/service-security/web

PROD: https://api.fiscal.treasury.gov/ap/exp/v1/service-security/web

Enter the Reference Number and Authorization Code provided by the Technical Project Management 

Team and enter a strong Keystore Password of your choosing. To retrieve your certificate, click on the 

[Get my certificate] button on the form. You will then save your certificate to the appropriate server or 

truststore.

 
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

116

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

APPENDIX C

List of Acronyms

ABA ..................................... American Banking Association

ARL ..................................... Automatic Revocation of Exemption List

CAGE ................................... Commercial and Government Entity

CAIVRS ............................... Credit Alert System

CCR ...................................... Central Contractor Registration

CMS ..................................... Centers for Medicare and Medicaid Services

DBA ..................................... Database Administrator

DBCK ................................... Debt Check

DMF-Full ...............................Death Master File-Full

DNP ...................................... Do Not Pay

DOJ ...................................... Department of Justice

DDM ..................................... Disbursing and Debt Management

EFT ....................................... Electronic Funds Transfer

EIN ....................................... Employer Identification Number

EPLS .................................... Excluded Parties List System

FSC ....................................... Federal Supply Class

Form 990-N............................Form 990-N (e-Postcard)

GSA ...................................... General Services Administration

HHS ...................................... Health and Human Services

HREF..................................... Hypertext REFerence

HTTP .................................... Hypertext Transfer Protocol

HTTPS .................................. Hypertext Transfer Protocol Secure

HUD ..................................... Housing and Urban Development

JSON API ............................. JavaScript Object Notation Application Program Interface

LEIE ..................................... List of Excluded Individuals and Entities

NAICS .................................. North American Industry Classification System

NCAGE ................................ NATO Commercial and Government Entity

OIG ....................................... Office of the Inspector General

OFAC ................................... Office of Foreign Assets Control

PC ......................................... Personal Computer
CONTROLLED UNCLASSIFIED INFORMATION

Do Not Pay Portal API Implementation Guide 

Last Updated: June 2024

117

CONTROLLED UNCLASSIFIED INFORMATION

TREASURY SBU/CUI // EXTERNAL

PUB 78 ................................. Publication 78

REST .................................... REpresentational State Transfer

SAM ..................................... System for Award Management

SBA ...................................... Small Business Administration

SDN ...................................... Specially Designated Nationals

SOAP .................................... Simple Object Access Protocol

SSL ....................................... Secure Socket Layer

SSN ...................................... Social Security Number

TIN ....................................... Tax Identification Number

TOCA ................................... Treasury Operational Certificate Authority

TOP ...................................... Treasury Offset Program

UEI ....................................... Unique Entity Identifier

URI ....................................... Uniform Resource Identifier

URL ...................................... Uniform Resource Locator

USDA ................................... United States Department of Agriculture

VA ........................................ Veterans Affairs