<!-- https://staircase.co/products/verification/tax -->
# Tax

# Tax

Income verification from tax transcripts and the returns behind them, as a check against employer-reported figures.

Transcript-derived income is the qualification path for a borrower whose income is not a straightforward salary — self-employment, rental income, and variable compensation all appear in returns before they appear in a payroll record.

The product reads the transcript and the return schedules, extracts the income lines that qualification uses, and writes them into the canonical income classes, where they sit alongside employer-reported figures from Income rather than replacing them.

## How it works

The two slots that share this name share nothing else. This one reads a borrower's tax record; the other reads a parcel's. The category is the only thing that distinguishes them, which is why the catalogue's own family and category fields matter more here than the name does.

What is recorded for this slot is its provisioning surface: activating a transcript partner, holding the credential that reaches it, and reading the schema that partner expects. The verification calls themselves are not separately recorded — they run through the same product surface every verification vertical shares.

## Dual listing

Tax is filed under two categories. The other listing is Tax under Assessment
<!--source:api-specifications-->
, and the recorded specifications resolve there — its 17 operations render on that page.
<!--/source-->

## Operations

<!--source:api-specifications-->

### Setup
<!--/source-->

`POST` `/partner/activate`

<!--source:api-specifications-->

#### Request to Activate Partner
<!--/source-->

`activatePartner`

<!--source:api-specifications-->
If you wish to use Staircase contract to activate a partner, please execute this endpoint.

By executing this API Staircase will be informed that you as our customer want to use requested partner for verification process.

The request body should contain which partner needs to be activated and for which environment. Once the request is received it will take between 1-3 working days to activate a partner. Once the partner is set up the partner will be active and ready to be used. You can check the partner status by calling the Retrieve Partners endpoint. If response for specific partner is "active": true, partner is ready to be used for verification.

List of partners available for activation: Modern Tax.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "partner": "partner_name",
 "environment": "my-domain.staircaseapi.com"
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
200400403422500
<!--/source-->

<!--source:api-specifications-->
application/json Copy Request to Activate API Triggered Successfully

```
{
 "message": "We have started with enabling Partner, Partner will be activated automatically after process is finished within X working days."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "message": "{'data': ['Missing data for required field.']}"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "message": "Invalid request body",
 "error": "[object has missing required properties ([\"client_secret\"])]"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error

```
{
 "message": "The product has encountered an internal server error"
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
1
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Environment API Key<!--/source--> |

##### Request body`application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `partner`required | `string` | <!--source:api-specifications-->Partner name that needs to be activated<!--/source--> |
| `environment`required | `string` | <!--source:api-specifications-->Environment for which the partner needs to be activated.<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request to Activate API Triggered Successfully
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

##### Response `422``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |
| `error` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error Message<!--/source--> |

##### Other responses

`404`

`POST` `/modernTax/credentials`

<!--source:api-specifications-->

#### Set Modern Tax Credentials
<!--/source-->

`setModernTaxCredentials`

<!--source:api-specifications-->
By using Set Modern Tax Credentials API we allow our customers to configure Modern Tax in customer environment.

If you don't have Modern Tax contract, please use our Request to Activate Partner API. Partner will be activated within next 3 business days.

If you want to use your own Modern Tax contract for verification, please check Request body Schema example for required values from partner side and execute Set Modern Tax Credentials API.

You can check the partner status by calling the Retrieve Partners endpoint.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "client_id": "--------",
 "client_secret": "<redacted>",
 "contract": "BYOC",
 "type": "test"
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
200400403422500
<!--/source-->

<!--source:api-specifications-->
application/json Copy Setup API Triggered Successfully

```
{
 "message": "Credentials are saved and verified"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "message": "{'data': ['Missing data for required field.']}"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "message": "Invalid request body",
 "error": "[object has missing required properties ([\"client_secret\"])]"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error

```
{
 "message": "The product has encountered an internal server error"
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
1
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Environment API Key<!--/source--> |

##### Request body`application/json`

<!--source:api-specifications-->
4 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `client_id`required | `string` | <!--source:api-specifications-->Modern Tax client ID value<!--/source--> |
| `client_secret`required | `string` | <!--source:api-specifications-->Modern Tax client secret value<!--/source--> |
| `contract` | `string` | <!--source:api-specifications-->Partner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC<!--/source--> |
| `type`required | `string` | <!--source:api-specifications-->Type of credentials, can be either test or production<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Setup API Triggered Successfully
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

##### Response `422``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |
| `error` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error Message<!--/source--> |

##### Other responses

`404`

`GET` `/partners/{partner}/schema`

<!--source:api-specifications-->

#### Retrieve Partner Credentials Schema
<!--/source-->

`getPartnerCredentialsSchema`

<!--source:api-specifications-->
Get Credentials Schema
<!--/source-->

<!--source:api-specifications-->
Get credentials schema for specific partner. You can use retrieved schema for updating the partner credentials.

<!--/source-->

##### Response

<!--source:api-specifications-->
400403422500
<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "message": "{'data': ['Missing data for required field.']}"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "message": "Invalid request body",
 "error": "[object has missing required properties ([\"client_secret\"])]"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error

```
{
 "message": "The product has encountered an internal server error"
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
2
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Environment API Key<!--/source--> |
| `partner` required | `string` path | `modernTax` | <!--source:api-specifications-->Partner name<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Create Adapter API Triggered Successfully
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

##### Response `422``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |
| `error` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error Message<!--/source--> |

##### Other responses

`404`

## Errors

`400``403``404``422``500`

## More in Verification

- Previous product: Income