---
title: "Read payee tax status"
method: POST
path: "/payeeTaxStatus"
---

# Read payee tax status

`POST /payeeTaxStatus`

## Request

- Base URL: `https://api.cowrie.io`
- URL: `https://api.cowrie.io/payeeTaxStatus`
- Auth: API key in header `Authorization`

Privileged per-payee read returning completion state plus the flat withholding rate in integer basis points (stored 24% -> `2400`). Requires a client secret carrying the `payee_tax_detail` scope. This is a server-to-server interface: no CORS headers are set, so it cannot be called from a browser. `withholdingRateBps: null` means no flat rate exists for the payee: either no completed submission, or a payment-dependent form family (8233) whose withholding cannot be expressed as a flat rate even after completion. The address `0x0000000000000000000000000000000000000001` is reserved for testing and always returns `completed: true` with a null rate.

## Request body

- object
  - `ethereumAddress` string, required: EVM-compatible address of the payee.

## Response `200`

Completion state and flat withholding rate for the payee.

- object
  - `completed` boolean: Whether screening is complete.
  - `withholdingRateBps` integer, nullable: Flat withholding rate in integer basis points, or null when no flat rate exists.

## Other responses

- `400`: Invalid address payload.
- `401`: Missing or invalid client credentials.
- `403`: Client lacks the `payee_tax_detail` scope.

---

[API](https://skmtc.dev/cowrie/apis/cowrie-api.md) - [All operations](https://skmtc.dev/cowrie/apis/cowrie-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cowrie/apis/cowrie-api/revisions/fb6c0613b557?raw)