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