The Administration for Children and Families v1 API
The v1 API from The Administration for Children and Families — 35 operation(s) for v1.
The v1 API from The Administration for Children and Families — 35 operation(s) for v1.
swagger: '2.0'
info:
title: TDP plg_auth_check v1 API
description: TANF Data Portal API documentation
contact:
email: tanfdata@acf.hhs.gov
version: v1
host: tanfdata.acf.hhs.gov
basePath: /
schemes:
- https
consumes:
- application/json
produces:
- application/json
security:
- Basic: []
tags:
- name: v1
paths:
/v1/auth_check:
parameters: []
get:
operationId: v1_auth_check_list
description: Handle get request and verify user is authorized.
parameters: []
responses:
'200':
description: ''
tags:
- v1
/v1/change-request-logs/:
parameters: []
get:
operationId: v1_change-request-logs_list
description: ViewSet for change request audit logs.
parameters:
- name: page
in: query
description: A page number within the paginated result set.
required: false
type: integer
responses:
'200':
description: ''
schema:
required:
- count
- results
type: object
properties:
count:
type: integer
next:
type: string
format: uri
x-nullable: true
previous:
type: string
format: uri
x-nullable: true
results:
type: array
items:
$ref: '#/definitions/ChangeRequestAuditLog'
tags:
- v1
/v1/change-request-logs/{id}/:
parameters:
- name: id
in: path
required: true
type: string
get:
operationId: v1_change-request-logs_read
description: ViewSet for change request audit logs.
parameters: []
responses:
'200':
description: ''
schema:
$ref: '#/definitions/ChangeRequestAuditLog'
tags:
- v1
/v1/change-requests/:
parameters: []
get:
operationId: v1_change-requests_list
description: ViewSet for user change requests.
parameters:
- name: page
in: query
description: A page number within the paginated result set.
required: false
type: integer
responses:
'200':
description: ''
schema:
required:
- count
- results
type: object
properties:
count:
type: integer
next:
type: string
format: uri
x-nullable: true
previous:
type: string
format: uri
x-nullable: true
results:
type: array
items:
$ref: '#/definitions/UserChangeRequest'
tags:
- v1
/v1/change-requests/{id}/:
parameters:
- name: id
in: path
required: true
type: string
get:
operationId: v1_change-requests_read
description: ViewSet for user change requests.
parameters: []
responses:
'200':
description: ''
schema:
$ref: '#/definitions/UserChangeRequest'
tags:
- v1
/v1/data_files/:
parameters: []
get:
operationId: v1_data_files_list
description: Override to handle the list request with url param validation.
parameters:
- name: stt
in: query
description: ''
required: true
type: string
- name: quarter
in: query
description: ''
required: false
type: string
- name: year
in: query
description: ''
required: false
type: string
responses:
'200':
description: ''
schema:
type: array
items:
$ref: '#/definitions/DataFile'
consumes:
- multipart/form-data
tags:
- v1
post:
operationId: v1_data_files_create
description: Override create to upload in case of successful scan.
parameters:
- name: file
in: formData
required: true
type: file
- name: original_filename
in: formData
required: true
type: string
maxLength: 256
minLength: 1
- name: slug
in: formData
required: true
type: string
maxLength: 256
minLength: 1
- name: extension
in: formData
required: false
type: string
maxLength: 8
minLength: 1
- name: user
in: formData
required: true
type: string
format: uuid
- name: stt
in: formData
required: true
type: integer
- name: year
in: formData
required: true
type: integer
maximum: 2147483647
minimum: -2147483648
- name: quarter
in: formData
required: true
type: string
enum:
- Q1
- Q2
- Q3
- Q4
- name: section
in: formData
required: true
type: string
enum:
- Active Case Data
- Closed Case Data
- Aggregate Data
- Stratum Data
- Work Outcomes of TANF Exiters
- Secondary School Attainment
- Supplemental Work Outcomes
- name: ssp
in: formData
required: true
type: boolean
- name: s3_versioning_id
in: formData
required: false
type: string
maxLength: 1024
minLength: 1
x-nullable: true
- name: is_program_audit
in: formData
required: false
type: boolean
default: false
responses:
'201':
description: ''
schema:
$ref: '#/definitions/DataFile'
consumes:
- multipart/form-data
tags:
- v1
/v1/data_files/years:
parameters: []
get:
operationId: v1_data_files_years_list
description: Handle get action for get list of years there are data_files.
parameters:
- name: stt
in: path
description: The unique identifier of the target STT, if not specified will default to user STT
required: true
type: integer
responses:
'200':
description: ''
tags:
- v1
/v1/data_files/years/{stt}:
parameters:
- name: stt
in: path
required: true
type: string
get:
operationId: v1_data_files_years_read
description: Handle get action for get list of years there are data_files.
parameters:
- name: stt
in: path
description: The unique identifier of the target STT, if not specified will default to user STT
required: true
type: integer
responses:
'200':
description: ''
tags:
- v1
/v1/data_files/{id}/:
parameters:
- name: id
in: path
description: A unique integer value identifying this data file.
required: true
type: integer
get:
operationId: v1_data_files_read
description: Data file views.
parameters: []
responses:
'200':
description: ''
schema:
$ref: '#/definitions/DataFile'
consumes:
- multipart/form-data
tags:
- v1
/v1/data_files/{id}/download/:
parameters:
- name: id
in: path
description: A unique integer value identifying this data file.
required: true
type: integer
get:
operationId: v1_data_files_download
description: Retrieve a file from s3 then stream it to the client.
parameters: []
responses:
'200':
description: ''
schema:
$ref: '#/definitions/DataFile'
consumes:
- multipart/form-data
tags:
- v1
/v1/data_files/{id}/download_error_report/:
parameters:
- name: id
in: path
description: A unique integer value identifying this data file.
required: true
type: integer
get:
operationId: v1_data_files_download_error_report
description: Generate and return the parsing error report xlsx.
parameters: []
responses:
'200':
description: ''
schema:
$ref: '#/definitions/DataFile'
consumes:
- multipart/form-data
tags:
- v1
/v1/feature-flags/:
parameters: []
get:
operationId: v1_feature-flags_list
description: Get the feature flag list from the cache if available, else fetch the queryset.
parameters: []
responses:
'200':
description: ''
schema:
type: array
items:
$ref: '#/definitions/FeatureFlag'
tags:
- v1
/v1/feature-flags/{feature_name}/:
parameters:
- name: feature_name
in: path
required: true
type: string
get:
operationId: v1_feature-flags_read
description: Get the feature flag from cache if available, fallback to db.
parameters: []
responses:
'200':
description: ''
schema:
$ref: '#/definitions/FeatureFlag'
tags:
- v1
/v1/feedback/:
parameters: []
get:
operationId: v1_feedback_list
description: Feedback viewset.
parameters:
- name: page
in: query
description: A page number within the paginated result set.
required: false
type: integer
responses:
'200':
description: ''
schema:
required:
- count
- results
type: object
properties:
count:
type: integer
next:
type: string
format: uri
x-nullable: true
previous:
type: string
format: uri
x-nullable: true
results:
type: array
items:
$ref: '#/definitions/Feedback'
tags:
- v1
post:
operationId: v1_feedback_create
description: Create feedback with user.
parameters:
- name: data
in: body
required: true
schema:
$ref: '#/definitions/Feedback'
responses:
'201':
description: ''
schema:
$ref: '#/definitions/Feedback'
tags:
- v1
/v1/feedback/{id}/:
parameters:
- name: id
in: path
description: A UUID string identifying this Feedback.
required: true
type: string
format: uuid
get:
operationId: v1_feedback_read
description: Feedback viewset.
parameters: []
responses:
'200':
description: ''
schema:
$ref: '#/definitions/Feedback'
tags:
- v1
put:
operationId: v1_feedback_update
description: Update feedback.
parameters:
- name: data
in: body
required: true
schema:
$ref: '#/definitions/Feedback'
responses:
'200':
description: ''
schema:
$ref: '#/definitions/Feedback'
tags:
- v1
patch:
operationId: v1_feedback_partial_update
description: Feedback viewset.
parameters:
- name: data
in: body
required: true
schema:
$ref: '#/definitions/Feedback'
responses:
'200':
description: ''
schema:
$ref: '#/definitions/Feedback'
tags:
- v1
delete:
operationId: v1_feedback_delete
description: Override the destroy method to disallow it.
parameters: []
responses:
'204':
description: ''
tags:
- v1
/v1/login/:
parameters: []
get:
operationId: v1_login_list
description: Handle decoding auth token and authenticate user.
parameters: []
responses:
'200':
description: ''
schema:
type: array
items:
$ref: '#/definitions/AuthToken'
tags:
- v1
post:
operationId: v1_login_create
description: Define methods for handling login request from login.gov.
parameters:
- name: data
in: body
required: true
schema:
$ref: '#/definitions/AuthToken'
responses:
'201':
description: ''
schema:
$ref: '#/definitions/AuthToken'
tags:
- v1
/v1/logout:
parameters: []
get:
operationId: v1_logout_list
description: Destroy user session.
parameters: []
responses:
'200':
description: ''
tags:
- v1
/v1/logs/:
parameters: []
post:
operationId: v1_logs_create
summary: Pass request bodies to the system logger.
description: Mainly used to log client-side alerts and errors.
parameters: []
responses:
'201':
description: ''
tags:
- v1
/v1/oidc/ams:
parameters: []
get:
operationId: v1_oidc_ams_list
description: Handle decoding auth token and authenticate user.
parameters: []
responses:
'200':
description: ''
schema:
type: array
items:
$ref: '#/definitions/AuthToken'
tags:
- v1
post:
operationId: v1_oidc_ams_create
description: Define methods for handling login request from HHS AMS.
parameters:
- name: data
in: body
required: true
schema:
$ref: '#/definitions/AuthToken'
responses:
'201':
description: ''
schema:
$ref: '#/definitions/AuthToken'
tags:
- v1
/v1/reports/:
parameters: []
get:
operationId: v1_reports_list
description: Report file views.
parameters:
- name: page
in: query
description: A page number within the paginated result set.
required: false
type: integer
responses:
'200':
description: ''
schema:
required:
- count
- results
type: object
properties:
count:
type: integer
next:
type: string
format: uri
x-nullable: true
previous:
type: string
format: uri
x-nullable: true
results:
type: array
items:
$ref: '#/definitions/ReportFile'
tags:
- v1
post:
operationId: v1_reports_create
description: Report file views.
parameters:
- name: data
in: body
required: true
schema:
$ref: '#/definitions/ReportFile'
responses:
'201':
description: ''
schema:
$ref: '#/definitions/ReportFile'
tags:
- v1
/v1/reports/report-sources/:
parameters: []
get:
operationId: v1_reports_report-sources_list
description: Report source views for batch uploading report files.
parameters:
- name: page
in: query
description: A page number within the paginated result set.
required: false
type: integer
responses:
'200':
description: ''
schema:
required:
- count
- results
type: object
properties:
count:
type: integer
next:
type: string
format: uri
x-nullable: true
previous:
type: string
format: uri
x-nullable: true
results:
type: array
items:
$ref: '#/definitions/ReportSource'
tags:
- v1
post:
operationId: v1_reports_report-sources_create
description: Create a new report source and trigger async processing.
parameters:
- name: data
in: body
required: true
schema:
$ref: '#/definitions/ReportSource'
responses:
'201':
description: ''
schema:
$ref: '#/definitions/ReportSource'
tags:
- v1
/v1/reports/report-sources/{id}/:
parameters:
- name: id
in: path
description: A unique integer value identifying this report source.
required: true
type: integer
get:
operationId: v1_reports_report-sources_read
description: Report source views for batch uploading report files.
parameters: []
responses:
'200':
description: ''
schema:
$ref: '#/definitions/ReportSource'
tags:
- v1
/v1/reports/{id}/:
parameters:
- name: id
in: path
description: A unique integer value identifying this report file.
required: true
type: integer
get:
operationId: v1_reports_read
description: Report file views.
parameters: []
responses:
'200':
description: ''
schema:
$ref: '#/definitions/ReportFile'
tags:
- v1
/v1/reports/{id}/download/:
parameters:
- name: id
in: path
description: A unique integer value identifying this report file.
required: true
type: integer
get:
operationId: v1_reports_download
description: Retrieve a file from s3 then stream it to the client.
parameters: []
responses:
'200':
description: ''
schema:
$ref: '#/definitions/ReportFile'
tags:
- v1
/v1/roles/:
parameters: []
get:
operationId: v1_roles_list
description: GET for groups (roles).
parameters: []
responses:
'200':
description: ''
schema:
type: array
items:
$ref: '#/definitions/Group'
tags:
- v1
/v1/security/event-token:
parameters: []
post:
operationId: v1_security_event-token_create
description: Process incoming Security Event Token from Login.gov.
parameters: []
responses:
'201':
description: ''
tags:
- v1
/v1/security/get-token:
parameters: []
get:
operationId: v1_security_get-token_list
description: Generate new token for the API user.
parameters: []
responses:
'200':
description: ''
tags:
- v1
/v1/stts/:
parameters: []
get:
operationId: v1_stts_list
description: Simple view to get all STTs.
parameters: []
responses:
'200':
description: ''
schema:
type: array
items:
$ref: '#/definitions/STT'
tags:
- v1
/v1/stts/alpha:
parameters: []
get:
operationId: v1_stts_alpha_list
description: Simple view to get all STTs alphabetized.
parameters: []
responses:
'200':
description: ''
schema:
type: array
items:
$ref: '#/definitions/STT'
tags:
- v1
/v1/stts/by_region:
parameters: []
get:
operationId: v1_stts_by_region_list
description: Simple view to get all regions and STTs, without pagination.
parameters: []
responses:
'200':
description: ''
schema:
type: array
items:
$ref: '#/definitions/Region'
tags:
- v1
/v1/users/:
parameters: []
get:
operationId: v1_users_list
description: User accounts viewset.
parameters:
- name: page
in: query
description: A page number within the paginated result set.
required: false
type: integer
responses:
'200':
description: ''
schema:
required:
- count
- results
type: object
properties:
count:
type: integer
next:
type: string
format: uri
x-nullable: true
previous:
type: string
format: uri
x-nullable: true
results:
type: array
items:
$ref: '#/definitions/User'
tags:
- v1
/v1/users/profile/:
parameters: []
get:
operationId: v1_users_profile
description: Get the current user's profile.
parameters:
- name: page
in: query
description: A page number within the paginated result set.
required: false
type: integer
responses:
'200':
description: ''
schema:
required:
- count
- results
type: object
properties:
count:
type: integer
next:
type: string
format: uri
x-nullable: true
previous:
type: string
format: uri
x-nullable: true
results:
type: array
items:
$ref: '#/definitions/UserProfile'
tags:
- v1
/v1/users/request_access/:
parameters: []
get:
operationId: v1_users_request_access_read
description: Update request.user with provided data, set `account_approval_status` to 'Access Request'.
parameters:
- name: page
in: query
description: A page number within the paginated result set.
required: false
type: integer
responses:
'200':
description: ''
schema:
required:
- count
- results
type: object
properties:
count:
type: integer
next:
type: string
format: uri
x-nullable: true
previous:
type: string
format: uri
x-nullable: true
results:
type: array
items:
$ref: '#/definitions/UserProfile'
tags:
- v1
patch:
operationId: v1_users_request_access_partial_update
description: Update request.user with provided data, set `account_approval_status` to 'Access Request'.
parameters:
- name: data
in: body
required: true
schema:
$ref: '#/definitions/UserProfile'
responses:
'200':
description: ''
schema:
$ref: '#/definitions/UserProfile'
tags:
- v1
/v1/users/update_profile/:
parameters: []
patch:
operationId: v1_users_update_profile
description: Update the current user's profile through change requests.
parameters:
- name: data
in: body
required: true
schema:
$ref: '#/definitions/UserProfileChangeRequest'
responses:
'200':
description: ''
schema:
$ref: '#/definitions/UserProfileChangeRequest'
tags:
- v1
/v1/users/{id}/:
parameters:
- name: id
in: path
description: A UUID string identifying this user.
required: true
type: string
format: uuid
get:
operationId: v1_users_read
description: Return a specific user.
parameters: []
responses:
'200':
description: ''
schema:
$ref: '#/definitions/User'
tags:
- v1
put:
operationId: v1_users_update
description: User accounts viewset.
parameters:
- name: data
in: body
required: true
schema:
$ref: '#/definitions/User'
responses:
'200':
description: ''
schema:
$ref: '#/definitions/User'
tags:
- v1
patch:
operationId: v1_users_partial_update
description: User accounts viewset.
parameters:
- name: data
in: body
required: true
schema:
$ref: '#/definitions/User'
responses:
'200':
description: ''
schema:
$ref: '#/definitions/User'
tags:
- v1
definitions:
AuthToken:
required:
- username
- password
type: object
properties:
username:
title: Username
type: string
minLength: 1
password:
title: Password
type: string
minLength: 1
token:
title: Token
type: string
readOnly: true
minLength: 1
Permission:
required:
- codename
- name
type: object
properties:
id:
title: ID
type: integer
readOnly: true
codename:
title: Codename
type: string
maxLength: 100
minLength: 1
name:
title: Name
type: string
maxLength: 255
minLength: 1
content_type:
title: Content type
type: string
minLength: 1
x-nullable: true
UserChangeRequest:
required:
- user
- field_name
type: object
properties:
id:
title: Id
type: string
format: uuid
readOnly: true
user:
title: User
type: string
format: uuid
field_name:
title: Field name
description: 'The name of the field being changed, possible values include: first_name, last_name, regions and has_fra_access'
type: string
maxLength: 100
minLength: 1
requested_value:
title: Requested value
description: The requested new value for the field
type: string
status:
title: Status
description: The current status of this change request
type: string
enum:
- pending
- approved
- rejected
- cancelled
readOnly: true
requested_at:
title: Requested at
description: When this change was requested
type: string
format: date-time
readOnly: true
User:
type: object
properties:
id:
title: Id
type: string
format: uuid
readOnly: true
username:
title: Username
description: Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.
type: string
readOnly: true
minLength: 1
first_name:
title: First name
type: string
maxLength: 150
last_name:
title: Last name
type: string
maxLength: 150
account_approval_status:
title: Account approval status
description: Designates whether this user account is active and approved to access TDP. Users in an approved state are allowed access.
type: string
enum:
- Initial
- Access request
- Pending
- Approved
- Denied
- Deactivated
readOnly: true
groups:
description: The groups this user belongs to. A user will get all permissions granted to each of their groups.
type: array
items:
description: The groups this user belongs to. A user will get all permissions granted to each of their groups.
type: string
format: uuid
readOnly: true
uniqueItems: true
is_superuser:
title: Superuser status
description: Designates that this user has all permissions without explicitly assigning them.
type: boolean
readOnly: true
is_staff:
title: Staff status
description: Designates whether the user can log into this admin site.
type: boolean
readOnly: true
stt:
title: Stt
type: integer
x-nullable: true
regions:
description: Regions this user is associated with.
type: array
items:
description: Regions this user is associated with.
type: string
format: uuid
readOnly: true
uniqueItems: true
login_gov_uuid:
title: Login gov uuid
type: string
format: uuid
readOnly: true
x-nullable: true
hhs_id:
title: Hhs id
type: string
readOnly: true
minLength: 1
x-nullable: true
last_login:
title: Last login
type: string
format: date-time
readOnly: true
x-nullable: true
date_joined:
title: Date joined
type: string
format: date-time
readOnly: true
access_requested_date:
title: Access requested date
type: string
format: date-time
readOnly: true
feature_flags:
title: Feature flags
description: 'Feature flags for this user. This is a JSON field that can be used to store key-value pairs. E.g: {"some_feature": true}'
type: object
Group:
required:
- name
- permissions
type: object
properties:
id:
title: ID
type: integer
readOnly: true
name:
title: Name
type: string
maxLength: 150
minLength: 1
permissions:
type: array
items:
$ref: '#/definitions/Permission'
ReportFile:
required:
- stt
- year
type: object
properties:
id:
title: ID
type: integer
readOnly: true
stt:
title: Stt
type: integer
user:
title: User
type: string
format: uuid
readOnly: true
date_extracted_on:
title: Date extracted on
type: string
format: date
x-nullable: true
year:
title: Year
type: integer
maximum: 2147483647
minimum: -2147483648
report_type:
title: Report type
type: string
enum:
- TANF_SSP
- FRA
default: TANF_SSP
version:
title: Version
type: integer
readOnly: true
original_filename:
title: Original filename
type: string
readOnly: true
minLength: 1
extension:
title: Extension
type: string
readOnly: true
minLength: 1
created_at:
title: Created at
type: string
format: date-time
readOnly: true
file:
title: File
type: string
readOnly: true
format: uri
DataFile:
required:
- original_filename
- slug
- user
- stt
- year
- quarter
- section
- ssp
type: object
properties:
file:
title: File
type: string
readOnly: true
format: uri
id:
title: ID
type: integer
readOnly: true
original_filename:
title: Original filename
type: string
maxLength: 256
minLength: 1
slug:
title: Slug
type: string
maxLength: 256
minLength: 1
extension:
title: Extension
type: string
maxLength: 8
minLength: 1
user:
title: User
type: string
format: uuid
stt:
title: Stt
type: integer
year:
title: Year
type: integer
maximum: 2147483647
minimum: -2147483648
quarter:
title: Quarter
type: string
enum:
- Q1
- Q2
- Q3
- Q4
section:
title: Section
type: string
enum:
- Active Case Data
- Closed Case Data
- Aggregate Data
- Stratum Data
- Work Outcomes of TANF Exiters
- Secondary School Attainment
- Supplemental Work Outcomes
created_at:
title: Created at
type: string
format: date-time
readOnly: true
ssp:
title: Ssp
type: boolean
submitted_by:
title: Submitted by
type: string
readOnly: true
vers
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/the-administration-for-children-and-families/refs/heads/main/openapi/the-administration-for-children-and-families-v1-api-openapi.yml