# Models

## The ApplicantGroup object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"ApplicantGroup":{"type":"object","description":"An applicant group represents a verification request for multiple applicants","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant group"},"decision_maker_display_name":{"type":"string","description":"Display name for the decision maker"},"property":{"type":"object","description":"Property information where applicants will be residing","properties":{"id":{"type":"string","format":"uuid","description":"Property unique identifier"},"name":{"type":"string","description":"Property name"},"street_address":{"type":"string","description":"Property street address"},"city":{"type":"string","description":"Property city"},"state":{"type":"string","description":"Property state"},"zip_code":{"type":"string","description":"Property ZIP code"}}},"status":{"type":"string","description":"Current status of the applicant group","enum":["not_started","in_progress","completed"]},"created_at_timestamp":{"type":"number","format":"float","description":"Unix timestamp when the applicant group was created"},"monthly_rent_cents":{"type":"integer","description":"Monthly rent amount in cents"},"unit_number":{"type":"string","description":"Unit number or identifier"},"unit_id":{"type":"string","format":"uuid","description":"Unique identifier for the unit","nullable":true},"is_free":{"type":"boolean","description":"Whether this is a free verification"},"is_decision_maker_paying":{"type":"boolean","description":"Whether the decision maker is paying for the verification"},"correlation_id":{"type":"string","description":"External system correlation identifier","nullable":true},"verification_types":{"type":"array","description":"List of unique verification types across all applicants in this group","items":{"type":"string","enum":["asset_verification","identity_verification","payroll_income_verification","bank_income_verification","flexible_income_verification","document_income_verification"]}},"is_expired":{"type":"boolean","description":"Whether the applicant group has expired"},"applicants":{"type":"array","description":"List of applicants in this group","items":{"$ref":"#/components/schemas/Applicant"}}}},"Applicant":{"type":"object","description":"An individual applicant within an applicant group","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant"},"first_name":{"type":"string","description":"Applicant's first name"},"last_name":{"type":"string","description":"Applicant's last name"},"email":{"type":"string","format":"email","description":"Applicant's email address"},"phone_number":{"type":"string","description":"Applicant's phone number"},"created_at":{"type":"string","format":"date-time","description":"When the applicant was created"},"updated_at":{"type":"string","format":"date-time","description":"When the applicant was last updated"},"verifications":{"type":"array","description":"List of verifications assigned to this applicant. Note - This field is only included in detail view on create, not in list views (e.g., when fetching multiple applicant groups).","items":{"$ref":"#/components/schemas/Verification"}}}},"Verification":{"type":"object","description":"A verification assigned to an applicant","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the verification"},"type":{"type":"string","enum":["asset_verification","identity_verification","payroll_income_verification","bank_income_verification","flexible_income_verification","document_income_verification"],"description":"Type of verification"},"status":{"type":"string","description":"Current status of the verification","enum":["not_started","in_progress","completed"]}}}}}}
```

## The Applicant object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"Applicant":{"type":"object","description":"An individual applicant within an applicant group","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant"},"first_name":{"type":"string","description":"Applicant's first name"},"last_name":{"type":"string","description":"Applicant's last name"},"email":{"type":"string","format":"email","description":"Applicant's email address"},"phone_number":{"type":"string","description":"Applicant's phone number"},"created_at":{"type":"string","format":"date-time","description":"When the applicant was created"},"updated_at":{"type":"string","format":"date-time","description":"When the applicant was last updated"},"verifications":{"type":"array","description":"List of verifications assigned to this applicant. Note - This field is only included in detail view on create, not in list views (e.g., when fetching multiple applicant groups).","items":{"$ref":"#/components/schemas/Verification"}}}},"Verification":{"type":"object","description":"A verification assigned to an applicant","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the verification"},"type":{"type":"string","enum":["asset_verification","identity_verification","payroll_income_verification","bank_income_verification","flexible_income_verification","document_income_verification"],"description":"Type of verification"},"status":{"type":"string","description":"Current status of the verification","enum":["not_started","in_progress","completed"]}}}}}}
```

## The Verification object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"Verification":{"type":"object","description":"A verification assigned to an applicant","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the verification"},"type":{"type":"string","enum":["asset_verification","identity_verification","payroll_income_verification","bank_income_verification","flexible_income_verification","document_income_verification"],"description":"Type of verification"},"status":{"type":"string","description":"Current status of the verification","enum":["not_started","in_progress","completed"]}}}}}}
```

## The Report object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"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"}}}}}}
```

## The ReportDataResponse object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"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"}}}}}}}}}
```

## The IncomeReportData object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}}}}
```

## The IdentityReportData object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"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}}}}}}}}}
```

## The AssetReportData object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}}}}
```