> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://useroot.docs.buildwithfern.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://useroot.docs.buildwithfern.com/_mcp/server. # Create a new payee POST https://api.useroot.com/api/payees Content-Type: application/json 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 | Reference: https://useroot.docs.buildwithfern.com/api-reference/payees-api/create-payee ## Authentication - `x-api-key` header (required) — RootPay API key sent in the x-api-key header. Keys are environment-scoped: live_* for production, test_* for sandbox. ## Request ### Body (application/json) - `name` (string, required) - `email` (string, required) - `country_code` (enum, optional) - Allowed values: `US`, `GB`, `IN` - `country_sub_division` (string, optional, nullable) — State, province, or country subdivision - `city` (string, optional, nullable) — City or town name - `address_line` (string, optional, nullable) — Street address, building number, postal code, etc. - `postal_code` (string, optional, nullable) — Zip or postal code - `metadata` (map from string to string, optional, nullable) ## Response ### 201 Payee created successfully - `data` (object, required) - `created_at` (datetime, required) - `updated_at` (datetime, required) - `id` (string, required) - `name` (string, required) - `email` (string, required) - `country_code` (enum, optional) - Allowed values: `US`, `GB`, `IN` - `country_sub_division` (string, optional, nullable) — State, province, or country subdivision - `city` (string, optional, nullable) — City or town name - `address_line` (string, optional, nullable) — Street address, building number, postal code, etc. - `postal_code` (string, optional, nullable) — Zip or postal code - `client_metadata` (map from string to string, optional) - `warning` (string, optional, nullable) ## Examples **Request** ```json { "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" } ``` **Response** ```json { "data": { "created_at": "2024-03-20T12:00:00Z", "updated_at": "2024-03-20T12:00:00Z", "id": "123e4567-e89b-12d3-a456-426614174000", "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" } } ``` **SDK Code** ```python United States payee import requests url = "https://api.useroot.com/api/payees" payload = { "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" } headers = { "x-api-key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript United States payee const url = 'https://api.useroot.com/api/payees'; const options = { method: 'POST', headers: {'x-api-key': '', 'Content-Type': 'application/json'}, body: '{"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"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go United States payee package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.useroot.com/api/payees" payload := strings.NewReader("{\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"country_code\": \"US\",\n \"country_sub_division\": \"NY\",\n \"city\": \"New York\",\n \"address_line\": \"123 Main Street, Apt 4B\",\n \"postal_code\": \"10001\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("x-api-key", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby United States payee require 'uri' require 'net/http' url = URI("https://api.useroot.com/api/payees") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["x-api-key"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"country_code\": \"US\",\n \"country_sub_division\": \"NY\",\n \"city\": \"New York\",\n \"address_line\": \"123 Main Street, Apt 4B\",\n \"postal_code\": \"10001\"\n}" response = http.request(request) puts response.read_body ``` ```java United States payee import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.useroot.com/api/payees") .header("x-api-key", "") .header("Content-Type", "application/json") .body("{\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"country_code\": \"US\",\n \"country_sub_division\": \"NY\",\n \"city\": \"New York\",\n \"address_line\": \"123 Main Street, Apt 4B\",\n \"postal_code\": \"10001\"\n}") .asString(); ``` ```php United States payee request('POST', 'https://api.useroot.com/api/payees', [ 'body' => '{ "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" }', 'headers' => [ 'Content-Type' => 'application/json', 'x-api-key' => '', ], ]); echo $response->getBody(); ``` ```csharp United States payee using RestSharp; var client = new RestClient("https://api.useroot.com/api/payees"); var request = new RestRequest(Method.POST); request.AddHeader("x-api-key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"country_code\": \"US\",\n \"country_sub_division\": \"NY\",\n \"city\": \"New York\",\n \"address_line\": \"123 Main Street, Apt 4B\",\n \"postal_code\": \"10001\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift United States payee import Foundation let headers = [ "x-api-key": "", "Content-Type": "application/json" ] let parameters = [ "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" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.useroot.com/api/payees")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```