Skip to navigation

Create a new payee

View as Markdown

Creates a new payee with the provided information. Email must be unique within the entity.

Request Body

FieldTypeRequiredDescriptionValidation Rules
nameStringYesName of the payeeMin length: 1, Max length: 255. Note: external/bank rails may truncate to a smaller limit. See Name rules below.
emailStringYesEmail address of the payeeMust be a valid email address. Must be unique among your payees. Special-use domains (such as .test) are rejected; see Email rules below.
country_codeStringYesCountry code of the payeeMust be “US” (only US is currently supported)
country_sub_divisionStringNoState, province, or country subdivisionMax length: 35 characters
cityStringNoCity or town nameMax length: 35 characters
address_lineStringNoStreet address, building number, etc.Max length: 500 characters
postal_codeStringNoZip or postal codeMax length: 16 characters
metadataObjectNoArbitrary metadata as key-value pairs to store with the payee for your own reference.Must be an object with string keys and string values. Maximum 50 keys, each key max 40 characters, each value max 500 characters, total size max 16KB.

Name rules

name may contain only:

  • Letters A–Z and a–z
  • Characters in Unicode range U+00C0–U+017F: accented Latin letters (for example é, ñ, ü, ł), plus × and ÷
  • Digits 0–9
  • Spaces, hyphens (-), underscores (_), and straight apostrophes (')

Any other character is rejected, including &, ,, ., /, (, ), en dash (–), em dash (—), and curly apostrophe (’). For example, O'Brien and José Núñez are accepted. Smith & Sons, LLC and Ana–María are rejected. To send a business name, remove or replace the punctuation (for example, Smith and Sons LLC).

Leading and trailing spaces are removed, and runs of whitespace become one space, before the name is checked and stored.

Email rules

email must be a valid address, and it must be unique among your payees. Addresses on special-use domains are rejected: .arpa, .invalid, .local, .localhost, .onion, and .test. In the test environment, use an address on a real domain that you control.

Success Responses

Status CodeDescription
201Created - The payee was successfully created

Error Responses

Status CodeError CodeDescription
401AUTHENTICATION_ERRORAuthentication credentials are invalid or missing
403AUTHORIZATION_ERRORYou do not have permission to perform this action
409DUPLICATE_RESOURCEA payee with this email already exists. details.duplicate_fields is ["email"].
422VALIDATION_ERRORThe request body failed validation, for example a name with characters that are not allowed or an email on a reserved domain. details.errors[] lists each failing field and its message.

Example: duplicate email (409)

{
"error_code": "DUPLICATE_RESOURCE",
"message": "A payee with this email already exists",
"details": { "duplicate_fields": ["email"] }
}

Example: name not allowed (422)

{
"error_code": "VALIDATION_ERROR",
"message": "The provided data failed validation",
"details": {
"path": "https://api.useroot.com/api/payees",
"errors": [
{
"field": "body.name",
"message": "Value error, Name may contain only letters A-Z and a-z, characters in U+00C0-U+017F (accented Latin letters such as é, ñ, ü, ł, plus × and ÷), digits, spaces, hyphens (-), underscores (_), and straight apostrophes ('). Other punctuation, such as & , . / ( ), en or em dashes, and curly apostrophes (’), is not allowed.",
"type": "value_error"
}
]
}
}

Authentication

x-api-keystring

RootPay API key sent in the x-api-key header. Keys are environment-scoped: live_* for production, test_* for sandbox.

Request

This endpoint expects an object.
namestringRequired1-255 characters

Name may contain only letters A-Z and a-z, characters in U+00C0-U+017F (accented Latin letters such as é, ñ, ü, ł, plus × and ÷), digits, spaces, hyphens (-), underscores (_), and straight apostrophes (’). Other punctuation, such as & , . / ( ), en or em dashes, and curly apostrophes (’), is not allowed.

emailstringRequiredformat: "email"<=255 characters

Must be a valid email address. Special-use domains are rejected: .arpa, .invalid, .local, .localhost, .onion, and .test.

country_codeenumOptional
Allowed values:
country_sub_divisionstring or nullOptional<=35 characters
State, province, or country subdivision
citystring or nullOptional<=35 characters
City or town name
address_linestring or nullOptional<=500 characters
Street address, building number, postal code, etc.
postal_codestring or nullOptional<=16 characters
Zip or postal code
metadatamap from strings to strings or nullOptional

Response

Payee created successfully
dataobject
warningstring or nullOptional