Dartmouth API Developer Portal
Grants Accounting API
Request
GET /api/grants_accounting/accounts/{ptaeo_string}
or
GET /api/grants_accounting/accounts?attribute=query
Required Scopes
None
Required Headers
Authorization: Bearer {jwt}
Parameters
None
Notes on usage
The Grants Accounting API operates in 2 modes based on the calling pattern. If a full 5 segment PTAEO string is passed to the service then an account validation is performed in real time for validity and returns Payload Description 1 below.
NOTE: Calling the API in this mode is the only way to determine real time validity for use in transactions.
In the second mode of use, if the API is called using query parameters the API can be used to generically search for and find PTA combinations. See documentation on filtering and paging for details on how to fully utilize this capability. When used in this mode the payload available for searching and returned from the API is described in Payload Description 2 below.
The api should always return a status code of 200 as long as the backend database service is available (NOTE that periodic maintenance may make the database unavailable). The backend service always tries to match and validate as much of the URI parameter {chart_string} as possible. You must look at the result flags of is_well_formed, is_legal in order to determine that status of the {ptaeo_string}. Checking the is_legal flag should be examined for determining if the {ptaeo_string} is legal to use in a transaction.
Mode 2 relies on a cached version of the data and therefore is highly available.
Mode 1 Call
Returns
| Status Code | Description |
|---|---|
| 200 | The Account Lookup completed |
| 500 | The database is unavailable |
| Field | Type | Description |
|---|---|---|
| is_well_formed | boolean | equals true if well formed, otherwise false |
| is_fully_formed | boolean | if all five segments present, then this equals true, otherwise false |
| is_legal | boolean | equals true if a legal segment combination, otherwise false |
| project_segment_length | number | |
| project_format_mask | string | |
| is_project_well_formed | boolean | |
| project_segment_value | number | |
| project_id | number | |
| project_description | string | |
| project_status | string | |
| project_completion_date | string | |
| task_name | string | |
| task_segment_length | number | |
| task_format_mask | string | |
| is_task_well_formed | boolean | |
| task_segment_value | string | |
| task_id | number | |
| task_description | string | |
| award_name | string | |
| award_segment_length | number | |
| is_award_well_formed | boolean | |
| award_segment_value | string | |
| award_id | number | |
| award_description | string | |
| award_award_status | string | |
| award_allowable_schedule_id | number | |
| award_end_date | string | |
| award_gl_funding | string | |
| is_award_federally_funded | boolean | |
| exp_type_name | string | |
| exp_type_segment_length | number | |
| exp_type_format_mask | string | |
| is_exp_type_well_formed | boolean | |
| exp_type_segment_value | string | |
| exp_type_id | number | |
| exp_type_expenditure_type | string | |
| exp_type_description | string | |
| exp_type_exp_start_date_active | date string | |
| exp_type_exp_end_date_active | date_string | |
| exp_type_sysl_start_date_active | date string | |
| exp_type_sysl_end_date_active | date string | |
| org_name | string | |
| org_segment_length | number | |
| org_format_mask | string | |
| is_org_well_formed | boolean | |
| org_segment_value | string | |
| org_id | number | |
| org_description | string | |
| short_description | string | |
| concatenated_str | string | |
| parse_error_desc | string | |
| validation_error_desc | string |
Sample Request
https://api.dartmouth.edu/api/grants_accounting/accounts/514282.6000.C00030.8501A.843
Payload Description 1 Sample Return
{
"is_well_formed": true,
"is_fully_formed": true,
"is_legal": true,
"project_segment_length": 6,
"project_format_mask": "NNNNNN",
"is_project_well_formed": true,
"project_segment_value": "514282",
"project_id": 1864713,
"project_description": "CBI",
"project_status": "ACTIVE",
"project_completion_date": "2018-03-31T04:00:00Z",
"task_name": "task",
"task_segment_length": 4,
"task_format_mask": "NNNN",
"is_task_well_formed": true,
"task_segment_value": "6000",
"task_id": 1999330,
"task_description": "Internally Funded",
"award_name": "award",
"award_segment_length": 6,
"award_format_mask": "AENNNN",
"is_award_well_formed": true,
"award_segment_value": "C00030",
"award_id": 945,
"award_description": "RE-THAY-Subvention",
"award_award_status": "ACTIVE",
"award_allowable_schedule_id": 2,
"award_end_date": "2021-07-31T04:00:00Z",
"award_gl_funding": "368002",
"is_award_federally_funded": false,
"exp_type_name": "expense_type",
"exp_type_segment_length": 5,
"exp_type_format_mask": "NNNNA",
"is_exp_type_well_formed": true,
"exp_type_segment_value": "8501A",
"exp_type_id": null,
"exp_type_expenditure_type": "8501A FAC ADMIN Cost Sharing",
"exp_type_description": "FAC ADMIN Cost Sharing",
"exp_type_exp_start_date_active": "1951-01-01T05:00:00Z",
"exp_type_exp_end_date_active": null,
"exp_type_sysl_start_date_active": "1951-01-01T05:00:00Z",
"exp_type_sysl_end_date_active": null,
"org_name": "org",
"org_segment_length": 3,
"org_format_mask": "NNN",
"is_org_well_formed": true,
"org_segment_value": "843",
"org_id": 6887,
"org_description": "Chem/Biochem Thayer",
"short_description": "CBI:RE-THAY-Subvention",
"pta_str": "514282.6000.C00030",
"concatenated_str": "514282.6000.C00030.8501A.843",
"parse_error_desc": null,
"validation_error_desc": null
}
Mode 2 Call
Notes on usage
Calling this endpoint with query parameters immediately puts the API into Mode 2, or search mode. All of the attributes in the payload are available for query (see Basic filtering and paging documentation for more information). Both active and inactive projects are available. A collection is always returned with the search results.
Example Search Parameter
https://api.dartmouth.edu/api/grants_accounting/accounts?pta_str=*B02766*
Payload Description 2 Sample Return
[
{
"project_number": "514706",
"project_name": "UVM EPSCoR 2016 - Year 3",
"project_completion_date": "2019-05-31T04:00:00Z",
"pta_desc": "UVM EPSCoR 2016 - Year 3:Externally Funded:UVM EPSCoR 2016 - Year 3",
"short_desc": "UVM EPSCoR 2016 - Year 3:UVM EPSCoR 2016 - Year 3",
"task_number": "5000",
"gl_funding": "126500",
"task_name": "Externally Funded",
"concatenated_desc": "UVM EPSCoR 2016 - Year 3:Externally Funded:UVM EPSCoR 2016 - Year 3:Geography",
"project_status_code": "CLOSED",
"federally_funded": "N",
"award_short_name": "UVM EPSCoR 2016 - Year 3",
"award_number": "B02766",
"task_completion_date": "2019-05-31T04:00:00Z",
"ptaeo_str": "514706.5000.B02766.xxxx.483",
"award_status": "CLOSED",
"pta_str": "514706.5000.B02766",
"award_end_date": "2019-05-31T04:00:00Z",
"org": "483",
"chargeable_flag": "Y",
"org_desc": "Geography",
"ptao_str": "514706.5000.B02766..483",
"sponsor_name": "Nat’l Inst of Child Health & Human Devel (NICHD",
"sponsor_award_number": "ANT-0440523",
"principal_investigators": [
{
"pi_name":"Baker, Ian",
"netid":"d23329t"
}
],
"cfda_numbers": [
{
"cfda_number":"47.078"
}
]
}
]