List applications
GET /api/v1/admin/programs/<programSlug>/applicationsExport applications to a specific program as JSON.
Path parameters
Path component | Type | Description |
|---|---|---|
programSlug | string | Human readable identifier for the program to export. The CiviForm admin can find the slug for a given program by examining the deep link link URL on the program index page or in the list of allowed programs on the API key index page. |
Query parameters
Param name | Presence | Type | Description |
|---|---|---|---|
fromDate | optional | string | An ISO-8601 formatted date (i.e. YYYY-MM-DD). Limits results to applications submitted on or after the provided date. |
toDate | optional | string | An ISO-8601 formatted date (i.e. YYYY-MM-DD). Limits results to applications submitted before the provided date. |
pageSize | optional | uint | A positive integer. Limits the number of results per page. If pageSize is larger than CiviForm's maximum page size then the maximum will be used. The default maximum is 1,000 and is configurable. |
nextPageToken | optional | string | An opaque, alphanumeric identifier for a specific page of results. When included CiviForm will return a page of results corresponding to the token. |
Returned if any request parameters fail validation.
Returned if the API key is invalid or does not have access to the program.
For valid requests, CiviForm returns a status code 200 with a JSON body of the structure:
{
payload: Array<ProgramApplication>,
nextPageToken: string
}
Pagination
If there are more results for the request,
nextPageToken will be a string. If there are no more results to fetch it will be null. API consumers should request more pages using the nextPageToken until it returns null to ensure they have received a complete result set.If
nextPageToken is present the other query parameters are optional. Including them will not change the response of the request unless they differ from the values provided on the initial request, in which case CiviForm will reject the request as invalid.Payload
The value of the
payload key is an array of program application objects, each of the structure:{
program_name: string,
program_version_id: integer,
application_id: integer,
language: string,
submitter_email: string,
application: object
}
program_name the immutable admin name of the program.program_version_id the integer ID of the program version for this application.application_id the unique integer ID of this application.language an IETF language tag indicating the applicant's preferred language submitter_email either the applicant's email or trusted intermediary's, depending one which submitted the application.application the contents of the application. Structure of the application data is determined by the question and program configuration. Each question has a JSON path derived from its admin name and enumerator relationship and an answer object containing the answer scalars and metadata. Metadata includes a timestamp of when the scalar was updated, useful so that program administrators can see if data was provided at an earlier time and may be out of date.basic_question_path = \.[a-zA-Z_]+
index = [0-9]
enumerator_question_path = basic_question_path\[index\]
full_question_path = [enumerator_question_path]*basic_question_path
Question names are converted to paths by removing all non-alphabetic characters and replacing one or more spaces with an underscore (source).
Questions that are skipped are present but have null values for the skipped scalars. Scalar names and value types are determined by question type. Strings may contain unicode characters.
Question type export values
Question type | Scalar name | Value |
|---|---|---|
Address | street | string |
| line2 | string |
| city | string |
| state | string, two-character state code |
| zip | string, 5-character zip code |
Currency | currency_dollars | float with two digits of precision after the decimal |
Date | date | string, date formatted as an ISO 8601 date YYYY-MM-DD |
Email | email | string |
ID | id | string |
Multiselect | selections | array of strings, en-US localized strings of the selected options |
Name | first_name | string |
| middle_name | string |
| last_name | string |
Number | number | integer |
Single select | selection | string, en-US localized string of the selected option |
Text | text | string |
Updated at | updated_at | ISO 8601 date and time of when the scalar was updated |
Phone Number | phone_number | E.164 format |
Example export
{
"nextPageToken": "YXR0ZXJuIG9mIHZpb2xhdGlvbiBvZiBjb21tdW5pdHkKc3Rhb",
"payload": [{
"program_name": "Example Program With Enumerator",
"program_version_id": 912,
"applicant_id": 767,
"application_id": 866,
"language": "en-US",
"create_time": "2022-04-19T21:46:05.774Z",
"submitter_email": "Applicant",
"submit_time": "2022-04-19T21:46:05.774624Z",
"application": {
"phone":{
"phone_number":"+14258103298"
},
"applicant_favorite_color": {
"text": "brown",
"updated_at": "2022-03-31T18:02:11.822075Z"
},
"applicant_monthly_income": {
"currency_dollars": 3000.00,
"updated_at": "2022-03-31T18:02:11.822075Z"
},
"applicant_household_members": [
{
"household_members_name": {
"last_name": "Jameson",
"middle_name": null,
"first_name": "James",
"updated_at": "2022-03-31T18:02:11.822075Z"
},
"household_members_jobs": [
{
"household_members_days_worked": {
"number": 111,
"updated_at": "2022-03-31T18:02:11.822075Z"
}
},
{
"household_members_days_worked": {
"number": 222,
"updated_at": "2022-03-31T18:02:11.822075Z"
}
},
{
"household_members_days_worked": {
"number": 333,
"updated_at": "2022-03-31T18:02:11.822075Z"
}
}
]
}
],
"applicant_name": {
"last_name": "Doe",
"middle_name": null,
"first_name": "John",
"updated_at": "2022-03-31T18:02:11.822075Z"
}
}
}]
}
Example client code: python
Requesting applications to a program named "Utility discount program" between January 3, 2022 and February 4, 2022, with a page size of 100.
example_request.py
1
import json
2
import os
3
import requests
4
5
URL = 'https://civiform.example.gov/api/v1/admin/programs/utility-discount-program/applications'
6
AUTH_HEADERS = { 'Authorization': 'Basic ' + os.getenv('CIVIFORM_API_KEY') }
7
8
params = { 'fromDate': '2022-01-03', 'toDate': '2022-02-04', 'pageSize': 100 }
9
results = []
10
11
while True:
12
response = requests.get(URL, params=params, headers=AUTH_HEADERS)
13
14
if response.status_code != 200:
15
print("Request failed with status code: " + str(response.status_code))
16
exit(1)
17
18
response_json = response.json()
19
results.extend(response_json['payload'])
20
21
if response_json['nextPageToken'] is None:
22
break
23
24
params['nextPageToken'] = response_json['nextPageToken']
25
26
with open('exported_applications.json', 'w', encoding='utf-8') as f:
27
json.dump(results, f, ensure_ascii=False)
28
29
print(f'Exported {len(results)} applications.')
Last modified 27d ago