Relational Datastore with API Access
GivingTuesday provides users with an application program interface (API) to query data from our relational data store. You can find the list of fields accessible through each endpoint via our data dictionary. This option requires the user to open a free AWS account – please note that you will not be charged for using the Data Lake. To access via a free AWS account, you will need to enter your billing information per AWS validation protocol. You can find out more at aws.amazon.com/free.
Access
The GivingTuesday API has open access an does not require any user authentication. However, there is a rate limit of 300 requests over 5 minutes, if you require a higher rate limit, please contact the GivingTuesday team through this feedback form.
Request Format
The API only accepts GET requests. All requests begin with: https://990-infrastructure.gtdata.org
Response Format
The GivingTuesday API responses are available in JSON format.
Parameters
- We are using Query Strings as EIN
- Pass EIN keyword in lowercase i.e. ein= not EIN=
- When passing EINs as parameters they must be 9 digits
- Do not pass hyphens in EINs i.e. use 123456789 instead of 12-3456789
- Prefix EINS with 0’s for those shorter than 9 digits i.e. 000123456
API Endpoints & Results
| Endpoint | Contents | Required Parameter | Sample Request | |
| GET /irs_data/990basic120fields | Form 990 Basic 120 Fields | ein | curl ‘https://990-infrastructure.gtdata.org/irs-data/990basic120fields?ein=842929872’ | |
| GET /irs_data/bmf | IRS Business Master File Extract | ein | curl ‘https://990-infrastructure.gtdata.org/irs-data/bmf?ein=530196605’ | |
| GET /irs_data/efilexml | Index of all available efiled xml files in GTDC data lake | ein | curl ‘https://990-infrastructure.gtdata.org/irs-data/efilexml?ein=842929872’ | |
| GET /irs_data/postcard | Form 990 N Postcard | ein | curl ‘https://990-infrastructure.gtdata.org/irs-data/postcard?ein=000100514’ | |
| GET /irs_data/pub78-deductible | Pub 78 Deductible Organizations | ein | curl ‘https://990-infrastructure.gtdata.org/irs-data/pub78-deductible?ein=000635913’ | |
| GET /irs_data/revoked | IRS Revoked Organizations which have lost their charity status | ein | curl ‘https://990-infrastructure.gtdata.org/irs-data/revoked?ein=000065837’ |
Results format
{
"statusCode": 200,
"headers": {
"content-type": "application/json"
},
"body": {
"query": "<provided ein>",
"no_results": <number of results found>,
"results": […]
}
}