# 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"}}}}}}
```