Create a new payee

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

Request Body

Field	Type	Required	Description	Validation Rules
`name`	String	Yes	Name of the payee	Min length: 1, Max length: 255. Note: external/bank rails may truncate to a smaller limit. Must contain only alphanumeric characters, spaces, hyphens, and underscores
`email`	String	Yes	Email address of the payee	Must be a valid email format
`country_code`	String	Yes	Country code of the payee	Must be “US” (only US is currently supported)
`country_sub_division`	String	No	State, province, or country subdivision	Max length: 35 characters
`city`	String	No	City or town name	Max length: 35 characters
`address_line`	String	No	Street address, building number, etc.	Max length: 500 characters
`postal_code`	String	No	Zip or postal code	Max length: 16 characters
`metadata`	Object	No	Arbitrary 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.

Success Responses

Status Code	Description
201	Created - The payee was successfully created

Error Responses

Status Code	Error Code	Description
400	VALIDATION_ERROR	The provided data failed validation
401	AUTHENTICATION_ERROR	Authentication credentials are invalid or missing
403	AUTHORIZATION_ERROR	You do not have permission to perform this action
409	DUPLICATE_EMAIL	A payee with the provided email already exists

Creates a new payee with the provided information. Email must be unique within the entity. **Request Body** | Field | Type | Required | Description | Validation Rules | |-------|------|----------|-------------|-----------------| | `name` | String | Yes | Name of the payee | Min length: 1, Max length: 255. Note: external/bank rails may truncate to a smaller limit. Must contain only alphanumeric characters, spaces, hyphens, and underscores | | `email` | String | Yes | Email address of the payee | Must be a valid email format | | `country_code` | String | Yes | Country code of the payee | Must be "US" (only US is currently supported) | | `country_sub_division` | String | No | State, province, or country subdivision | Max length: 35 characters | | `city` | String | No | City or town name | Max length: 35 characters | | `address_line` | String | No | Street address, building number, etc. | Max length: 500 characters | | `postal_code` | String | No | Zip or postal code | Max length: 16 characters | | `metadata` | Object | No | Arbitrary 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. | **Success Responses** | Status Code | Description | |-------------|-------------| | 201 | Created - The payee was successfully created | **Error Responses** | Status Code | Error Code | Description | |-------------|------------|-------------| | 400 | VALIDATION_ERROR | The provided data failed validation | | 401 | AUTHENTICATION_ERROR | Authentication credentials are invalid or missing | | 403 | AUTHORIZATION_ERROR | You do not have permission to perform this action | | 409 | DUPLICATE_EMAIL | A payee with the provided email already exists |

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

emailstringRequiredformat: "email"<=255 characters

country_codeenumOptional

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 null

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

Request Body

Field	Type	Required	Description	Validation Rules
`name`	String	Yes	Name of the payee	Min length: 1, Max length: 255. Note: external/bank rails may truncate to a smaller limit. Must contain only alphanumeric characters, spaces, hyphens, and underscores
`email`	String	Yes	Email address of the payee	Must be a valid email format
`country_code`	String	Yes	Country code of the payee	Must be “US” (only US is currently supported)
`country_sub_division`	String	No	State, province, or country subdivision	Max length: 35 characters
`city`	String	No	City or town name	Max length: 35 characters
`address_line`	String	No	Street address, building number, etc.	Max length: 500 characters
`postal_code`	String	No	Zip or postal code	Max length: 16 characters
`metadata`	Object	No	Arbitrary 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.

Success Responses

Status Code	Description
201	Created - The payee was successfully created

Error Responses

Status Code	Error Code	Description
400	VALIDATION_ERROR	The provided data failed validation
401	AUTHENTICATION_ERROR	Authentication credentials are invalid or missing
403	AUTHORIZATION_ERROR	You do not have permission to perform this action
409	DUPLICATE_EMAIL	A payee with the provided email already exists

$	curl -X POST https://api.useroot.com/api/payees \
>	-H "x-api-key: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"name": "John Doe",
>	"email": "john.doe@example.com",
>	"country_code": "US",
>	"country_sub_division": "NY",
>	"city": "New York",
>	"address_line": "123 Main Street, Apt 4B",
>	"postal_code": "10001"
>	}'

1	{
2	"data": {
3	"created_at": "2024-03-20T12:00:00Z",
4	"updated_at": "2024-03-20T12:00:00Z",
5	"id": "123e4567-e89b-12d3-a456-426614174000",
6	"name": "John Doe",
7	"email": "john.doe@example.com",
8	"country_code": "US",
9	"country_sub_division": "NY",
10	"city": "New York",
11	"address_line": "123 Main Street, Apt 4B",
12	"postal_code": "10001"
13	}
14	}