# Reports

## Get reports for an applicant group

> Retrieves all household and individual reports associated with a specific applicant group. Returns both household-level reports (aggregated across all applicants) and individual applicant reports.

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"tags":[{"name":"Reports"}],"servers":[{"url":"https://api.payscore.com","description":"Production server"},{"url":"https://staging.api.payscore.com","description":"Staging server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token obtained from the `/api/v1/tenants/auth` endpoint.\nToken expires after 30 minutes and must be refreshed.\n\nExample: `Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...`\n"}},"schemas":{"Report":{"type":"object","description":"A report generated from a completed verification","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the report"},"report_name":{"type":"string","enum":["Income","Identity","Asset"],"description":"Name of the report"},"is_expired":{"type":"boolean","description":"Whether the report data has expired and is no longer available"},"created_at":{"type":"string","format":"date-time","description":"When the report was created"},"applicant_group_id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant group this report belongs to (only present for household reports, not individual reports)"},"applicant_id":{"type":"string","format":"uuid","description":"Unique identifier for the individual applicant (only present for individual reports, not household reports)","nullable":true},"path":{"type":"string","description":"URL path to view the pdf"}}}}},"paths":{"/api/v1/applicant_groups/{id}/reports":{"get":{"summary":"Get reports for an applicant group","description":"Retrieves all household and individual reports associated with a specific applicant group. Returns both household-level reports (aggregated across all applicants) and individual applicant reports.","operationId":"getApplicantGroupReports","tags":["Reports"],"parameters":[{"name":"id","in":"path","required":true,"description":"Unique identifier of the applicant group","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Reports retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"household_reports":{"type":"array","description":"Household-level reports aggregating data across all applicants such as for income","items":{"$ref":"#/components/schemas/Report"}},"individual_reports":{"type":"array","description":"Individual reports for each applicant such as for identity","items":{"$ref":"#/components/schemas/Report"}}}}}}},"401":{"description":"Unauthorized - invalid or missing authentication token"},"404":{"description":"Applicant group not found"}}}}}}
```

## Get report data

> Retrieves the data for a specific report. The response structure varies based on the report type (income, identity, or asset verification).

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"tags":[{"name":"Reports"}],"servers":[{"url":"https://api.payscore.com","description":"Production server"},{"url":"https://staging.api.payscore.com","description":"Staging server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token obtained from the `/api/v1/tenants/auth` endpoint.\nToken expires after 30 minutes and must be refreshed.\n\nExample: `Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...`\n"}},"schemas":{"ReportDataResponse":{"type":"object","description":"Wrapper response containing report data that varies by report type, including PDF download URL","required":["report_id","report_type","applicant_group_id","pdf_url","data"],"properties":{"report_id":{"type":"string","format":"uuid","description":"Unique identifier for the report"},"report_type":{"type":"string","enum":["income","identity","asset"],"description":"Type of report data contained in this response"},"applicant_group_id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant group this report belongs to"},"applicant_id":{"type":"string","format":"uuid","description":"Unique identifier for the individual applicant (only present for individual reports, not household reports)"},"pdf_url":{"type":"string","format":"uri","description":"Secure URL to download the PDF report (expires in 2 hours)"},"data":{"oneOf":[{"$ref":"#/components/schemas/IncomeReportData"},{"$ref":"#/components/schemas/IdentityReportData"},{"$ref":"#/components/schemas/AssetReportData"}],"discriminator":{"propertyName":"report_type","mapping":{"income":"#/components/schemas/IncomeReportData","identity":"#/components/schemas/IdentityReportData","asset":"#/components/schemas/AssetReportData"}}}}},"IncomeReportData":{"type":"object","description":"Income verification report data containing bank accounts, transactions, payroll data, and uploaded documents","properties":{"summary":{"type":"object","description":"High-level income summary","properties":{"total_monthly_income":{"type":"integer","description":"Total monthly income in cents"},"income_to_rent_ratio":{"type":"number","format":"float","description":"Ratio of income to requested rent"},"recommendation":{"type":"string","enum":["approve","review","deny"],"description":"Automated recommendation based on income criteria"}}},"accounts":{"type":"array","description":"Bank accounts used for income verification","items":{"type":"object","properties":{"account_id":{"type":"string","description":"Account identifier"},"institution_name":{"type":"string","description":"Name of the financial institution"},"account_type":{"type":"string","enum":["checking","savings"],"description":"Type of bank account"},"monthly_income":{"type":"integer","description":"Monthly income from this account in cents"}}}},"transactions":{"type":"array","description":"Income transactions analyzed for verification","items":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Transaction date"},"amount":{"type":"integer","description":"Transaction amount in cents"},"description":{"type":"string","description":"Transaction description"}}}},"uploaded_documents":{"type":"array","description":"Documents uploaded by the applicant for verification (bank statements or pay stubs)","items":{"type":"object","properties":{"name":{"type":"string","description":"Filename of the uploaded document"},"type":{"type":"string","enum":["paystub","bank_statement"],"description":"Type of document uploaded"},"fraud_risk":{"type":"string","enum":["low","medium","high"],"description":"Overall fraud risk assessment"},"fraud_risk_score":{"type":"integer","description":"Numerical fraud risk score (0-100, higher is riskier)"},"applicant_name":{"type":"string","description":"Name of the applicant who uploaded the document"},"fraud_risk_signals":{"type":"array","description":"List of fraud risk signals detected in the document","items":{"type":"object","properties":{"type":{"type":"string","description":"Type of fraud signal detected"},"description":{"type":"string","nullable":true,"description":"Additional details about the fraud signal"}}}}}}},"income_sources":{"type":"array","description":"Sources of income used for verification (e.g., bank, document, payroll)","items":{"type":"object","properties":{"source":{"type":"string","enum":["bank","document","payroll"],"description":"Type of income source"}}}}}},"IdentityReportData":{"type":"object","description":"Identity verification report data from a completed identity verification","properties":{"outcome":{"type":"string","enum":["passed","failed"],"description":"Overall outcome of the identity verification"},"verification_types":{"type":"array","description":"Types of verification performed (e.g., government_id, selfie, tin, ecbsv)","items":{"type":"string","enum":["government_id","selfie","tin","ecbsv"]}},"checks":{"type":"array","description":"Individual verification checks performed during identity verification","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the verification check"},"identity_verification_id":{"type":"string","format":"uuid","description":"ID of the parent identity verification"},"name":{"type":"string","description":"Specific check name (e.g., id_entity_detection, selfie_liveness_detection)"},"verification_type":{"type":"string","enum":["government_id","selfie","tin","ecbsv"],"description":"Type of verification performed"},"status":{"type":"string","enum":["passed","failed","not_applicable"],"description":"Status of the verification check"},"reasons":{"type":"array","description":"Array of reason codes for check failure","items":{"type":"string"}},"metadata":{"type":"object","description":"Additional metadata about the check","nullable":true}}}}}},"AssetReportData":{"type":"object","description":"Asset verification report data containing account balances and financial assets","properties":{"total_assets":{"type":"integer","description":"Total verified assets in cents"},"asset_summary":{"type":"object","description":"Summary of different asset types","properties":{"liquid_assets":{"type":"integer","description":"Cash and easily liquidated assets in cents"},"investment_assets":{"type":"integer","description":"Investment account balances in cents"}}},"accounts":{"type":"array","description":"Individual accounts contributing to total assets","items":{"type":"object","properties":{"account_id":{"type":"string","description":"Account identifier"},"institution_name":{"type":"string","description":"Financial institution name"},"account_type":{"type":"string","enum":["checking","savings","investment","retirement"],"description":"Type of account"},"balance":{"type":"integer","description":"Current account balance in cents"},"average_balance":{"type":"integer","description":"6-month average balance in cents"}}}}}}}},"paths":{"/api/v1/reports/{id}":{"get":{"summary":"Get report data","description":"Retrieves the data for a specific report. The response structure varies based on the report type (income, identity, or asset verification).","operationId":"getReportData","tags":["Reports"],"parameters":[{"name":"id","in":"path","required":true,"description":"Unique identifier of the report","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Report data retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportDataResponse"}}}},"404":{"description":"Report not found"},"410":{"description":"Report data has expired and is no longer available"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.payscore.com/api-reference/reports.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.