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


---

# 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/models.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.