{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"759e0ee1-d097-4b93-ad95-124e86aaf513","name":"Root - Instant Account to Account Money Movement","description":"Root is an instant money movement platform that connects directly to your bank and enables you to configure and initiate money movement workflows intelligently. Its simple to implement and free to get started.\n\nIf you're a marketplace with high money movement volume, you're likely using platforms like Airwallex, Hyperwallet, Payoneer, or Bill.com, for various workflows like account receivables, account payables, mass payouts & disbursements. Each of these platforms are practically closed loop systems (you have to pre-fund and hold money in those accounts) charging high fees, slow processing times, and complex reconciliation processes. Building this functionality directly on your existing bank infrastructure might seem like an option, but it’s costly, time-consuming, and riddled with technical challenges. Root seamlessly connects to your existing bank accounts, simplifying workflows with just a few API calls. It eliminates inefficiencies, delivers faster transactions (in many cases near instant settlements), ensures reliable reconciliation, and saves you money.\n\nThis guide will walk you through implementing Root in your system.\n\n---\n\n## API Reference\n\nThe Root API follows REST principles with JSON-encoded requests and responses. You'll find familiar HTTP methods, standardized response codes, and predictable URL patterns.\n\n## Key Features\n\n- **Seamless Integration**: Use test mode to simulate payout operations without touching live data or financial networks. Your API key determines whether you're working in test mode or live mode.\n    \n- **Single & Bulk Operations**: Perform single-object actions or handle bulk updates with ease, giving you full control over how you manage payouts.\n    \n- **Evolving with You**: The API adapts through versioning and customizations specific to your account, so it grows alongside your needs.\n    \n\n## Getting Started\n\nThis guide takes you through each step of managing payouts—from setting up your environment to running tests, and finally deploying to production. Here's the roadmap:\n\n- **Configure Your Environment**: Get your API keys and configure your environment\n    \n- **Test Your Integration**: Use test mode to verify your implementation works correctly\n    \n- **Go Live**: Switch to live mode when you're ready to process real transactions\n    \n\n## Test Mode vs. Live Mode\n\nYour API key determines which mode you're in:\n\n- **Test Mode**: Safely simulate API calls in a sandbox environment. Test mode keys are only valid in this environment and do not affect live data or external systems. Test mode credentials are prefixed with `test_`.\n    \n- **Live Mode**: Once your integration is tested and ready, switch to live mode to interact with real data and systems. Live mode credentials are prefixed with `live_`.\n    \n\nEach mode uses separate API keys. Be cautious when switching between modes to avoid unintended interactions. You can find more about the test environemt in the **Test Environment** section.\n\n---\n\n## API Authentication\n\nAll API requests require an API key for authentication. This key uniquely identifies your account and ensures only authorized users can access your data.\n\n#### **Using API Key Authentication**\n\n- To authenticate your requests, include your API key in the X`-API-KEY` HTTP header:\n    \n\n``` plaintext\nX-API-KEY: [YOUR_API_KEY]\n\n ```\n\n**Ensure your API key is kept secure**:\n\n- Do not expose your API key in publicly accessible locations, such as GitHub repositories or client-side code.\n    \n- Rotate your API key periodically to minimize security risks.\n    \n\n<img src=\"https://content.pstmn.io/0eaf89e1-ec69-4881-a617-8c3594bccc95/T25ib2FyZGluZy5naWY=\" alt=\"Auth%20Flow\">\n\n---\n\n## Pagination\n\nYou can paginate through lists of objects using cursor-based pagination. Each list endpoint supports this feature. This is a forward-only pagination system that returns objects in chronological order. You can control pagination using these parameters:\n\n- `limit`: Set the number of objects per page (default varies by endpoint, max: 100)\n    \n- `cursor`: Get objects created after a specific object ID (forward pagination only)\n    \n- `order`: Sort order by created_at - \"desc\" for newest first (default), \"asc\" for oldest first\n    \n\n**Note:** This implementation supports forward-only pagination. You can move forward through pages by using the `next_cursor` from the previous response.\n\n#### Example\n\n```\n// Get the first page (newest first by default)\nGET /transfers?limit=25\n// Get oldest first instead\nGET /transfers?limit=25&order=asc\n// Get the next page using the next_cursor from previous response\nGET /transfers?limit=25&cursor=transfer_123&order=desc\n\n ```\n\n#### Response Format\n\nThe API response includes pagination metadata to help you navigate through pages:\n\n```\n{\n  \"data\": [...],\n  \"has_more\": true,           // More pages exist\n  \"total_count\": 150,         // Total number of records\n  \"next_cursor\": \"transfer_148\", // Use this cursor to get the next page\n  \"previous_cursor\": \"transfer_123\" // The cursor used to get current page (for reference)\n}\n\n ```\n\n**Pagination Flow:**\n\n- **First page**: Make a request without a cursor parameter\n    \n- **Subsequent pages**: Use the `next_cursor` value from the previous response as the `cursor` parameter\n    \n- **End of results**: When `has_more` is `false`, you've reached the end\n    \n\n---\n\n## Idempotency\n\nAll transfer creation requests support idempotency to help you safely retry operations without creating duplicate transactions. This is particularly useful when your API call fails and you aren't sure if your request was received.\n\nTo make an idempotent request, add an `Idempotency-Key` header with a unique value:\n\n```\nIdempotency-Key: <your-unique-key>\n\n ```\n\nWhen you include this header, we'll ensure that multiple requests with the same key return the same result, preventing duplicate operations. The first request creates the transfer, while subsequent requests with the same key return the original result.\n\n#### Example: Request Without Idempotency\n\nHere's a transfer request without an `Idempotency-Key` header:\n\n``` shell\ncurl --location https://api.useroot.com/payouts --header 'Content-Type: application/json' --header 'X-API-KEY: [YOUR_API_KEY]' --data '{\n    \"payee_id\": \"0862d70b-e74d-428e-99f5-11e942e23d90\",\n    \"amount_in_cents\": 100,\n    \"currency_code\": \"USD\"\n}'\n\n ```\n\nIf this API call is repeated (for example, if a user double-clicks a submit button in your web interface), it could create duplicate transfers and cause double spending.\n\n#### Example: Using Idempotency\n\nHere's how to prevent duplicate transfers using an `Idempotency-Key`:\n\n``` shell\n# First request\ncurl --location https://api.useroot.com/payouts -H \"Idempotency-Key: 1zByArFNupaumBTijz3XXTlj9ZL\"\n--header 'Content-Type: application/json' --header 'X-API-KEY [YOUR_API_KEY]' --data '{\n    \"payee_id\": \"0862d70b-e74d-428e-99f5-11e942e23d90\",\n    \"amount_in_cents\": 100,\n    \"currency_code\": \"USD\"\n}'\n# Second request with same Idempotency-Key\ncurl --location https://api.useroot.com/payouts -H \"Idempotency-Key: 1zByArFNupaumBTijz3XXTlj9ZL\"\n--header 'Content-Type: application/json' --header 'X-API-KEY [YOUR_API_KEY]' --data '{\n    \"payee_id\": \"0862d70b-e74d-428e-99f5-11e942e23d90\",\n    \"amount_in_cents\": 100,\n    \"currency_code\": \"USD\"\n}'\n\n ```\n\nIn this example, both requests include the same `Idempotency-Key`. Only the first request creates a transfer - the second request returns the result of the first operation, preventing any duplicate transfers.\n\n#### Safe Retry Guide\n\nIdempotency keys are looked up by key only (not by request body comparison). This means you can safely retry requests with the same idempotency key after any error.\n\n**When to retry with the same key:**\n\n- After network errors or timeouts\n    \n- After 500 Internal Server Error or 503 Service Unavailable\n    \n- After any unexpected error where you're unsure if the request was processed\n    \n\n**Response codes:**\n\n- **200 OK**: Resource already exists - safe to use the returned resource\n    \n- **201 Created**: New resource was created\n    \n- **400 Bad Request**: Validation error - fix your request before retrying\n    \n\n**Example: Retry after error**\n\n``` shell\n# First request fails with 500 error\ncurl --location https://api.useroot.com/payouts -H \"Idempotency-Key: retry-key-123\" --header 'Content-Type: application/json' --header 'X-API-KEY: [YOUR_API_KEY]' --data '{\n    \"payee_id\": \"0862d70b-e74d-428e-99f5-11e942e23d90\",\n    \"amount_in_cents\": 100,\n    \"currency_code\": \"USD\"\n}'\n# Returns: 500 Internal Server Error\n# Retry with same idempotency key - safe!\ncurl --location https://api.useroot.com/payouts -H \"Idempotency-Key: retry-key-123\" --header 'Content-Type: application/json' --header 'X-API-KEY: [YOUR_API_KEY]' --data '{\n    \"payee_id\": \"0862d70b-e74d-428e-99f5-11e942e23d90\",\n    \"amount_in_cents\": 100,\n    \"currency_code\": \"USD\"\n}'\n# Returns: 200 OK with existing payout (if created) or 201 Created (if not)\n\n ```\n\n---\n\n## Error Handling\n\nWe provide detailed error responses to help you quickly identify and resolve issues.\n\n#### HTTP Status Codes\n\nThe HTTP status code indicates the general category of the response:\n\n| Status Code | Meaning |\n| --- | --- |\n| 200 | Success - Your request was processed correctly |\n| 400 | Bad Request - Missing or invalid parameters, or situational issues like insufficient balance |\n| 401 | Unauthorized - Invalid or missing API key |\n| 403 | Forbidden - Your API key doesn't have permission for this operation |\n| 404 | Not Found - The requested resource doesn't exist |\n| 408 | Request Timeout - The request took too long to complete |\n| 429 | Rate Limited - Too many requests in a short time period |\n| 5xx | Server Error - An issue with our systems that we're actively investigating |\n\n#### Error Response Format\n\nEvery error response includes these fields:\n\n``` json\n{\n  \"type\": \"\",\n  \"code\": \"\",\n  \"message\": \"\",\n  \"documentation_url\": \"https://docs.root.credit\",\n  \"details\": null\n}\n\n ```\n\n#### Understanding Error Fields\n\n- `type`: The broad category of the error\n    \n- `code`: A specific error identifier you can handle programmatically\n    \n- `message`: A developer-friendly explanation of what went wrong\n    \n- `documentation_url`: A link to relevant documentation\n    \n- `details`: Additional information about the error (when available)\n    \n\n**Note:** The `message` field may change over time. For stable error handling, use the `code` field in your logic.\n\n#### Error Categories\n\nYou may encounter these error types:\n\n- `authentication_error`: API key and permission issues\n    \n- `bank_account_error`: Problems with bank account operations\n    \n- `dashboard_error`: Dashboard-related issues\n    \n- `server_error`: System-level problems we're actively monitoring\n    \n- `transfer_error`: Transfer operation issues\n    \n- `validation_error`: Request formatting and parameter problems","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"39578386","team":6524518,"collectionId":"759e0ee1-d097-4b93-ad95-124e86aaf513","publishedId":"2sAYBViBrA","public":true,"publicUrl":"https://docs.useroot.com","privateUrl":"https://go.postman.co/documentation/39578386-759e0ee1-d097-4b93-ad95-124e86aaf513","customColor":{"top-bar":"FFFFFF","right-sidebar":"f6f7f9","highlight":"1e30ca"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"system_default","themes":[{"name":"dark","logo":"https://content.pstmn.io/86e7b809-c231-4031-8b23-3f82f295433e/TG9nbyBkYXJrLnBuZw==","colors":{"top-bar":"212121","right-sidebar":"282828","highlight":"6b94ff"}},{"name":"light","logo":"https://content.pstmn.io/4395436e-94fa-46ec-ab4d-68f8b140e4a3/TG9nbyBMaWdodC5wbmc=","colors":{"top-bar":"FFFFFF","right-sidebar":"f6f7f9","highlight":"1e30ca"}}]}},"version":"8.10.0","publishDate":"2025-07-11T20:03:36.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":"https://content.pstmn.io/4395436e-94fa-46ec-ab4d-68f8b140e4a3/TG9nbyBMaWdodC5wbmc=","logoDark":"https://content.pstmn.io/86e7b809-c231-4031-8b23-3f82f295433e/TG9nbyBkYXJrLnBuZw=="}},"statusCode":200},"environments":[{"name":"docs.useroot.com","id":"c6e5b28e-ac9e-4a21-9270-58b046f34ec1","owner":"39578386","values":[{"key":"base_url","value":"https://api.useroot.com","enabled":true,"type":"default"}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/297f17b79ed59276cdb8c55bc6df55d5b3efa1147ea18472c9b0270417c5c4c9","favicon":"https://res.cloudinary.com/postman/image/upload/v1736164479/team/e2d879e3e22fc60223662d9c8ce8585f.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"docs.useroot.com","value":"39578386-c6e5b28e-ac9e-4a21-9270-58b046f34ec1"}],"canonicalUrl":"https://docs.useroot.com/view/metadata/2sAYBViBrA"}