---
title: "Configure income entity"
method: POST
path: "/v2/book/{uuid}/income/entity_config"
tags: ["Income"]
---

# Configure income entity

`POST /v2/book/{uuid}/income/entity_config`

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.

## Path parameters

- `uuid` string, uuid, required

## Request body

- object
  - `entity_details` object, required — Details about the employer entity.
    - `name` string, required — Full legal name of the employer.
    - `ein` string — Employer's Identification Number (EIN).
  - `borrower_details` object, required — Details about the borrower.
    - `name` string, required — Full name of the borrower.
    - `last_four_ssn_digits` string — Last four digits of the borrower's SSN.
  - `xid` string — 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_date` string, 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.

## Response `200`

Success

- object
  - `response` object — Response object containing income entity details.
    - `data` object — Contains the details of the income entity.
      - `uuid` string, uuid — Unique identifier for the borrower–employer configuration.
      - `book_uuid` string, uuid — Unique identifier of the Ocrolus Book.
      - `borrower_details` object — Object containing borrower information.
        - `name` string — Name of the borrower.
        - `last_four_ssn_digits` string — Last four digits of the borrower's SSN.
      - `entity_details` object — Object containing employer details.
        - `name` string — Name of the entity.
        - `ein` string — Employer Identification Number (EIN) of the entity.
      - `income_type` 'SELF_EMPLOYED' | 'WAGE_EARNER' — Type of income.
      - `employment_start_date` string, date — Employment start date.
      - `created_ts` string, date-time — Timestamp when the configuration was created.
      - `updated_ts` string, date-time — Timestamp when the configuration was updated.
      - `xid` string — A unique identifier for the borrower/employer pair.
    - `success` boolean — Indicates if the request was successful.
    - `code` integer — HTTP status code of the response.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `500` — Internal Server Error

---

[API](https://skmtc.net/ocrolus/apis/user-management.md) · [All operations](https://skmtc.net/ocrolus/apis/user-management/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ocrolus/user-management/versions/3571ef602d13/schema)