--- title: "Create a Payee" method: POST path: "/payables/payer_accounts/{payer_id}/payees" tags: ["Payees"] --- # Create a Payee `POST /payables/payer_accounts/{payer_id}/payees` ## Request - Base URL: `https://api.justifi.ai/v1` - URL: `https://api.justifi.ai/v1/payables/payer_accounts/{payer_id}/payees` - Auth: none declared. Required headers: `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Create a payee under this payer account. `name`, `entity_type`, `tax_id` and `address` are all required — together they are the identity a payee is paid and filed against, and none of them has a sensible default. A payee is still created without a bank account and has one registered later, through `CreateBankAccount`. `entity_type` and `tax_id` are fixed here — they are the taxpayer the payee is filed against, and `UpdatePayee` does not accept them. **The payer account must be `active`.** A payer account that is `pending`, `disabled` or `archived` creates nothing, and a payee create under one is refused with a `400`. ## Path parameters - `payer_id` string, required ## Headers - `Authorization` string, required ## Request body - object - `name` string, required: the payee's legal name - `entity_type` 'c_corporation' | 's_corporation' | 'partnership' | 'limited_liability_company' | 'sole_proprietorship', required: the payee's IRS entity classification; no default, and not changeable later - `tax_id` string, required: the payee's taxpayer identification number — **an EIN or an SSN**, nine digits with or without separators. Which one it is follows `entity_type`: a `sole_proprietorship` files under the proprietor's SSN, or under an EIN where it has one; every other entity type files under an EIN. Write-only — it is stored encrypted and never returned; responses carry `tax_id_last4`. Payables does not validate it against the IRS, and does not check it against the entity type. - `address` object, required: A postal address, in the shape JustiFi's other APIs use. The shape is enforced; the address itself is not — Payables does not verify that it exists, and stores it as given without normalizing case or spacing. - `line1` string: street address - `line2` string, nullable: suite, unit or floor, when there is one - `city` string - `state` string: two-letter state or territory code, uppercase. Not normalized — `mn` is rejected rather than corrected. - `postal_code` string: ZIP or ZIP+4 - `country` 'USA': ISO 3166-1 alpha-3 country code, matching the rest of JustiFi. `USA` is the only value Payables accepts — it pays by US domestic ACH and files US tax forms — and it is what a payee gets when the field is omitted. - `email` string, email - `metadata` object ## Response `201` Payee was created successfully - object: the standard JustiFi response envelope for a single record - `id` string, required: the object id, also found in the data object - `type` string, required: the object type - `data` object, required: A payee is a party that receives Payables payments. Payees are standalone: they can exist and be paid without being tied to a business. `business_id` reports a link to a JustiFi business where there is one, and is null by default. - `id` string: unique payee id - `type` string: the object type, matching the enclosing envelope's `type` - `payer_account_id` string: the id of the payer account this payee is scoped to - `name` string: the payee's legal name. Required on create. - `entity_type` 'c_corporation' | 's_corporation' | 'partnership' | 'limited_liability_company' | 'sole_proprietorship': the payee's IRS entity classification. Required on create, with no default — it decides both the tax form filed for the payee and, for `sole_proprietorship`, how the ACH credit to them is classified. Immutable — with `tax_id` it is the taxpayer this payee is filed against. The set is open and may grow; unknown values should be treated as a business entity. - `email` string, email, nullable: contact email for the payee, when provided - `tax_id_last4` string: the last four digits of the payee's taxpayer identification number — an EIN, or an SSN where the payee is a `sole_proprietorship`. The number itself is required on create and never returned — it is stored encrypted, and this is what reads back. Immutable, on the same terms as `entity_type`. - `address` object: the payee's address. Required on create. - `line1` string: street address - `line2` string, nullable: suite, unit or floor, when there is one - `city` string - `state` string: two-letter state or territory code, uppercase. Not normalized — `mn` is rejected rather than corrected. - `postal_code` string: ZIP or ZIP+4 - `country` 'USA': ISO 3166-1 alpha-3 country code, matching the rest of JustiFi. `USA` is the only value Payables accepts — it pays by US domestic ACH and files US tax forms — and it is what a payee gets when the field is omitted. - `receiving_bank_account_id` string, nullable: pointer to the payee's active receiving bank account (denormalized for lookup, like capital's `accounts.payout_account_id`). In this version a payee has a single active account. Null until one is registered. - `business_id` string, nullable: the business this payee belongs to, where JustiFi has linked one. Null for standalone payees, and a payee is created and paid without one. - `status` 'pending' | 'active' | 'disabled' | 'archived': the payee's status. `pending` — created but not cleared for payments; `active` — able to receive payments, and the only state a payment can be scheduled or paid out under; `disabled` — was active previously and can no longer be paid; `archived` — was active previously and can never be paid again. A payment whose payee credit is already held is not paid out while the payee is not `active`. It stays held until the payee is active again, rather than failing. **Payables disables a payee when its bank says the account cannot be paid.** Either the bank returned a credit for a reason a retry will not change — the account is closed, frozen, not a transaction account, or does not exist — or it sent a notification of change we cannot act on, because it named no corrected numbers or corrects something Payables does not hold. Both mean the next payment would go to an account the bank has already refused. A correction about the entry rather than the account — the payee's name, the entry description — changes nothing. **Registering a corrected receiving bank account returns the payee to `active`**, and any payment held for it pays out on the next cycle. Until then those payments wait rather than failing, which is what stops a queue of payments following the first one into a closed account. - `metadata` object: any useful information you'd like to store alongside this payee - `created_at` string, date-time - `updated_at` string, date-time - `page_info` unknown, required ## Other responses - `400`: The request was malformed, failed validation, or referenced a resource that cannot be used in its current state — for example scheduling a payment to a payee that is not active, or creating anything under a payer account that is not active. When the failure is field-level, `error.details` carries one array of messages per rejected attribute. - `401`: The access token is missing, expired, or invalid. - `403`: The credentials are valid but not permitted to access this resource. - `404`: No resource exists for the given id (within the scoped payer account). - `422`: The request was well-formed and passed field validation, but a business rule rejected it — for example a payer funding account that is not `verified`, or a payee with no receiving bank account to credit. Field-level validation failures return `400`, not this. `error.details` carries per-attribute messages where the rule is attributable to one. - `429`: The rate limit has been exceeded. Back off and retry after the interval indicated by the `Retry-After` header. --- [API](https://skmtc.dev/justifi/apis/justifi-api-documentation.md) - [All operations](https://skmtc.dev/justifi/apis/justifi-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/justifi/apis/justifi-api-documentation/revisions/dd9f3fed7e46?raw)