# Applicant Groups

## List all applicant groups

> Retrieves a paginated list of all applicant groups. Supports filtering by status, correlation ID, creation date range, and search query.

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"tags":[{"name":"Applicant Groups"}],"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":{"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"]}}}}},"paths":{"/api/v1/applicant_groups":{"get":{"summary":"List all applicant groups","description":"Retrieves a paginated list of all applicant groups. Supports filtering by status, correlation ID, creation date range, and search query.","operationId":"listApplicantGroups","tags":["Applicant Groups"],"parameters":[{"name":"search","in":"query","description":"Search query to filter applicant groups","schema":{"type":"string"}},{"name":"statuses","in":"query","description":"Comma-separated list of statuses to filter by","schema":{"type":"string"}},{"name":"correlation_id","in":"query","description":"Filter by external correlation identifier","schema":{"type":"string"}},{"name":"created_after","in":"query","description":"Filter applicant groups created after this Unix timestamp","schema":{"type":"integer","format":"int"}},{"name":"created_before","in":"query","description":"Filter applicant groups created before this Unix timestamp","schema":{"type":"integer","format":"int"}},{"name":"page","in":"query","description":"Page number for pagination","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"List of applicant groups retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"applicant_groups":{"type":"array","items":{"$ref":"#/components/schemas/ApplicantGroup"}},"total_count":{"type":"integer","description":"Total number of applicant groups matching the query"}}}}}},"401":{"description":"Unauthorized - invalid or missing authentication token"}}}}}}
```

## Create a new applicant group

> Creates a new applicant group to send applicants their corresponding verifications. When an applicant group is created successfully, an email and/or text is sent to all applicants inviting them to complete their verifications unless the invitation is disabled.

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"tags":[{"name":"Applicant Groups"}],"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":{"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"]}}}}},"paths":{"/api/v1/applicant_groups":{"post":{"summary":"Create a new applicant group","description":"Creates a new applicant group to send applicants their corresponding verifications. When an applicant group is created successfully, an email and/or text is sent to all applicants inviting them to complete their verifications unless the invitation is disabled.","operationId":"createApplicantGroup","tags":["Applicant Groups"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["applicants","property","decision_maker_display_name","monthly_rent"],"properties":{"applicants":{"type":"array","description":"The applicants attached to the verification request","minItems":1,"items":{"type":"object","required":["first_name","last_name","email","verifications"],"properties":{"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. This is the email address where we will send the verification invite"},"phone_number":{"type":"string","description":"Applicant's phone number, including the international code (ex. +19842342345). \nIncluding this will send a text message invite as well as an email.\n"},"verifications":{"type":"array","description":"Types of verification to be sent to applicant","minItems":1,"items":{"type":"object","properties":{"type":{"type":"string","enum":["asset_verification","identity_verification","payroll_income_verification","bank_income_verification","flexible_income_verification","document_income_verification"],"description":"Type of verification"},"allowed_income_sources":{"type":"array","description":"Restricts which income sources the applicant may use to complete a flexible_income_verification.\nOnly applicable when type is flexible_income_verification. If omitted, the tenant's default\nallowed income sources are used.\n","items":{"type":"string","enum":["bank","payroll","applicant_document","support_document"]}}}}}}}},"property":{"type":"object","description":"The property's address that will be displayed in the applicant workflow to let the applicant know they are in the right place.","required":["name","street_address","city","state","zip_code"],"properties":{"name":{"type":"string","description":"The property's name"},"street_address":{"type":"string","description":"The property's street address"},"city":{"type":"string","description":"The property's city"},"state":{"type":"string","description":"The property's state"},"zip_code":{"type":"string","description":"The property's ZIP code"},"unit":{"type":"string","description":"Unit number"}}},"decision_maker_display_name":{"type":"string","description":"Display name for the decision maker"},"monthly_rent":{"type":"number","format":"integer","description":"Monthly rent amount in dollars"},"webhook_url":{"type":"string","description":"The URL that will receive webhook notifications for the applicant group created.\n"},"is_invitation_disabled":{"type":"boolean","description":"If you decide to not want Payscore to invite the applicant via email and/or text, pass in true for this field.\nIf you are utilizing our embedded widget, you will want to pass in true to this field.\n"},"correlation_id":{"type":"string","description":"External system correlation identifier"},"config":{"type":"object","description":"Optional configuration overrides for this applicant group","properties":{"block_business_accounts":{"type":"boolean","description":"When true, applicants will be blocked from connecting business bank accounts\nor uploading business statements during income verification. Defaults to false if not included.\n"}}}}}}}},"responses":{"200":{"description":"Applicant group created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicantGroup"}}}},"400":{"description":"Bad request - validation errors","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"}}}}}}}}}}}}
```


---

# 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/applicant-groups.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.