Sign in

v1

latestOpenAPI 3.0.02026-07-2482421001.1 KB
Income

Configure income entity

This API allows you to update the employment start date for a borrower–employer pair linked to a specific Ocrolus <glossary:Book>. You can optionally include identifiers such as the employer’s EIN (Employer Identification Number) and the borrower’s last four SSN digits (Social Security Number) for more accurate matching. If the borrower–employer pair exists, the record is updated; otherwise, a new one is created. When provided, the employment start date is also used in income calculation to ensure the precise and consistent results across the platform.

📘 Note

  • If the borrower–employer pair already exists, the system updates the existing record with the new start date.
  • If the pair does not exist, a new configuration entry is created automatically.
  • Optional identifiers (ein, last_four_ssn_digits, and income_type) help ensure accurate borrower–employer matching.
post/v2/book/{uuid}/income/entity_config

Path parameters

uuidstring uuid required

The unique identifier of the Ocrolus <glossary:Book> for which borrower–employer data should be configured.

Request body

xidstring

A unique identifier for the borrower/employer pair. If you are using xid to match or update an existing income record, it is recommended to also provide the corresponding income_type. If income_type is not included, the system may not match the existing record.

employment_start_datestring date

Employment start date in the YYYY-MM-DD format.

income_type'WAGE_EARNER' | 'SELF_EMPLOYED'

Type of income of the borrower.

👍 Tip Providing income_type along with xid is recommended for accurate matching of existing records. If income_type is not provided, the system may not recognize the existing record.

Example request

{
  "entity_details": {
    "name": "ACME MANUFACTURING INC",
    "ein": "112233445"
  },
  "borrower_details": {
    "name": "JOHN A DOE",
    "last_four_ssn_digits": "6789"
  },
  "xid": "Xid-1",
  "employment_start_date": "2023-09-15",
  "income_type": "WAGE_EARNER"
}

Response

Success

Example response

{
  "response": {
    "data": {
      "uuid": "84b2e33c-94e0-4bb7-bb16-7125d553aa52",
      "book_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "borrower_details": {
        "name": "JOHN A DOE",
        "last_four_ssn_digits": "6789"
      },
      "entity_details": {
        "name": "ACME MANUFACTURING INC",
        "ein": "112233445"
      },
      "income_type": "WAGE_EARNER",
      "employment_start_date": "2023-09-15",
      "created_ts": "2025-10-15T13:44:42.367040",
      "updated_ts": "2025-09-15T13:44:42.367040",
      "xid": "XID-1"
    },
    "success": true,
    "code": 201
  }
}