Applicant Groups

List all applicant groups

get

https://api.payscore.comhttps://staging.api.payscore.com

/api/v1/applicant_groups

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

Authorizations

bearerAuth

AuthorizationstringRequired

JWT token obtained from the /api/v1/tenants/auth endpoint. Token expires after 30 minutes and must be refreshed.

Example: Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

Query parameters

searchstringOptional

Search query to filter applicant groups

Example: Jane Doe

statusesstringOptional

Comma-separated list of statuses to filter by

Example: not_started,in_progress,completed

correlation_idstringOptional

Filter by external correlation identifier

Example: PROP-123-UNIT-456

created_afterinteger · intOptional

Filter applicant groups created after this Unix timestamp

Example: 1761966000

created_beforeinteger · intOptional

Filter applicant groups created before this Unix timestamp

Example: 1764557999

pageinteger · min: 1Optional

Page number for pagination

Example: 1

Responses

200

List of applicant groups retrieved successfully

application/json

total_countintegerOptional

Total number of applicant groups matching the query

Example: 150

401

Unauthorized - invalid or missing authentication token

get

/api/v1/applicant_groups

HTTPcURLJavaScriptPython

GET /api/v1/applicant_groups HTTP/1.1
Host: api.payscore.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "applicant_groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "decision_maker_display_name": "ABC Property Management",
      "property": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "ABC Apartments",
        "street_address": "123 Main Street",
        "city": "San Francisco",
        "state": "CA",
        "zip_code": "94102"
      },
      "status": "in_progress",
      "created_at_timestamp": 1640995200.123,
      "monthly_rent_cents": 250000,
      "unit_number": "2A",
      "unit_id": "550e8400-e29b-41d4-a716-446655440003",
      "is_free": false,
      "is_decision_maker_paying": true,
      "correlation_id": "PROP-123-UNIT-456",
      "verification_types": [
        "payroll_income_verification",
        "identity_verification"
      ],
      "is_expired": false,
      "applicants": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440001",
          "first_name": "Jane",
          "last_name": "Doe",
          "email": "[email protected]",
          "phone_number": "[phone]",
          "created_at": "2024-01-01T12:00:00Z",
          "updated_at": "2024-01-01T12:00:00Z",
          "verifications": [
            {
              "id": "123e4567-e89b-12d3-a456-426614174000",
              "type": "asset_verification",
              "status": "in_progress"
            }
          ]
        }
      ]
    }
  ],
  "total_count": 150
}

Create a new applicant group

post

https://api.payscore.comhttps://staging.api.payscore.com

/api/v1/applicant_groups

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.

Authorizations

bearerAuth

AuthorizationstringRequired

JWT token obtained from the /api/v1/tenants/auth endpoint. Token expires after 30 minutes and must be refreshed.

Example: Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

Body

application/json

decision_maker_display_namestringRequired

Display name for the decision maker

Example: ABC Property Management

monthly_rentnumber · integerRequired

Monthly rent amount in cents

Example: 250000

webhook_urlstringOptional

The URL that will receive webhook notifications for the applicant group created.

Example: https://www.yourwebsite.com/webhook

is_invitation_disabledbooleanOptional

If you decide to not want Payscore to invite the applicant via email and/or text, pass in true for this field. If you are utilizing our embedded widget, you will want to pass in true to this field.

correlation_idstringOptional

External system correlation identifier

Example: PROP-123-UNIT-456

Responses

200

Applicant group created successfully

application/json

An applicant group represents a verification request for multiple applicants

idstring · uuidOptional

Unique identifier for the applicant group

Example: 550e8400-e29b-41d4-a716-446655440000

decision_maker_display_namestringOptional

Display name for the decision maker

Example: ABC Property Management

statusstring · enumOptional

Current status of the applicant group

Example: in_progressPossible values:

created_at_timestampnumber · floatOptional

Unix timestamp when the applicant group was created

Example: 1640995200.123

monthly_rent_centsintegerOptional

Monthly rent amount in cents

Example: 250000

unit_numberstringOptional

Unit number or identifier

Example: 2A

unit_idstring · uuid · nullableOptional

Unique identifier for the unit

Example: 550e8400-e29b-41d4-a716-446655440003

is_freebooleanOptional

Whether this is a free verification

Example: false

is_decision_maker_payingbooleanOptional

Whether the decision maker is paying for the verification

Example: true

correlation_idstring · nullableOptional

External system correlation identifier

Example: PROP-123-UNIT-456

is_expiredbooleanOptional

Whether the applicant group has expired

Example: false

400

Bad request - validation errors

application/json

post

/api/v1/applicant_groups

HTTPcURLJavaScriptPython

POST /api/v1/applicant_groups HTTP/1.1
Host: api.payscore.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 501

{
  "applicants": [
    {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone_number": "[phone]",
      "verifications": [
        {
          "type": "asset_verification"
        }
      ]
    }
  ],
  "property": {
    "name": "ABC Apartments",
    "street_address": "123 Main Street",
    "city": "San Francisco",
    "state": "CA",
    "zip_code": "94102",
    "unit": "2A"
  },
  "decision_maker_display_name": "ABC Property Management",
  "monthly_rent": 250000,
  "webhook_url": "https://www.yourwebsite.com/webhook",
  "is_invitation_disabled": true,
  "correlation_id": "PROP-123-UNIT-456"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "decision_maker_display_name": "ABC Property Management",
  "property": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "ABC Apartments",
    "street_address": "123 Main Street",
    "city": "San Francisco",
    "state": "CA",
    "zip_code": "94102"
  },
  "status": "in_progress",
  "created_at_timestamp": 1640995200.123,
  "monthly_rent_cents": 250000,
  "unit_number": "2A",
  "unit_id": "550e8400-e29b-41d4-a716-446655440003",
  "is_free": false,
  "is_decision_maker_paying": true,
  "correlation_id": "PROP-123-UNIT-456",
  "verification_types": [
    "payroll_income_verification",
    "identity_verification"
  ],
  "is_expired": false,
  "applicants": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone_number": "[phone]",
      "created_at": "2024-01-01T12:00:00Z",
      "updated_at": "2024-01-01T12:00:00Z",
      "verifications": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "type": "asset_verification",
          "status": "in_progress"
        }
      ]
    }
  ]
}