> For the complete documentation index, see [llms.txt](https://docs.payscore.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payscore.com/api-reference/reports.md).

# 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"],"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"}],"discriminator":{"propertyName":"report_type","mapping":{"income":"#/components/schemas/IncomeReportData","identity":"#/components/schemas/IdentityReportData"}}}}},"IncomeReportData":{"description":"Income report data — either a household (combined) report or an individual applicant report","oneOf":[{"$ref":"#/components/schemas/HouseholdIncomeReport"},{"$ref":"#/components/schemas/IndividualIncomeReport"}]},"HouseholdIncomeReport":{"type":"object","description":"Combined income report aggregating data across all applicants in the group. Contains a reports array with each applicant's individual sub-report.","properties":{"reports":{"type":"array","description":"Individual income sub-reports for each applicant in the group","items":{"$ref":"#/components/schemas/ApplicantIncomeSubReport"}},"recurring":{"$ref":"#/components/schemas/RecurringIncomeData"},"non_recurring":{"$ref":"#/components/schemas/NonRecurringIncomeData"},"summary_timespan_length":{"type":"integer","description":"Minimum data timespan across all applicants, in days"},"criteria_rule_results":{"type":"array","nullable":true,"description":"Results of income criteria rule evaluations","items":{"$ref":"#/components/schemas/IncomeCriteriaResult"}},"applicant_group_id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant group"},"property_name":{"type":"string","nullable":true,"description":"Property name associated with the application"},"property_monthly_rent_cents":{"type":"integer","nullable":true,"description":"Property monthly rent in cents"},"created_at":{"type":"string","format":"date-time","description":"When the report was created"},"uploaded_documents":{"type":"array","nullable":true,"description":"Documents uploaded across all applicants for verification","items":{"$ref":"#/components/schemas/UploadedDocument"}}}},"ApplicantIncomeSubReport":{"type":"object","description":"An individual applicant's income data nested within a HouseholdIncomeReport. Contains richer per-applicant detail than the top-level individual report.","properties":{"verification_id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant's income verification"},"identity":{"type":"object","description":"Identity information for this applicant","properties":{"full_name":{"type":"string"},"email":{"type":"string","format":"email"}}},"reason_completed":{"type":"string","nullable":true,"description":"Reason the verification was completed"},"income_sources":{"type":"array","description":"Income sources used for this applicant's verification","items":{"type":"object","properties":{"source":{"type":"string","enum":["bank","payroll","document"],"description":"Type of income source"}}}},"recurring":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/RecurringIncomeData"}]},"non_recurring":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/NonRecurringIncomeData"}]},"summary_timespan_length":{"type":"integer","nullable":true,"description":"Data timespan for this applicant, in days"},"bank_connections":{"type":"array","nullable":true,"description":"Income summaries for each linked bank connection (bank income source only)","items":{"$ref":"#/components/schemas/BankConnectionIncomeSummary"}},"payroll_connections":{"type":"array","nullable":true,"description":"Income summaries for each payroll connection (payroll income source only)","items":{"$ref":"#/components/schemas/PayrollConnectionIncomeSummary"}},"income_explanation":{"type":"string","nullable":true,"description":"Human-readable explanation of the income determination (bank income source only)"},"uploaded_documents":{"type":"array","nullable":true,"description":"Documents uploaded by this applicant for verification","items":{"$ref":"#/components/schemas/UploadedDocument"}}}},"RecurringIncomeData":{"type":"object","description":"Aggregated recurring income data","properties":{"total":{"type":"integer","description":"Total net recurring income in cents within the summary timespan"},"one_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 1 month in cents"},"two_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 2 months in cents (null if timespan < 50 days)"},"three_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 3 months in cents (null if timespan < 80 days)"},"six_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 6 months in cents (null if timespan < 170 days)"},"nine_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 9 months in cents (null if timespan < 260 days)"},"twelve_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 12 months in cents (null if timespan < 350 days)"},"income_streams":{"type":"array","description":"Individual recurring income streams contributing to this total","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}}}},"IncomeStreamProperties":{"type":"object","description":"Properties of a single identified income stream","properties":{"name":{"type":"string","description":"Name of the income stream (typically the income source or employer)"},"total":{"type":"integer","description":"Total net amount for this income stream in cents"},"monthly_income":{"type":"integer","description":"Calculated monthly income for this stream in cents"},"start_date":{"type":"string","format":"date","description":"Start date of this income stream's period"},"end_date":{"type":"string","format":"date","description":"End date of this income stream's period"},"transactions":{"type":"array","description":"Individual transactions belonging to this income stream","items":{"$ref":"#/components/schemas/TransactionProperties"}},"paystubs":{"type":"array","description":"Paystub records for this income stream (populated for payroll sources)","items":{"$ref":"#/components/schemas/PaystubProperties"}},"pay_gap_after_transaction_indexes":{"type":"array","description":"Indexes of transactions after which an unusual pay gap was detected","items":{"type":"integer"}}}},"TransactionProperties":{"type":"object","description":"A single bank transaction within an income stream","properties":{"name":{"type":"string","description":"Transaction name or description"},"amount":{"type":"integer","description":"Transaction amount in cents"},"date":{"type":"string","description":"Transaction date formatted as MM/DD/YYYY"}}},"PaystubProperties":{"type":"object","description":"A single paystub within a payroll income stream","properties":{"gross_pay":{"type":"integer","nullable":true,"description":"Gross pay in cents"},"base_pay":{"type":"integer","nullable":true,"description":"Base pay in cents"},"bonus":{"type":"integer","nullable":true,"description":"Bonus amount in cents"},"commission":{"type":"integer","nullable":true,"description":"Commission amount in cents"},"tips":{"type":"integer","nullable":true,"description":"Tips amount in cents"},"overtime":{"type":"integer","nullable":true,"description":"Overtime pay in cents"},"other":{"type":"integer","nullable":true,"description":"Other pay in cents"},"net_pay":{"type":"integer","nullable":true,"description":"Net pay in cents"},"hours_worked":{"type":"number","nullable":true,"description":"Hours worked, rounded to 2 decimal places"},"pay_date":{"type":"string","description":"Pay date (pretty formatted)"},"start_date":{"type":"string","description":"Pay period start date (pretty formatted)"},"end_date":{"type":"string","description":"Pay period end date (pretty formatted)"}}},"NonRecurringIncomeData":{"type":"object","description":"Aggregated non-recurring income data (no gross estimates)","properties":{"total":{"type":"integer","description":"Total net non-recurring income in cents within the summary timespan"},"one_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 1 month in cents"},"two_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 2 months in cents"},"three_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 3 months in cents"},"six_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 6 months in cents"},"nine_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 9 months in cents"},"twelve_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 12 months in cents"},"income_streams":{"type":"array","description":"Individual non-recurring income streams","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}}}},"BankConnectionIncomeSummary":{"type":"object","description":"Income summary for a single linked bank connection","properties":{"institution_name":{"type":"string","description":"Name of the financial institution"},"accounts":{"type":"array","description":"Bank accounts on this connection used for income analysis","items":{"type":"object","description":"Account properties including name, holder names, type, and balances"}},"income":{"type":"object","description":"Aggregated income analysis for this bank connection","properties":{"total":{"type":"integer","description":"Total net income in cents within the summary timespan"},"two_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 2 months in cents"},"three_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 3 months in cents"},"six_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 6 months in cents"},"nine_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 9 months in cents"},"twelve_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 12 months in cents"},"income_streams":{"type":"array","description":"Recurring income streams identified for this bank connection","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}},"non_recurring":{"type":"object","description":"Non-recurring income for this bank connection","properties":{"total":{"type":"integer","description":"Total non-recurring income in cents"},"income_streams":{"type":"array","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}}}},"start_date":{"type":"string","format":"date","description":"Earliest transaction date across all income streams"},"end_date":{"type":"string","format":"date","description":"Latest transaction date across all income streams"},"transaction_timespan_length":{"type":"integer","description":"Number of days covered by income transactions"}}}}},"PayrollConnectionIncomeSummary":{"type":"object","description":"Income summary for a single payroll connection","properties":{"employee_name":{"type":"string","nullable":true,"description":"Employee name as reported by the payroll provider"},"company_name":{"type":"string","nullable":true,"description":"Employer company name"},"institution_name":{"type":"string","nullable":true,"description":"Name of the payroll provider"},"company_address":{"type":"string","nullable":true,"description":"Employer address"},"title":{"type":"string","nullable":true,"description":"Job title"},"start_date":{"type":"string","nullable":true,"description":"Employment start date"},"end_date":{"type":"string","nullable":true,"description":"Employment end date (null if currently employed)"},"pay_frequency":{"type":"string","nullable":true,"description":"Pay frequency"},"pay_rate":{"type":"string","nullable":true,"description":"Pay rate description"},"pay_amount":{"type":"integer","nullable":true,"description":"Pay amount in cents"},"income":{"type":"object","nullable":true,"description":"Aggregated income analysis for this payroll connection","properties":{"total":{"type":"integer","description":"Total net income in cents within the summary timespan"},"two_month_avg_monthly":{"type":"integer","nullable":true},"three_month_avg_monthly":{"type":"integer","nullable":true},"six_month_avg_monthly":{"type":"integer","nullable":true},"nine_month_avg_monthly":{"type":"integer","nullable":true},"twelve_month_avg_monthly":{"type":"integer","nullable":true},"income_streams":{"type":"array","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}},"start_date":{"type":"string","format":"date","description":"Earliest paystub date"},"end_date":{"type":"string","format":"date","description":"Latest paystub date"},"transaction_timespan_length":{"type":"integer","description":"Number of days covered by paystubs"}}},"is_name_mismatched":{"type":"boolean","description":"Whether the employee name on paystubs does not match the applicant name"}}},"UploadedDocument":{"type":"object","description":"A document uploaded by the applicant (bank statement or pay stub)","properties":{"name":{"type":"string","description":"Filename of the uploaded document"},"type":{"type":"string","description":"Document type"},"fraud_risk":{"type":"string","enum":["low","needs_review","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","nullable":true,"description":"Name of the applicant who uploaded the document"},"fraud_risk_signals":{"type":"array","description":"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"}}}}}},"IncomeCriteriaResult":{"type":"object","description":"Result of evaluating a single income criteria rule","properties":{"result":{"type":"string","description":"Whether the applicant passed or failed this criteria"},"multiplier_result":{"type":"string","nullable":true,"description":"Income-to-rent multiplier result for this criteria"},"multiplier_threshold":{"type":"number","nullable":true,"description":"The multiplier threshold used in this criteria evaluation"},"criteria_used":{"type":"string","nullable":true,"description":"The specific income figure used for evaluation (e.g., which monthly average)"},"criteria_from_rule":{"type":"string","nullable":true,"description":"The rule that determined which income criteria to use"}}},"IndividualIncomeReport":{"type":"object","description":"Income report for a single applicant fetched directly. Has the same exposed fields as HouseholdIncomeReport but includes income_sources and no reports array.","properties":{"recurring":{"$ref":"#/components/schemas/RecurringIncomeData"},"non_recurring":{"$ref":"#/components/schemas/NonRecurringIncomeData"},"summary_timespan_length":{"type":"integer","description":"Data timespan, in days"},"criteria_rule_results":{"type":"array","nullable":true,"description":"Results of income criteria rule evaluations","items":{"$ref":"#/components/schemas/IncomeCriteriaResult"}},"income_sources":{"type":"array","description":"Income sources used for this applicant's verification","items":{"type":"object","properties":{"source":{"type":"string","enum":["bank","payroll","document"],"description":"Type of income source"}}}},"applicant_group_id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant group"},"property_name":{"type":"string","nullable":true,"description":"Property name associated with the application"},"property_monthly_rent_cents":{"type":"integer","nullable":true,"description":"Property monthly rent in cents"},"created_at":{"type":"string","format":"date-time","description":"When the report was created"},"uploaded_documents":{"type":"array","nullable":true,"description":"Documents uploaded by the applicant for verification","items":{"$ref":"#/components/schemas/UploadedDocument"}}}},"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}}}}}}}},"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"}}}}}}
```