{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"45e4c5c6-b9ad-4890-94e9-02378d45b2b2","name":"ArtisPay API V1","description":"# ArtisPay API V1\n\nThe ArtisPay API lets Funders and Buyers work with their ArtisPay data from their own systems: Buyers, suppliers and their users, banking settings, 3rd-party payees, invoices, FastTrack uploads and payable groups.\n\n## Base URL\n\n`https://api.artispay.com/v1`\n\nEvery path in this documentation starts with `/v1`. Use HTTPS.\n\n**Test and production use the same base URL.** The API identity you log in with decides which environment your calls reach: test credentials reach the test environment and production credentials reach production. To move to production, change the `identity_token` and `password`, not the URL.\n\n## Authentication\n\n1. Call **POST /v1/login** with the `identity_token` and `password` of your API identity.\n2. The response holds `access_token`, `token_type` (`\"Bearer\"`) and `expires_in`, the token lifetime in seconds (currently `86400`, which is 24 hours).\n3. Send the token on every other call:\n\n```\nAuthorization: Bearer <access_token>\n```\n\n4. On every call that has a body, send `Content-Type: application/json` exactly. A value with a parameter, such as `application/json; charset=utf-8`, is refused with 415.\n\nLog in again before the token expires, and whenever a call returns \"Invalid or expired bearer token\". Keep the identity token, password and access token secret: anyone who has them can act as your API identity.\n\n## Token types and scope\n\nEvery token belongs to one API identity, and every API identity belongs to one account. The account decides what the token can reach:\n\n| Token | What it can reach |\n|---|---|\n| Funder | The Funder's own data: its Buyers, their suppliers, users and invoices, and the Funder's 3rd-party payees, pay types, fee programs, FastTrack jobs and payable groups. |\n| Buyer | One Buyer's data. `{buyerid}` must be the Buyer's own `account_number`; any other value returns 404 \"Buyer not found\". The token sees only the Buyer's own suppliers and their invoices, and only the pay types and payees the Buyer may use. Funder-only requests return 403. |\n| Supplier | No endpoint accepts Supplier tokens. Calls return 403 \"Identity does not have sufficient permissions\". |\n\nEach request page says which tokens can call it under **Who can call it**.\n\n## Permissions\n\nEvery call except login also checks the permission named on its request page (for example \"Accounts - View Account Detail\"). Two security roles must both include it:\n\n- the role of the API identity's user, and\n- the security role of the account (the Funder or Buyer).\n\nThe names are those shown in the web app's security role settings. A missing permission returns 403 \"Identity does not have sufficient permissions\".\n\nGive each API identity a login (email address) of its own, with no other identities, and do not use that login to sign in to the web app. Some requests, marked on their pages, read the user's role from the login instead of from the API identity. Signing in to the web app with another identity of the same login changes that role, and those requests then follow the other identity's role: they can return 403, or succeed, when the API identity's own role says otherwise.\n\nAn API identity whose user or account is inactive, locked or not registered cannot log in, and tokens it received earlier are refused (see **Responses and errors**).\n\n## Identifiers\n\n| Placeholder | What to send |\n|---|---|\n| `{buyerid}` | The Buyer's `account_number`. A Buyer token must use its own, which Query Buyers returns. |\n| `{supplierid}` | The supplier's `account_number`. The supplier must belong to the Buyer in `{buyerid}`. |\n| `{userid}` | The user's current email address, URL-encoded (for example `jane.doe%40example.com`). Not case-sensitive. After Change User Email, use the new address. |\n| `{payeeid}` | The 3rd-party payee's `payee_number`. Letter case counts. |\n| `{currencyid}` | A currency code such as `USD` (not case-sensitive). It must be an active currency of the Funder. |\n| `{invoiceid}` | The invoice's `invoice_number`. |\n| `{fasttrackid}` | The `fasttrack_id` returned by POST /v1/fasttrack. |\n| `{payablegroupid}` | The payable group number: `payable_group_number` in Query Payable Groups. |\n\nURL-encode identifiers that contain spaces or other special characters.\n\n## Pagination\n\nThe Query endpoints return one page at a time. Both parameters are required:\n\n| Parameter | Rule |\n|---|---|\n| `pageSize` | Records per page: 1 to 250 (1 to 50 for Query Invoices). |\n| `pageNumber` | Page to return, starting at 1. |\n\nEvery query response has the same outer shape:\n\n```json\n{\n    \"total_count\": 37,\n    \"page_size\": 25,\n    \"page_number\": 2,\n    \"records\": []\n}\n```\n\n- `total_count` counts the matching records on all pages, not just this one.\n- `page_size` and `page_number` repeat your request.\n- `records` holds the requested page, oldest first (by creation date).\n- A page after the last one returns 200 with `\"records\": []` and the same `total_count`.\n- A missing or out-of-range value returns 400 \"Request is missing required properties or values\".\n\n## Conventions\n\n- Request and response bodies are JSON.\n- Booleans are `true` or `false`. A field without a value is returned as `\"\"` or `null`, depending on the field.\n- Amounts are JSON numbers, for example `1250.5`. Do not rely on a fixed number of decimals.\n- Invoice and due dates use `YYYY-MM-DD`. Creation and history timestamps use ISO 8601 in UTC, for example `2026-10-30T14:05:00.000Z`.\n- Email addresses that create or change a login (`email`, `new_email`, `primary_admin_email`) are trimmed and lower-cased before they are checked and saved, so `\" Jane.Doe@Example.com \"` is saved as `jane.doe@example.com`. An address that is still not valid returns 400.\n\n## Responses and errors\n\nA successful call returns 200. Calls that finish their work in the background return 202: POST /v1/fasttrack, Change User Email (Buyers and Suppliers) and Cancel Invoice.\n\nErrors return a JSON body with `status`, which matches the HTTP status code, and `message`:\n\n```json\n{\n    \"status\": 404,\n    \"message\": \"Buyer not found\"\n}\n```\n\nSome calls add `valid_value_check` to a 400 body. It shows `true` or `false` for each field the call checked:\n\n```json\n{\n    \"status\": 400,\n    \"message\": \"Missing or invalid values\",\n    \"valid_value_check\": {\n        \"first_name\": true,\n        \"user_role\": true,\n        \"email\": false\n    }\n}\n```\n\nA request that fails several checks returns only the first error. After the checks on the `Authorization` header, the token, the `Content-Type` header and the JSON body, the checks run in this order: maintenance mode (503), the API identity (401), token type and permissions (403), required values (400), identifiers (404), then the rules listed on the request page.\n\nCommon errors:\n\n| Status | Message | When |\n|---|---|---|\n| 400 | Request is missing required properties or values | A required path, query or body value is missing or not valid. |\n| 400 | Missing or invalid values | A required field is missing or not valid. `valid_value_check` shows which. |\n| 400 | Missing authorization header | The `Authorization` header is missing. |\n| 400 | Invalid or expired bearer token | The token is not valid. Log in again. |\n| 400 | Could not parse JSON object | The request body is not valid JSON. |\n| 401 | Invalid API Identity | The API identity no longer exists, its user is inactive, locked or not registered, or its account is inactive or locked. |\n| 403 | Identity does not have sufficient permissions | Your token type cannot call this endpoint, or a role lacks the permission. |\n| 403 | Other messages, for example \"User already activated\" | The request is valid, but a business rule refuses it. Each request page lists these. |\n| 404 | Buyer not found, Supplier not found, Payee not found, ... | The identifier does not match a record your token can see. |\n| 404 | Not Found | The path does not exist. The body is `{\"message\": \"Not Found\"}`, without `status`. |\n| 415 | 'Content-Type' header is missing or not valid.  Only 'application/json' is allowed. | A request with a body did not send exactly `Content-Type: application/json`. |\n| 503 | Server in maintenance mode | ArtisPay is in maintenance. Try again later. |\n\nThe fee program requests (Buyers and Suppliers), Update Invoice, Modify Invoice, Request Quick Pay and Cancel Invoice return 403 \"Identity does not have sufficient permissions\" instead of 401 when the API identity's user or account is inactive, locked or not registered.\n\n## What's new for Buyer tokens\n\n- **Your `{buyerid}`.** Query Buyers returns one record: your own Buyer. Use its `account_number` as `{buyerid}` in every URL and as `buyer_id` in FastTrack invoices.\n- **Pay types and payees.** Query Pay Types, Query 3rd Party Payees and Retrieve Payee accept Buyer tokens and return only what your Buyer may use. Other payees return 404 \"Payee not found\".\n- **Suppliers.** Retrieve Supplier returns 404 \"Supplier not found\" for a supplier that does not exist. Update Supplier applies `fasttrack_only`, `auto_hold_invoices`, `invoice_profile_required` and `invoice_profile` as sent.\n- **Users.** `{userid}` is the user's current email address.\n- **Supplier banking.** Update Banking Settings (Suppliers) applies Buyer rules: send the complete banking block for the pay type; a missing or invalid field returns 400 naming the field; a supplier whose current pay type Buyers may not change, a supplier with a pending banking change request, and a pay type or payee your Buyer may not use return 403; unchanged banking returns 200 and changes nothing. The request page lists every rule.\n- **Payees in banking.** In banking settings, your suppliers' and your Buyer's own, a 3rd-party payee is shown to Buyer tokens only by its `payee_number` and `payee_name`, or as `null` when it is not a payee your Buyer may use. Its bank details are never returned.\n- **FastTrack.** Jobs you create with your Buyer token belong to your Buyer, and their invoices follow the Buyer approval path. So do invoices you create with Create Invoice and `\"fasttrack\": true`. Jobs created with another token return 404 \"FastTrack Job not found\".\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"16425652","team":5561129,"collectionId":"45e4c5c6-b9ad-4890-94e9-02378d45b2b2","publishedId":"2s9YC4WDd8","public":true,"publicUrl":"https://docs.artispay.com","privateUrl":"https://go.postman.co/documentation/16425652-45e4c5c6-b9ad-4890-94e9-02378d45b2b2","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.12.12","publishDate":"2023-09-14T03:41:27.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[{"name":"ArtisPay","id":"eb00400b-6d7c-4457-a6b7-78fe4c73d029","owner":"16425652","values":[{"key":"identity_token","value":"1c12edd89fcd968119e84a97d14aa5235e8f4fb2afd80e8c3e8056e8ab1e498c20851e76795a38538ec16477e9aea935ad6064c092eca3ccd68f7f245b6e9eaa8fb80347edf84b1c5ddbfbdf741797f38a2fa8291114c74c12d0b8e8fd389e10d89755f6a7300446a45b2e7c04e28629e1f2e66845e05ff9eca9427fc5ca5fc4","enabled":true,"type":"secret"},{"key":"identity_password","value":"P@ss@word1","enabled":true,"type":"secret"},{"key":"bearer_token","value":"","enabled":true,"type":"secret"},{"key":"buyerid","value":"1","enabled":true,"type":"default"},{"key":"supplierid","value":"1","enabled":true,"type":"default"},{"key":"invoiceid","value":"1","enabled":true,"type":"default"},{"key":"userid","value":"jsmith@artispay.com","enabled":true,"type":"default"},{"key":"fasttrackid","value":"55","enabled":true,"type":"default"},{"key":"currency","value":"USD","enabled":true,"type":"default"},{"key":"payeeid","value":"1","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/b0ca96521b365777bf2571ad06f82eecc21d44fb79ef7e75a77e088d9ce2c64d","favicon":"https://artispay.com/favicon.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":"ArtisPay","value":"16425652-eb00400b-6d7c-4457-a6b7-78fe4c73d029"}],"canonicalUrl":"https://docs.artispay.com/view/metadata/2s9YC4WDd8"}