{ "openapi": "3.1.0", "info": { "title": "ProcurementExpress API", "version": "2026-10-21", "description": "V3 (OAuth2) and V1 (authentication_token) endpoints of the ProcurementExpress API. Generated from verified requests; see https://docs.procurementexpress.com.", "contact": { "name": "ProcurementExpress support", "email": "support@procurementexpress.com" } }, "servers": [ { "url": "https://app.procurementexpress.com" } ], "tags": [ { "name": "Authentication", "description": "https://docs.procurementexpress.com/#authentication" }, { "name": "Approval Flows", "description": "https://docs.procurementexpress.com/#approval-flows" }, { "name": "Budgets", "description": "https://docs.procurementexpress.com/#budgets" }, { "name": "Companies", "description": "https://docs.procurementexpress.com/#companies" }, { "name": "Compliance", "description": "https://docs.procurementexpress.com/#compliance" }, { "name": "Currencies", "description": "https://docs.procurementexpress.com/#currencies" }, { "name": "Custom Fields", "description": "https://docs.procurementexpress.com/#custom-fields" }, { "name": "Departments", "description": "https://docs.procurementexpress.com/#departments" }, { "name": "Invoices", "description": "https://docs.procurementexpress.com/#invoices" }, { "name": "Payments", "description": "https://docs.procurementexpress.com/#payments" }, { "name": "Products", "description": "https://docs.procurementexpress.com/#products" }, { "name": "Purchase Orders", "description": "https://docs.procurementexpress.com/#purchase-orders" }, { "name": "Purchase Orders: Attachments", "description": "https://docs.procurementexpress.com/#purchase-orders-attachments" }, { "name": "Purchase Orders: Comments", "description": "https://docs.procurementexpress.com/#purchase-orders-comments" }, { "name": "Purchase Orders: Receiving & Delivery", "description": "https://docs.procurementexpress.com/#purchase-orders-receiving-delivery" }, { "name": "Purchase Orders: Sending to Suppliers", "description": "https://docs.procurementexpress.com/#purchase-orders-sending-to-suppliers" }, { "name": "QuickBooks Online: Chart of Accounts", "description": "https://docs.procurementexpress.com/#quickbooks-online-chart-of-accounts" }, { "name": "QuickBooks Online: Classes", "description": "https://docs.procurementexpress.com/#quickbooks-online-classes" }, { "name": "QuickBooks Online: Customers", "description": "https://docs.procurementexpress.com/#quickbooks-online-customers" }, { "name": "QuickBooks Online: Item Budget Mappings", "description": "https://docs.procurementexpress.com/#quickbooks-online-item-budget-mappings" }, { "name": "SAM.gov Supplier Audit", "description": "https://docs.procurementexpress.com/#sam-gov-supplier-audit" }, { "name": "Suppliers", "description": "https://docs.procurementexpress.com/#suppliers" }, { "name": "Suppliers: Approvals", "description": "https://docs.procurementexpress.com/#suppliers-approvals" }, { "name": "Tax Rates", "description": "https://docs.procurementexpress.com/#tax-rates" }, { "name": "Users", "description": "https://docs.procurementexpress.com/#users" }, { "name": "Webhooks", "description": "https://docs.procurementexpress.com/#webhooks" } ], "paths": { "/oauth/token": { "post": { "tags": [ "Authentication" ], "operationId": "v3_oauth_token_create", "summary": "Get an access token", "description": "Exchange your OAuth application's client id and secret for a V3 bearer access token.\n\nOAuth2 token endpoint. Integrations use the **client credentials**\ngrant only. The token acts as the user who owns the OAuth application.\n\n* Send the fields as `application/x-www-form-urlencoded` (shown) or as a JSON\n object; the client can also authenticate with HTTP Basic\n (`Authorization: Basic base64(client_id:client_secret)`) instead of the two\n body fields.\n* The only scope is `public` (the default; `scope` can be omitted).\n* No refresh token is issued for this grant and tokens are not reused: every call\n creates a new token valid for 7200 seconds.\n* `grant_type=password` and `grant_type=authorization_code` are refused for\n integration applications (`unauthorized_client`); `grant_type=refresh_token` is\n refused as well, because client-credentials tokens have no refresh token.\n* The response carries `Cache-Control: no-store`.\n* The endpoint only accepts POST (`GET /oauth/token` answers 404, or 405 on\n deployments where the MCP integration is enabled).\n\n\nV3 only. V1 does not use OAuth: V1 clients obtain an `authentication_token` with\n`POST /api/v1/login`. The token endpoint is not under `/api`, so the path is\nabsolute.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string" }, "expires_in": { "type": "integer" }, "scope": { "type": "string" }, "created_at": { "type": "integer" } } }, "example": { "access_token": "", "token_type": "Bearer", "expires_in": 7200, "scope": "public", "created_at": 1792577106 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "invalid_client", "error_description": "Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method." } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "unauthorized_client" } } } } }, "security": [ ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "description": "Must be `client_credentials`." }, "client_id": { "type": "string", "description": "The application's client id (UID). Not needed when using HTTP Basic." }, "client_secret": { "type": "string", "description": "The application's client secret. Not needed when using HTTP Basic." }, "scope": { "type": "string", "description": "Only `public` is valid; MCP scopes such as `procurement:read` answer 400 `invalid_scope`." } }, "required": [ "grant_type", "client_id", "client_secret" ] } } } } } }, "/oauth/token/info": { "get": { "tags": [ "Authentication" ], "operationId": "v3_oauth_token_info", "summary": "Check an access token", "description": "Returns 200 while the bearer token is valid and 401 once it is invalid, expired or revoked.\n\nThe OAuth2 token-info endpoint. Send the token in the `Authorization` header.\nUse the **status code** to decide whether the token is still usable: `200` means\nvalid, `401` (with `WWW-Authenticate: Bearer realm=\"Doorkeeper\", error=\"invalid_token\", ...`)\nmeans request a new token. The body of the 200 response is currently an empty\nobject; use `POST /oauth/introspect` if you need the expiry time.\n\n\nV3 only (OAuth). V1 has no equivalent; any V1 call answers 401 for an invalid token.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { } }, "example": { } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "invalid_token", "error_description": "The access token is invalid", "state": "unauthorized" } } } } }, "security": [ ] } }, "/oauth/introspect": { "post": { "tags": [ "Authentication" ], "operationId": "v3_oauth_introspect", "summary": "Introspect an access token", "description": "RFC 7662 token introspection - tells whether a token is active, its scope and expiry.\n\nAuthenticate as the OAuth application (form fields `client_id` / `client_secret`,\nor HTTP Basic) and pass the token to inspect. An unknown, expired or revoked token\nanswers `200 {\"active\": false}`. Tokens of MCP clients are reported inactive\nunless the request comes from the MCP client itself.\n\n\nV3 only (OAuth). V1 does not use OAuth.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "boolean" }, "scope": { "type": "string" }, "client_id": { "type": "string" }, "token_type": { "type": "string" }, "exp": { "type": "integer" }, "iat": { "type": "integer" } } }, "example": { "active": true, "scope": "public", "client_id": "", "token_type": "Bearer", "exp": 1792584335, "iat": 1792577135 } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "invalid_request", "error_description": "The request is missing a required parameter, includes an unsupported parameter value, or is otherwise malformed." } } } } }, "security": [ ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The access token to inspect." }, "client_id": { "type": "string", "description": "Your application's client id (or HTTP Basic)." }, "client_secret": { "type": "string", "description": "Your application's client secret (or HTTP Basic)." }, "token_type_hint": { "type": "string", "description": "Optional RFC 7662 hint (`access_token`)." } }, "required": [ "token", "client_id", "client_secret" ] } } } } } }, "/oauth/revoke": { "post": { "tags": [ "Authentication" ], "operationId": "v3_oauth_revoke", "summary": "Revoke an access token", "description": "Revoke (sign out) an access token issued to your application.\n\nRFC 7009 revocation. The token stops working immediately (V3 calls then answer\n401 `The access token was revoked`, introspection reports `active: false`).\nRevoking an unknown token also answers `200 {}`. A token issued to a *different*\napplication cannot be revoked (403).\n\n\nV3 only (OAuth). The V1 counterpart is `POST /api/v1/logout`.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { } }, "example": { } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "error": "unauthorized_client", "error_description": "You are not authorized to revoke this token" } } } } }, "security": [ ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The access token to revoke." }, "client_id": { "type": "string", "description": "Your application's client id (or HTTP Basic)." }, "client_secret": { "type": "string", "description": "Your application's client secret (or HTTP Basic)." }, "token_type_hint": { "type": "string", "description": "Optional (`access_token`)." } }, "required": [ "token", "client_id", "client_secret" ] } } } } } }, "/api/v1/login": { "post": { "tags": [ "Authentication" ], "operationId": "v1_auth_login", "summary": "Sign in (V1)", "description": "Exchange e-mail and password for the user's V1 authentication_token.\n\nValidates the password (counting failures towards the Devise lockout).\n\n* **No 2FA required anywhere** for this account: returns the user object with\n `authentication_token`. The existing token is returned (a token is created only\n if the user has none), so all clients of the same user share it. The token is\n marked as *not* OTP-verified.\n* **Any company or membership of the account requires 2FA**: a 6-digit code is\n generated and e-mailed, and the response is `{\"otp_sent\": true}`. Complete the\n sign-in with `POST /verify_otp`. Signing in again within 30 seconds re-sends\n the same code instead of a new one.\n* Wrong password, unknown e-mail, locked, deactivated or archived account all\n answer the same `400 Invalid email or password.`\n\n`email` is matched case-insensitively. Pass `slim_companies` (any value) to shrink\nevery company except the default one to `{id, name, is_removed}`. The call also\nstarts a web session (a session cookie is set), which API clients can ignore.\n\n\nV1 only. V3 has no sign-in route:\n`POST /api/v3/login` falls through to the catch-all and answers `404 Invalid URL`\n(or 401 without a bearer token). V3 integrations authenticate with\n`POST /oauth/token`.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" }, "approver_name": { "type": "string" }, "phone_number": { "type": "string" }, "setup_incomplete": { "type": "boolean" }, "employer_id": { "type": "integer" }, "approval_limit": { "type": "number" }, "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "external_user_id": { "type": "null" }, "membership_archived": { "type": "boolean" }, "is_locked": { "type": "boolean" }, "is_removed": { "type": "boolean" }, "approval_limit": { "type": "number" }, "in_trial": { "type": "boolean" }, "trial_expired": { "type": "boolean" }, "remaining_trial_days": { "type": "integer" }, "roles": { "type": "array", "items": { "type": "string" } }, "has_unassigned_budgets": { "type": "boolean" } } } }, "roles": { "type": "null" }, "authentication_token": { "type": "string" }, "external_user_id": { "type": "null" } } }, "example": { "id": 4, "email": "lee.login@example.com", "name": "Lee Login", "approver_name": "Lee Login", "phone_number": "+15550199", "setup_incomplete": false, "employer_id": 3, "approval_limit": 1000000.0, "companies": [ { "id": 3, "name": "Lee Workshop", "external_user_id": null, "membership_archived": false, "is_locked": false, "is_removed": false, "approval_limit": 1000000.0, "in_trial": true, "trial_expired": false, "remaining_trial_days": 365, "roles": [ "companyadmin", "approver", "finance", "teammember" ], "has_unassigned_budgets": false } ], "roles": null, "authentication_token": "", "external_user_id": null } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "Invalid email or password.", "status": 400 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Login e-mail (case-insensitive). Missing: 400 `Enter email or username`." }, "password": { "type": "string", "description": "Account password." }, "slim_companies": { "type": "string", "description": "Any non-empty value returns slim company entries (see User object)." } }, "required": [ "email", "password" ] }, "example": { "email": "lee.login@example.com", "password": "" } } } } } }, "/api/v3/verify_otp": { "post": { "tags": [ "Authentication" ], "operationId": "v3_auth_verify_otp", "summary": "Verify a one-time code", "description": "Complete a 2FA sign-in with the e-mailed 6-digit code and receive the V1 authentication_token.\n\nSecond step after `POST /api/v1/login` answered `{\"otp_sent\": true}`. On success\nthe code is consumed, the user's token is marked as OTP-verified (it is replaced\nby a new one if it was issued while the account already required 2FA) and the\nuser object with `authentication_token` is returned. That token is then accepted\nin companies that require 2FA.\n\nCodes are valid for 5 minutes; after 5 wrong attempts the code is burned and the\nuser must sign in again. Every failure (wrong, expired or burned code, unknown\ne-mail, no pending challenge) answers the same `400 Invalid OTP`.\n\n\nRouted in both versions, but V3 has no `login`, so a challenge can only be started\nfrom V1 (or `google_login`), and V3 `verify_otp` returns the **V1**\n`authentication_token`, not an OAuth token. V3 matches `email` case-sensitively\n(`Olivia.Otp@Example.com` answers `Invalid OTP` in V3, succeeds in V1 - see the\nextra capture) and ignores `slim_companies`.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" }, "approver_name": { "type": "string" }, "phone_number": { "type": "string" }, "setup_incomplete": { "type": "boolean" }, "employer_id": { "type": "integer" }, "approval_limit": { "type": "number" }, "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "external_user_id": { "type": "null" }, "membership_archived": { "type": "boolean" }, "is_locked": { "type": "boolean" }, "is_removed": { "type": "boolean" }, "approval_limit": { "type": "number" }, "in_trial": { "type": "boolean" }, "trial_expired": { "type": "boolean" }, "remaining_trial_days": { "type": "integer" }, "roles": { "type": "array", "items": { "type": "string" } }, "has_unassigned_budgets": { "type": "boolean" } } } }, "roles": { "type": "null" }, "authentication_token": { "type": "string" }, "external_user_id": { "type": "null" } } }, "example": { "id": 3, "email": "olivia.otp@example.com", "name": "Olivia Otp", "approver_name": "Olivia Otp", "phone_number": "+15550199", "setup_incomplete": false, "employer_id": 2, "approval_limit": 1000000.0, "companies": [ { "id": 2, "name": "Initech OTP", "external_user_id": null, "membership_archived": false, "is_locked": false, "is_removed": false, "approval_limit": 1000000.0, "in_trial": true, "trial_expired": false, "remaining_trial_days": 365, "roles": [ "companyadmin", "approver", "finance", "teammember" ], "has_unassigned_budgets": false }, { "id": 6, "name": "Initrode Inc (archived member)", "external_user_id": null, "membership_archived": false, "is_locked": false, "is_removed": false, "approval_limit": 1000000.0, "in_trial": true, "trial_expired": false, "remaining_trial_days": 365, "roles": [ "companyadmin", "approver", "finance", "teammember" ], "has_unassigned_budgets": false } ], "roles": null, "authentication_token": "", "external_user_id": null } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The e-mail used for `login` (V1: case-insensitive; V3: must match the stored lower-case address exactly)." }, "otp_attempt": { "type": "string", "description": "The 6-digit code as a string." }, "slim_companies": { "type": "string", "description": "V1 only: slim company entries." } }, "required": [ "email", "otp_attempt" ] }, "example": { "email": "olivia.otp@example.com", "otp_attempt": "628354", "slim_companies": "1" } } } } } }, "/api/v1/verify_otp": { "post": { "tags": [ "Authentication" ], "operationId": "v1_auth_verify_otp", "summary": "Verify a one-time code", "description": "Complete a 2FA sign-in with the e-mailed 6-digit code and receive the V1 authentication_token.\n\nSecond step after `POST /api/v1/login` answered `{\"otp_sent\": true}`. On success\nthe code is consumed, the user's token is marked as OTP-verified (it is replaced\nby a new one if it was issued while the account already required 2FA) and the\nuser object with `authentication_token` is returned. That token is then accepted\nin companies that require 2FA.\n\nCodes are valid for 5 minutes; after 5 wrong attempts the code is burned and the\nuser must sign in again. Every failure (wrong, expired or burned code, unknown\ne-mail, no pending challenge) answers the same `400 Invalid OTP`.\n\n\nRouted in both versions, but V3 has no `login`, so a challenge can only be started\nfrom V1 (or `google_login`), and V3 `verify_otp` returns the **V1**\n`authentication_token`, not an OAuth token. V3 matches `email` case-sensitively\n(`Olivia.Otp@Example.com` answers `Invalid OTP` in V3, succeeds in V1 - see the\nextra capture) and ignores `slim_companies`.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" }, "approver_name": { "type": "string" }, "phone_number": { "type": "string" }, "setup_incomplete": { "type": "boolean" }, "employer_id": { "type": "integer" }, "approval_limit": { "type": "number" }, "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "external_user_id": { "type": "null" }, "membership_archived": { "type": "boolean" }, "is_locked": { "type": "boolean" }, "is_removed": { "type": "boolean" }, "approval_limit": { "type": "number" }, "in_trial": { "type": "boolean" }, "trial_expired": { "type": "boolean" }, "remaining_trial_days": { "type": "integer" }, "roles": { "type": "array", "items": { "type": "string" } }, "has_unassigned_budgets": { "type": "boolean" } } } }, "roles": { "type": "null" }, "authentication_token": { "type": "string" }, "external_user_id": { "type": "null" } } }, "example": { "id": 3, "email": "olivia.otp@example.com", "name": "Olivia Otp", "approver_name": "Olivia Otp", "phone_number": "+15550199", "setup_incomplete": false, "employer_id": 2, "approval_limit": 1000000.0, "companies": [ { "id": 2, "name": "Initech OTP", "external_user_id": null, "membership_archived": false, "is_locked": false, "is_removed": false, "approval_limit": 1000000.0, "in_trial": true, "trial_expired": false, "remaining_trial_days": 365, "roles": [ "companyadmin", "approver", "finance", "teammember" ], "has_unassigned_budgets": false }, { "id": 6, "name": "Initrode Inc (archived member)", "external_user_id": null, "membership_archived": false, "is_locked": false, "is_removed": false, "approval_limit": 1000000.0, "in_trial": true, "trial_expired": false, "remaining_trial_days": 365, "roles": [ "companyadmin", "approver", "finance", "teammember" ], "has_unassigned_budgets": false } ], "roles": null, "authentication_token": "", "external_user_id": null } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "Invalid OTP", "status": 400 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The e-mail used for `login` (V1: case-insensitive; V3: must match the stored lower-case address exactly)." }, "otp_attempt": { "type": "string", "description": "The 6-digit code as a string." }, "slim_companies": { "type": "string", "description": "V1 only: slim company entries." } }, "required": [ "email", "otp_attempt" ] }, "example": { "email": "olivia.otp@example.com", "otp_attempt": "835374" } } } } } }, "/api/v3/resend_otp": { "post": { "tags": [ "Authentication" ], "operationId": "v3_auth_resend_otp", "summary": "Resend the one-time code", "description": "Re-send a fresh code for a pending 2FA sign-in.\n\nAlways answers `{\"otp_sent\": true}`, whether or not the address exists or has a\npending challenge, so it cannot be used to probe accounts. The mail is sent in the\nbackground, and only when a password (or Google) login started a challenge that\nhas not expired; the new code keeps the earlier wrong-attempt count.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "otp_sent": { "type": "boolean" } } }, "example": { "otp_sent": true } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The e-mail used for `login`." } }, "required": [ "email" ] }, "example": { "email": "olivia.otp@example.com" } } } } } }, "/api/v1/resend_otp": { "post": { "tags": [ "Authentication" ], "operationId": "v1_auth_resend_otp", "summary": "Resend the one-time code", "description": "Re-send a fresh code for a pending 2FA sign-in.\n\nAlways answers `{\"otp_sent\": true}`, whether or not the address exists or has a\npending challenge, so it cannot be used to probe accounts. The mail is sent in the\nbackground, and only when a password (or Google) login started a challenge that\nhas not expired; the new code keeps the earlier wrong-attempt count.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "otp_sent": { "type": "boolean" } } }, "example": { "otp_sent": true } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The e-mail used for `login`." } }, "required": [ "email" ] }, "example": { "email": "olivia.otp@example.com" } } } } } }, "/api/v1/logout": { "post": { "tags": [ "Authentication" ], "operationId": "v1_auth_logout", "summary": "Sign out (V1)", "description": "Invalidate the user's V1 authentication_token.\n\nReplaces the user's `authentication_token` with a new, unpublished one. Because the\ntoken is shared by every client of the same user, this signs the user out of\n**all** apps and integrations that use the V1 token. The next `login` returns the\nnew token. No body is needed and `app_company_id` is not required.\n\n\nV1 only (route commented out in V3; `POST /api/v3/logout` answers `404 Invalid URL`).\nV3 clients revoke their bearer token with `POST /oauth/revoke`.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "info": { "type": "string" } } }, "example": { "success": true, "info": "Logged out" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Authentication token is nil", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/reset_password": { "post": { "tags": [ "Authentication" ], "operationId": "v3_auth_reset_password", "summary": "Request a password reset e-mail", "description": "E-mail password-reset instructions to an address.\n\nAlways answers `{\"success\": \"true\"}` (note: a string), whether or not the address\nis registered. When it is, Devise reset instructions are e-mailed in the\nbackground. Rate limited to 3 requests per e-mail per hour and 10 per IP per 15\nminutes.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "string" } } }, "example": { "success": "true" } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Account e-mail (case-insensitive)." } }, "required": [ "email" ] }, "example": { "email": "lee.login@example.com" } } } } } }, "/api/v1/reset_password": { "post": { "tags": [ "Authentication" ], "operationId": "v1_auth_reset_password", "summary": "Request a password reset e-mail", "description": "E-mail password-reset instructions to an address.\n\nAlways answers `{\"success\": \"true\"}` (note: a string), whether or not the address\nis registered. When it is, Devise reset instructions are e-mailed in the\nbackground. Rate limited to 3 requests per e-mail per hour and 10 per IP per 15\nminutes.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "string" } } }, "example": { "success": "true" } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Account e-mail (case-insensitive)." } }, "required": [ "email" ] }, "example": { "email": "lee.login@example.com" } } } } } }, "/api/v3/approval_flows": { "get": { "tags": [ "Approval Flows" ], "operationId": "v3_approval_flows_list", "summary": "List approval flows", "description": "Returns the company's non-archived approval flows, newest first, without their steps and conditions.\n\nLists all approval flows of every document type for the company in the `app_company_id`\nheader. Archived and deleted flows are not included (an archived flow can still be fetched by\nid). Items are the flow summary only - fetch a flow by id to get its steps and conditions.\n\n* `search` filters by name (case-insensitive substring).\n* Sorting defaults to `id` descending. `sort` must be a table-qualified column,\n `approval_flows.` (e.g. `approval_flows.name`, `approval_flows.created_at`,\n `approval_flows.total_entities_count`); anything else - including a bare `name` - silently\n falls back to `id`. The special value\n `approval_flows.completed_entities_count+approval_flows.rejected_entities_count` sorts by\n finished runs (URL-encode the `+` as `%2B`).\n* Paginated with `page` / `per_page`.\n\n\nNone - identical request and response.", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Case-insensitive substring of the flow name.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`approval_flows.` or `approval_flows.completed_entities_count+approval_flows.rejected_entities_count`. Invalid values fall back to `id`.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "`asc` or `desc`.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "10, 20, 50 or 100. Defaults to the user's results-per-page setting for the company; any other value means 10.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval_flows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "document_type": { "type": "string" }, "self_approval_allowed": { "type": "boolean" }, "company_id": { "type": "integer" }, "version_no": { "type": "null" }, "archived": { "type": "boolean" }, "status": { "type": "string" }, "in_progress_entities_count": { "type": "integer" }, "completed_entities_count": { "type": "integer" }, "rejected_entities_count": { "type": "integer" }, "cancelled_entities_count": { "type": "integer" }, "total_entities_count": { "type": "integer" }, "is_default": { "type": "boolean" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "next_page": { "type": "null" }, "prev_page": { "type": "null" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "example": { "approval_flows": [ { "id": 4, "name": "Large outstanding invoices", "document_type": "invoice", "self_approval_allowed": true, "company_id": 20000, "version_no": null, "archived": false, "status": "unpublished", "in_progress_entities_count": 0, "completed_entities_count": 0, "rejected_entities_count": 0, "cancelled_entities_count": 0, "total_entities_count": 0, "is_default": false, "created_at": 1792576869, "updated_at": 1792576869 }, { "id": 3, "name": "Large outstanding invoices", "document_type": "invoice", "self_approval_allowed": true, "company_id": 20000, "version_no": null, "archived": false, "status": "unpublished", "in_progress_entities_count": 0, "completed_entities_count": 0, "rejected_entities_count": 0, "cancelled_entities_count": 0, "total_entities_count": 0, "is_default": false, "created_at": 1792576869, "updated_at": 1792576869 } ], "meta": { "current_page": 1, "next_page": null, "prev_page": null, "total_pages": 1, "total_count": 4 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] }, "post": { "tags": [ "Approval Flows" ], "operationId": "v3_approval_flows_create", "summary": "Create an approval flow", "description": "Creates an unpublished approval flow with its steps, approvers and conditions in one request.\n\nCreates the flow and all nested records atomically (nested attributes). The new flow is\nalways `unpublished` - publish it with `PATCH /approval_flows/:id/publish` (V1) once it has\nbeen reviewed.\n\nValidation:\n* `name` required (max 255).\n* At least one flow-level condition and at least one step.\n* Each step needs `step_no` and at least one approver; each approver must be an active member\n of the company.\n* Each condition needs `property`, `operator` and `value`.\n* Nested entries whose fields are all blank are ignored.\n\nThe request source (`app_source` header, default `api`) is stored on the flow.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "document_type": { "type": "string" }, "self_approval_allowed": { "type": "boolean" }, "company_id": { "type": "integer" }, "version_no": { "type": "null" }, "archived": { "type": "boolean" }, "status": { "type": "string" }, "in_progress_entities_count": { "type": "integer" }, "completed_entities_count": { "type": "integer" }, "rejected_entities_count": { "type": "integer" }, "cancelled_entities_count": { "type": "integer" }, "total_entities_count": { "type": "integer" }, "is_default": { "type": "boolean" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "approval_steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "step_no": { "type": "integer" }, "all_should_approve": { "type": "boolean" }, "approval_flow_id": { "type": "integer" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "approval_step_approvers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_step_id": { "type": "integer" }, "user_id": { "type": "integer" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "on_holiday": { "type": "boolean" } } }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } }, "approval_conditions": { "type": "array", "items": { } } } } }, "approval_conditions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "property": { "type": "string" }, "operator": { "type": "string" }, "value": { "type": "string" }, "custom_field_id": { "type": "null" }, "approval_flow_id": { "type": "integer" }, "approval_step_id": { "type": "null" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "human_readable_description": { "type": "string" }, "property_label": { "type": "string" }, "value_label": { "type": "string" } } } } } }, "example": { "id": 2, "name": "Lab PO routing v3", "document_type": "purchase_order", "self_approval_allowed": false, "company_id": 20000, "version_no": null, "archived": false, "status": "unpublished", "in_progress_entities_count": 0, "completed_entities_count": 0, "rejected_entities_count": 0, "cancelled_entities_count": 0, "total_entities_count": 0, "is_default": false, "created_at": 1792576781, "updated_at": 1792576781, "approval_steps": [ { "id": 3, "step_no": 1, "all_should_approve": false, "approval_flow_id": 2, "created_at": 1792576781, "updated_at": 1792576781, "approval_step_approvers": [ { "id": 4, "approval_step_id": 3, "user_id": 50000, "user": { "id": 50000, "name": "Priya Patel", "email": "priya.patel@example.com", "on_holiday": false }, "created_at": 1792576781, "updated_at": 1792576781 } ], "approval_conditions": [ ] }, { "id": 4, "step_no": 2, "all_should_approve": true, "approval_flow_id": 2, "created_at": 1792576781, "updated_at": 1792576781, "approval_step_approvers": [ { "id": 5, "approval_step_id": 4, "user_id": 40000, "user": { "id": 40000, "name": "Jane Doe", "email": "jane.doe@example.com", "on_holiday": false }, "created_at": 1792576781, "updated_at": 1792576781 }, { "id": 6, "approval_step_id": 4, "user_id": 50000, "user": { "id": 50000, "name": "Priya Patel", "email": "priya.patel@example.com", "on_holiday": false }, "created_at": 1792576781, "updated_at": 1792576781 } ], "approval_conditions": [ { "id": 3, "property": "gross_amount", "operator": "greater_than", "value": "1000", "custom_field_id": null, "approval_flow_id": null, "approval_step_id": 4, "created_at": 1792576781, "updated_at": 1792576781, "human_readable_description": "Gross amount greater than 1000", "property_label": "Gross amount", "value_label": "1000" } ] } ], "approval_conditions": [ { "id": 4, "property": "department", "operator": "equals", "value": "5", "custom_field_id": null, "approval_flow_id": 2, "approval_step_id": null, "created_at": 1792576781, "updated_at": 1792576781, "human_readable_description": "Department equals Approval Flow Lab", "property_label": "Department", "value_label": "Approval Flow Lab" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": { "name": [ "can't be blank" ], "approval_steps": [ "must have at least one step" ], "approval_conditions": [ "must have at least one condition" ] }, "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "approval_flow[name]": { "type": "string", "description": "Flow name, max 255 characters." }, "approval_flow[document_type]": { "type": "string", "description": "`purchase_order` (default), `invoice` or `rfq`. Any other value causes HTTP 500." }, "approval_flow[self_approval_allowed]": { "type": "boolean", "description": "Default `false`. See intro." }, "approval_flow[approval_conditions_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "Flow conditions (all must match). At least one." }, "approval_flow[approval_conditions_attributes][][property]": { "type": "string", "description": "See the Conditions table, e.g. `department`, `gross_amount`, `custom_field_12`." }, "approval_flow[approval_conditions_attributes][][operator]": { "type": "string", "description": "One of the operators in the intro. Any other value causes HTTP 500." }, "approval_flow[approval_conditions_attributes][][value]": { "type": "string", "description": "Value as a string; comma-separated ids for `is_any_of` / `is_none_of`." }, "approval_flow[approval_conditions_attributes][][custom_field_id]": { "type": "integer", "description": "Legacy; prefer `property: \"custom_field_\"` (matching uses the property)." }, "approval_flow[approval_conditions_attributes][][approval_flow_id]": { "type": "integer", "description": "Ignored on create (set automatically)." }, "approval_flow[approval_steps_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "Steps. At least one." }, "approval_flow[approval_steps_attributes][][step_no]": { "type": "integer", "description": "Order of the step (1, 2, 3 ...)." }, "approval_flow[approval_steps_attributes][][all_should_approve]": { "type": "boolean", "description": "Default `false` (any one approver)." }, "approval_flow[approval_steps_attributes][][approval_step_approvers_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "Approvers of the step. At least one." }, "approval_flow[approval_steps_attributes][][approval_step_approvers_attributes][][user_id]": { "type": "integer", "description": "An active member of the company (any role)." }, "approval_flow[approval_steps_attributes][][approval_conditions_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "Step conditions (`property`, `operator`, `value`, `custom_field_id`) - the step is skipped unless all match." } }, "required": [ "approval_flow[name]", "approval_flow[approval_conditions_attributes][]", "approval_flow[approval_conditions_attributes][][property]", "approval_flow[approval_conditions_attributes][][operator]", "approval_flow[approval_conditions_attributes][][value]", "approval_flow[approval_steps_attributes][]", "approval_flow[approval_steps_attributes][][step_no]", "approval_flow[approval_steps_attributes][][approval_step_approvers_attributes][]", "approval_flow[approval_steps_attributes][][approval_step_approvers_attributes][][user_id]" ] }, "example": { "approval_flow": { "name": "Lab PO routing v3", "document_type": "purchase_order", "self_approval_allowed": false, "approval_conditions_attributes": [ { "property": "department", "operator": "equals", "value": "5" } ], "approval_steps_attributes": [ { "step_no": 1, "all_should_approve": false, "approval_step_approvers_attributes": [ { "user_id": 50000 } ] }, { "step_no": 2, "all_should_approve": true, "approval_step_approvers_attributes": [ { "user_id": 40000 }, { "user_id": 50000 } ], "approval_conditions_attributes": [ { "property": "gross_amount", "operator": "greater_than", "value": "1000" } ] } ] } } } } } } }, "/api/v1/approval_flows": { "get": { "tags": [ "Approval Flows" ], "operationId": "v1_approval_flows_list", "summary": "List approval flows", "description": "Returns the company's non-archived approval flows, newest first, without their steps and conditions.\n\nLists all approval flows of every document type for the company in the `app_company_id`\nheader. Archived and deleted flows are not included (an archived flow can still be fetched by\nid). Items are the flow summary only - fetch a flow by id to get its steps and conditions.\n\n* `search` filters by name (case-insensitive substring).\n* Sorting defaults to `id` descending. `sort` must be a table-qualified column,\n `approval_flows.` (e.g. `approval_flows.name`, `approval_flows.created_at`,\n `approval_flows.total_entities_count`); anything else - including a bare `name` - silently\n falls back to `id`. The special value\n `approval_flows.completed_entities_count+approval_flows.rejected_entities_count` sorts by\n finished runs (URL-encode the `+` as `%2B`).\n* Paginated with `page` / `per_page`.\n\n\nNone - identical request and response.", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Case-insensitive substring of the flow name.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`approval_flows.` or `approval_flows.completed_entities_count+approval_flows.rejected_entities_count`. Invalid values fall back to `id`.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "`asc` or `desc`.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "10, 20, 50 or 100. Defaults to the user's results-per-page setting for the company; any other value means 10.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval_flows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "document_type": { "type": "string" }, "self_approval_allowed": { "type": "boolean" }, "company_id": { "type": "integer" }, "version_no": { "type": "null" }, "archived": { "type": "boolean" }, "status": { "type": "string" }, "in_progress_entities_count": { "type": "integer" }, "completed_entities_count": { "type": "integer" }, "rejected_entities_count": { "type": "integer" }, "cancelled_entities_count": { "type": "integer" }, "total_entities_count": { "type": "integer" }, "is_default": { "type": "boolean" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "next_page": { "type": "null" }, "prev_page": { "type": "null" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "example": { "approval_flows": [ { "id": 4, "name": "Large outstanding invoices", "document_type": "invoice", "self_approval_allowed": true, "company_id": 20000, "version_no": null, "archived": false, "status": "unpublished", "in_progress_entities_count": 0, "completed_entities_count": 0, "rejected_entities_count": 0, "cancelled_entities_count": 0, "total_entities_count": 0, "is_default": false, "created_at": 1792576869, "updated_at": 1792576869 }, { "id": 3, "name": "Large outstanding invoices", "document_type": "invoice", "self_approval_allowed": true, "company_id": 20000, "version_no": null, "archived": false, "status": "unpublished", "in_progress_entities_count": 0, "completed_entities_count": 0, "rejected_entities_count": 0, "cancelled_entities_count": 0, "total_entities_count": 0, "is_default": false, "created_at": 1792576869, "updated_at": 1792576869 } ], "meta": { "current_page": 1, "next_page": null, "prev_page": null, "total_pages": 1, "total_count": 4 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "post": { "tags": [ "Approval Flows" ], "operationId": "v1_approval_flows_create", "summary": "Create an approval flow", "description": "Creates an unpublished approval flow with its steps, approvers and conditions in one request.\n\nCreates the flow and all nested records atomically (nested attributes). The new flow is\nalways `unpublished` - publish it with `PATCH /approval_flows/:id/publish` (V1) once it has\nbeen reviewed.\n\nValidation:\n* `name` required (max 255).\n* At least one flow-level condition and at least one step.\n* Each step needs `step_no` and at least one approver; each approver must be an active member\n of the company.\n* Each condition needs `property`, `operator` and `value`.\n* Nested entries whose fields are all blank are ignored.\n\nThe request source (`app_source` header, default `api`) is stored on the flow.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "document_type": { "type": "string" }, "self_approval_allowed": { "type": "boolean" }, "company_id": { "type": "integer" }, "version_no": { "type": "null" }, "archived": { "type": "boolean" }, "status": { "type": "string" }, "in_progress_entities_count": { "type": "integer" }, "completed_entities_count": { "type": "integer" }, "rejected_entities_count": { "type": "integer" }, "cancelled_entities_count": { "type": "integer" }, "total_entities_count": { "type": "integer" }, "is_default": { "type": "boolean" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "approval_steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "step_no": { "type": "integer" }, "all_should_approve": { "type": "boolean" }, "approval_flow_id": { "type": "integer" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "approval_step_approvers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_step_id": { "type": "integer" }, "user_id": { "type": "integer" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "on_holiday": { "type": "boolean" } } }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } }, "approval_conditions": { "type": "array", "items": { } } } } }, "approval_conditions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "property": { "type": "string" }, "operator": { "type": "string" }, "value": { "type": "string" }, "custom_field_id": { "type": "null" }, "approval_flow_id": { "type": "integer" }, "approval_step_id": { "type": "null" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "human_readable_description": { "type": "string" }, "property_label": { "type": "string" }, "value_label": { "type": "string" } } } } } }, "example": { "id": 1, "name": "Lab PO routing v1", "document_type": "purchase_order", "self_approval_allowed": false, "company_id": 20000, "version_no": null, "archived": false, "status": "unpublished", "in_progress_entities_count": 0, "completed_entities_count": 0, "rejected_entities_count": 0, "cancelled_entities_count": 0, "total_entities_count": 0, "is_default": false, "created_at": 1792576772, "updated_at": 1792576772, "approval_steps": [ { "id": 1, "step_no": 1, "all_should_approve": false, "approval_flow_id": 1, "created_at": 1792576772, "updated_at": 1792576772, "approval_step_approvers": [ { "id": 1, "approval_step_id": 1, "user_id": 50000, "user": { "id": 50000, "name": "Priya Patel", "email": "priya.patel@example.com", "on_holiday": false }, "created_at": 1792576772, "updated_at": 1792576772 } ], "approval_conditions": [ ] }, { "id": 2, "step_no": 2, "all_should_approve": true, "approval_flow_id": 1, "created_at": 1792576772, "updated_at": 1792576772, "approval_step_approvers": [ { "id": 2, "approval_step_id": 2, "user_id": 40000, "user": { "id": 40000, "name": "Jane Doe", "email": "jane.doe@example.com", "on_holiday": false }, "created_at": 1792576772, "updated_at": 1792576772 }, { "id": 3, "approval_step_id": 2, "user_id": 50000, "user": { "id": 50000, "name": "Priya Patel", "email": "priya.patel@example.com", "on_holiday": false }, "created_at": 1792576772, "updated_at": 1792576772 } ], "approval_conditions": [ { "id": 1, "property": "gross_amount", "operator": "greater_than", "value": "1000", "custom_field_id": null, "approval_flow_id": null, "approval_step_id": 2, "created_at": 1792576772, "updated_at": 1792576772, "human_readable_description": "Gross amount greater than 1000", "property_label": "Gross amount", "value_label": "1000" } ] } ], "approval_conditions": [ { "id": 2, "property": "department", "operator": "equals", "value": "5", "custom_field_id": null, "approval_flow_id": 1, "approval_step_id": null, "created_at": 1792576772, "updated_at": 1792576772, "human_readable_description": "Department equals Approval Flow Lab", "property_label": "Department", "value_label": "Approval Flow Lab" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": { "name": [ "can't be blank" ], "approval_steps": [ "must have at least one step" ], "approval_conditions": [ "must have at least one condition" ] }, "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "approval_flow[name]": { "type": "string", "description": "Flow name, max 255 characters." }, "approval_flow[document_type]": { "type": "string", "description": "`purchase_order` (default), `invoice` or `rfq`. Any other value causes HTTP 500." }, "approval_flow[self_approval_allowed]": { "type": "boolean", "description": "Default `false`. See intro." }, "approval_flow[approval_conditions_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "Flow conditions (all must match). At least one." }, "approval_flow[approval_conditions_attributes][][property]": { "type": "string", "description": "See the Conditions table, e.g. `department`, `gross_amount`, `custom_field_12`." }, "approval_flow[approval_conditions_attributes][][operator]": { "type": "string", "description": "One of the operators in the intro. Any other value causes HTTP 500." }, "approval_flow[approval_conditions_attributes][][value]": { "type": "string", "description": "Value as a string; comma-separated ids for `is_any_of` / `is_none_of`." }, "approval_flow[approval_conditions_attributes][][custom_field_id]": { "type": "integer", "description": "Legacy; prefer `property: \"custom_field_\"` (matching uses the property)." }, "approval_flow[approval_conditions_attributes][][approval_flow_id]": { "type": "integer", "description": "Ignored on create (set automatically)." }, "approval_flow[approval_steps_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "Steps. At least one." }, "approval_flow[approval_steps_attributes][][step_no]": { "type": "integer", "description": "Order of the step (1, 2, 3 ...)." }, "approval_flow[approval_steps_attributes][][all_should_approve]": { "type": "boolean", "description": "Default `false` (any one approver)." }, "approval_flow[approval_steps_attributes][][approval_step_approvers_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "Approvers of the step. At least one." }, "approval_flow[approval_steps_attributes][][approval_step_approvers_attributes][][user_id]": { "type": "integer", "description": "An active member of the company (any role)." }, "approval_flow[approval_steps_attributes][][approval_conditions_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "Step conditions (`property`, `operator`, `value`, `custom_field_id`) - the step is skipped unless all match." } }, "required": [ "approval_flow[name]", "approval_flow[approval_conditions_attributes][]", "approval_flow[approval_conditions_attributes][][property]", "approval_flow[approval_conditions_attributes][][operator]", "approval_flow[approval_conditions_attributes][][value]", "approval_flow[approval_steps_attributes][]", "approval_flow[approval_steps_attributes][][step_no]", "approval_flow[approval_steps_attributes][][approval_step_approvers_attributes][]", "approval_flow[approval_steps_attributes][][approval_step_approvers_attributes][][user_id]" ] }, "example": { "approval_flow": { "name": "Lab PO routing v1", "document_type": "purchase_order", "self_approval_allowed": false, "approval_conditions_attributes": [ { "property": "department", "operator": "equals", "value": "5" } ], "approval_steps_attributes": [ { "step_no": 1, "all_should_approve": false, "approval_step_approvers_attributes": [ { "user_id": 50000 } ] }, { "step_no": 2, "all_should_approve": true, "approval_step_approvers_attributes": [ { "user_id": 40000 }, { "user_id": 50000 } ], "approval_conditions_attributes": [ { "property": "gross_amount", "operator": "greater_than", "value": "1000" } ] } ] } } } } } } }, "/api/v3/approval_flows/{id}": { "get": { "tags": [ "Approval Flows" ], "operationId": "v3_approval_flows_show", "summary": "Get an approval flow", "description": "Returns one approval flow with its steps, approvers and conditions.\n\nReturns the flow with its steps (ordered by `step_no`), each step's approvers (in the order\nthey were added) and step conditions, and the flow-level conditions. Archived flows can be\nfetched; deleted ones return 404.\n\nConditions are returned with three helper fields resolved for display:\n`property_label` (e.g. \"Department\", or the custom field's name), `value_label` (ids turned\ninto names, e.g. \"Approval Flow Lab\") and `human_readable_description`.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Approval flow id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "document_type": { "type": "string" }, "self_approval_allowed": { "type": "boolean" }, "company_id": { "type": "integer" }, "version_no": { "type": "null" }, "archived": { "type": "boolean" }, "status": { "type": "string" }, "in_progress_entities_count": { "type": "integer" }, "completed_entities_count": { "type": "integer" }, "rejected_entities_count": { "type": "integer" }, "cancelled_entities_count": { "type": "integer" }, "total_entities_count": { "type": "integer" }, "is_default": { "type": "boolean" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "approval_steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "step_no": { "type": "integer" }, "all_should_approve": { "type": "boolean" }, "approval_flow_id": { "type": "integer" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "approval_step_approvers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_step_id": { "type": "integer" }, "user_id": { "type": "integer" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "on_holiday": { "type": "boolean" } } }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } }, "approval_conditions": { "type": "array", "items": { } } } } }, "approval_conditions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "property": { "type": "string" }, "operator": { "type": "string" }, "value": { "type": "string" }, "custom_field_id": { "type": "null" }, "approval_flow_id": { "type": "integer" }, "approval_step_id": { "type": "null" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "human_readable_description": { "type": "string" }, "property_label": { "type": "string" }, "value_label": { "type": "string" } } } } } }, "example": { "id": 1, "name": "Lab PO routing v1", "document_type": "purchase_order", "self_approval_allowed": false, "company_id": 20000, "version_no": null, "archived": false, "status": "unpublished", "in_progress_entities_count": 0, "completed_entities_count": 0, "rejected_entities_count": 0, "cancelled_entities_count": 0, "total_entities_count": 0, "is_default": false, "created_at": 1792576772, "updated_at": 1792576772, "approval_steps": [ { "id": 1, "step_no": 1, "all_should_approve": false, "approval_flow_id": 1, "created_at": 1792576772, "updated_at": 1792576772, "approval_step_approvers": [ { "id": 1, "approval_step_id": 1, "user_id": 50000, "user": { "id": 50000, "name": "Priya Patel", "email": "priya.patel@example.com", "on_holiday": false }, "created_at": 1792576772, "updated_at": 1792576772 } ], "approval_conditions": [ ] }, { "id": 2, "step_no": 2, "all_should_approve": true, "approval_flow_id": 1, "created_at": 1792576772, "updated_at": 1792576772, "approval_step_approvers": [ { "id": 2, "approval_step_id": 2, "user_id": 40000, "user": { "id": 40000, "name": "Jane Doe", "email": "jane.doe@example.com", "on_holiday": false }, "created_at": 1792576772, "updated_at": 1792576772 }, { "id": 3, "approval_step_id": 2, "user_id": 50000, "user": { "id": 50000, "name": "Priya Patel", "email": "priya.patel@example.com", "on_holiday": false }, "created_at": 1792576772, "updated_at": 1792576772 } ], "approval_conditions": [ { "id": 1, "property": "gross_amount", "operator": "greater_than", "value": "1000", "custom_field_id": null, "approval_flow_id": null, "approval_step_id": 2, "created_at": 1792576772, "updated_at": 1792576772, "human_readable_description": "Gross amount greater than 1000", "property_label": "Gross amount", "value_label": "1000" } ] } ], "approval_conditions": [ { "id": 2, "property": "department", "operator": "equals", "value": "5", "custom_field_id": null, "approval_flow_id": 1, "approval_step_id": null, "created_at": 1792576772, "updated_at": 1792576772, "human_readable_description": "Department equals Approval Flow Lab", "property_label": "Department", "value_label": "Approval Flow Lab" } ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": [ "Invalid id passed" ], "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] }, "put": { "tags": [ "Approval Flows" ], "operationId": "v3_approval_flows_update", "summary": "Update an approval flow", "description": "Renames a flow or adds, changes and removes its steps, approvers and conditions.\n\nAccepts the same `approval_flow` body as create; send only what changes. Nested records:\n\n* include `id` to change an existing step / approver / condition;\n* omit `id` to add a new one;\n* include `id` and `\"_destroy\": true` (or `1`) to remove it. Destroying a step removes its\n approvers and step conditions.\n\nThe flow must still be valid afterwards (at least one step, one flow condition, one approver\nper step), otherwise nothing is saved.\n\nEvery update stamps a new `version_no` and records a version. Updating does not change\n`status` and does not re-route documents already in approval. When steps, approvers or\nconditions change, all in-progress runs whose document is still active are flagged\n(`flow_changed_at`) so they can be re-evaluated with\n`POST /approval_flows/rerun_approval_flows`. Archived flows can be updated too.\n\n\nNone - identical request and response. Both versions accept PUT and PATCH (the V1 example\nuses PUT, the V3 example PATCH).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Approval flow id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "document_type": { "type": "string" }, "self_approval_allowed": { "type": "boolean" }, "company_id": { "type": "integer" }, "version_no": { "type": "string" }, "archived": { "type": "boolean" }, "status": { "type": "string" }, "in_progress_entities_count": { "type": "integer" }, "completed_entities_count": { "type": "integer" }, "rejected_entities_count": { "type": "integer" }, "cancelled_entities_count": { "type": "integer" }, "total_entities_count": { "type": "integer" }, "is_default": { "type": "boolean" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "approval_steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "step_no": { "type": "integer" }, "all_should_approve": { "type": "boolean" }, "approval_flow_id": { "type": "integer" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "approval_step_approvers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_step_id": { "type": "integer" }, "user_id": { "type": "integer" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "on_holiday": { "type": "boolean" } } }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } }, "approval_conditions": { "type": "array", "items": { } } } } }, "approval_conditions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "property": { "type": "string" }, "operator": { "type": "string" }, "value": { "type": "string" }, "custom_field_id": { "type": "null" }, "approval_flow_id": { "type": "integer" }, "approval_step_id": { "type": "null" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "human_readable_description": { "type": "string" }, "property_label": { "type": "string" }, "value_label": { "type": "string" } } } } } }, "example": { "id": 2, "name": "Lab PO routing v3 - updated", "document_type": "purchase_order", "self_approval_allowed": false, "company_id": 20000, "version_no": "20261021050206", "archived": false, "status": "unpublished", "in_progress_entities_count": 0, "completed_entities_count": 0, "rejected_entities_count": 0, "cancelled_entities_count": 0, "total_entities_count": 0, "is_default": false, "created_at": 1792576781, "updated_at": 1792576926, "approval_steps": [ { "id": 3, "step_no": 1, "all_should_approve": false, "approval_flow_id": 2, "created_at": 1792576781, "updated_at": 1792576781, "approval_step_approvers": [ { "id": 4, "approval_step_id": 3, "user_id": 50000, "user": { "id": 50000, "name": "Priya Patel", "email": "priya.patel@example.com", "on_holiday": false }, "created_at": 1792576781, "updated_at": 1792576781 } ], "approval_conditions": [ ] }, { "id": 4, "step_no": 2, "all_should_approve": true, "approval_flow_id": 2, "created_at": 1792576781, "updated_at": 1792576781, "approval_step_approvers": [ { "id": 5, "approval_step_id": 4, "user_id": 40000, "user": { "id": 40000, "name": "Jane Doe", "email": "jane.doe@example.com", "on_holiday": false }, "created_at": 1792576781, "updated_at": 1792576781 } ], "approval_conditions": [ { "id": 3, "property": "gross_amount", "operator": "greater_than", "value": "2500", "custom_field_id": null, "approval_flow_id": null, "approval_step_id": 4, "created_at": 1792576781, "updated_at": 1792576926, "human_readable_description": "Gross amount greater than 2500", "property_label": "Gross amount", "value_label": "2500" } ] } ], "approval_conditions": [ { "id": 4, "property": "department", "operator": "equals", "value": "5", "custom_field_id": null, "approval_flow_id": 2, "approval_step_id": null, "created_at": 1792576781, "updated_at": 1792576781, "human_readable_description": "Department equals Approval Flow Lab", "property_label": "Department", "value_label": "Approval Flow Lab" }, { "id": 16, "property": "supplier", "operator": "is_any_of", "value": "1,2,3", "custom_field_id": null, "approval_flow_id": 2, "approval_step_id": null, "created_at": 1792576926, "updated_at": 1792576926, "human_readable_description": "Supplier is any of Northwind Office Supplies, Contoso Hardware, Globex Logistics", "property_label": "Supplier", "value_label": "Northwind Office Supplies, Contoso Hardware, Globex Logistics" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": { "approval_conditions": [ "must have at least one condition" ], "approval_steps.approval_step_approvers": [ "must have at least one approver" ] }, "status": 400 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": [ "Invalid id passed" ], "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "approval_flow[name]": { "type": "string", "description": "New name." }, "approval_flow[document_type]": { "type": "string", "description": "`purchase_order`, `invoice` or `rfq`. Changing the type of a flow that has runs is not prevented - avoid it." }, "approval_flow[self_approval_allowed]": { "type": "boolean", "description": "See intro." }, "approval_flow[approval_conditions_attributes][][id]": { "type": "integer", "description": "Existing flow condition to change or remove." }, "approval_flow[approval_conditions_attributes][][property]": { "type": "string", "description": "Required for a new condition." }, "approval_flow[approval_conditions_attributes][][operator]": { "type": "string", "description": "Required for a new condition." }, "approval_flow[approval_conditions_attributes][][value]": { "type": "string", "description": "Required for a new condition." }, "approval_flow[approval_conditions_attributes][][custom_field_id]": { "type": "integer", "description": "Legacy custom field link." }, "approval_flow[approval_conditions_attributes][][_destroy]": { "type": "boolean", "description": "`true` removes the condition." }, "approval_flow[approval_steps_attributes][][id]": { "type": "integer", "description": "Existing step to change or remove." }, "approval_flow[approval_steps_attributes][][step_no]": { "type": "integer", "description": "Required for a new step." }, "approval_flow[approval_steps_attributes][][all_should_approve]": { "type": "boolean", "description": "Approval rule." }, "approval_flow[approval_steps_attributes][][_destroy]": { "type": "boolean", "description": "`true` removes the step with its approvers and conditions." }, "approval_flow[approval_steps_attributes][][approval_step_approvers_attributes][][id]": { "type": "integer", "description": "Existing approver assignment." }, "approval_flow[approval_steps_attributes][][approval_step_approvers_attributes][][user_id]": { "type": "integer", "description": "Approver (active company member)." }, "approval_flow[approval_steps_attributes][][approval_step_approvers_attributes][][_destroy]": { "type": "boolean", "description": "`true` removes the approver from the step." }, "approval_flow[approval_steps_attributes][][approval_conditions_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "Step conditions: `id`, `property`, `operator`, `value`, `custom_field_id`, `_destroy`." } } }, "example": { "approval_flow": { "name": "Lab PO routing v3 - updated", "approval_steps_attributes": [ { "id": 4, "approval_step_approvers_attributes": [ { "id": 6, "_destroy": true } ], "approval_conditions_attributes": [ { "id": 3, "value": "2500" } ] }, { "step_no": 3, "all_should_approve": false, "approval_step_approvers_attributes": [ { "user_id": 50000 } ], "approval_conditions_attributes": [ { "property": "gross_amount", "operator": "greater_than", "value": "10000" } ] } ], "approval_conditions_attributes": [ { "property": "supplier", "operator": "is_any_of", "value": "1,2,3" } ] } } } } } }, "delete": { "tags": [ "Approval Flows" ], "operationId": "v3_approval_flows_delete", "summary": "Delete an approval flow", "description": "Soft-deletes an approval flow that has no documents in approval.\n\nDeletes the flow (soft delete - it disappears from every endpoint) together with its steps\nand conditions. Its runs (the links to the documents it routed) are removed permanently; the\ndocuments and their approval requests/history are kept.\n\nRefused (`401`) for the system default invoice flow and while the flow has in-progress runs -\narchive the flow instead if documents are still in approval.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Approval flow id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "Approval Flow has been successfully deleted" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": [ "Invalid id passed" ], "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/approval_flows/{id}": { "get": { "tags": [ "Approval Flows" ], "operationId": "v1_approval_flows_show", "summary": "Get an approval flow", "description": "Returns one approval flow with its steps, approvers and conditions.\n\nReturns the flow with its steps (ordered by `step_no`), each step's approvers (in the order\nthey were added) and step conditions, and the flow-level conditions. Archived flows can be\nfetched; deleted ones return 404.\n\nConditions are returned with three helper fields resolved for display:\n`property_label` (e.g. \"Department\", or the custom field's name), `value_label` (ids turned\ninto names, e.g. \"Approval Flow Lab\") and `human_readable_description`.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Approval flow id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "document_type": { "type": "string" }, "self_approval_allowed": { "type": "boolean" }, "company_id": { "type": "integer" }, "version_no": { "type": "null" }, "archived": { "type": "boolean" }, "status": { "type": "string" }, "in_progress_entities_count": { "type": "integer" }, "completed_entities_count": { "type": "integer" }, "rejected_entities_count": { "type": "integer" }, "cancelled_entities_count": { "type": "integer" }, "total_entities_count": { "type": "integer" }, "is_default": { "type": "boolean" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "approval_steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "step_no": { "type": "integer" }, "all_should_approve": { "type": "boolean" }, "approval_flow_id": { "type": "integer" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "approval_step_approvers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_step_id": { "type": "integer" }, "user_id": { "type": "integer" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "on_holiday": { "type": "boolean" } } }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } }, "approval_conditions": { "type": "array", "items": { } } } } }, "approval_conditions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "property": { "type": "string" }, "operator": { "type": "string" }, "value": { "type": "string" }, "custom_field_id": { "type": "null" }, "approval_flow_id": { "type": "integer" }, "approval_step_id": { "type": "null" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "human_readable_description": { "type": "string" }, "property_label": { "type": "string" }, "value_label": { "type": "string" } } } } } }, "example": { "id": 1, "name": "Lab PO routing v1", "document_type": "purchase_order", "self_approval_allowed": false, "company_id": 20000, "version_no": null, "archived": false, "status": "unpublished", "in_progress_entities_count": 0, "completed_entities_count": 0, "rejected_entities_count": 0, "cancelled_entities_count": 0, "total_entities_count": 0, "is_default": false, "created_at": 1792576772, "updated_at": 1792576772, "approval_steps": [ { "id": 1, "step_no": 1, "all_should_approve": false, "approval_flow_id": 1, "created_at": 1792576772, "updated_at": 1792576772, "approval_step_approvers": [ { "id": 1, "approval_step_id": 1, "user_id": 50000, "user": { "id": 50000, "name": "Priya Patel", "email": "priya.patel@example.com", "on_holiday": false }, "created_at": 1792576772, "updated_at": 1792576772 } ], "approval_conditions": [ ] }, { "id": 2, "step_no": 2, "all_should_approve": true, "approval_flow_id": 1, "created_at": 1792576772, "updated_at": 1792576772, "approval_step_approvers": [ { "id": 2, "approval_step_id": 2, "user_id": 40000, "user": { "id": 40000, "name": "Jane Doe", "email": "jane.doe@example.com", "on_holiday": false }, "created_at": 1792576772, "updated_at": 1792576772 }, { "id": 3, "approval_step_id": 2, "user_id": 50000, "user": { "id": 50000, "name": "Priya Patel", "email": "priya.patel@example.com", "on_holiday": false }, "created_at": 1792576772, "updated_at": 1792576772 } ], "approval_conditions": [ { "id": 1, "property": "gross_amount", "operator": "greater_than", "value": "1000", "custom_field_id": null, "approval_flow_id": null, "approval_step_id": 2, "created_at": 1792576772, "updated_at": 1792576772, "human_readable_description": "Gross amount greater than 1000", "property_label": "Gross amount", "value_label": "1000" } ] } ], "approval_conditions": [ { "id": 2, "property": "department", "operator": "equals", "value": "5", "custom_field_id": null, "approval_flow_id": 1, "approval_step_id": null, "created_at": 1792576772, "updated_at": 1792576772, "human_readable_description": "Department equals Approval Flow Lab", "property_label": "Department", "value_label": "Approval Flow Lab" } ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": [ "Invalid id passed" ], "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "put": { "tags": [ "Approval Flows" ], "operationId": "v1_approval_flows_update", "summary": "Update an approval flow", "description": "Renames a flow or adds, changes and removes its steps, approvers and conditions.\n\nAccepts the same `approval_flow` body as create; send only what changes. Nested records:\n\n* include `id` to change an existing step / approver / condition;\n* omit `id` to add a new one;\n* include `id` and `\"_destroy\": true` (or `1`) to remove it. Destroying a step removes its\n approvers and step conditions.\n\nThe flow must still be valid afterwards (at least one step, one flow condition, one approver\nper step), otherwise nothing is saved.\n\nEvery update stamps a new `version_no` and records a version. Updating does not change\n`status` and does not re-route documents already in approval. When steps, approvers or\nconditions change, all in-progress runs whose document is still active are flagged\n(`flow_changed_at`) so they can be re-evaluated with\n`POST /approval_flows/rerun_approval_flows`. Archived flows can be updated too.\n\n\nNone - identical request and response. Both versions accept PUT and PATCH (the V1 example\nuses PUT, the V3 example PATCH).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Approval flow id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "document_type": { "type": "string" }, "self_approval_allowed": { "type": "boolean" }, "company_id": { "type": "integer" }, "version_no": { "type": "string" }, "archived": { "type": "boolean" }, "status": { "type": "string" }, "in_progress_entities_count": { "type": "integer" }, "completed_entities_count": { "type": "integer" }, "rejected_entities_count": { "type": "integer" }, "cancelled_entities_count": { "type": "integer" }, "total_entities_count": { "type": "integer" }, "is_default": { "type": "boolean" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "approval_steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "step_no": { "type": "integer" }, "all_should_approve": { "type": "boolean" }, "approval_flow_id": { "type": "integer" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "approval_step_approvers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_step_id": { "type": "integer" }, "user_id": { "type": "integer" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "on_holiday": { "type": "boolean" } } }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } }, "approval_conditions": { "type": "array", "items": { } } } } }, "approval_conditions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "property": { "type": "string" }, "operator": { "type": "string" }, "value": { "type": "string" }, "custom_field_id": { "type": "null" }, "approval_flow_id": { "type": "integer" }, "approval_step_id": { "type": "null" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "human_readable_description": { "type": "string" }, "property_label": { "type": "string" }, "value_label": { "type": "string" } } } } } }, "example": { "id": 1, "name": "Lab PO routing v1 - updated", "document_type": "purchase_order", "self_approval_allowed": false, "company_id": 20000, "version_no": "20261021050157", "archived": false, "status": "unpublished", "in_progress_entities_count": 0, "completed_entities_count": 0, "rejected_entities_count": 0, "cancelled_entities_count": 0, "total_entities_count": 0, "is_default": false, "created_at": 1792576772, "updated_at": 1792576917, "approval_steps": [ { "id": 1, "step_no": 1, "all_should_approve": false, "approval_flow_id": 1, "created_at": 1792576772, "updated_at": 1792576772, "approval_step_approvers": [ { "id": 1, "approval_step_id": 1, "user_id": 50000, "user": { "id": 50000, "name": "Priya Patel", "email": "priya.patel@example.com", "on_holiday": false }, "created_at": 1792576772, "updated_at": 1792576772 } ], "approval_conditions": [ ] }, { "id": 2, "step_no": 2, "all_should_approve": true, "approval_flow_id": 1, "created_at": 1792576772, "updated_at": 1792576772, "approval_step_approvers": [ { "id": 2, "approval_step_id": 2, "user_id": 40000, "user": { "id": 40000, "name": "Jane Doe", "email": "jane.doe@example.com", "on_holiday": false }, "created_at": 1792576772, "updated_at": 1792576772 } ], "approval_conditions": [ { "id": 1, "property": "gross_amount", "operator": "greater_than", "value": "2500", "custom_field_id": null, "approval_flow_id": null, "approval_step_id": 2, "created_at": 1792576772, "updated_at": 1792576917, "human_readable_description": "Gross amount greater than 2500", "property_label": "Gross amount", "value_label": "2500" } ] } ], "approval_conditions": [ { "id": 2, "property": "department", "operator": "equals", "value": "5", "custom_field_id": null, "approval_flow_id": 1, "approval_step_id": null, "created_at": 1792576772, "updated_at": 1792576772, "human_readable_description": "Department equals Approval Flow Lab", "property_label": "Department", "value_label": "Approval Flow Lab" }, { "id": 14, "property": "supplier", "operator": "is_any_of", "value": "1,2,3", "custom_field_id": null, "approval_flow_id": 1, "approval_step_id": null, "created_at": 1792576917, "updated_at": 1792576917, "human_readable_description": "Supplier is any of Northwind Office Supplies, Contoso Hardware, Globex Logistics", "property_label": "Supplier", "value_label": "Northwind Office Supplies, Contoso Hardware, Globex Logistics" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": { "approval_conditions": [ "must have at least one condition" ], "approval_steps.approval_step_approvers": [ "must have at least one approver" ] }, "status": 400 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": [ "Invalid id passed" ], "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "approval_flow[name]": { "type": "string", "description": "New name." }, "approval_flow[document_type]": { "type": "string", "description": "`purchase_order`, `invoice` or `rfq`. Changing the type of a flow that has runs is not prevented - avoid it." }, "approval_flow[self_approval_allowed]": { "type": "boolean", "description": "See intro." }, "approval_flow[approval_conditions_attributes][][id]": { "type": "integer", "description": "Existing flow condition to change or remove." }, "approval_flow[approval_conditions_attributes][][property]": { "type": "string", "description": "Required for a new condition." }, "approval_flow[approval_conditions_attributes][][operator]": { "type": "string", "description": "Required for a new condition." }, "approval_flow[approval_conditions_attributes][][value]": { "type": "string", "description": "Required for a new condition." }, "approval_flow[approval_conditions_attributes][][custom_field_id]": { "type": "integer", "description": "Legacy custom field link." }, "approval_flow[approval_conditions_attributes][][_destroy]": { "type": "boolean", "description": "`true` removes the condition." }, "approval_flow[approval_steps_attributes][][id]": { "type": "integer", "description": "Existing step to change or remove." }, "approval_flow[approval_steps_attributes][][step_no]": { "type": "integer", "description": "Required for a new step." }, "approval_flow[approval_steps_attributes][][all_should_approve]": { "type": "boolean", "description": "Approval rule." }, "approval_flow[approval_steps_attributes][][_destroy]": { "type": "boolean", "description": "`true` removes the step with its approvers and conditions." }, "approval_flow[approval_steps_attributes][][approval_step_approvers_attributes][][id]": { "type": "integer", "description": "Existing approver assignment." }, "approval_flow[approval_steps_attributes][][approval_step_approvers_attributes][][user_id]": { "type": "integer", "description": "Approver (active company member)." }, "approval_flow[approval_steps_attributes][][approval_step_approvers_attributes][][_destroy]": { "type": "boolean", "description": "`true` removes the approver from the step." }, "approval_flow[approval_steps_attributes][][approval_conditions_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "Step conditions: `id`, `property`, `operator`, `value`, `custom_field_id`, `_destroy`." } } }, "example": { "approval_flow": { "name": "Lab PO routing v1 - updated", "approval_steps_attributes": [ { "id": 2, "approval_step_approvers_attributes": [ { "id": 3, "_destroy": true } ], "approval_conditions_attributes": [ { "id": 1, "value": "2500" } ] }, { "step_no": 3, "all_should_approve": false, "approval_step_approvers_attributes": [ { "user_id": 50000 } ], "approval_conditions_attributes": [ { "property": "gross_amount", "operator": "greater_than", "value": "10000" } ] } ], "approval_conditions_attributes": [ { "property": "supplier", "operator": "is_any_of", "value": "1,2,3" } ] } } } } } }, "delete": { "tags": [ "Approval Flows" ], "operationId": "v1_approval_flows_delete", "summary": "Delete an approval flow", "description": "Soft-deletes an approval flow that has no documents in approval.\n\nDeletes the flow (soft delete - it disappears from every endpoint) together with its steps\nand conditions. Its runs (the links to the documents it routed) are removed permanently; the\ndocuments and their approval requests/history are kept.\n\nRefused (`401`) for the system default invoice flow and while the flow has in-progress runs -\narchive the flow instead if documents are still in approval.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Approval flow id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "Approval Flow has been successfully deleted" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": [ "Invalid id passed" ], "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/approval_flows/{id}/archive": { "put": { "tags": [ "Approval Flows" ], "operationId": "v3_approval_flows_archive", "summary": "Archive an approval flow", "description": "Archives a flow so it is hidden from the list and never attached to new documents.\n\nSets `archived: true`. Archived flows are skipped by matching (even if `status` is still\n`published`), no longer count towards \"approval flows enabled\" for the company, and are\nexcluded from the list; `GET /approval_flows/:id` still returns them and existing runs\ncontinue. Archiving is idempotent and cannot be undone through the API (there is no\nunarchive and `archived` is not an accepted update param). Only `PUT` is routed (`PATCH`\nreturns 404).\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Approval flow id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "Approval Flow has been successfully archived" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": [ "Invalid id passed" ], "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/approval_flows/{id}/archive": { "put": { "tags": [ "Approval Flows" ], "operationId": "v1_approval_flows_archive", "summary": "Archive an approval flow", "description": "Archives a flow so it is hidden from the list and never attached to new documents.\n\nSets `archived: true`. Archived flows are skipped by matching (even if `status` is still\n`published`), no longer count towards \"approval flows enabled\" for the company, and are\nexcluded from the list; `GET /approval_flows/:id` still returns them and existing runs\ncontinue. Archiving is idempotent and cannot be undone through the API (there is no\nunarchive and `archived` is not an accepted update param). Only `PUT` is routed (`PATCH`\nreturns 404).\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Approval flow id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "Approval Flow has been successfully archived" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": [ "Invalid id passed" ], "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v1/approval_flows/{id}/publish": { "patch": { "tags": [ "Approval Flows" ], "operationId": "v1_approval_flows_publish", "summary": "Publish an approval flow", "description": "Makes an unpublished flow live so it is attached to matching documents from now on (V1 only).\n\nChanges `status` from `unpublished` to `published`. From the next submission on, documents\nof the flow's type whose flow conditions match get this flow. Documents already in approval\nare not affected.\n\n\n\n\nV1 only. V3 routes `PATCH /api/v3/approval_flows/:id/publish` but the V3 controller has no\n`publish` action: it answers `404` with a non-JSON body (an HTML \"Unknown action\" page). Only `PATCH` is routed in V1 (`PUT` returns 404).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Approval flow id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "document_type": { "type": "string" }, "self_approval_allowed": { "type": "boolean" }, "company_id": { "type": "integer" }, "version_no": { "type": "string" }, "archived": { "type": "boolean" }, "status": { "type": "string" }, "in_progress_entities_count": { "type": "integer" }, "completed_entities_count": { "type": "integer" }, "rejected_entities_count": { "type": "integer" }, "cancelled_entities_count": { "type": "integer" }, "total_entities_count": { "type": "integer" }, "is_default": { "type": "boolean" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "approval_steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "step_no": { "type": "integer" }, "all_should_approve": { "type": "boolean" }, "approval_flow_id": { "type": "integer" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } }, "approval_conditions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "property": { "type": "string" }, "operator": { "type": "string" }, "value": { "type": "string" }, "custom_field_id": { "type": "null" }, "approval_flow_id": { "type": "integer" }, "approval_step_id": { "type": "null" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "human_readable_description": { "type": "string" }, "property_label": { "type": "string" }, "value_label": { "type": "string" } } } } } }, "example": { "id": 1, "name": "Lab PO routing v1 - updated", "document_type": "purchase_order", "self_approval_allowed": false, "company_id": 20000, "version_no": "20261021050157", "archived": false, "status": "published", "in_progress_entities_count": 0, "completed_entities_count": 0, "rejected_entities_count": 0, "cancelled_entities_count": 0, "total_entities_count": 0, "is_default": false, "created_at": 1792576772, "updated_at": 1792577229, "approval_steps": [ { "id": 1, "step_no": 1, "all_should_approve": false, "approval_flow_id": 1, "created_at": 1792576772, "updated_at": 1792576772 }, { "id": 2, "step_no": 2, "all_should_approve": true, "approval_flow_id": 1, "created_at": 1792576772, "updated_at": 1792576772 } ], "approval_conditions": [ { "id": 2, "property": "department", "operator": "equals", "value": "5", "custom_field_id": null, "approval_flow_id": 1, "approval_step_id": null, "created_at": 1792576772, "updated_at": 1792576772, "human_readable_description": "Department equals Approval Flow Lab", "property_label": "Department", "value_label": "Approval Flow Lab" }, { "id": 14, "property": "supplier", "operator": "is_any_of", "value": "1,2,3", "custom_field_id": null, "approval_flow_id": 1, "approval_step_id": null, "created_at": 1792576917, "updated_at": 1792576917, "human_readable_description": "Supplier is any of Northwind Office Supplies, Contoso Hardware, Globex Logistics", "property_label": "Supplier", "value_label": "Northwind Office Supplies, Contoso Hardware, Globex Logistics" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": [ "Invalid id passed" ], "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v1/approval_flows/{id}/unpublish": { "patch": { "tags": [ "Approval Flows" ], "operationId": "v1_approval_flows_unpublish", "summary": "Unpublish an approval flow", "description": "Takes a published flow out of matching; documents already routed by it carry on (V1 only).\n\nChanges `status` from `published` to `unpublished`. New documents are no longer matched to the\nflow; in-progress runs keep their approval requests and finish normally. If this was the\ncompany's last published, non-archived flow of its document type, that document type goes\nback to classic routing.\n\n\nV1 only. V3 routes `PATCH /api/v3/approval_flows/:id/unpublish` but has no action: `404` with\na non-JSON \"Unknown action\" body.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Approval flow id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "document_type": { "type": "string" }, "self_approval_allowed": { "type": "boolean" }, "company_id": { "type": "integer" }, "version_no": { "type": "string" }, "archived": { "type": "boolean" }, "status": { "type": "string" }, "in_progress_entities_count": { "type": "integer" }, "completed_entities_count": { "type": "integer" }, "rejected_entities_count": { "type": "integer" }, "cancelled_entities_count": { "type": "integer" }, "total_entities_count": { "type": "integer" }, "is_default": { "type": "boolean" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "approval_steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "step_no": { "type": "integer" }, "all_should_approve": { "type": "boolean" }, "approval_flow_id": { "type": "integer" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } }, "approval_conditions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "property": { "type": "string" }, "operator": { "type": "string" }, "value": { "type": "string" }, "custom_field_id": { "type": "null" }, "approval_flow_id": { "type": "integer" }, "approval_step_id": { "type": "null" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "human_readable_description": { "type": "string" }, "property_label": { "type": "string" }, "value_label": { "type": "string" } } } } } }, "example": { "id": 1, "name": "Lab PO routing v1 - updated", "document_type": "purchase_order", "self_approval_allowed": false, "company_id": 20000, "version_no": "20261021050157", "archived": false, "status": "unpublished", "in_progress_entities_count": 1, "completed_entities_count": 0, "rejected_entities_count": 0, "cancelled_entities_count": 0, "total_entities_count": 1, "is_default": false, "created_at": 1792576772, "updated_at": 1792577231, "approval_steps": [ { "id": 1, "step_no": 1, "all_should_approve": false, "approval_flow_id": 1, "created_at": 1792576772, "updated_at": 1792576772 }, { "id": 2, "step_no": 2, "all_should_approve": true, "approval_flow_id": 1, "created_at": 1792576772, "updated_at": 1792576772 } ], "approval_conditions": [ { "id": 2, "property": "department", "operator": "equals", "value": "5", "custom_field_id": null, "approval_flow_id": 1, "approval_step_id": null, "created_at": 1792576772, "updated_at": 1792576772, "human_readable_description": "Department equals Approval Flow Lab", "property_label": "Department", "value_label": "Approval Flow Lab" }, { "id": 14, "property": "supplier", "operator": "is_any_of", "value": "1,2,3", "custom_field_id": null, "approval_flow_id": 1, "approval_step_id": null, "created_at": 1792576917, "updated_at": 1792576917, "human_readable_description": "Supplier is any of Northwind Office Supplies, Contoso Hardware, Globex Logistics", "property_label": "Supplier", "value_label": "Northwind Office Supplies, Contoso Hardware, Globex Logistics" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/approval_flows/{id}/runs": { "get": { "tags": [ "Approval Flows" ], "operationId": "v3_approval_flows_runs", "summary": "List the runs of an approval flow", "description": "Lists the documents a flow was attached to (its runs), newest first, with their status.\n\nEach run (`approval_entity`) links the flow to one document (`entity_type` `PurchaseOrder`\nor `Invoice`) and tracks that flow's progress on it. Works for unpublished and archived flows\ntoo. Newest first, paginated.\n\nFilters:\n* `status` - `in_progress`, `completed`, `rejected` or `cancelled`. An unknown value returns\n an empty list.\n* `date_range` - `24h`, `7d`, `30d`, `60d` (run created within that period) or `custom` with\n `date_from` and `date_to` in `MM/DD/YYYY` (whole days, inclusive). `custom` without both\n dates is ignored; other values are ignored.\n* `keyword` - matches a run `id` exactly, or a PO `approval_key` / invoice number exactly\n (case-insensitive, no partial match). **Only numeric keywords work today**: any keyword that\n is not an integer (such as an approval key `3-10/21/2026` or an invoice number with letters)\n makes the request fail with HTTP 500.\n\n\nV1 hides runs whose purchase order is cancelled, deleted or archived; V3 returns them (with\nrun status `cancelled`). Verified: after cancelling PO 47, V1 returned 0 runs and V3 1\n(`approval_flows_runs_cancelled_po`). Otherwise identical.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Approval flow id.", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "description": "`in_progress`, `completed`, `rejected`, `cancelled`.", "schema": { "type": "string" } }, { "name": "date_range", "in": "query", "required": false, "description": "`24h`, `7d`, `30d`, `60d` or `custom`.", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": false, "description": "With `date_range=custom`: start date `MM/DD/YYYY`.", "schema": { "type": "string" } }, { "name": "date_to", "in": "query", "required": false, "description": "With `date_range=custom`: end date `MM/DD/YYYY` (inclusive).", "schema": { "type": "string" } }, { "name": "keyword", "in": "query", "required": false, "description": "Run id (see the warning above).", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "10, 20, 50 or 100 (default: user setting, else 10).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval_entities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_flow_id": { "type": "integer" }, "entity_id": { "type": "integer" }, "entity_type": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "approval_flow": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "document_type": { "type": "string" }, "self_approval_allowed": { "type": "boolean" }, "company_id": { "type": "integer" }, "version_no": { "type": "string" }, "archived": { "type": "boolean" }, "status": { "type": "string" }, "in_progress_entities_count": { "type": "integer" }, "completed_entities_count": { "type": "integer" }, "rejected_entities_count": { "type": "integer" }, "cancelled_entities_count": { "type": "integer" }, "total_entities_count": { "type": "integer" }, "is_default": { "type": "boolean" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } }, "entity": { "type": "object", "properties": { "type": { "type": "string" }, "purchase_order": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_key": { "type": "null" }, "creator_name": { "type": "string" }, "amount": { "type": "string" }, "status": { "type": "string" }, "supplier_name": { "type": "string" }, "supplier_id": { "type": "integer" }, "keywords": { "type": "string" }, "created_at": { "type": "integer" }, "currency_id": { "type": "integer" }, "currency_symbol": { "type": "string" }, "currency_iso_code": { "type": "string" }, "total_gross_amount": { "type": "string" }, "total_net_amount": { "type": "string" }, "base_gross_amount": { "type": "number" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "effective_tax_amount": { "type": "number" }, "shipping_amount_overridden": { "type": "boolean" }, "shipping_amount_override": { "type": "null" }, "effective_shipping_amount": { "type": "string" }, "submitted_on": { "type": "integer" }, "po_date": { "type": "null" }, "share_key": { "type": "string" }, "department_id": { "type": "integer" }, "department_name": { "type": "string" }, "budget_name": { "type": "string" }, "compliance_status": { "type": "null" }, "delivered_on": { "type": "null" }, "delivery_status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_progress": { "type": "string" }, "xero_export_status": { "type": "null" }, "synced_with_xero": { "type": "boolean" }, "xero_is_changed": { "type": "boolean" } } } } } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "next_page": { "type": "null" }, "prev_page": { "type": "null" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "example": { "approval_entities": [ { "id": 1, "approval_flow_id": 1, "entity_id": 47, "entity_type": "PurchaseOrder", "status": "in_progress", "created_at": 1792577230, "updated_at": 1792577230, "approval_flow": { "id": 1, "name": "Lab PO routing v1 - updated", "document_type": "purchase_order", "self_approval_allowed": false, "company_id": 20000, "version_no": "20261021050157", "archived": false, "status": "unpublished", "in_progress_entities_count": 1, "completed_entities_count": 0, "rejected_entities_count": 0, "cancelled_entities_count": 0, "total_entities_count": 1, "is_default": false, "created_at": 1792576772, "updated_at": 1792577231 }, "entity": { "type": "purchase_order", "purchase_order": { "id": 47, "approval_key": null, "creator_name": "Sam Smith", "amount": "3000.0", "status": "pending", "supplier_name": "Northwind Office Supplies", "supplier_id": 1, "keywords": "47 Northwind Office Supplies Sam Smith pending 3000.00 Lab Budget Lab test kit 3000.0 3000.0 ", "created_at": 1792577230000, "currency_id": 2000, "currency_symbol": "$", "currency_iso_code": "USD", "total_gross_amount": "3000.0", "total_net_amount": "3000.0", "base_gross_amount": 3000.0, "tax_amount_overridden": false, "tax_amount_override": null, "effective_tax_amount": 0.0, "shipping_amount_overridden": false, "shipping_amount_override": null, "effective_shipping_amount": "0.0", "submitted_on": 1792577230000, "po_date": null, "share_key": "7DA09AB02D4ACBA7B76305FF0439D283288D5A2F", "department_id": 5, "department_name": "Approval Flow Lab", "budget_name": "Lab Budget", "compliance_status": null, "delivered_on": null, "delivery_status": "not_delivered", "payment_status": "unpaid", "payment_progress": "unpaid", "xero_export_status": null, "synced_with_xero": false, "xero_is_changed": false } } } ], "meta": { "current_page": 1, "next_page": null, "prev_page": null, "total_pages": 1, "total_count": 1 } } } } }, "500": { "description": "Internal Server Error" }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": [ "Invalid id passed" ], "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/approval_flows/{id}/runs": { "get": { "tags": [ "Approval Flows" ], "operationId": "v1_approval_flows_runs", "summary": "List the runs of an approval flow", "description": "Lists the documents a flow was attached to (its runs), newest first, with their status.\n\nEach run (`approval_entity`) links the flow to one document (`entity_type` `PurchaseOrder`\nor `Invoice`) and tracks that flow's progress on it. Works for unpublished and archived flows\ntoo. Newest first, paginated.\n\nFilters:\n* `status` - `in_progress`, `completed`, `rejected` or `cancelled`. An unknown value returns\n an empty list.\n* `date_range` - `24h`, `7d`, `30d`, `60d` (run created within that period) or `custom` with\n `date_from` and `date_to` in `MM/DD/YYYY` (whole days, inclusive). `custom` without both\n dates is ignored; other values are ignored.\n* `keyword` - matches a run `id` exactly, or a PO `approval_key` / invoice number exactly\n (case-insensitive, no partial match). **Only numeric keywords work today**: any keyword that\n is not an integer (such as an approval key `3-10/21/2026` or an invoice number with letters)\n makes the request fail with HTTP 500.\n\n\nV1 hides runs whose purchase order is cancelled, deleted or archived; V3 returns them (with\nrun status `cancelled`). Verified: after cancelling PO 47, V1 returned 0 runs and V3 1\n(`approval_flows_runs_cancelled_po`). Otherwise identical.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Approval flow id.", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "description": "`in_progress`, `completed`, `rejected`, `cancelled`.", "schema": { "type": "string" } }, { "name": "date_range", "in": "query", "required": false, "description": "`24h`, `7d`, `30d`, `60d` or `custom`.", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": false, "description": "With `date_range=custom`: start date `MM/DD/YYYY`.", "schema": { "type": "string" } }, { "name": "date_to", "in": "query", "required": false, "description": "With `date_range=custom`: end date `MM/DD/YYYY` (inclusive).", "schema": { "type": "string" } }, { "name": "keyword", "in": "query", "required": false, "description": "Run id (see the warning above).", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "10, 20, 50 or 100 (default: user setting, else 10).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval_entities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_flow_id": { "type": "integer" }, "entity_id": { "type": "integer" }, "entity_type": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "approval_flow": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "document_type": { "type": "string" }, "self_approval_allowed": { "type": "boolean" }, "company_id": { "type": "integer" }, "version_no": { "type": "string" }, "archived": { "type": "boolean" }, "status": { "type": "string" }, "in_progress_entities_count": { "type": "integer" }, "completed_entities_count": { "type": "integer" }, "rejected_entities_count": { "type": "integer" }, "cancelled_entities_count": { "type": "integer" }, "total_entities_count": { "type": "integer" }, "is_default": { "type": "boolean" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } }, "entity": { "type": "object", "properties": { "type": { "type": "string" }, "purchase_order": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_key": { "type": "null" }, "creator_name": { "type": "string" }, "amount": { "type": "string" }, "status": { "type": "string" }, "supplier_name": { "type": "string" }, "supplier_id": { "type": "integer" }, "keywords": { "type": "string" }, "created_at": { "type": "integer" }, "currency_id": { "type": "integer" }, "currency_symbol": { "type": "string" }, "currency_iso_code": { "type": "string" }, "total_gross_amount": { "type": "string" }, "total_net_amount": { "type": "string" }, "base_gross_amount": { "type": "number" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "effective_tax_amount": { "type": "number" }, "shipping_amount_overridden": { "type": "boolean" }, "shipping_amount_override": { "type": "null" }, "effective_shipping_amount": { "type": "string" }, "submitted_on": { "type": "integer" }, "po_date": { "type": "null" }, "share_key": { "type": "string" }, "department_id": { "type": "integer" }, "department_name": { "type": "string" }, "budget_name": { "type": "string" }, "compliance_status": { "type": "null" }, "delivered_on": { "type": "null" }, "delivery_status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_progress": { "type": "string" }, "xero_export_status": { "type": "null" }, "synced_with_xero": { "type": "boolean" }, "xero_is_changed": { "type": "boolean" } } } } } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "next_page": { "type": "null" }, "prev_page": { "type": "null" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "example": { "approval_entities": [ { "id": 1, "approval_flow_id": 1, "entity_id": 47, "entity_type": "PurchaseOrder", "status": "in_progress", "created_at": 1792577230, "updated_at": 1792577230, "approval_flow": { "id": 1, "name": "Lab PO routing v1 - updated", "document_type": "purchase_order", "self_approval_allowed": false, "company_id": 20000, "version_no": "20261021050157", "archived": false, "status": "unpublished", "in_progress_entities_count": 1, "completed_entities_count": 0, "rejected_entities_count": 0, "cancelled_entities_count": 0, "total_entities_count": 1, "is_default": false, "created_at": 1792576772, "updated_at": 1792577231 }, "entity": { "type": "purchase_order", "purchase_order": { "id": 47, "approval_key": null, "creator_name": "Sam Smith", "amount": "3000.0", "status": "pending", "supplier_name": "Northwind Office Supplies", "supplier_id": 1, "keywords": "47 Northwind Office Supplies Sam Smith pending 3000.00 Lab Budget Lab test kit 3000.0 3000.0 ", "created_at": 1792577230000, "currency_id": 2000, "currency_symbol": "$", "currency_iso_code": "USD", "total_gross_amount": "3000.0", "total_net_amount": "3000.0", "base_gross_amount": 3000.0, "tax_amount_overridden": false, "tax_amount_override": null, "effective_tax_amount": 0.0, "shipping_amount_overridden": false, "shipping_amount_override": null, "effective_shipping_amount": "0.0", "submitted_on": 1792577230000, "po_date": null, "share_key": "7DA09AB02D4ACBA7B76305FF0439D283288D5A2F", "department_id": 5, "department_name": "Approval Flow Lab", "budget_name": "Lab Budget", "compliance_status": null, "delivered_on": null, "delivery_status": "not_delivered", "payment_status": "unpaid", "payment_progress": "unpaid", "xero_export_status": null, "synced_with_xero": false, "xero_is_changed": false } } } ], "meta": { "current_page": 1, "next_page": null, "prev_page": null, "total_pages": 1, "total_count": 1 } } } } }, "500": { "description": "Internal Server Error" }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": [ "Invalid id passed" ], "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/approval_flows/{id}/show_entity": { "get": { "tags": [ "Approval Flows" ], "operationId": "v3_approval_flows_show_entity", "summary": "Get one run of an approval flow", "description": "Returns one run of the flow with its document.\n\n`entity_id` is the **run id** (`approval_entities[].id` from the runs list), not the purchase\norder or invoice id. Runs of cancelled POs are returned by both versions.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Approval flow id.", "schema": { "type": "integer" } }, { "name": "entity_id", "in": "query", "required": true, "description": "Run id. A document id, a run of another flow or a missing value returns 404.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_flow_id": { "type": "integer" }, "entity_id": { "type": "integer" }, "entity_type": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "entity": { "type": "object", "properties": { "type": { "type": "string" }, "purchase_order": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_key": { "type": "null" }, "creator_name": { "type": "string" }, "amount": { "type": "string" }, "status": { "type": "string" }, "supplier_name": { "type": "string" }, "supplier_id": { "type": "integer" }, "keywords": { "type": "string" }, "created_at": { "type": "integer" }, "currency_id": { "type": "integer" }, "currency_symbol": { "type": "string" }, "currency_iso_code": { "type": "string" }, "total_gross_amount": { "type": "string" }, "total_net_amount": { "type": "string" }, "base_gross_amount": { "type": "number" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "effective_tax_amount": { "type": "number" }, "shipping_amount_overridden": { "type": "boolean" }, "shipping_amount_override": { "type": "null" }, "effective_shipping_amount": { "type": "string" }, "submitted_on": { "type": "integer" }, "po_date": { "type": "null" }, "share_key": { "type": "string" }, "department_id": { "type": "integer" }, "department_name": { "type": "string" }, "budget_name": { "type": "string" }, "compliance_status": { "type": "null" }, "delivered_on": { "type": "null" }, "delivery_status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_progress": { "type": "string" }, "xero_export_status": { "type": "null" }, "synced_with_xero": { "type": "boolean" }, "xero_is_changed": { "type": "boolean" } } } } } } }, "example": { "id": 1, "approval_flow_id": 1, "entity_id": 47, "entity_type": "PurchaseOrder", "status": "in_progress", "created_at": 1792577230, "updated_at": 1792577230, "entity": { "type": "purchase_order", "purchase_order": { "id": 47, "approval_key": null, "creator_name": "Sam Smith", "amount": "3000.0", "status": "pending", "supplier_name": "Northwind Office Supplies", "supplier_id": 1, "keywords": "47 Northwind Office Supplies Sam Smith pending 3000.00 Lab Budget Lab test kit 3000.0 3000.0 ", "created_at": 1792577230000, "currency_id": 2000, "currency_symbol": "$", "currency_iso_code": "USD", "total_gross_amount": "3000.0", "total_net_amount": "3000.0", "base_gross_amount": 3000.0, "tax_amount_overridden": false, "tax_amount_override": null, "effective_tax_amount": 0.0, "shipping_amount_overridden": false, "shipping_amount_override": null, "effective_shipping_amount": "0.0", "submitted_on": 1792577230000, "po_date": null, "share_key": "7DA09AB02D4ACBA7B76305FF0439D283288D5A2F", "department_id": 5, "department_name": "Approval Flow Lab", "budget_name": "Lab Budget", "compliance_status": null, "delivered_on": null, "delivery_status": "not_delivered", "payment_status": "unpaid", "payment_progress": "unpaid", "xero_export_status": null, "synced_with_xero": false, "xero_is_changed": false } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/approval_flows/{id}/show_entity": { "get": { "tags": [ "Approval Flows" ], "operationId": "v1_approval_flows_show_entity", "summary": "Get one run of an approval flow", "description": "Returns one run of the flow with its document.\n\n`entity_id` is the **run id** (`approval_entities[].id` from the runs list), not the purchase\norder or invoice id. Runs of cancelled POs are returned by both versions.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Approval flow id.", "schema": { "type": "integer" } }, { "name": "entity_id", "in": "query", "required": true, "description": "Run id. A document id, a run of another flow or a missing value returns 404.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_flow_id": { "type": "integer" }, "entity_id": { "type": "integer" }, "entity_type": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "entity": { "type": "object", "properties": { "type": { "type": "string" }, "purchase_order": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_key": { "type": "null" }, "creator_name": { "type": "string" }, "amount": { "type": "string" }, "status": { "type": "string" }, "supplier_name": { "type": "string" }, "supplier_id": { "type": "integer" }, "keywords": { "type": "string" }, "created_at": { "type": "integer" }, "currency_id": { "type": "integer" }, "currency_symbol": { "type": "string" }, "currency_iso_code": { "type": "string" }, "total_gross_amount": { "type": "string" }, "total_net_amount": { "type": "string" }, "base_gross_amount": { "type": "number" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "effective_tax_amount": { "type": "number" }, "shipping_amount_overridden": { "type": "boolean" }, "shipping_amount_override": { "type": "null" }, "effective_shipping_amount": { "type": "string" }, "submitted_on": { "type": "integer" }, "po_date": { "type": "null" }, "share_key": { "type": "string" }, "department_id": { "type": "integer" }, "department_name": { "type": "string" }, "budget_name": { "type": "string" }, "compliance_status": { "type": "null" }, "delivered_on": { "type": "null" }, "delivery_status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_progress": { "type": "string" }, "xero_export_status": { "type": "null" }, "synced_with_xero": { "type": "boolean" }, "xero_is_changed": { "type": "boolean" } } } } } } }, "example": { "id": 1, "approval_flow_id": 1, "entity_id": 47, "entity_type": "PurchaseOrder", "status": "in_progress", "created_at": 1792577230, "updated_at": 1792577230, "entity": { "type": "purchase_order", "purchase_order": { "id": 47, "approval_key": null, "creator_name": "Sam Smith", "amount": "3000.0", "status": "pending", "supplier_name": "Northwind Office Supplies", "supplier_id": 1, "keywords": "47 Northwind Office Supplies Sam Smith pending 3000.00 Lab Budget Lab test kit 3000.0 3000.0 ", "created_at": 1792577230000, "currency_id": 2000, "currency_symbol": "$", "currency_iso_code": "USD", "total_gross_amount": "3000.0", "total_net_amount": "3000.0", "base_gross_amount": 3000.0, "tax_amount_overridden": false, "tax_amount_override": null, "effective_tax_amount": 0.0, "shipping_amount_overridden": false, "shipping_amount_override": null, "effective_shipping_amount": "0.0", "submitted_on": 1792577230000, "po_date": null, "share_key": "7DA09AB02D4ACBA7B76305FF0439D283288D5A2F", "department_id": 5, "department_name": "Approval Flow Lab", "budget_name": "Lab Budget", "compliance_status": null, "delivered_on": null, "delivery_status": "not_delivered", "payment_status": "unpaid", "payment_progress": "unpaid", "xero_export_status": null, "synced_with_xero": false, "xero_is_changed": false } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/approval_flows/{id}/versions": { "get": { "tags": [ "Approval Flows" ], "operationId": "v3_approval_flows_versions", "summary": "List the versions of an approval flow", "description": "Lists earlier states of a flow, newest first.\n\nEvery change to the flow record creates a version: updates, publish/unpublish, and also the\nautomatic run-counter updates when documents are routed, approved or cancelled. Each entry is\nthe flow **as it was before** that change, and `created_at` is when the change happened. The\ncreate event has no earlier state and is not listed.\n\nUse an entry's `id` with `GET /approval_flows/:id/version_details`.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Approval flow id.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "10, 20, 50 or 100 (default: user setting, else 10).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "created_at": { "type": "integer" }, "conditions_count": { "type": "integer" }, "steps_count": { "type": "integer" } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "next_page": { "type": "null" }, "prev_page": { "type": "null" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "example": { "versions": [ { "id": 154, "name": "Lab PO routing v1 - updated", "created_at": 1792577440, "conditions_count": 2, "steps_count": 3 }, { "id": 113, "name": "Lab PO routing v1 - updated", "created_at": 1792577231, "conditions_count": 2, "steps_count": 3 } ], "meta": { "current_page": 1, "next_page": null, "prev_page": null, "total_pages": 1, "total_count": 8 } } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/approval_flows/{id}/versions": { "get": { "tags": [ "Approval Flows" ], "operationId": "v1_approval_flows_versions", "summary": "List the versions of an approval flow", "description": "Lists earlier states of a flow, newest first.\n\nEvery change to the flow record creates a version: updates, publish/unpublish, and also the\nautomatic run-counter updates when documents are routed, approved or cancelled. Each entry is\nthe flow **as it was before** that change, and `created_at` is when the change happened. The\ncreate event has no earlier state and is not listed.\n\nUse an entry's `id` with `GET /approval_flows/:id/version_details`.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Approval flow id.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "10, 20, 50 or 100 (default: user setting, else 10).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "created_at": { "type": "integer" }, "conditions_count": { "type": "integer" }, "steps_count": { "type": "integer" } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "next_page": { "type": "null" }, "prev_page": { "type": "null" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "example": { "versions": [ { "id": 154, "name": "Lab PO routing v1 - updated", "created_at": 1792577440, "conditions_count": 2, "steps_count": 3 }, { "id": 113, "name": "Lab PO routing v1 - updated", "created_at": 1792577231, "conditions_count": 2, "steps_count": 3 } ], "meta": { "current_page": 1, "next_page": null, "prev_page": null, "total_pages": 1, "total_count": 8 } } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/approval_flows/{id}/version_details": { "get": { "tags": [ "Approval Flows" ], "operationId": "v3_approval_flows_version_details", "summary": "Get a version of an approval flow", "description": "Returns the flow as it was before the change recorded by a version.\n\nReturns a historical state in the same shape as *Get an approval flow*. The flow's own\nattributes (`name`, `status`, `version_no`, counters, `updated_at`) and its flow-level\n`approval_conditions` are the historical values.\n\n\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Approval flow id.", "schema": { "type": "integer" } }, { "name": "version_id", "in": "query", "required": true, "description": "A version id of this flow (from `versions`). Another flow's version or a missing value returns 404.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "document_type": { "type": "string" }, "self_approval_allowed": { "type": "boolean" }, "company_id": { "type": "integer" }, "version_no": { "type": "null" }, "archived": { "type": "boolean" }, "status": { "type": "string" }, "in_progress_entities_count": { "type": "integer" }, "completed_entities_count": { "type": "integer" }, "rejected_entities_count": { "type": "integer" }, "cancelled_entities_count": { "type": "integer" }, "total_entities_count": { "type": "integer" }, "is_default": { "type": "boolean" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "approval_steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "step_no": { "type": "integer" }, "all_should_approve": { "type": "boolean" }, "approval_flow_id": { "type": "integer" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "approval_step_approvers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_step_id": { "type": "integer" }, "user_id": { "type": "integer" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "on_holiday": { "type": "boolean" } } }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } }, "approval_conditions": { "type": "array", "items": { } } } } }, "approval_conditions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "property": { "type": "string" }, "operator": { "type": "string" }, "value": { "type": "string" }, "custom_field_id": { "type": "null" }, "approval_flow_id": { "type": "integer" }, "approval_step_id": { "type": "null" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "human_readable_description": { "type": "string" }, "property_label": { "type": "string" }, "value_label": { "type": "string" } } } } } }, "example": { "id": 1, "name": "Lab PO routing v1", "document_type": "purchase_order", "self_approval_allowed": false, "company_id": 20000, "version_no": null, "archived": false, "status": "unpublished", "in_progress_entities_count": 0, "completed_entities_count": 0, "rejected_entities_count": 0, "cancelled_entities_count": 0, "total_entities_count": 0, "is_default": false, "created_at": 1792576772, "updated_at": 1792576772, "approval_steps": [ { "id": 1, "step_no": 1, "all_should_approve": false, "approval_flow_id": 1, "created_at": 1792576772, "updated_at": 1792576772, "approval_step_approvers": [ { "id": 1, "approval_step_id": 1, "user_id": 50000, "user": { "id": 50000, "name": "Priya Patel", "email": "priya.patel@example.com", "on_holiday": false }, "created_at": 1792576772, "updated_at": 1792576772 } ], "approval_conditions": [ ] }, { "id": 2, "step_no": 2, "all_should_approve": true, "approval_flow_id": 1, "created_at": 1792576772, "updated_at": 1792576772, "approval_step_approvers": [ { "id": 2, "approval_step_id": 2, "user_id": 40000, "user": { "id": 40000, "name": "Jane Doe", "email": "jane.doe@example.com", "on_holiday": false }, "created_at": 1792576772, "updated_at": 1792576772 } ], "approval_conditions": [ { "id": 1, "property": "gross_amount", "operator": "greater_than", "value": "2500", "custom_field_id": null, "approval_flow_id": null, "approval_step_id": 2, "created_at": 1792576772, "updated_at": 1792576917, "human_readable_description": "Gross amount greater than 2500", "property_label": "Gross amount", "value_label": "2500" } ] } ], "approval_conditions": [ { "id": 2, "property": "department", "operator": "equals", "value": "5", "custom_field_id": null, "approval_flow_id": 1, "approval_step_id": null, "created_at": 1792576772, "updated_at": 1792576772, "human_readable_description": "Department equals Approval Flow Lab", "property_label": "Department", "value_label": "Approval Flow Lab" } ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/approval_flows/{id}/version_details": { "get": { "tags": [ "Approval Flows" ], "operationId": "v1_approval_flows_version_details", "summary": "Get a version of an approval flow", "description": "Returns the flow as it was before the change recorded by a version.\n\nReturns a historical state in the same shape as *Get an approval flow*. The flow's own\nattributes (`name`, `status`, `version_no`, counters, `updated_at`) and its flow-level\n`approval_conditions` are the historical values.\n\n\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Approval flow id.", "schema": { "type": "integer" } }, { "name": "version_id", "in": "query", "required": true, "description": "A version id of this flow (from `versions`). Another flow's version or a missing value returns 404.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "document_type": { "type": "string" }, "self_approval_allowed": { "type": "boolean" }, "company_id": { "type": "integer" }, "version_no": { "type": "null" }, "archived": { "type": "boolean" }, "status": { "type": "string" }, "in_progress_entities_count": { "type": "integer" }, "completed_entities_count": { "type": "integer" }, "rejected_entities_count": { "type": "integer" }, "cancelled_entities_count": { "type": "integer" }, "total_entities_count": { "type": "integer" }, "is_default": { "type": "boolean" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "approval_steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "step_no": { "type": "integer" }, "all_should_approve": { "type": "boolean" }, "approval_flow_id": { "type": "integer" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "approval_step_approvers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_step_id": { "type": "integer" }, "user_id": { "type": "integer" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "on_holiday": { "type": "boolean" } } }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } }, "approval_conditions": { "type": "array", "items": { } } } } }, "approval_conditions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "property": { "type": "string" }, "operator": { "type": "string" }, "value": { "type": "string" }, "custom_field_id": { "type": "null" }, "approval_flow_id": { "type": "integer" }, "approval_step_id": { "type": "null" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "human_readable_description": { "type": "string" }, "property_label": { "type": "string" }, "value_label": { "type": "string" } } } } } }, "example": { "id": 1, "name": "Lab PO routing v1", "document_type": "purchase_order", "self_approval_allowed": false, "company_id": 20000, "version_no": null, "archived": false, "status": "unpublished", "in_progress_entities_count": 0, "completed_entities_count": 0, "rejected_entities_count": 0, "cancelled_entities_count": 0, "total_entities_count": 0, "is_default": false, "created_at": 1792576772, "updated_at": 1792576772, "approval_steps": [ { "id": 1, "step_no": 1, "all_should_approve": false, "approval_flow_id": 1, "created_at": 1792576772, "updated_at": 1792576772, "approval_step_approvers": [ { "id": 1, "approval_step_id": 1, "user_id": 50000, "user": { "id": 50000, "name": "Priya Patel", "email": "priya.patel@example.com", "on_holiday": false }, "created_at": 1792576772, "updated_at": 1792576772 } ], "approval_conditions": [ ] }, { "id": 2, "step_no": 2, "all_should_approve": true, "approval_flow_id": 1, "created_at": 1792576772, "updated_at": 1792576772, "approval_step_approvers": [ { "id": 2, "approval_step_id": 2, "user_id": 40000, "user": { "id": 40000, "name": "Jane Doe", "email": "jane.doe@example.com", "on_holiday": false }, "created_at": 1792576772, "updated_at": 1792576772 } ], "approval_conditions": [ { "id": 1, "property": "gross_amount", "operator": "greater_than", "value": "2500", "custom_field_id": null, "approval_flow_id": null, "approval_step_id": 2, "created_at": 1792576772, "updated_at": 1792576917, "human_readable_description": "Gross amount greater than 2500", "property_label": "Gross amount", "value_label": "2500" } ] } ], "approval_conditions": [ { "id": 2, "property": "department", "operator": "equals", "value": "5", "custom_field_id": null, "approval_flow_id": 1, "approval_step_id": null, "created_at": 1792576772, "updated_at": 1792576772, "human_readable_description": "Department equals Approval Flow Lab", "property_label": "Department", "value_label": "Approval Flow Lab" } ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/approval_flows/rerun_approval_flows": { "post": { "tags": [ "Approval Flows" ], "operationId": "v3_approval_flows_rerun", "summary": "Rerun approval flows for documents", "description": "Queues a background re-evaluation of documents whose approval flow was edited while they were in approval.\n\nUse after editing a flow's steps, approvers or conditions to bring documents that are\nalready in approval in line with the new definition. The request only **enqueues** a\nbackground job; the response does not say what changed.\n\nThe job processes each purchase order that is still pending (approved, rejected, cancelled,\ndeleted, draft and archived POs are skipped) and only its runs that were flagged as \"flow\nchanged\" by a flow update (POs with no flagged run are left as they are):\n* if the PO still matches the edited flow, approved requests are kept and pending requests\n of approvers who are no longer in the active step are removed;\n* if it no longer matches, the run and its pending requests are removed;\n* published flows that now match are attached, approvers are re-assigned (new requests are\n sent), and a \"was reconfigured and manually restarted\" comment is added to the PO.\n\nInvoices (V1 `invoice_ids`) go through the single-invoice rerun service (same rules as\n`POST /invoices/:id/rerun_approval_flow`).\n\nIds that do not belong to the company are ignored. In V1, POs that are draft, cancelled,\ndeleted or archived are dropped before queueing.\n\n\n* V1 accepts `order_ids` and `invoice_ids` and returns `job_ids` (array); V3 accepts\n `order_ids` only and returns `job_id` (string).\n* V1 drops draft, cancelled, deleted and archived POs before queueing (a draft-only request is\n a 404); V3 queues any PO of the company (draft PO 39: V1 404, V3 queued - captures\n `approval_flows_rerun_draft_po`). The job itself skips such POs.\n* Invoice-only request: V1 queues an invoice job, V3 answers 404 (`approval_flows_rerun_invoice_only`).", "parameters": [ ], "responses": { "500": { "description": "Internal Server Error" }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": [ "Invalid id passed" ], "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "order_ids": { "type": "array", "items": { "type": "integer" }, "description": "Purchase order ids. Required in V3." }, "invoice_ids": { "type": "array", "items": { "type": "integer" }, "description": "V1 only: invoice ids. Ignored by V3." } } }, "example": { "order_ids": [ 47 ] } } } } } }, "/api/v1/approval_flows/rerun_approval_flows": { "post": { "tags": [ "Approval Flows" ], "operationId": "v1_approval_flows_rerun", "summary": "Rerun approval flows for documents", "description": "Queues a background re-evaluation of documents whose approval flow was edited while they were in approval.\n\nUse after editing a flow's steps, approvers or conditions to bring documents that are\nalready in approval in line with the new definition. The request only **enqueues** a\nbackground job; the response does not say what changed.\n\nThe job processes each purchase order that is still pending (approved, rejected, cancelled,\ndeleted, draft and archived POs are skipped) and only its runs that were flagged as \"flow\nchanged\" by a flow update (POs with no flagged run are left as they are):\n* if the PO still matches the edited flow, approved requests are kept and pending requests\n of approvers who are no longer in the active step are removed;\n* if it no longer matches, the run and its pending requests are removed;\n* published flows that now match are attached, approvers are re-assigned (new requests are\n sent), and a \"was reconfigured and manually restarted\" comment is added to the PO.\n\nInvoices (V1 `invoice_ids`) go through the single-invoice rerun service (same rules as\n`POST /invoices/:id/rerun_approval_flow`).\n\nIds that do not belong to the company are ignored. In V1, POs that are draft, cancelled,\ndeleted or archived are dropped before queueing.\n\n\n* V1 accepts `order_ids` and `invoice_ids` and returns `job_ids` (array); V3 accepts\n `order_ids` only and returns `job_id` (string).\n* V1 drops draft, cancelled, deleted and archived POs before queueing (a draft-only request is\n a 404); V3 queues any PO of the company (draft PO 39: V1 404, V3 queued - captures\n `approval_flows_rerun_draft_po`). The job itself skips such POs.\n* Invoice-only request: V1 queues an invoice job, V3 answers 404 (`approval_flows_rerun_invoice_only`).", "parameters": [ ], "responses": { "500": { "description": "Internal Server Error" }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": [ "Invalid id passed" ], "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "order_ids": { "type": "array", "items": { "type": "integer" }, "description": "Purchase order ids. Required in V3." }, "invoice_ids": { "type": "array", "items": { "type": "integer" }, "description": "V1 only: invoice ids. Ignored by V3." } } }, "example": { "order_ids": [ 47 ], "invoice_ids": [ 22 ] } } } } } }, "/api/v1/approval_flows/export": { "get": { "tags": [ "Approval Flows" ], "operationId": "v1_approval_flows_export", "summary": "Export approval flows to Excel", "description": "Downloads all approval flows of the company as an .xlsx workbook (V1 only).\n\nReturns an Excel workbook with one sheet per document type (\"PO Approval Flows\",\n\"RFQ Approval Flows\", \"Invoice Approval Flows\"). Each row is a flow - published first, then\nunpublished, then archived, alphabetically within each group - with the columns Name,\nStatus (`Published` / `Unpublished` / `Archived`), Self-Approval Allowed, Flow Conditions\n(human-readable, `; `-separated), Total, In Progress, Completed (approved + rejected), and\nfor each step: Approvers, Approval Rule (\"Any one can approve\" / \"All must approve\") and\nConditions. Archived flows are included; deleted flows are not.\n\n\nV1 only. In V3 `GET /approval_flows/export` is matched by the show route with id `export` and\nreturns `404` `{\"error\": [\"Invalid id passed\"], \"status\": 404}`.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/budgets": { "get": { "tags": [ "Budgets" ], "operationId": "v3_budget_list", "summary": "List budgets", "description": "Returns the company's budgets; V3 paginates and filters, V1 returns every active, non-expired budget.\n\nLists budgets of the company in the `app_company_id` header.\n\n**V3** (OAuth) - paginated, ordered by name:\n\n* `archived` - `false` (default) returns active budgets, `true` archived ones.\n* `department_id` - only budgets linked to that department (company-wide\n budgets are *not* included). An unknown id answers 404.\n* `only_active=true` - only budgets usable today: open-ended budgets plus\n periodic budgets whose `start_date <= today <= end_date`. Without it,\n expired and future periodic budgets are included.\n* `search` - case-insensitive substring match on name, cost code or cost\n type.\n* `page` / `per_page` - `per_page` defaults to 20 and is capped at 20.\n\n**V1** (authentication token) - returns a bare JSON array of every matching\nbudget, **without pagination** (`page`, `per_page`, `search` and\n`only_active` are ignored):\n\n* Only budgets usable today are returned (open-ended + periodic valid\n today); expired or future periodic budgets are never listed.\n* `department_id` returns the department's budgets **plus** all company-wide\n budgets (no department), i.e. what that department can pick on a PO.\n* `archived=true` returns archived budgets (same date rule).\n* `show_mappings` (any value) adds `third_party_id_mappings` to every budget.\n* Order: open-ended budgets by name, then periodic budgets by name.\n\nThe list is not narrowed to the caller's own departments: every member of\nthe company sees all budgets here (the PO form needs them), even team\nmembers who cannot open a budget with [GET /budgets/:id](#get-a-budget).\n\n\n* Envelope: V1 returns a bare array; V3 returns `{budgets, meta}`.\n* Pagination: V1 none (all rows); V3 `page` / `per_page` (max 20).\n* Expired / future periodic budgets: V1 never lists them; V3 lists them\n unless `only_active=true`.\n* `department_id`: V1 adds company-wide (no-department) budgets; V3 returns\n only budgets linked to the department.\n* `search`: V3 only (ignored by V1).\n* `third_party_id_mappings`: always in V3; V1 only with `show_mappings`.\n* Order: V3 by name; V1 open-ended budgets first, then periodic ones.\n* Internal: a V3 request with header `app_source: mobile_ios`,\n `mobile_android` or `push_cart` (our own apps) uses the V1 selection rules\n (non-expired only, department + company-wide) but keeps the V3 envelope.", "parameters": [ { "name": "archived", "in": "query", "required": false, "description": "`true` lists archived budgets instead of active ones.", "schema": { "type": "boolean" } }, { "name": "department_id", "in": "query", "required": false, "description": "Department filter. V3: only budgets linked to the department. V1: the department's budgets plus company-wide budgets. Unknown id -> 404.", "schema": { "type": "integer" } }, { "name": "only_active", "in": "query", "required": false, "description": "V3 only. `true` excludes expired and not-yet-started periodic budgets (V1 always excludes them).", "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "required": false, "description": "V3 only. Case-insensitive substring of name, cost code or cost type.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "V3 only. Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "V3 only. Page size, capped at 20.", "schema": { "type": "integer" } }, { "name": "show_mappings", "in": "query", "required": false, "description": "V1 only. When present (any value) each budget includes `third_party_id_mappings`. V3 always includes them.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "budgets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "amount": { "type": "number" }, "cost_code": { "type": "string" }, "cost_type": { "type": "string" }, "archived": { "type": "boolean" }, "currency_id": { "type": "integer" }, "base_amount": { "type": "number" }, "base_rate": { "type": "string" }, "allow_anyone_to_approve_a_po": { "type": "boolean" }, "start_date": { "type": "null" }, "end_date": { "type": "null" }, "summary": { "type": "string" }, "remaining_amount": { "type": "number" }, "creator_id": { "type": "integer" }, "qbo_class": { "type": "null" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "approver_ids": { "type": "array", "items": { } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "chart_of_account_id": { "type": "null" }, "chart_of_account_name": { "type": "null" }, "third_party_id_mappings": { "type": "array", "items": { } }, "chart_of_account": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "quickbooks_class": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "next_page": { "type": "null" }, "prev_page": { "type": "null" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "example": { "budgets": [ { "id": 11, "company_id": 20000, "name": "Customer Events Q4", "amount": 2500.0, "cost_code": "EVT-Q4", "cost_type": "Opex", "archived": false, "currency_id": 2000, "base_amount": 2500.0, "base_rate": "1.0", "allow_anyone_to_approve_a_po": false, "start_date": null, "end_date": null, "summary": "Customer Events Q4 : EVT-Q4 : Opex", "remaining_amount": 2500.0, "creator_id": 40000, "qbo_class": null, "department_ids": [ 3 ], "approver_ids": [ ], "created_at": "2026-10-21T05:02:17.243-05:00", "updated_at": "2026-10-21T05:02:27.319-05:00", "chart_of_account_id": null, "chart_of_account_name": null, "third_party_id_mappings": [ ], "chart_of_account": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null } }, { "id": 9, "company_id": 20000, "name": "Expired FY25", "amount": 3000.0, "cost_code": "EXP-25", "cost_type": null, "archived": false, "currency_id": 2000, "base_amount": 3000.0, "base_rate": "1.0", "allow_anyone_to_approve_a_po": false, "start_date": 1735689600, "end_date": 1767139200, "summary": "Expired FY25 : EXP-25", "remaining_amount": 3000.0, "creator_id": 40000, "qbo_class": null, "department_ids": [ 3 ], "approver_ids": [ ], "created_at": "2026-10-21T05:01:46.123-05:00", "updated_at": "2026-10-21T05:01:46.123-05:00", "chart_of_account_id": null, "chart_of_account_name": null, "third_party_id_mappings": [ ], "chart_of_account": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null } } ], "meta": { "current_page": 1, "next_page": null, "prev_page": null, "total_pages": 1, "total_count": 4 } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] }, "post": { "tags": [ "Budgets" ], "operationId": "v3_budget_create", "summary": "Create a budget", "description": "Creates a budget in the company's base currency.\n\nCreates a budget owned by the caller (`creator_id` = caller) in the\ncompany's base currency (`currency_id` is ignored). Send dates in the\ncompany `date_format`; both or neither must be present.\n\n`department_ids` and `approver_ids` set the budget's departments and\napprovers (ids must belong to the company; an id that does not exist at all\nanswers 404, an approver who is not a live member of the company -> 400\n`Approver ids is invalid`). When the company setting\n`make_department_required` is on, at least one department is required.\n\nIntegration ids: `xero_id`, `zapier_id` and `quickbooks_id` store the\nbudget's id in that system (a `third_party_id_mappings` row with service\n`xero` / `zapier` / `quickbooks`); `third_party_id_mappings_attributes` sets\nmappings explicitly (service must be one of `xero`, `zapier`, `quickbooks`,\n`sage50`, `sage200`, `sage200_api`, `mindee`, `llm`, `greatplains`,\n`sage_intacct`, `lightyear`).\n\nThe JSON body may also be sent without the `budget` wrapper for plain\nattributes (Rails wraps known column names), but array params such as\n`department_ids` are only read inside `budget` - always send the wrapper.\n\nOptional header `app_source` records where the budget came from (`api` when\nabsent); it must be one of `website`, `mobile_ios`, `mobile_android`,\n`mobile_other`, `zapier`, `api`, `sage50`, `sage200`, `sage200_api`,\n`po_generator`, `xero_marketplace` (and a few internal values) - an unknown\nvalue makes the request fail with 500.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "amount": { "type": "number" }, "cost_code": { "type": "string" }, "cost_type": { "type": "string" }, "archived": { "type": "boolean" }, "currency_id": { "type": "integer" }, "base_amount": { "type": "number" }, "base_rate": { "type": "string" }, "allow_anyone_to_approve_a_po": { "type": "boolean" }, "start_date": { "type": "integer" }, "end_date": { "type": "integer" }, "summary": { "type": "string" }, "remaining_amount": { "type": "number" }, "creator_id": { "type": "integer" }, "qbo_class": { "type": "null" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "approver_ids": { "type": "array", "items": { "type": "integer" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "chart_of_account_id": { "type": "integer" }, "chart_of_account_name": { "type": "string" }, "chart_of_account": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "quickbooks_class": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } } } }, "example": { "id": 6, "company_id": 20000, "name": "Field Marketing FY27", "amount": 8000.0, "cost_code": "FMK-27", "cost_type": "Opex", "archived": false, "currency_id": 2000, "base_amount": 8000.0, "base_rate": "1.0", "allow_anyone_to_approve_a_po": false, "start_date": 1790812800, "end_date": 1822262400, "summary": "Field Marketing FY27 : FMK-27 : Opex", "remaining_amount": 8000.0, "creator_id": 40000, "qbo_class": null, "department_ids": [ 3 ], "approver_ids": [ 40000, 50000 ], "created_at": "2026-10-21T04:59:50.497-05:00", "updated_at": "2026-10-21T04:59:50.497-05:00", "chart_of_account_id": 3, "chart_of_account_name": "Advertising & Marketing", "chart_of_account": { "id": 3, "name": "Advertising & Marketing" }, "quickbooks_class": { "id": null, "name": null } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Name can't be blank", "Name is too short (minimum is 1 character)" ], "status": 400 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "budget[name]": { "type": "string", "description": "1-255 characters." }, "budget[amount]": { "type": "number", "description": "Budget amount, at most 10,000,000,000,000." }, "budget[cost_code]": { "type": "string", "description": "Max 255 characters; whitespace is stripped." }, "budget[cost_type]": { "type": "string", "description": "Max 255 characters; whitespace is stripped." }, "budget[start_date]": { "type": "string", "description": "Start date in the company date format (e.g. `10/01/2026` for `%m/%d/%Y`). Required when `end_date` is given; must not be after `end_date`. A value in another format is silently ignored." }, "budget[end_date]": { "type": "string", "description": "End date (inclusive) in the company date format. Required when `start_date` is given." }, "budget[department_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Departments of the company. Empty / omitted = company-wide budget. Required when `make_department_required` is on." }, "budget[approver_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "User ids of live members of the company who approve POs on this budget (classic routing)." }, "budget[allow_anyone_to_approve_a_po]": { "type": "boolean", "description": "Let team-member-only requesters self-approve POs on this budget within their limit." }, "budget[chart_of_account_id]": { "type": "integer", "description": "Chart of account of the company to link." }, "budget[qbo_class]": { "type": "string", "description": "Legacy free-text class label. Does not link a QuickBooks class (`quickbooks_class_id` is not accepted)." }, "budget[custom_field_values_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "Budget custom field values: `{custom_field_id, value}` (plus `id` to update an existing value). The custom field must belong to the company." }, "budget[xero_id]": { "type": "string", "description": "Budget's id in Xero (creates a `xero` third-party mapping)." }, "budget[zapier_id]": { "type": "string", "description": "Id in Zapier (creates a `zapier` mapping)." }, "budget[quickbooks_id]": { "type": "string", "description": "Id in QuickBooks (creates a `quickbooks` mapping)." }, "budget[third_party_id_mappings_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "Explicit mappings `{service, third_party_id, realm_id}`." }, "budget[currency_id]": { "type": "integer", "description": "Ignored on create - the company base currency is always used." }, "budget[creator_id]": { "type": "integer", "description": "Ignored on create - the caller becomes the creator." } }, "required": [ "budget[name]", "budget[amount]" ] }, "example": { "budget": { "name": "Field Marketing FY27", "amount": 8000, "cost_code": "FMK-27", "cost_type": "Opex", "start_date": "10/01/2026", "end_date": "09/30/2027", "department_ids": [ 3 ], "approver_ids": [ 40000, 50000 ], "chart_of_account_id": 3, "allow_anyone_to_approve_a_po": false } } } } } } }, "/api/v1/budgets": { "get": { "tags": [ "Budgets" ], "operationId": "v1_budget_list", "summary": "List budgets", "description": "Returns the company's budgets; V3 paginates and filters, V1 returns every active, non-expired budget.\n\nLists budgets of the company in the `app_company_id` header.\n\n**V3** (OAuth) - paginated, ordered by name:\n\n* `archived` - `false` (default) returns active budgets, `true` archived ones.\n* `department_id` - only budgets linked to that department (company-wide\n budgets are *not* included). An unknown id answers 404.\n* `only_active=true` - only budgets usable today: open-ended budgets plus\n periodic budgets whose `start_date <= today <= end_date`. Without it,\n expired and future periodic budgets are included.\n* `search` - case-insensitive substring match on name, cost code or cost\n type.\n* `page` / `per_page` - `per_page` defaults to 20 and is capped at 20.\n\n**V1** (authentication token) - returns a bare JSON array of every matching\nbudget, **without pagination** (`page`, `per_page`, `search` and\n`only_active` are ignored):\n\n* Only budgets usable today are returned (open-ended + periodic valid\n today); expired or future periodic budgets are never listed.\n* `department_id` returns the department's budgets **plus** all company-wide\n budgets (no department), i.e. what that department can pick on a PO.\n* `archived=true` returns archived budgets (same date rule).\n* `show_mappings` (any value) adds `third_party_id_mappings` to every budget.\n* Order: open-ended budgets by name, then periodic budgets by name.\n\nThe list is not narrowed to the caller's own departments: every member of\nthe company sees all budgets here (the PO form needs them), even team\nmembers who cannot open a budget with [GET /budgets/:id](#get-a-budget).\n\n\n* Envelope: V1 returns a bare array; V3 returns `{budgets, meta}`.\n* Pagination: V1 none (all rows); V3 `page` / `per_page` (max 20).\n* Expired / future periodic budgets: V1 never lists them; V3 lists them\n unless `only_active=true`.\n* `department_id`: V1 adds company-wide (no-department) budgets; V3 returns\n only budgets linked to the department.\n* `search`: V3 only (ignored by V1).\n* `third_party_id_mappings`: always in V3; V1 only with `show_mappings`.\n* Order: V3 by name; V1 open-ended budgets first, then periodic ones.\n* Internal: a V3 request with header `app_source: mobile_ios`,\n `mobile_android` or `push_cart` (our own apps) uses the V1 selection rules\n (non-expired only, department + company-wide) but keeps the V3 envelope.", "parameters": [ { "name": "archived", "in": "query", "required": false, "description": "`true` lists archived budgets instead of active ones.", "schema": { "type": "boolean" } }, { "name": "department_id", "in": "query", "required": false, "description": "Department filter. V3: only budgets linked to the department. V1: the department's budgets plus company-wide budgets. Unknown id -> 404.", "schema": { "type": "integer" } }, { "name": "only_active", "in": "query", "required": false, "description": "V3 only. `true` excludes expired and not-yet-started periodic budgets (V1 always excludes them).", "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "required": false, "description": "V3 only. Case-insensitive substring of name, cost code or cost type.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "V3 only. Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "V3 only. Page size, capped at 20.", "schema": { "type": "integer" } }, { "name": "show_mappings", "in": "query", "required": false, "description": "V1 only. When present (any value) each budget includes `third_party_id_mappings`. V3 always includes them.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "amount": { "type": "number" }, "cost_code": { "type": "string" }, "cost_type": { "type": "string" }, "archived": { "type": "boolean" }, "currency_id": { "type": "integer" }, "base_amount": { "type": "number" }, "base_rate": { "type": "string" }, "allow_anyone_to_approve_a_po": { "type": "boolean" }, "start_date": { "type": "null" }, "end_date": { "type": "null" }, "summary": { "type": "string" }, "remaining_amount": { "type": "number" }, "creator_id": { "type": "integer" }, "qbo_class": { "type": "null" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "approver_ids": { "type": "array", "items": { } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "chart_of_account_id": { "type": "null" }, "chart_of_account_name": { "type": "null" }, "chart_of_account": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "quickbooks_class": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } } } } }, "example": [ { "id": 11, "company_id": 20000, "name": "Customer Events Q4", "amount": 2500.0, "cost_code": "EVT-Q4", "cost_type": "Opex", "archived": false, "currency_id": 2000, "base_amount": 2500.0, "base_rate": "1.0", "allow_anyone_to_approve_a_po": false, "start_date": null, "end_date": null, "summary": "Customer Events Q4 : EVT-Q4 : Opex", "remaining_amount": 2500.0, "creator_id": 40000, "qbo_class": null, "department_ids": [ 3 ], "approver_ids": [ ], "created_at": "2026-10-21T05:02:17.243-05:00", "updated_at": "2026-10-21T05:02:27.319-05:00", "chart_of_account_id": null, "chart_of_account_name": null, "chart_of_account": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null } }, { "id": 6, "company_id": 20000, "name": "Field Marketing FY27", "amount": 9500.0, "cost_code": "FMK-27", "cost_type": "Opex", "archived": false, "currency_id": 2000, "base_amount": 8000.0, "base_rate": "1.0", "allow_anyone_to_approve_a_po": false, "start_date": 1790812800, "end_date": 1830211200, "summary": "Field Marketing FY27 : FMK-27 : Opex", "remaining_amount": 9500.0, "creator_id": 40000, "qbo_class": null, "department_ids": [ 2, 3 ], "approver_ids": [ 40000 ], "created_at": "2026-10-21T04:59:50.497-05:00", "updated_at": "2026-10-21T05:02:55.998-05:00", "chart_of_account_id": 3, "chart_of_account_name": "Advertising & Marketing", "chart_of_account": { "id": 3, "name": "Advertising & Marketing" }, "quickbooks_class": { "id": null, "name": null } } ] } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "post": { "tags": [ "Budgets" ], "operationId": "v1_budget_create", "summary": "Create a budget", "description": "Creates a budget in the company's base currency.\n\nCreates a budget owned by the caller (`creator_id` = caller) in the\ncompany's base currency (`currency_id` is ignored). Send dates in the\ncompany `date_format`; both or neither must be present.\n\n`department_ids` and `approver_ids` set the budget's departments and\napprovers (ids must belong to the company; an id that does not exist at all\nanswers 404, an approver who is not a live member of the company -> 400\n`Approver ids is invalid`). When the company setting\n`make_department_required` is on, at least one department is required.\n\nIntegration ids: `xero_id`, `zapier_id` and `quickbooks_id` store the\nbudget's id in that system (a `third_party_id_mappings` row with service\n`xero` / `zapier` / `quickbooks`); `third_party_id_mappings_attributes` sets\nmappings explicitly (service must be one of `xero`, `zapier`, `quickbooks`,\n`sage50`, `sage200`, `sage200_api`, `mindee`, `llm`, `greatplains`,\n`sage_intacct`, `lightyear`).\n\nThe JSON body may also be sent without the `budget` wrapper for plain\nattributes (Rails wraps known column names), but array params such as\n`department_ids` are only read inside `budget` - always send the wrapper.\n\nOptional header `app_source` records where the budget came from (`api` when\nabsent); it must be one of `website`, `mobile_ios`, `mobile_android`,\n`mobile_other`, `zapier`, `api`, `sage50`, `sage200`, `sage200_api`,\n`po_generator`, `xero_marketplace` (and a few internal values) - an unknown\nvalue makes the request fail with 500.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "amount": { "type": "number" }, "cost_code": { "type": "string" }, "cost_type": { "type": "string" }, "archived": { "type": "boolean" }, "currency_id": { "type": "integer" }, "base_amount": { "type": "number" }, "base_rate": { "type": "string" }, "allow_anyone_to_approve_a_po": { "type": "boolean" }, "start_date": { "type": "integer" }, "end_date": { "type": "integer" }, "summary": { "type": "string" }, "remaining_amount": { "type": "number" }, "creator_id": { "type": "integer" }, "qbo_class": { "type": "null" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "approver_ids": { "type": "array", "items": { "type": "integer" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "chart_of_account_id": { "type": "integer" }, "chart_of_account_name": { "type": "string" }, "chart_of_account": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "quickbooks_class": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } } } }, "example": { "id": 5, "company_id": 20000, "name": "Facilities FY27", "amount": 12000.0, "cost_code": "FAC-27", "cost_type": "Opex", "archived": false, "currency_id": 2000, "base_amount": 12000.0, "base_rate": "1.0", "allow_anyone_to_approve_a_po": false, "start_date": 1790812800, "end_date": 1822262400, "summary": "Facilities FY27 : FAC-27 : Opex", "remaining_amount": 12000.0, "creator_id": 40000, "qbo_class": null, "department_ids": [ 4 ], "approver_ids": [ 40000, 50000 ], "created_at": "2026-10-21T04:59:50.191-05:00", "updated_at": "2026-10-21T04:59:50.191-05:00", "chart_of_account_id": 1, "chart_of_account_name": "Office Expenses", "chart_of_account": { "id": 1, "name": "Office Expenses" }, "quickbooks_class": { "id": null, "name": null } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Name can't be blank", "Name is too short (minimum is 1 character)" ], "status": 400 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "budget[name]": { "type": "string", "description": "1-255 characters." }, "budget[amount]": { "type": "number", "description": "Budget amount, at most 10,000,000,000,000." }, "budget[cost_code]": { "type": "string", "description": "Max 255 characters; whitespace is stripped." }, "budget[cost_type]": { "type": "string", "description": "Max 255 characters; whitespace is stripped." }, "budget[start_date]": { "type": "string", "description": "Start date in the company date format (e.g. `10/01/2026` for `%m/%d/%Y`). Required when `end_date` is given; must not be after `end_date`. A value in another format is silently ignored." }, "budget[end_date]": { "type": "string", "description": "End date (inclusive) in the company date format. Required when `start_date` is given." }, "budget[department_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Departments of the company. Empty / omitted = company-wide budget. Required when `make_department_required` is on." }, "budget[approver_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "User ids of live members of the company who approve POs on this budget (classic routing)." }, "budget[allow_anyone_to_approve_a_po]": { "type": "boolean", "description": "Let team-member-only requesters self-approve POs on this budget within their limit." }, "budget[chart_of_account_id]": { "type": "integer", "description": "Chart of account of the company to link." }, "budget[qbo_class]": { "type": "string", "description": "Legacy free-text class label. Does not link a QuickBooks class (`quickbooks_class_id` is not accepted)." }, "budget[custom_field_values_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "Budget custom field values: `{custom_field_id, value}` (plus `id` to update an existing value). The custom field must belong to the company." }, "budget[xero_id]": { "type": "string", "description": "Budget's id in Xero (creates a `xero` third-party mapping)." }, "budget[zapier_id]": { "type": "string", "description": "Id in Zapier (creates a `zapier` mapping)." }, "budget[quickbooks_id]": { "type": "string", "description": "Id in QuickBooks (creates a `quickbooks` mapping)." }, "budget[third_party_id_mappings_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "Explicit mappings `{service, third_party_id, realm_id}`." }, "budget[currency_id]": { "type": "integer", "description": "Ignored on create - the company base currency is always used." }, "budget[creator_id]": { "type": "integer", "description": "Ignored on create - the caller becomes the creator." } }, "required": [ "budget[name]", "budget[amount]" ] }, "example": { "budget": { "name": "Facilities FY27", "amount": 12000, "cost_code": "FAC-27", "cost_type": "Opex", "start_date": "10/01/2026", "end_date": "09/30/2027", "department_ids": [ 4 ], "approver_ids": [ 40000, 50000 ], "chart_of_account_id": 1, "allow_anyone_to_approve_a_po": false } } } } } } }, "/api/v3/budgets/{id}": { "get": { "tags": [ "Budgets" ], "operationId": "v3_budget_show", "summary": "Get a budget", "description": "Returns one budget of the company, archived budgets included.\n\nReturns a single budget by id. Archived budgets are returned too. The\nresponse never includes `third_party_id_mappings` (use the list for those).\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Budget id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "amount": { "type": "number" }, "cost_code": { "type": "string" }, "cost_type": { "type": "string" }, "archived": { "type": "boolean" }, "currency_id": { "type": "integer" }, "base_amount": { "type": "number" }, "base_rate": { "type": "string" }, "allow_anyone_to_approve_a_po": { "type": "boolean" }, "start_date": { "type": "integer" }, "end_date": { "type": "integer" }, "summary": { "type": "string" }, "remaining_amount": { "type": "number" }, "creator_id": { "type": "integer" }, "qbo_class": { "type": "null" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "approver_ids": { "type": "array", "items": { "type": "integer" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "chart_of_account_id": { "type": "integer" }, "chart_of_account_name": { "type": "string" }, "chart_of_account": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "quickbooks_class": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } }, "example": { "id": 1, "company_id": 20000, "name": "Engineering Hardware FY26", "amount": 50000.0, "cost_code": "ENG-HW", "cost_type": "Capex", "archived": false, "currency_id": 2000, "base_amount": 50000.0, "base_rate": "1.0", "allow_anyone_to_approve_a_po": false, "start_date": 1767225600, "end_date": 1798675200, "summary": "Engineering Hardware FY26 : ENG-HW : Capex", "remaining_amount": 25845.78, "creator_id": 40000, "qbo_class": null, "department_ids": [ 2 ], "approver_ids": [ 40000, 50000 ], "created_at": "2026-10-21T04:48:43.335-05:00", "updated_at": "2026-10-21T05:02:00.107-05:00", "chart_of_account_id": 2, "chart_of_account_name": "Computer Equipment", "chart_of_account": { "id": 2, "name": "Computer Equipment" }, "quickbooks_class": { "id": 1, "name": "Northeast" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] }, "put": { "tags": [ "Budgets" ], "operationId": "v3_budget_update", "summary": "Update a budget", "description": "Updates the given attributes of a budget; omitted attributes are unchanged.\n\nPartial update: only the attributes you send change. In particular a date\nthat is not sent is kept, and an amount-only update keeps the dates. Sending\n`start_date` / `end_date` as an empty string clears it (clear both to make\nthe budget open-ended); a date in the wrong format also clears it, which\nusually fails with `Start date can't be blank` / `End date can't be blank`.\n\n`department_ids` / `approver_ids` **replace** the whole set. `currency_id`\ncan be changed here (unlike create), but `base_amount` and `base_rate` keep\ntheir creation values. `creator_id` may be reassigned to a live member of\nthe company. `archived` is not accepted - use V3\n[archive](#archive-a-budget) / [unarchive](#unarchive-a-budget). Archived\nbudgets can still be updated.\n\n\nNone - identical request and response; PUT and PATCH behave the same in both.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Budget id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "amount": { "type": "number" }, "cost_code": { "type": "string" }, "cost_type": { "type": "string" }, "archived": { "type": "boolean" }, "currency_id": { "type": "integer" }, "base_amount": { "type": "number" }, "base_rate": { "type": "string" }, "allow_anyone_to_approve_a_po": { "type": "boolean" }, "start_date": { "type": "integer" }, "end_date": { "type": "integer" }, "summary": { "type": "string" }, "remaining_amount": { "type": "number" }, "creator_id": { "type": "integer" }, "qbo_class": { "type": "null" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "approver_ids": { "type": "array", "items": { "type": "integer" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "chart_of_account_id": { "type": "integer" }, "chart_of_account_name": { "type": "string" }, "chart_of_account": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "quickbooks_class": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } } } }, "example": { "id": 6, "company_id": 20000, "name": "Field Marketing FY27", "amount": 9500.0, "cost_code": "FMK-27", "cost_type": "Opex", "archived": false, "currency_id": 2000, "base_amount": 8000.0, "base_rate": "1.0", "allow_anyone_to_approve_a_po": false, "start_date": 1790812800, "end_date": 1830211200, "summary": "Field Marketing FY27 : FMK-27 : Opex", "remaining_amount": 9500.0, "creator_id": 40000, "qbo_class": null, "department_ids": [ 3, 2 ], "approver_ids": [ 40000 ], "created_at": "2026-10-21T04:59:50.497-05:00", "updated_at": "2026-10-21T05:02:55.998-05:00", "chart_of_account_id": 3, "chart_of_account_name": "Advertising & Marketing", "chart_of_account": { "id": 3, "name": "Advertising & Marketing" }, "quickbooks_class": { "id": null, "name": null } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Name can't be blank", "Name is too short (minimum is 1 character)", "Start date Must be less than end date", "End date Must be greater than start date" ], "status": 400 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "budget[name]": { "type": "string", "description": "1-255 characters." }, "budget[amount]": { "type": "number", "description": "At most 10,000,000,000,000. `base_amount` is not recalculated." }, "budget[cost_code]": { "type": "string", "description": "Max 255 characters." }, "budget[cost_type]": { "type": "string", "description": "Max 255 characters." }, "budget[start_date]": { "type": "string", "description": "Company date format; empty string clears. Keep start <= end and both-or-neither." }, "budget[end_date]": { "type": "string", "description": "Company date format; empty string clears." }, "budget[department_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Replaces the budget's departments." }, "budget[approver_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Replaces the budget's approvers (live members of the company)." }, "budget[allow_anyone_to_approve_a_po]": { "type": "boolean", "description": "See create." }, "budget[chart_of_account_id]": { "type": "integer", "description": "Chart of account of the company." }, "budget[currency_id]": { "type": "integer", "description": "Changes the budget currency (base_amount / base_rate are not recalculated)." }, "budget[creator_id]": { "type": "integer", "description": "Reassign the creator; must be a live member of the company (`Creator is invalid`)." }, "budget[qbo_class]": { "type": "string", "description": "Legacy free-text label." }, "budget[custom_field_values_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "`{id, custom_field_id, value}`." }, "budget[xero_id]": { "type": "string", "description": "Adds a `xero` mapping." }, "budget[zapier_id]": { "type": "string", "description": "Adds a `zapier` mapping." }, "budget[quickbooks_id]": { "type": "string", "description": "Adds a `quickbooks` mapping." }, "budget[third_party_id_mappings_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "`{service, third_party_id, realm_id}`." } } }, "example": { "budget": { "amount": 9500, "end_date": "12/31/2027", "approver_ids": [ 40000 ], "department_ids": [ 3, 2 ] } } } } } } }, "/api/v1/budgets/{id}": { "get": { "tags": [ "Budgets" ], "operationId": "v1_budget_show", "summary": "Get a budget", "description": "Returns one budget of the company, archived budgets included.\n\nReturns a single budget by id. Archived budgets are returned too. The\nresponse never includes `third_party_id_mappings` (use the list for those).\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Budget id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "amount": { "type": "number" }, "cost_code": { "type": "string" }, "cost_type": { "type": "string" }, "archived": { "type": "boolean" }, "currency_id": { "type": "integer" }, "base_amount": { "type": "number" }, "base_rate": { "type": "string" }, "allow_anyone_to_approve_a_po": { "type": "boolean" }, "start_date": { "type": "integer" }, "end_date": { "type": "integer" }, "summary": { "type": "string" }, "remaining_amount": { "type": "number" }, "creator_id": { "type": "integer" }, "qbo_class": { "type": "null" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "approver_ids": { "type": "array", "items": { "type": "integer" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "chart_of_account_id": { "type": "integer" }, "chart_of_account_name": { "type": "string" }, "chart_of_account": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "quickbooks_class": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } }, "example": { "id": 1, "company_id": 20000, "name": "Engineering Hardware FY26", "amount": 50000.0, "cost_code": "ENG-HW", "cost_type": "Capex", "archived": false, "currency_id": 2000, "base_amount": 50000.0, "base_rate": "1.0", "allow_anyone_to_approve_a_po": false, "start_date": 1767225600, "end_date": 1798675200, "summary": "Engineering Hardware FY26 : ENG-HW : Capex", "remaining_amount": 25845.78, "creator_id": 40000, "qbo_class": null, "department_ids": [ 2 ], "approver_ids": [ 40000, 50000 ], "created_at": "2026-10-21T04:48:43.335-05:00", "updated_at": "2026-10-21T05:02:00.107-05:00", "chart_of_account_id": 2, "chart_of_account_name": "Computer Equipment", "chart_of_account": { "id": 2, "name": "Computer Equipment" }, "quickbooks_class": { "id": 1, "name": "Northeast" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "put": { "tags": [ "Budgets" ], "operationId": "v1_budget_update", "summary": "Update a budget", "description": "Updates the given attributes of a budget; omitted attributes are unchanged.\n\nPartial update: only the attributes you send change. In particular a date\nthat is not sent is kept, and an amount-only update keeps the dates. Sending\n`start_date` / `end_date` as an empty string clears it (clear both to make\nthe budget open-ended); a date in the wrong format also clears it, which\nusually fails with `Start date can't be blank` / `End date can't be blank`.\n\n`department_ids` / `approver_ids` **replace** the whole set. `currency_id`\ncan be changed here (unlike create), but `base_amount` and `base_rate` keep\ntheir creation values. `creator_id` may be reassigned to a live member of\nthe company. `archived` is not accepted - use V3\n[archive](#archive-a-budget) / [unarchive](#unarchive-a-budget). Archived\nbudgets can still be updated.\n\n\nNone - identical request and response; PUT and PATCH behave the same in both.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Budget id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "amount": { "type": "number" }, "cost_code": { "type": "string" }, "cost_type": { "type": "string" }, "archived": { "type": "boolean" }, "currency_id": { "type": "integer" }, "base_amount": { "type": "number" }, "base_rate": { "type": "string" }, "allow_anyone_to_approve_a_po": { "type": "boolean" }, "start_date": { "type": "integer" }, "end_date": { "type": "integer" }, "summary": { "type": "string" }, "remaining_amount": { "type": "number" }, "creator_id": { "type": "integer" }, "qbo_class": { "type": "null" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "approver_ids": { "type": "array", "items": { "type": "integer" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "chart_of_account_id": { "type": "integer" }, "chart_of_account_name": { "type": "string" }, "chart_of_account": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "quickbooks_class": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } } } }, "example": { "id": 5, "company_id": 20000, "name": "Facilities FY27", "amount": 15000.0, "cost_code": "FAC-27", "cost_type": "Opex", "archived": false, "currency_id": 2000, "base_amount": 12000.0, "base_rate": "1.0", "allow_anyone_to_approve_a_po": false, "start_date": 1790812800, "end_date": 1830211200, "summary": "Facilities FY27 : FAC-27 : Opex", "remaining_amount": 15000.0, "creator_id": 40000, "qbo_class": null, "department_ids": [ 4, 2 ], "approver_ids": [ 40000 ], "created_at": "2026-10-21T04:59:50.191-05:00", "updated_at": "2026-10-21T05:02:55.649-05:00", "chart_of_account_id": 1, "chart_of_account_name": "Office Expenses", "chart_of_account": { "id": 1, "name": "Office Expenses" }, "quickbooks_class": { "id": null, "name": null } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Name can't be blank", "Name is too short (minimum is 1 character)", "Start date Must be less than end date", "End date Must be greater than start date" ], "status": 400 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "budget[name]": { "type": "string", "description": "1-255 characters." }, "budget[amount]": { "type": "number", "description": "At most 10,000,000,000,000. `base_amount` is not recalculated." }, "budget[cost_code]": { "type": "string", "description": "Max 255 characters." }, "budget[cost_type]": { "type": "string", "description": "Max 255 characters." }, "budget[start_date]": { "type": "string", "description": "Company date format; empty string clears. Keep start <= end and both-or-neither." }, "budget[end_date]": { "type": "string", "description": "Company date format; empty string clears." }, "budget[department_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Replaces the budget's departments." }, "budget[approver_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Replaces the budget's approvers (live members of the company)." }, "budget[allow_anyone_to_approve_a_po]": { "type": "boolean", "description": "See create." }, "budget[chart_of_account_id]": { "type": "integer", "description": "Chart of account of the company." }, "budget[currency_id]": { "type": "integer", "description": "Changes the budget currency (base_amount / base_rate are not recalculated)." }, "budget[creator_id]": { "type": "integer", "description": "Reassign the creator; must be a live member of the company (`Creator is invalid`)." }, "budget[qbo_class]": { "type": "string", "description": "Legacy free-text label." }, "budget[custom_field_values_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "`{id, custom_field_id, value}`." }, "budget[xero_id]": { "type": "string", "description": "Adds a `xero` mapping." }, "budget[zapier_id]": { "type": "string", "description": "Adds a `zapier` mapping." }, "budget[quickbooks_id]": { "type": "string", "description": "Adds a `quickbooks` mapping." }, "budget[third_party_id_mappings_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "`{service, third_party_id, realm_id}`." } } }, "example": { "budget": { "amount": 15000, "end_date": "12/31/2027", "approver_ids": [ 40000 ], "department_ids": [ 4, 2 ] } } } } } } }, "/api/v3/budgets/{id}/archive": { "post": { "tags": [ "Budgets" ], "operationId": "v3_budget_archive", "summary": "Archive a budget", "description": "Archives a budget (idempotent).\n\nSets `archived: true`. Archived budgets disappear from the default lists and\ncan no longer be chosen on new POs; existing POs keep them. Idempotent:\narchiving an archived budget succeeds and changes nothing (unlike the web\napp's toggle, so a retried request cannot undo itself).\n\n\nV3 only. V1 has no archive route: `POST /api/v1/budgets/:id/archive` answers\n404 `{\"error\": \"Invalid URL\"}`, and V1 update does not accept `archived`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Budget id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "amount": { "type": "number" }, "cost_code": { "type": "string" }, "cost_type": { "type": "string" }, "archived": { "type": "boolean" }, "currency_id": { "type": "integer" }, "base_amount": { "type": "number" }, "base_rate": { "type": "string" }, "allow_anyone_to_approve_a_po": { "type": "boolean" }, "start_date": { "type": "null" }, "end_date": { "type": "null" }, "summary": { "type": "string" }, "remaining_amount": { "type": "number" }, "creator_id": { "type": "integer" }, "qbo_class": { "type": "null" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "approver_ids": { "type": "array", "items": { } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "chart_of_account_id": { "type": "null" }, "chart_of_account_name": { "type": "null" }, "chart_of_account": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "quickbooks_class": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } } } }, "example": { "id": 11, "company_id": 20000, "name": "Customer Events Q4", "amount": 2500.0, "cost_code": "EVT-Q4", "cost_type": "Opex", "archived": true, "currency_id": 2000, "base_amount": 2500.0, "base_rate": "1.0", "allow_anyone_to_approve_a_po": false, "start_date": null, "end_date": null, "summary": "Customer Events Q4 : EVT-Q4 : Opex", "remaining_amount": 2500.0, "creator_id": 40000, "qbo_class": null, "department_ids": [ 3 ], "approver_ids": [ ], "created_at": "2026-10-21T05:02:17.243-05:00", "updated_at": "2026-10-21T05:02:26.400-05:00", "chart_of_account_id": null, "chart_of_account_name": null, "chart_of_account": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v3/budgets/{id}/unarchive": { "post": { "tags": [ "Budgets" ], "operationId": "v3_budget_unarchive", "summary": "Unarchive a budget", "description": "Restores an archived budget (idempotent).\n\nSets `archived: false`, making the budget selectable again. Idempotent.\n\n\nV3 only. `POST /api/v1/budgets/:id/unarchive` answers 404 `Invalid URL`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Budget id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "amount": { "type": "number" }, "cost_code": { "type": "string" }, "cost_type": { "type": "string" }, "archived": { "type": "boolean" }, "currency_id": { "type": "integer" }, "base_amount": { "type": "number" }, "base_rate": { "type": "string" }, "allow_anyone_to_approve_a_po": { "type": "boolean" }, "start_date": { "type": "null" }, "end_date": { "type": "null" }, "summary": { "type": "string" }, "remaining_amount": { "type": "number" }, "creator_id": { "type": "integer" }, "qbo_class": { "type": "null" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "approver_ids": { "type": "array", "items": { } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "chart_of_account_id": { "type": "null" }, "chart_of_account_name": { "type": "null" }, "chart_of_account": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "quickbooks_class": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } } } }, "example": { "id": 11, "company_id": 20000, "name": "Customer Events Q4", "amount": 2500.0, "cost_code": "EVT-Q4", "cost_type": "Opex", "archived": false, "currency_id": 2000, "base_amount": 2500.0, "base_rate": "1.0", "allow_anyone_to_approve_a_po": false, "start_date": null, "end_date": null, "summary": "Customer Events Q4 : EVT-Q4 : Opex", "remaining_amount": 2500.0, "creator_id": 40000, "qbo_class": null, "department_ids": [ 3 ], "approver_ids": [ ], "created_at": "2026-10-21T05:02:17.243-05:00", "updated_at": "2026-10-21T05:02:27.319-05:00", "chart_of_account_id": null, "chart_of_account_name": null, "chart_of_account": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v3/companies": { "get": { "tags": [ "Companies" ], "operationId": "v3_companies_list", "summary": "List companies", "description": "Lists every company the caller is a member of, with the caller's roles and approval limit in each.\n\nReturns all companies the authenticated user has a membership in,\nincluding companies where that membership is archived\n(`membership_archived: true`) and companies that are locked or removed\n(`is_locked`, `is_removed`). Use it after authenticating to choose the\n`app_company_id` to send on every other request.\n\nThe `app_company_id` header is **optional** here (the request succeeds\nwithout it). Results are not paginated and not filterable; order is\ncompany creation order.\n\n**V3 only - sparse fieldsets.** Pass `fields` with a comma-separated list\nof company attributes to receive only those (plus `id`, always included).\nThis also skips the per-company work behind the omitted attributes, so it\nis noticeably faster for users with many companies. Whitespace around\nnames is ignored; an unknown name answers `400`. Use the comma form -\nthe array form `fields[]=name` is rejected as unknown.\n\n\n* V3 accepts `fields` (sparse fieldsets) and answers `400`\n `Unknown fields: . Allowed fields are: ...` for unknown names.\n V1 ignores `fields` and always returns every attribute.\n* Otherwise identical request and response.", "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "V3 only. Comma-separated attribute names to return, e.g. `name,roles,in_trial`. Allowed: `id`, `name`, `external_user_id`, `membership_archived`, `is_locked`, `is_removed`, `approval_limit`, `in_trial`, `trial_expired`, `remaining_trial_days`, `roles`, `has_unassigned_budgets`. Ignored by V1.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "external_user_id": { "type": "null" }, "membership_archived": { "type": "boolean" }, "is_locked": { "type": "boolean" }, "is_removed": { "type": "boolean" }, "approval_limit": { "type": "number" }, "in_trial": { "type": "boolean" }, "trial_expired": { "type": "boolean" }, "remaining_trial_days": { "type": "integer" }, "roles": { "type": "array", "items": { "type": "string" } }, "has_unassigned_budgets": { "type": "boolean" } } } }, "example": [ { "id": 20000, "name": "Acme Corporation", "external_user_id": null, "membership_archived": false, "is_locked": false, "is_removed": false, "approval_limit": 1000000.0, "in_trial": true, "trial_expired": false, "remaining_trial_days": 365, "roles": [ "companyadmin", "approver", "finance", "teammember" ], "has_unassigned_budgets": true }, { "id": 9, "name": "Globex Subsidiary", "external_user_id": null, "membership_archived": false, "is_locked": false, "is_removed": false, "approval_limit": 1000000.0, "in_trial": true, "trial_expired": false, "remaining_trial_days": 365, "roles": [ "companyadmin", "approver", "finance", "teammember" ], "has_unassigned_budgets": false } ] } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "Unknown fields: colour. Allowed fields are: id, name, external_user_id, membership_archived, is_locked, is_removed, approval_limit, in_trial, trial_expired, remaining_trial_days, roles, has_unassigned_budgets.", "status": 400 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] }, "post": { "tags": [ "Companies" ], "operationId": "v3_companies_create", "summary": "Create a company", "description": "Creates a new company owned by the caller, on a free trial, with the caller as its administrator.\n\nCreates a company and makes the caller its creator and first member with\nthe roles `companyadmin`, `approver`, `finance` and `teammember`. The\n`app_company_id` header is not required.\n\nWhat is created with the company:\n\n* company settings from `company_setting_attributes` - a currency is\n mandatory. Some settings are always forced on create:\n `allow_budget_overruns` = false (the request value is ignored),\n approval required after PO edit, invoice upload off, supplier rating on,\n PDF attachment in supplier emails on, auto-approval of own requests off;\n* a budget named **Sample Budget** (10,000,000 in the company currency),\n in addition to any `budgets_attributes` you send;\n* a trial subscription on the trial plan (5 seats);\n* tax rates `None` and `Tax exempt` (`None` becomes the default when\n `default_tax_rate` is 0), default payment terms and default reports;\n* the default currency is added to `supported_currency_ids` automatically.\n\n**Department.** When the caller originally signed up through the website\n(the usual case), `company[department]` is mandatory: a department with\nthat name is created, linked to the Sample Budget, the caller is made the\nSample Budget's approver and is assigned to the department. For users\ncreated another way (mobile app, integrations) `company[department]` is\nignored and no department is created.\n\n**Side effects.** A Slack notification to the sales team is queued. The\ncaller's primary company (`employer_id`, used e.g. by `GET /currentuser`)\nis switched to the new company. If the caller's profile country requires\npayment before a trial, the company is created locked (`is_locked: true`)\nand every request in it answers 402 until a subscription is bought.\n\nThe optional `app_source` request header records where the company came\nfrom (`api` by default; one of `website`, `mobile_ios`,\n`mobile_android`, `mobile_other`, `mobile_android_offline`,\n`mobile_ios_offline`, `push_cart`, `zapier`, `api`, `sage50`, `sage200`,\n`po_generator`, `xero_marketplace`, `sage200_api`).\n\nThe call is not idempotent: repeating it creates another company with\nthe same name.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "external_user_id": { "type": "null" }, "membership_archived": { "type": "null" }, "is_locked": { "type": "boolean" }, "is_removed": { "type": "boolean" }, "approval_limit": { "type": "null" }, "in_trial": { "type": "boolean" }, "trial_expired": { "type": "boolean" }, "remaining_trial_days": { "type": "integer" }, "roles": { "type": "null" }, "has_unassigned_budgets": { "type": "boolean" } } }, "example": { "id": 10, "name": "Globex Subsidiary", "external_user_id": null, "membership_archived": null, "is_locked": false, "is_removed": false, "approval_limit": null, "in_trial": true, "trial_expired": false, "remaining_trial_days": 365, "roles": null, "has_unassigned_budgets": false } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Department can't be blank" ], "status": 400 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "company[name]": { "type": "string", "description": "Company name, max 80 characters." }, "company[department]": { "type": "string", "description": "Name of the first department. **Required** when the caller signed up on the website (`Department can't be blank` otherwise); ignored for other users." }, "company[company_setting_attributes][currency_id]": { "type": "integer", "description": "Default currency id. Without it: `Company setting currency can't be blank` and `Budgets currency can't be blank`." }, "company[gross_or_net_config]": { "type": "string", "description": "`gross` or `net` (or `0` / `1`). Defaults to `gross`. Any other value answers 500." }, "company[default_tax_rate]": { "type": "number", "description": "Legacy default tax rate percent, greater than -1 and less than 101. Defaults to 0." }, "company[supported_currency_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Currency ids to enable. The default currency is added automatically." }, "company[budgets_attributes][][name]": { "type": "string", "description": "Additional budget to create (the Sample Budget is always created too)." }, "company[budgets_attributes][][amount]": { "type": "number", "description": "Additional budget amount." }, "company[budgets_attributes][][creator_id]": { "type": "integer", "description": "Ignored - the caller is always the creator." }, "company[budgets_attributes][][currency_id]": { "type": "integer", "description": "Ignored - the company currency is used. Sending any budget also forces `tax_label` to `Tax`." }, "company[company_setting_attributes][date_format]": { "type": "string", "description": "strftime pattern, e.g. `%Y-%m-%d`." }, "company[company_setting_attributes][tax_label]": { "type": "string", "description": "Tax label, e.g. `VAT` (overridden to `Tax` when `budgets_attributes` are sent)." }, "company[company_setting_attributes][departments_alias]": { "type": "string", "description": "Custom label for departments." }, "company[company_setting_attributes][budgets_alias]": { "type": "string", "description": "Custom label for budgets." }, "company[company_setting_attributes][pdf_font_size]": { "type": "integer", "description": "PDF font size." }, "company[company_setting_attributes][custom_field_to_include_in_po_number_id]": { "type": "integer", "description": "Custom field whose value is appended to PO numbers." }, "company[company_setting_attributes][approvals_require_login]": { "type": "boolean", "description": "Approvers must log in to approve." }, "company[company_setting_attributes][show_po_item_number]": { "type": "boolean", "description": "Show item numbers on PO lines." }, "company[company_setting_attributes][fixed_supplier_list]": { "type": "boolean", "description": "Requesters must pick an existing supplier." }, "company[company_setting_attributes][display_remaining_budget_amount]": { "type": "boolean", "description": "Show remaining budget amounts." }, "company[company_setting_attributes][display_budget_on_pdf]": { "type": "boolean", "description": "Print the budget on PO PDFs." }, "company[company_setting_attributes][pdf_background]": { "type": "string", "description": "PDF background." }, "company[company_setting_attributes][pdf_footer]": { "type": "string", "description": "PDF footer text." }, "company[company_setting_attributes][logo]": { "type": "string", "description": "Logo." }, "company[company_setting_attributes][logo_alignment]": { "type": "string", "description": "Logo alignment on PDFs." }, "company[company_setting_attributes][logo_content_type]": { "type": "string", "description": "Logo MIME type." }, "company[company_setting_attributes][fixed_product_list]": { "type": "boolean", "description": "PO lines must use catalogue products." }, "company[company_setting_attributes][show_tax_column]": { "type": "boolean", "description": "Show the tax column." }, "company[company_setting_attributes][show_company_name]": { "type": "boolean", "description": "Show the company name on PDFs." }, "company[company_setting_attributes][show_approver_name]": { "type": "boolean", "description": "Show the approver name on PDFs." }, "company[company_setting_attributes][user_can_add_supplier]": { "type": "boolean", "description": "Non-admin users may add suppliers." }, "company[company_setting_attributes][manually_approve_by_lowest_available_approvers]": { "type": "boolean", "description": "Restrict manual approver choice to the lowest sufficient approvers." }, "company[company_setting_attributes][share_po_access_by_department]": { "type": "boolean", "description": "Users see POs of their departments." }, "company[company_setting_attributes][allow_budget_overruns]": { "type": "boolean", "description": "Ignored on create - always set to false." }, "company[company_setting_attributes][auto_expire_session]": { "type": "boolean", "description": "Expire idle web sessions." }, "company[company_setting_attributes][allocations_enabled]": { "type": "boolean", "description": "Enable budget allocations." }, "company[company_setting_attributes][link_budgets_to_qbo_class]": { "type": "boolean", "description": "Link budgets to QuickBooks classes." }, "company[company_setting_attributes][po_fields][]": { "type": "array", "items": { "type": "string" }, "description": "PO list/export fields." }, "company[company_setting_attributes][mandatory_supplier_fields][]": { "type": "array", "items": { "type": "string" }, "description": "Supplier fields that must be filled in." }, "company[company_setting_attributes][id]": { "type": "integer", "description": "Permitted but meaningless on create; do not send." }, "company[company_currency_exchange_rates][]": { "type": "array", "items": { "type": "string" }, "description": "Permitted by the controller but not a Company attribute - sending it answers 500. Do not send." } }, "required": [ "company[name]", "company[company_setting_attributes][currency_id]" ] }, "example": { "company": { "name": "Globex Subsidiary", "department": "Finance", "gross_or_net_config": "net", "default_tax_rate": 0, "company_setting_attributes": { "currency_id": 2000, "date_format": "%Y-%m-%d", "tax_label": "VAT" }, "supported_currency_ids": [ 2000, 1000 ] } } } } } } }, "/api/v1/companies": { "get": { "tags": [ "Companies" ], "operationId": "v1_companies_list", "summary": "List companies", "description": "Lists every company the caller is a member of, with the caller's roles and approval limit in each.\n\nReturns all companies the authenticated user has a membership in,\nincluding companies where that membership is archived\n(`membership_archived: true`) and companies that are locked or removed\n(`is_locked`, `is_removed`). Use it after authenticating to choose the\n`app_company_id` to send on every other request.\n\nThe `app_company_id` header is **optional** here (the request succeeds\nwithout it). Results are not paginated and not filterable; order is\ncompany creation order.\n\n**V3 only - sparse fieldsets.** Pass `fields` with a comma-separated list\nof company attributes to receive only those (plus `id`, always included).\nThis also skips the per-company work behind the omitted attributes, so it\nis noticeably faster for users with many companies. Whitespace around\nnames is ignored; an unknown name answers `400`. Use the comma form -\nthe array form `fields[]=name` is rejected as unknown.\n\n\n* V3 accepts `fields` (sparse fieldsets) and answers `400`\n `Unknown fields: . Allowed fields are: ...` for unknown names.\n V1 ignores `fields` and always returns every attribute.\n* Otherwise identical request and response.", "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "V3 only. Comma-separated attribute names to return, e.g. `name,roles,in_trial`. Allowed: `id`, `name`, `external_user_id`, `membership_archived`, `is_locked`, `is_removed`, `approval_limit`, `in_trial`, `trial_expired`, `remaining_trial_days`, `roles`, `has_unassigned_budgets`. Ignored by V1.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "external_user_id": { "type": "null" }, "membership_archived": { "type": "boolean" }, "is_locked": { "type": "boolean" }, "is_removed": { "type": "boolean" }, "approval_limit": { "type": "number" }, "in_trial": { "type": "boolean" }, "trial_expired": { "type": "boolean" }, "remaining_trial_days": { "type": "integer" }, "roles": { "type": "array", "items": { "type": "string" } }, "has_unassigned_budgets": { "type": "boolean" } } } }, "example": [ { "id": 20000, "name": "Acme Corporation", "external_user_id": null, "membership_archived": false, "is_locked": false, "is_removed": false, "approval_limit": 1000000.0, "in_trial": true, "trial_expired": false, "remaining_trial_days": 365, "roles": [ "companyadmin", "approver", "finance", "teammember" ], "has_unassigned_budgets": true }, { "id": 9, "name": "Globex Subsidiary", "external_user_id": null, "membership_archived": false, "is_locked": false, "is_removed": false, "approval_limit": 1000000.0, "in_trial": true, "trial_expired": false, "remaining_trial_days": 365, "roles": [ "companyadmin", "approver", "finance", "teammember" ], "has_unassigned_budgets": false } ] } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "post": { "tags": [ "Companies" ], "operationId": "v1_companies_create", "summary": "Create a company", "description": "Creates a new company owned by the caller, on a free trial, with the caller as its administrator.\n\nCreates a company and makes the caller its creator and first member with\nthe roles `companyadmin`, `approver`, `finance` and `teammember`. The\n`app_company_id` header is not required.\n\nWhat is created with the company:\n\n* company settings from `company_setting_attributes` - a currency is\n mandatory. Some settings are always forced on create:\n `allow_budget_overruns` = false (the request value is ignored),\n approval required after PO edit, invoice upload off, supplier rating on,\n PDF attachment in supplier emails on, auto-approval of own requests off;\n* a budget named **Sample Budget** (10,000,000 in the company currency),\n in addition to any `budgets_attributes` you send;\n* a trial subscription on the trial plan (5 seats);\n* tax rates `None` and `Tax exempt` (`None` becomes the default when\n `default_tax_rate` is 0), default payment terms and default reports;\n* the default currency is added to `supported_currency_ids` automatically.\n\n**Department.** When the caller originally signed up through the website\n(the usual case), `company[department]` is mandatory: a department with\nthat name is created, linked to the Sample Budget, the caller is made the\nSample Budget's approver and is assigned to the department. For users\ncreated another way (mobile app, integrations) `company[department]` is\nignored and no department is created.\n\n**Side effects.** A Slack notification to the sales team is queued. The\ncaller's primary company (`employer_id`, used e.g. by `GET /currentuser`)\nis switched to the new company. If the caller's profile country requires\npayment before a trial, the company is created locked (`is_locked: true`)\nand every request in it answers 402 until a subscription is bought.\n\nThe optional `app_source` request header records where the company came\nfrom (`api` by default; one of `website`, `mobile_ios`,\n`mobile_android`, `mobile_other`, `mobile_android_offline`,\n`mobile_ios_offline`, `push_cart`, `zapier`, `api`, `sage50`, `sage200`,\n`po_generator`, `xero_marketplace`, `sage200_api`).\n\nThe call is not idempotent: repeating it creates another company with\nthe same name.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "external_user_id": { "type": "null" }, "membership_archived": { "type": "null" }, "is_locked": { "type": "boolean" }, "is_removed": { "type": "boolean" }, "approval_limit": { "type": "null" }, "in_trial": { "type": "boolean" }, "trial_expired": { "type": "boolean" }, "remaining_trial_days": { "type": "integer" }, "roles": { "type": "null" }, "has_unassigned_budgets": { "type": "boolean" } } }, "example": { "id": 9, "name": "Globex Subsidiary", "external_user_id": null, "membership_archived": null, "is_locked": false, "is_removed": false, "approval_limit": null, "in_trial": true, "trial_expired": false, "remaining_trial_days": 365, "roles": null, "has_unassigned_budgets": false } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Department can't be blank" ], "status": 400 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "company[name]": { "type": "string", "description": "Company name, max 80 characters." }, "company[department]": { "type": "string", "description": "Name of the first department. **Required** when the caller signed up on the website (`Department can't be blank` otherwise); ignored for other users." }, "company[company_setting_attributes][currency_id]": { "type": "integer", "description": "Default currency id. Without it: `Company setting currency can't be blank` and `Budgets currency can't be blank`." }, "company[gross_or_net_config]": { "type": "string", "description": "`gross` or `net` (or `0` / `1`). Defaults to `gross`. Any other value answers 500." }, "company[default_tax_rate]": { "type": "number", "description": "Legacy default tax rate percent, greater than -1 and less than 101. Defaults to 0." }, "company[supported_currency_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Currency ids to enable. The default currency is added automatically." }, "company[budgets_attributes][][name]": { "type": "string", "description": "Additional budget to create (the Sample Budget is always created too)." }, "company[budgets_attributes][][amount]": { "type": "number", "description": "Additional budget amount." }, "company[budgets_attributes][][creator_id]": { "type": "integer", "description": "Ignored - the caller is always the creator." }, "company[budgets_attributes][][currency_id]": { "type": "integer", "description": "Ignored - the company currency is used. Sending any budget also forces `tax_label` to `Tax`." }, "company[company_setting_attributes][date_format]": { "type": "string", "description": "strftime pattern, e.g. `%Y-%m-%d`." }, "company[company_setting_attributes][tax_label]": { "type": "string", "description": "Tax label, e.g. `VAT` (overridden to `Tax` when `budgets_attributes` are sent)." }, "company[company_setting_attributes][departments_alias]": { "type": "string", "description": "Custom label for departments." }, "company[company_setting_attributes][budgets_alias]": { "type": "string", "description": "Custom label for budgets." }, "company[company_setting_attributes][pdf_font_size]": { "type": "integer", "description": "PDF font size." }, "company[company_setting_attributes][custom_field_to_include_in_po_number_id]": { "type": "integer", "description": "Custom field whose value is appended to PO numbers." }, "company[company_setting_attributes][approvals_require_login]": { "type": "boolean", "description": "Approvers must log in to approve." }, "company[company_setting_attributes][show_po_item_number]": { "type": "boolean", "description": "Show item numbers on PO lines." }, "company[company_setting_attributes][fixed_supplier_list]": { "type": "boolean", "description": "Requesters must pick an existing supplier." }, "company[company_setting_attributes][display_remaining_budget_amount]": { "type": "boolean", "description": "Show remaining budget amounts." }, "company[company_setting_attributes][display_budget_on_pdf]": { "type": "boolean", "description": "Print the budget on PO PDFs." }, "company[company_setting_attributes][pdf_background]": { "type": "string", "description": "PDF background." }, "company[company_setting_attributes][pdf_footer]": { "type": "string", "description": "PDF footer text." }, "company[company_setting_attributes][logo]": { "type": "string", "description": "Logo." }, "company[company_setting_attributes][logo_alignment]": { "type": "string", "description": "Logo alignment on PDFs." }, "company[company_setting_attributes][logo_content_type]": { "type": "string", "description": "Logo MIME type." }, "company[company_setting_attributes][fixed_product_list]": { "type": "boolean", "description": "PO lines must use catalogue products." }, "company[company_setting_attributes][show_tax_column]": { "type": "boolean", "description": "Show the tax column." }, "company[company_setting_attributes][show_company_name]": { "type": "boolean", "description": "Show the company name on PDFs." }, "company[company_setting_attributes][show_approver_name]": { "type": "boolean", "description": "Show the approver name on PDFs." }, "company[company_setting_attributes][user_can_add_supplier]": { "type": "boolean", "description": "Non-admin users may add suppliers." }, "company[company_setting_attributes][manually_approve_by_lowest_available_approvers]": { "type": "boolean", "description": "Restrict manual approver choice to the lowest sufficient approvers." }, "company[company_setting_attributes][share_po_access_by_department]": { "type": "boolean", "description": "Users see POs of their departments." }, "company[company_setting_attributes][allow_budget_overruns]": { "type": "boolean", "description": "Ignored on create - always set to false." }, "company[company_setting_attributes][auto_expire_session]": { "type": "boolean", "description": "Expire idle web sessions." }, "company[company_setting_attributes][allocations_enabled]": { "type": "boolean", "description": "Enable budget allocations." }, "company[company_setting_attributes][link_budgets_to_qbo_class]": { "type": "boolean", "description": "Link budgets to QuickBooks classes." }, "company[company_setting_attributes][po_fields][]": { "type": "array", "items": { "type": "string" }, "description": "PO list/export fields." }, "company[company_setting_attributes][mandatory_supplier_fields][]": { "type": "array", "items": { "type": "string" }, "description": "Supplier fields that must be filled in." }, "company[company_setting_attributes][id]": { "type": "integer", "description": "Permitted but meaningless on create; do not send." }, "company[company_currency_exchange_rates][]": { "type": "array", "items": { "type": "string" }, "description": "Permitted by the controller but not a Company attribute - sending it answers 500. Do not send." } }, "required": [ "company[name]", "company[company_setting_attributes][currency_id]" ] }, "example": { "company": { "name": "Globex Subsidiary", "department": "Finance", "gross_or_net_config": "net", "default_tax_rate": 0, "company_setting_attributes": { "currency_id": 2000, "date_format": "%Y-%m-%d", "tax_label": "VAT" }, "supported_currency_ids": [ 2000, 1000 ] } } } } } } }, "/api/v3/companies/details": { "get": { "tags": [ "Companies" ], "operationId": "v3_companies_details", "summary": "Get the current company", "description": "Returns the full configuration of the company named in the `app_company_id` header.\n\nReturns the company selected by `app_company_id` with its settings, the\ncustom fields the caller may see, its supported currencies and a set of\nfeature switches. This is the call an integration makes to learn how the\ncompany is configured (gross or net amounts, mandatory QuickBooks\nfields, enabled modules, which custom fields to send on a purchase\norder) before creating documents.\n\nThe body is the same as [Get a company](#get-a-company) for the header\ncompany.\n\n**How to find active/required QuickBooks class and customer fields**\n\n* `company_setting.qbo_customer_required` - the QuickBooks customer field\n is mandatory on purchase orders and invoices.\n* `company_setting.qbo_customer_active` - the customer field is shown on\n the forms. Show it anyway when `qbo_customer_required` is `true`.\n* `company_setting.qbo_class_required` - the QuickBooks class field is\n mandatory.\n* `company_setting.qbo_class_active` - the class field is shown on the\n forms. Show it anyway when `qbo_class_required` is `true`.\n\n**Custom fields** are filtered by the caller's role in the company:\n`companyadmin` and `finance` see every field; `approver` sees fields with\n`access_level` `approvers_and_finance` or `everyone`; other members see\nonly `everyone` fields. Budget custom fields (`on_budget`) and RFQ\ncustom fields (`on_rfq`) are never included.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "employees_count": { "type": "integer" }, "default_tax_rate": { "type": "number" }, "prepaid_subscription": { "type": "boolean" }, "multicompany_pack": { "type": "boolean" }, "payment_term_ff_enabled": { "type": "null" }, "scan_and_match_ff_enabled": { "type": "null" }, "approval_flow_ff_enabled": { "type": "boolean" }, "policy_ff_enabled": { "type": "boolean" }, "sam_gov_enabled": { "type": "boolean" }, "company_setting": { "type": "object", "properties": { "id": { "type": "integer" }, "show_po_item_number": { "type": "boolean" }, "gross_or_net": { "type": "string" }, "company_id": { "type": "integer" }, "fixed_supplier_list": { "type": "boolean" }, "currency_id": { "type": "integer" }, "javascript": { "type": "null" }, "departments_alias": { "type": "null" }, "display_remaining_budget_amount": { "type": "boolean" }, "date_format": { "type": "string" }, "tax_label": { "type": "string" }, "approvals_require_login": { "type": "boolean" }, "fixed_product_list": { "type": "boolean" }, "fixed_product_price": { "type": "boolean" }, "show_tax_column": { "type": "boolean" }, "show_company_name": { "type": "boolean" }, "allow_budget_overruns": { "type": "boolean" }, "budgets_alias": { "type": "null" }, "enable_detailed_allocations_for_purchase_order_line_items": { "type": "boolean" }, "allocations_enabled": { "type": "boolean" }, "report_name": { "type": "null" }, "user_can_add_supplier": { "type": "boolean" }, "user_can_add_product": { "type": "boolean" }, "po_fields": { "type": "array", "items": { } }, "reserve_po_number": { "type": "boolean" }, "default_template_id": { "type": "null" }, "default_tax_rate_id": { "type": "null" }, "can_invite_user": { "type": "boolean" }, "show_remaining_budget_to_teammember": { "type": "boolean" }, "allow_open_draft_access": { "type": "boolean" }, "link_budgets_to_qbo_accounts": { "type": "boolean" }, "link_budgets_to_qbo_class": { "type": "boolean" }, "enable_offline_mode": { "type": "boolean" }, "is_quickbooks_connected": { "type": "null" }, "is_sage_connected": { "type": "boolean" }, "show_currency_symbol": { "type": "boolean" }, "enable_approval_override": { "type": "boolean" }, "can_upload_invoice": { "type": "boolean" }, "invoice_reference_mandatory": { "type": "boolean" }, "manually_approve_by_lowest_available_approvers": { "type": "boolean" }, "default_payment_term_id": { "type": "integer" }, "qbo_customer_required": { "type": "boolean" }, "qbo_customer_active": { "type": "boolean" }, "qbo_auto_select_new_customer": { "type": "boolean" }, "qbo_class_required": { "type": "boolean" }, "qbo_class_active": { "type": "boolean" }, "qbo_class_alias": { "type": "string" }, "qbo_customer_alias": { "type": "string" }, "qbo_description_required": { "type": "boolean" }, "show_qbo_chart_of_account_number": { "type": "boolean" }, "is_xero_connected": { "type": "null" }, "allow_members_to_see_budgets": { "type": "boolean" } } }, "supported_currencies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "iso_code": { "type": "string" }, "iso_numeric": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "field_type": { "type": "string" }, "active": { "type": "boolean" }, "required": { "type": "boolean" }, "options": { "type": "array", "items": { } }, "access_level": { "type": "string" }, "position": { "type": "integer" }, "on_line_item": { "type": "boolean" }, "on_budget": { "type": "boolean" }, "on_invoice_item": { "type": "boolean" }, "on_invoice": { "type": "boolean" }, "on_supplier": { "type": "boolean" }, "on_rfq": { "type": "boolean" }, "on_product": { "type": "boolean" }, "display_on_pdf": { "type": "boolean" }, "default_value": { "type": "null" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "editable_after_approval": { "type": "null" }, "readonly": { "type": "boolean" }, "webhook_enabled": { "type": "boolean" }, "response_populated": { "type": "boolean" }, "payload_included": { "type": "boolean" }, "is_auto_populated": { "type": "boolean" }, "show_on_receiving": { "type": "boolean" } } } } } }, "example": { "id": 20000, "name": "Acme Corporation", "employees_count": 5, "default_tax_rate": 0.0, "prepaid_subscription": false, "multicompany_pack": false, "payment_term_ff_enabled": null, "scan_and_match_ff_enabled": null, "approval_flow_ff_enabled": true, "policy_ff_enabled": true, "sam_gov_enabled": false, "company_setting": { "id": 2, "show_po_item_number": false, "gross_or_net": "net", "company_id": 20000, "fixed_supplier_list": false, "currency_id": 2000, "javascript": null, "departments_alias": null, "display_remaining_budget_amount": true, "date_format": "%m/%d/%Y", "tax_label": "Tax", "approvals_require_login": false, "fixed_product_list": false, "fixed_product_price": false, "show_tax_column": true, "show_company_name": true, "allow_budget_overruns": true, "budgets_alias": null, "enable_detailed_allocations_for_purchase_order_line_items": false, "allocations_enabled": false, "report_name": null, "user_can_add_supplier": true, "user_can_add_product": false, "po_fields": [ ], "reserve_po_number": false, "default_template_id": null, "default_tax_rate_id": null, "can_invite_user": true, "show_remaining_budget_to_teammember": false, "allow_open_draft_access": false, "link_budgets_to_qbo_accounts": false, "link_budgets_to_qbo_class": false, "enable_offline_mode": true, "is_quickbooks_connected": null, "is_sage_connected": false, "show_currency_symbol": true, "enable_approval_override": true, "can_upload_invoice": true, "invoice_reference_mandatory": false, "manually_approve_by_lowest_available_approvers": false, "default_payment_term_id": 1, "qbo_customer_required": false, "qbo_customer_active": false, "qbo_auto_select_new_customer": true, "qbo_class_required": false, "qbo_class_active": false, "qbo_class_alias": "", "qbo_customer_alias": "", "qbo_description_required": false, "show_qbo_chart_of_account_number": false, "is_xero_connected": null, "allow_members_to_see_budgets": false }, "supported_currencies": [ { "id": 1000, "iso_code": "EUR", "iso_numeric": "978", "name": "Euro", "symbol": "€", "created_at": "2026-10-21T04:44:44.790-05:00", "updated_at": "2026-10-21T04:44:44.790-05:00" }, { "id": 3000, "iso_code": "GBP", "iso_numeric": "826", "name": "British Pound", "symbol": "£", "created_at": "2026-10-21T04:44:44.794-05:00", "updated_at": "2026-10-21T04:44:44.794-05:00" } ], "custom_fields": [ { "id": 1, "company_id": 20000, "name": "Project code", "field_type": "string", "active": true, "required": false, "options": [ ], "access_level": "everyone", "position": 0, "on_line_item": false, "on_budget": false, "on_invoice_item": false, "on_invoice": false, "on_supplier": false, "on_rfq": false, "on_product": false, "display_on_pdf": true, "default_value": null, "created_at": "2026-10-21T04:48:43.644-05:00", "updated_at": "2026-10-21T04:48:43.644-05:00", "editable_after_approval": null, "readonly": false, "webhook_enabled": false, "response_populated": false, "payload_included": false, "is_auto_populated": false, "show_on_receiving": false }, { "id": 2, "company_id": 20000, "name": "Cost center", "field_type": "select", "active": true, "required": false, "options": [ "CC-100 Engineering", "CC-200 Marketing", "CC-300 Operations" ], "access_level": "everyone", "position": 1, "on_line_item": false, "on_budget": false, "on_invoice_item": false, "on_invoice": false, "on_supplier": false, "on_rfq": false, "on_product": false, "display_on_pdf": true, "default_value": null, "created_at": "2026-10-21T04:49:01.957-05:00", "updated_at": "2026-10-21T04:49:01.957-05:00", "editable_after_approval": null, "readonly": false, "webhook_enabled": false, "response_populated": false, "payload_included": false, "is_auto_populated": false, "show_on_receiving": false } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "App company id is nil", "status": 401 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/companies/details": { "get": { "tags": [ "Companies" ], "operationId": "v1_companies_details", "summary": "Get the current company", "description": "Returns the full configuration of the company named in the `app_company_id` header.\n\nReturns the company selected by `app_company_id` with its settings, the\ncustom fields the caller may see, its supported currencies and a set of\nfeature switches. This is the call an integration makes to learn how the\ncompany is configured (gross or net amounts, mandatory QuickBooks\nfields, enabled modules, which custom fields to send on a purchase\norder) before creating documents.\n\nThe body is the same as [Get a company](#get-a-company) for the header\ncompany.\n\n**How to find active/required QuickBooks class and customer fields**\n\n* `company_setting.qbo_customer_required` - the QuickBooks customer field\n is mandatory on purchase orders and invoices.\n* `company_setting.qbo_customer_active` - the customer field is shown on\n the forms. Show it anyway when `qbo_customer_required` is `true`.\n* `company_setting.qbo_class_required` - the QuickBooks class field is\n mandatory.\n* `company_setting.qbo_class_active` - the class field is shown on the\n forms. Show it anyway when `qbo_class_required` is `true`.\n\n**Custom fields** are filtered by the caller's role in the company:\n`companyadmin` and `finance` see every field; `approver` sees fields with\n`access_level` `approvers_and_finance` or `everyone`; other members see\nonly `everyone` fields. Budget custom fields (`on_budget`) and RFQ\ncustom fields (`on_rfq`) are never included.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "employees_count": { "type": "integer" }, "default_tax_rate": { "type": "number" }, "prepaid_subscription": { "type": "boolean" }, "multicompany_pack": { "type": "boolean" }, "payment_term_ff_enabled": { "type": "null" }, "scan_and_match_ff_enabled": { "type": "null" }, "approval_flow_ff_enabled": { "type": "boolean" }, "policy_ff_enabled": { "type": "boolean" }, "sam_gov_enabled": { "type": "boolean" }, "company_setting": { "type": "object", "properties": { "id": { "type": "integer" }, "show_po_item_number": { "type": "boolean" }, "gross_or_net": { "type": "string" }, "company_id": { "type": "integer" }, "fixed_supplier_list": { "type": "boolean" }, "currency_id": { "type": "integer" }, "javascript": { "type": "null" }, "departments_alias": { "type": "null" }, "display_remaining_budget_amount": { "type": "boolean" }, "date_format": { "type": "string" }, "tax_label": { "type": "string" }, "approvals_require_login": { "type": "boolean" }, "fixed_product_list": { "type": "boolean" }, "fixed_product_price": { "type": "boolean" }, "show_tax_column": { "type": "boolean" }, "show_company_name": { "type": "boolean" }, "allow_budget_overruns": { "type": "boolean" }, "budgets_alias": { "type": "null" }, "enable_detailed_allocations_for_purchase_order_line_items": { "type": "boolean" }, "allocations_enabled": { "type": "boolean" }, "report_name": { "type": "null" }, "user_can_add_supplier": { "type": "boolean" }, "user_can_add_product": { "type": "boolean" }, "po_fields": { "type": "array", "items": { } }, "reserve_po_number": { "type": "boolean" }, "default_template_id": { "type": "null" }, "default_tax_rate_id": { "type": "null" }, "can_invite_user": { "type": "boolean" }, "show_remaining_budget_to_teammember": { "type": "boolean" }, "allow_open_draft_access": { "type": "boolean" }, "link_budgets_to_qbo_accounts": { "type": "boolean" }, "link_budgets_to_qbo_class": { "type": "boolean" }, "enable_offline_mode": { "type": "boolean" }, "is_quickbooks_connected": { "type": "null" }, "is_sage_connected": { "type": "boolean" }, "show_currency_symbol": { "type": "boolean" }, "enable_approval_override": { "type": "boolean" }, "can_upload_invoice": { "type": "boolean" }, "invoice_reference_mandatory": { "type": "boolean" }, "manually_approve_by_lowest_available_approvers": { "type": "boolean" }, "default_payment_term_id": { "type": "integer" }, "qbo_customer_required": { "type": "boolean" }, "qbo_customer_active": { "type": "boolean" }, "qbo_auto_select_new_customer": { "type": "boolean" }, "qbo_class_required": { "type": "boolean" }, "qbo_class_active": { "type": "boolean" }, "qbo_class_alias": { "type": "string" }, "qbo_customer_alias": { "type": "string" }, "qbo_description_required": { "type": "boolean" }, "show_qbo_chart_of_account_number": { "type": "boolean" }, "is_xero_connected": { "type": "null" }, "allow_members_to_see_budgets": { "type": "boolean" } } }, "supported_currencies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "iso_code": { "type": "string" }, "iso_numeric": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "field_type": { "type": "string" }, "active": { "type": "boolean" }, "required": { "type": "boolean" }, "options": { "type": "array", "items": { } }, "access_level": { "type": "string" }, "position": { "type": "integer" }, "on_line_item": { "type": "boolean" }, "on_budget": { "type": "boolean" }, "on_invoice_item": { "type": "boolean" }, "on_invoice": { "type": "boolean" }, "on_supplier": { "type": "boolean" }, "on_rfq": { "type": "boolean" }, "on_product": { "type": "boolean" }, "display_on_pdf": { "type": "boolean" }, "default_value": { "type": "null" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "editable_after_approval": { "type": "null" }, "readonly": { "type": "boolean" }, "webhook_enabled": { "type": "boolean" }, "response_populated": { "type": "boolean" }, "payload_included": { "type": "boolean" }, "is_auto_populated": { "type": "boolean" }, "show_on_receiving": { "type": "boolean" } } } } } }, "example": { "id": 20000, "name": "Acme Corporation", "employees_count": 5, "default_tax_rate": 0.0, "prepaid_subscription": false, "multicompany_pack": false, "payment_term_ff_enabled": null, "scan_and_match_ff_enabled": null, "approval_flow_ff_enabled": true, "policy_ff_enabled": true, "sam_gov_enabled": false, "company_setting": { "id": 2, "show_po_item_number": false, "gross_or_net": "net", "company_id": 20000, "fixed_supplier_list": false, "currency_id": 2000, "javascript": null, "departments_alias": null, "display_remaining_budget_amount": true, "date_format": "%m/%d/%Y", "tax_label": "Tax", "approvals_require_login": false, "fixed_product_list": false, "fixed_product_price": false, "show_tax_column": true, "show_company_name": true, "allow_budget_overruns": true, "budgets_alias": null, "enable_detailed_allocations_for_purchase_order_line_items": false, "allocations_enabled": false, "report_name": null, "user_can_add_supplier": true, "user_can_add_product": false, "po_fields": [ ], "reserve_po_number": false, "default_template_id": null, "default_tax_rate_id": null, "can_invite_user": true, "show_remaining_budget_to_teammember": false, "allow_open_draft_access": false, "link_budgets_to_qbo_accounts": false, "link_budgets_to_qbo_class": false, "enable_offline_mode": true, "is_quickbooks_connected": null, "is_sage_connected": false, "show_currency_symbol": true, "enable_approval_override": true, "can_upload_invoice": true, "invoice_reference_mandatory": false, "manually_approve_by_lowest_available_approvers": false, "default_payment_term_id": 1, "qbo_customer_required": false, "qbo_customer_active": false, "qbo_auto_select_new_customer": true, "qbo_class_required": false, "qbo_class_active": false, "qbo_class_alias": "", "qbo_customer_alias": "", "qbo_description_required": false, "show_qbo_chart_of_account_number": false, "is_xero_connected": null, "allow_members_to_see_budgets": false }, "supported_currencies": [ { "id": 1000, "iso_code": "EUR", "iso_numeric": "978", "name": "Euro", "symbol": "€", "created_at": "2026-10-21T04:44:44.790-05:00", "updated_at": "2026-10-21T04:44:44.790-05:00" }, { "id": 3000, "iso_code": "GBP", "iso_numeric": "826", "name": "British Pound", "symbol": "£", "created_at": "2026-10-21T04:44:44.794-05:00", "updated_at": "2026-10-21T04:44:44.794-05:00" } ], "custom_fields": [ { "id": 1, "company_id": 20000, "name": "Project code", "field_type": "string", "active": true, "required": false, "options": [ ], "access_level": "everyone", "position": 0, "on_line_item": false, "on_budget": false, "on_invoice_item": false, "on_invoice": false, "on_supplier": false, "on_rfq": false, "on_product": false, "display_on_pdf": true, "default_value": null, "created_at": "2026-10-21T04:48:43.644-05:00", "updated_at": "2026-10-21T04:48:43.644-05:00", "editable_after_approval": null, "readonly": false, "webhook_enabled": false, "response_populated": false, "payload_included": false, "is_auto_populated": false, "show_on_receiving": false }, { "id": 2, "company_id": 20000, "name": "Cost center", "field_type": "select", "active": true, "required": false, "options": [ "CC-100 Engineering", "CC-200 Marketing", "CC-300 Operations" ], "access_level": "everyone", "position": 1, "on_line_item": false, "on_budget": false, "on_invoice_item": false, "on_invoice": false, "on_supplier": false, "on_rfq": false, "on_product": false, "display_on_pdf": true, "default_value": null, "created_at": "2026-10-21T04:49:01.957-05:00", "updated_at": "2026-10-21T04:49:01.957-05:00", "editable_after_approval": null, "readonly": false, "webhook_enabled": false, "response_populated": false, "payload_included": false, "is_auto_populated": false, "show_on_receiving": false } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "App company id is nil", "status": 401 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/companies/{id}": { "get": { "tags": [ "Companies" ], "operationId": "v3_companies_show", "summary": "Get a company", "description": "Returns the full configuration of one of the caller's companies by id.\n\nSame body as [Get the current company](#get-the-current-company), for\nany company in which the caller has an **active** (non-archived)\nmembership and which is not deactivated - it need not be the\n`app_company_id` company. A valid `app_company_id` header is still\nrequired.\n\nRole-dependent parts (custom field visibility) are evaluated in the\nrequested company.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Company id (from [List companies](#list-companies)).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "employees_count": { "type": "integer" }, "default_tax_rate": { "type": "number" }, "prepaid_subscription": { "type": "boolean" }, "multicompany_pack": { "type": "boolean" }, "payment_term_ff_enabled": { "type": "null" }, "scan_and_match_ff_enabled": { "type": "null" }, "approval_flow_ff_enabled": { "type": "boolean" }, "policy_ff_enabled": { "type": "boolean" }, "sam_gov_enabled": { "type": "boolean" }, "company_setting": { "type": "object", "properties": { "id": { "type": "integer" }, "show_po_item_number": { "type": "boolean" }, "gross_or_net": { "type": "string" }, "company_id": { "type": "integer" }, "fixed_supplier_list": { "type": "boolean" }, "currency_id": { "type": "integer" }, "javascript": { "type": "null" }, "departments_alias": { "type": "null" }, "display_remaining_budget_amount": { "type": "boolean" }, "date_format": { "type": "string" }, "tax_label": { "type": "string" }, "approvals_require_login": { "type": "boolean" }, "fixed_product_list": { "type": "boolean" }, "fixed_product_price": { "type": "boolean" }, "show_tax_column": { "type": "boolean" }, "show_company_name": { "type": "boolean" }, "allow_budget_overruns": { "type": "boolean" }, "budgets_alias": { "type": "null" }, "enable_detailed_allocations_for_purchase_order_line_items": { "type": "boolean" }, "allocations_enabled": { "type": "boolean" }, "report_name": { "type": "null" }, "user_can_add_supplier": { "type": "boolean" }, "user_can_add_product": { "type": "boolean" }, "po_fields": { "type": "array", "items": { } }, "reserve_po_number": { "type": "boolean" }, "default_template_id": { "type": "null" }, "default_tax_rate_id": { "type": "null" }, "can_invite_user": { "type": "boolean" }, "show_remaining_budget_to_teammember": { "type": "boolean" }, "allow_open_draft_access": { "type": "boolean" }, "link_budgets_to_qbo_accounts": { "type": "boolean" }, "link_budgets_to_qbo_class": { "type": "boolean" }, "enable_offline_mode": { "type": "boolean" }, "is_quickbooks_connected": { "type": "null" }, "is_sage_connected": { "type": "boolean" }, "show_currency_symbol": { "type": "boolean" }, "enable_approval_override": { "type": "boolean" }, "can_upload_invoice": { "type": "boolean" }, "invoice_reference_mandatory": { "type": "boolean" }, "manually_approve_by_lowest_available_approvers": { "type": "boolean" }, "default_payment_term_id": { "type": "integer" }, "qbo_customer_required": { "type": "boolean" }, "qbo_customer_active": { "type": "boolean" }, "qbo_auto_select_new_customer": { "type": "boolean" }, "qbo_class_required": { "type": "boolean" }, "qbo_class_active": { "type": "boolean" }, "qbo_class_alias": { "type": "string" }, "qbo_customer_alias": { "type": "string" }, "qbo_description_required": { "type": "boolean" }, "show_qbo_chart_of_account_number": { "type": "boolean" }, "is_xero_connected": { "type": "null" }, "allow_members_to_see_budgets": { "type": "boolean" } } }, "supported_currencies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "iso_code": { "type": "string" }, "iso_numeric": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "field_type": { "type": "string" }, "active": { "type": "boolean" }, "required": { "type": "boolean" }, "options": { "type": "array", "items": { } }, "access_level": { "type": "string" }, "position": { "type": "integer" }, "on_line_item": { "type": "boolean" }, "on_budget": { "type": "boolean" }, "on_invoice_item": { "type": "boolean" }, "on_invoice": { "type": "boolean" }, "on_supplier": { "type": "boolean" }, "on_rfq": { "type": "boolean" }, "on_product": { "type": "boolean" }, "display_on_pdf": { "type": "boolean" }, "default_value": { "type": "null" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "editable_after_approval": { "type": "null" }, "readonly": { "type": "boolean" }, "webhook_enabled": { "type": "boolean" }, "response_populated": { "type": "boolean" }, "payload_included": { "type": "boolean" }, "is_auto_populated": { "type": "boolean" }, "show_on_receiving": { "type": "boolean" } } } } } }, "example": { "id": 20000, "name": "Acme Corporation", "employees_count": 5, "default_tax_rate": 0.0, "prepaid_subscription": false, "multicompany_pack": false, "payment_term_ff_enabled": null, "scan_and_match_ff_enabled": null, "approval_flow_ff_enabled": true, "policy_ff_enabled": true, "sam_gov_enabled": false, "company_setting": { "id": 2, "show_po_item_number": false, "gross_or_net": "net", "company_id": 20000, "fixed_supplier_list": false, "currency_id": 2000, "javascript": null, "departments_alias": null, "display_remaining_budget_amount": true, "date_format": "%m/%d/%Y", "tax_label": "Tax", "approvals_require_login": false, "fixed_product_list": false, "fixed_product_price": false, "show_tax_column": true, "show_company_name": true, "allow_budget_overruns": true, "budgets_alias": null, "enable_detailed_allocations_for_purchase_order_line_items": false, "allocations_enabled": false, "report_name": null, "user_can_add_supplier": true, "user_can_add_product": false, "po_fields": [ ], "reserve_po_number": false, "default_template_id": null, "default_tax_rate_id": null, "can_invite_user": true, "show_remaining_budget_to_teammember": false, "allow_open_draft_access": false, "link_budgets_to_qbo_accounts": false, "link_budgets_to_qbo_class": false, "enable_offline_mode": true, "is_quickbooks_connected": null, "is_sage_connected": false, "show_currency_symbol": true, "enable_approval_override": true, "can_upload_invoice": true, "invoice_reference_mandatory": false, "manually_approve_by_lowest_available_approvers": false, "default_payment_term_id": 1, "qbo_customer_required": false, "qbo_customer_active": false, "qbo_auto_select_new_customer": true, "qbo_class_required": false, "qbo_class_active": false, "qbo_class_alias": "", "qbo_customer_alias": "", "qbo_description_required": false, "show_qbo_chart_of_account_number": false, "is_xero_connected": null, "allow_members_to_see_budgets": false }, "supported_currencies": [ { "id": 1000, "iso_code": "EUR", "iso_numeric": "978", "name": "Euro", "symbol": "€", "created_at": "2026-10-21T04:44:44.790-05:00", "updated_at": "2026-10-21T04:44:44.790-05:00" }, { "id": 3000, "iso_code": "GBP", "iso_numeric": "826", "name": "British Pound", "symbol": "£", "created_at": "2026-10-21T04:44:44.794-05:00", "updated_at": "2026-10-21T04:44:44.794-05:00" } ], "custom_fields": [ { "id": 1, "company_id": 20000, "name": "Project code", "field_type": "string", "active": true, "required": false, "options": [ ], "access_level": "everyone", "position": 0, "on_line_item": false, "on_budget": false, "on_invoice_item": false, "on_invoice": false, "on_supplier": false, "on_rfq": false, "on_product": false, "display_on_pdf": true, "default_value": null, "created_at": "2026-10-21T04:48:43.644-05:00", "updated_at": "2026-10-21T04:48:43.644-05:00", "editable_after_approval": null, "readonly": false, "webhook_enabled": false, "response_populated": false, "payload_included": false, "is_auto_populated": false, "show_on_receiving": false }, { "id": 2, "company_id": 20000, "name": "Cost center", "field_type": "select", "active": true, "required": false, "options": [ "CC-100 Engineering", "CC-200 Marketing", "CC-300 Operations" ], "access_level": "everyone", "position": 1, "on_line_item": false, "on_budget": false, "on_invoice_item": false, "on_invoice": false, "on_supplier": false, "on_rfq": false, "on_product": false, "display_on_pdf": true, "default_value": null, "created_at": "2026-10-21T04:49:01.957-05:00", "updated_at": "2026-10-21T04:49:01.957-05:00", "editable_after_approval": null, "readonly": false, "webhook_enabled": false, "response_populated": false, "payload_included": false, "is_auto_populated": false, "show_on_receiving": false } ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/companies/{id}": { "get": { "tags": [ "Companies" ], "operationId": "v1_companies_show", "summary": "Get a company", "description": "Returns the full configuration of one of the caller's companies by id.\n\nSame body as [Get the current company](#get-the-current-company), for\nany company in which the caller has an **active** (non-archived)\nmembership and which is not deactivated - it need not be the\n`app_company_id` company. A valid `app_company_id` header is still\nrequired.\n\nRole-dependent parts (custom field visibility) are evaluated in the\nrequested company.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Company id (from [List companies](#list-companies)).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "employees_count": { "type": "integer" }, "default_tax_rate": { "type": "number" }, "prepaid_subscription": { "type": "boolean" }, "multicompany_pack": { "type": "boolean" }, "payment_term_ff_enabled": { "type": "null" }, "scan_and_match_ff_enabled": { "type": "null" }, "approval_flow_ff_enabled": { "type": "boolean" }, "policy_ff_enabled": { "type": "boolean" }, "sam_gov_enabled": { "type": "boolean" }, "company_setting": { "type": "object", "properties": { "id": { "type": "integer" }, "show_po_item_number": { "type": "boolean" }, "gross_or_net": { "type": "string" }, "company_id": { "type": "integer" }, "fixed_supplier_list": { "type": "boolean" }, "currency_id": { "type": "integer" }, "javascript": { "type": "null" }, "departments_alias": { "type": "null" }, "display_remaining_budget_amount": { "type": "boolean" }, "date_format": { "type": "string" }, "tax_label": { "type": "string" }, "approvals_require_login": { "type": "boolean" }, "fixed_product_list": { "type": "boolean" }, "fixed_product_price": { "type": "boolean" }, "show_tax_column": { "type": "boolean" }, "show_company_name": { "type": "boolean" }, "allow_budget_overruns": { "type": "boolean" }, "budgets_alias": { "type": "null" }, "enable_detailed_allocations_for_purchase_order_line_items": { "type": "boolean" }, "allocations_enabled": { "type": "boolean" }, "report_name": { "type": "null" }, "user_can_add_supplier": { "type": "boolean" }, "user_can_add_product": { "type": "boolean" }, "po_fields": { "type": "array", "items": { } }, "reserve_po_number": { "type": "boolean" }, "default_template_id": { "type": "null" }, "default_tax_rate_id": { "type": "null" }, "can_invite_user": { "type": "boolean" }, "show_remaining_budget_to_teammember": { "type": "boolean" }, "allow_open_draft_access": { "type": "boolean" }, "link_budgets_to_qbo_accounts": { "type": "boolean" }, "link_budgets_to_qbo_class": { "type": "boolean" }, "enable_offline_mode": { "type": "boolean" }, "is_quickbooks_connected": { "type": "null" }, "is_sage_connected": { "type": "boolean" }, "show_currency_symbol": { "type": "boolean" }, "enable_approval_override": { "type": "boolean" }, "can_upload_invoice": { "type": "boolean" }, "invoice_reference_mandatory": { "type": "boolean" }, "manually_approve_by_lowest_available_approvers": { "type": "boolean" }, "default_payment_term_id": { "type": "integer" }, "qbo_customer_required": { "type": "boolean" }, "qbo_customer_active": { "type": "boolean" }, "qbo_auto_select_new_customer": { "type": "boolean" }, "qbo_class_required": { "type": "boolean" }, "qbo_class_active": { "type": "boolean" }, "qbo_class_alias": { "type": "string" }, "qbo_customer_alias": { "type": "string" }, "qbo_description_required": { "type": "boolean" }, "show_qbo_chart_of_account_number": { "type": "boolean" }, "is_xero_connected": { "type": "null" }, "allow_members_to_see_budgets": { "type": "boolean" } } }, "supported_currencies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "iso_code": { "type": "string" }, "iso_numeric": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "field_type": { "type": "string" }, "active": { "type": "boolean" }, "required": { "type": "boolean" }, "options": { "type": "array", "items": { } }, "access_level": { "type": "string" }, "position": { "type": "integer" }, "on_line_item": { "type": "boolean" }, "on_budget": { "type": "boolean" }, "on_invoice_item": { "type": "boolean" }, "on_invoice": { "type": "boolean" }, "on_supplier": { "type": "boolean" }, "on_rfq": { "type": "boolean" }, "on_product": { "type": "boolean" }, "display_on_pdf": { "type": "boolean" }, "default_value": { "type": "null" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "editable_after_approval": { "type": "null" }, "readonly": { "type": "boolean" }, "webhook_enabled": { "type": "boolean" }, "response_populated": { "type": "boolean" }, "payload_included": { "type": "boolean" }, "is_auto_populated": { "type": "boolean" }, "show_on_receiving": { "type": "boolean" } } } } } }, "example": { "id": 20000, "name": "Acme Corporation", "employees_count": 5, "default_tax_rate": 0.0, "prepaid_subscription": false, "multicompany_pack": false, "payment_term_ff_enabled": null, "scan_and_match_ff_enabled": null, "approval_flow_ff_enabled": true, "policy_ff_enabled": true, "sam_gov_enabled": false, "company_setting": { "id": 2, "show_po_item_number": false, "gross_or_net": "net", "company_id": 20000, "fixed_supplier_list": false, "currency_id": 2000, "javascript": null, "departments_alias": null, "display_remaining_budget_amount": true, "date_format": "%m/%d/%Y", "tax_label": "Tax", "approvals_require_login": false, "fixed_product_list": false, "fixed_product_price": false, "show_tax_column": true, "show_company_name": true, "allow_budget_overruns": true, "budgets_alias": null, "enable_detailed_allocations_for_purchase_order_line_items": false, "allocations_enabled": false, "report_name": null, "user_can_add_supplier": true, "user_can_add_product": false, "po_fields": [ ], "reserve_po_number": false, "default_template_id": null, "default_tax_rate_id": null, "can_invite_user": true, "show_remaining_budget_to_teammember": false, "allow_open_draft_access": false, "link_budgets_to_qbo_accounts": false, "link_budgets_to_qbo_class": false, "enable_offline_mode": true, "is_quickbooks_connected": null, "is_sage_connected": false, "show_currency_symbol": true, "enable_approval_override": true, "can_upload_invoice": true, "invoice_reference_mandatory": false, "manually_approve_by_lowest_available_approvers": false, "default_payment_term_id": 1, "qbo_customer_required": false, "qbo_customer_active": false, "qbo_auto_select_new_customer": true, "qbo_class_required": false, "qbo_class_active": false, "qbo_class_alias": "", "qbo_customer_alias": "", "qbo_description_required": false, "show_qbo_chart_of_account_number": false, "is_xero_connected": null, "allow_members_to_see_budgets": false }, "supported_currencies": [ { "id": 1000, "iso_code": "EUR", "iso_numeric": "978", "name": "Euro", "symbol": "€", "created_at": "2026-10-21T04:44:44.790-05:00", "updated_at": "2026-10-21T04:44:44.790-05:00" }, { "id": 3000, "iso_code": "GBP", "iso_numeric": "826", "name": "British Pound", "symbol": "£", "created_at": "2026-10-21T04:44:44.794-05:00", "updated_at": "2026-10-21T04:44:44.794-05:00" } ], "custom_fields": [ { "id": 1, "company_id": 20000, "name": "Project code", "field_type": "string", "active": true, "required": false, "options": [ ], "access_level": "everyone", "position": 0, "on_line_item": false, "on_budget": false, "on_invoice_item": false, "on_invoice": false, "on_supplier": false, "on_rfq": false, "on_product": false, "display_on_pdf": true, "default_value": null, "created_at": "2026-10-21T04:48:43.644-05:00", "updated_at": "2026-10-21T04:48:43.644-05:00", "editable_after_approval": null, "readonly": false, "webhook_enabled": false, "response_populated": false, "payload_included": false, "is_auto_populated": false, "show_on_receiving": false }, { "id": 2, "company_id": 20000, "name": "Cost center", "field_type": "select", "active": true, "required": false, "options": [ "CC-100 Engineering", "CC-200 Marketing", "CC-300 Operations" ], "access_level": "everyone", "position": 1, "on_line_item": false, "on_budget": false, "on_invoice_item": false, "on_invoice": false, "on_supplier": false, "on_rfq": false, "on_product": false, "display_on_pdf": true, "default_value": null, "created_at": "2026-10-21T04:49:01.957-05:00", "updated_at": "2026-10-21T04:49:01.957-05:00", "editable_after_approval": null, "readonly": false, "webhook_enabled": false, "response_populated": false, "payload_included": false, "is_auto_populated": false, "show_on_receiving": false } ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/companies/approvers": { "get": { "tags": [ "Companies" ], "operationId": "v3_companies_approvers", "summary": "List approvers", "description": "Lists the approvers a requester may choose for a new purchase order, optionally limited to a department.\n\nReturns the users a requester can pick as the approver of a new\npurchase order in the header company, in ascending order of approval\nlimit.\n\n**Empty when routing is automatic.** The list is `[]` when every\nnon-archived budget of the company has approvers assigned\n(`has_unassigned_budgets: false` in [List companies](#list-companies)) -\npurchase orders are then routed by budget - and also whenever a\npublished, active purchase-order approval flow exists.\n\n**Department filter.** With `department_id`, only approvers explicitly\nassigned to that department are considered (approvers with no\ndepartment assignments are not included). An unknown `department_id`\nanswers 404.\n\n**Holiday mode.** Approvers who are on holiday (out of office) and have\nno delegate are left out.\n\n**Approving your own request.** Unless the company setting *Allow\napprovers to approve their own request* is on, the caller is removed from\nthe list - except when the caller is the only approver or the one with\nthe highest approval limit (so a PO above everyone else's limit can still\nbe routed).\n\n\nNone - identical request and response.", "parameters": [ { "name": "department_id", "in": "query", "required": false, "description": "Only approvers assigned to this department of the header company. Unknown id -> 404 `Invalid id passed`.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" }, "approver_name": { "type": "string" }, "phone_number": { "type": "string" }, "setup_incomplete": { "type": "boolean" }, "employer_id": { "type": "integer" }, "approval_limit": { "type": "number" }, "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_limit": { "type": "number" } } } }, "roles": { "type": "array", "items": { "type": "string" } }, "external_user_id": { "type": "null" } } } }, "example": [ { "id": 50000, "email": "priya.patel@example.com", "name": "Priya Patel", "approver_name": "Priya Patel", "phone_number": "+1 555 0150", "setup_incomplete": false, "employer_id": 20000, "approval_limit": 50000.0, "companies": [ { "id": 20000, "approval_limit": 50000.0 } ], "roles": [ "approver", "teammember" ], "external_user_id": null }, { "id": 40000, "email": "jane.doe@example.com", "name": "Jane Doe", "approver_name": "Jane Doe", "phone_number": "+1 555 0140", "setup_incomplete": false, "employer_id": 20000, "approval_limit": 1000000.0, "companies": [ { "id": 20000, "approval_limit": 1000000.0 } ], "roles": [ "companyadmin", "approver", "finance", "teammember" ], "external_user_id": null } ] } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/companies/approvers": { "get": { "tags": [ "Companies" ], "operationId": "v1_companies_approvers", "summary": "List approvers", "description": "Lists the approvers a requester may choose for a new purchase order, optionally limited to a department.\n\nReturns the users a requester can pick as the approver of a new\npurchase order in the header company, in ascending order of approval\nlimit.\n\n**Empty when routing is automatic.** The list is `[]` when every\nnon-archived budget of the company has approvers assigned\n(`has_unassigned_budgets: false` in [List companies](#list-companies)) -\npurchase orders are then routed by budget - and also whenever a\npublished, active purchase-order approval flow exists.\n\n**Department filter.** With `department_id`, only approvers explicitly\nassigned to that department are considered (approvers with no\ndepartment assignments are not included). An unknown `department_id`\nanswers 404.\n\n**Holiday mode.** Approvers who are on holiday (out of office) and have\nno delegate are left out.\n\n**Approving your own request.** Unless the company setting *Allow\napprovers to approve their own request* is on, the caller is removed from\nthe list - except when the caller is the only approver or the one with\nthe highest approval limit (so a PO above everyone else's limit can still\nbe routed).\n\n\nNone - identical request and response.", "parameters": [ { "name": "department_id", "in": "query", "required": false, "description": "Only approvers assigned to this department of the header company. Unknown id -> 404 `Invalid id passed`.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" }, "approver_name": { "type": "string" }, "phone_number": { "type": "string" }, "setup_incomplete": { "type": "boolean" }, "employer_id": { "type": "integer" }, "approval_limit": { "type": "number" }, "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_limit": { "type": "number" } } } }, "roles": { "type": "array", "items": { "type": "string" } }, "external_user_id": { "type": "null" } } } }, "example": [ { "id": 50000, "email": "priya.patel@example.com", "name": "Priya Patel", "approver_name": "Priya Patel", "phone_number": "+1 555 0150", "setup_incomplete": false, "employer_id": 20000, "approval_limit": 50000.0, "companies": [ { "id": 20000, "approval_limit": 50000.0 } ], "roles": [ "approver", "teammember" ], "external_user_id": null }, { "id": 40000, "email": "jane.doe@example.com", "name": "Jane Doe", "approver_name": "Jane Doe", "phone_number": "+1 555 0140", "setup_incomplete": false, "employer_id": 20000, "approval_limit": 1000000.0, "companies": [ { "id": 20000, "approval_limit": 1000000.0 } ], "roles": [ "companyadmin", "approver", "finance", "teammember" ], "external_user_id": null } ] } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/companies/all_approvers": { "get": { "tags": [ "Companies" ], "operationId": "v3_companies_all_approvers", "summary": "List all approvers", "description": "Lists every active member with the approver role, regardless of routing.\n\nReturns all active (non-archived) members of the header company who\nhave the `approver` role, ignoring budget routing, approval flows,\ndepartments, holiday mode and self-approval rules. Use it to populate\napprover pickers outside the PO-creation flow (e.g. reports, filters).\nNot paginated, not filterable, no guaranteed order.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" }, "approver_name": { "type": "string" }, "phone_number": { "type": "string" }, "setup_incomplete": { "type": "boolean" }, "employer_id": { "type": "integer" }, "approval_limit": { "type": "number" }, "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_limit": { "type": "number" } } } }, "roles": { "type": "array", "items": { "type": "string" } }, "external_user_id": { "type": "null" } } } }, "example": [ { "id": 40000, "email": "jane.doe@example.com", "name": "Jane Doe", "approver_name": "Jane Doe", "phone_number": "+1 555 0140", "setup_incomplete": false, "employer_id": 20000, "approval_limit": 1000000.0, "companies": [ { "id": 20000, "approval_limit": 1000000.0 } ], "roles": [ "companyadmin", "approver", "finance", "teammember" ], "external_user_id": null }, { "id": 50000, "email": "priya.patel@example.com", "name": "Priya Patel", "approver_name": "Priya Patel", "phone_number": "+1 555 0150", "setup_incomplete": false, "employer_id": 20000, "approval_limit": 50000.0, "companies": [ { "id": 20000, "approval_limit": 50000.0 } ], "roles": [ "approver", "teammember" ], "external_user_id": null } ] } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/companies/all_approvers": { "get": { "tags": [ "Companies" ], "operationId": "v1_companies_all_approvers", "summary": "List all approvers", "description": "Lists every active member with the approver role, regardless of routing.\n\nReturns all active (non-archived) members of the header company who\nhave the `approver` role, ignoring budget routing, approval flows,\ndepartments, holiday mode and self-approval rules. Use it to populate\napprover pickers outside the PO-creation flow (e.g. reports, filters).\nNot paginated, not filterable, no guaranteed order.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" }, "approver_name": { "type": "string" }, "phone_number": { "type": "string" }, "setup_incomplete": { "type": "boolean" }, "employer_id": { "type": "integer" }, "approval_limit": { "type": "number" }, "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_limit": { "type": "number" } } } }, "roles": { "type": "array", "items": { "type": "string" } }, "external_user_id": { "type": "null" } } } }, "example": [ { "id": 40000, "email": "jane.doe@example.com", "name": "Jane Doe", "approver_name": "Jane Doe", "phone_number": "+1 555 0140", "setup_incomplete": false, "employer_id": 20000, "approval_limit": 1000000.0, "companies": [ { "id": 20000, "approval_limit": 1000000.0 } ], "roles": [ "companyadmin", "approver", "finance", "teammember" ], "external_user_id": null }, { "id": 50000, "email": "priya.patel@example.com", "name": "Priya Patel", "approver_name": "Priya Patel", "phone_number": "+1 555 0150", "setup_incomplete": false, "employer_id": 20000, "approval_limit": 50000.0, "companies": [ { "id": 20000, "approval_limit": 50000.0 } ], "roles": [ "approver", "teammember" ], "external_user_id": null } ] } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/companies/employees": { "get": { "tags": [ "Companies" ], "operationId": "v3_companies_employees", "summary": "List employees", "description": "Lists every active member of the company (company administrators only).\n\nReturns all active (non-archived) members of the header company with\ntheir roles and approval limits. Not paginated, not filterable.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" }, "approver_name": { "type": "string" }, "phone_number": { "type": "string" }, "setup_incomplete": { "type": "boolean" }, "employer_id": { "type": "integer" }, "approval_limit": { "type": "number" }, "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_limit": { "type": "number" } } } }, "roles": { "type": "array", "items": { "type": "string" } }, "external_user_id": { "type": "null" } } } }, "example": [ { "id": 40000, "email": "jane.doe@example.com", "name": "Jane Doe", "approver_name": "Jane Doe", "phone_number": "+1 555 0140", "setup_incomplete": false, "employer_id": 20000, "approval_limit": 1000000.0, "companies": [ { "id": 20000, "approval_limit": 1000000.0 } ], "roles": [ "companyadmin", "approver", "finance", "teammember" ], "external_user_id": null }, { "id": 41000, "email": "sam.smith@example.com", "name": "Sam Smith", "approver_name": "Sam Smith", "phone_number": "+1 555 0141", "setup_incomplete": false, "employer_id": 20000, "approval_limit": 0.0, "companies": [ { "id": 20000, "approval_limit": 0.0 } ], "roles": [ "teammember" ], "external_user_id": null } ] } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/companies/employees": { "get": { "tags": [ "Companies" ], "operationId": "v1_companies_employees", "summary": "List employees", "description": "Lists every active member of the company (company administrators only).\n\nReturns all active (non-archived) members of the header company with\ntheir roles and approval limits. Not paginated, not filterable.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" }, "approver_name": { "type": "string" }, "phone_number": { "type": "string" }, "setup_incomplete": { "type": "boolean" }, "employer_id": { "type": "integer" }, "approval_limit": { "type": "number" }, "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_limit": { "type": "number" } } } }, "roles": { "type": "array", "items": { "type": "string" } }, "external_user_id": { "type": "null" } } } }, "example": [ { "id": 40000, "email": "jane.doe@example.com", "name": "Jane Doe", "approver_name": "Jane Doe", "phone_number": "+1 555 0140", "setup_incomplete": false, "employer_id": 20000, "approval_limit": 1000000.0, "companies": [ { "id": 20000, "approval_limit": 1000000.0 } ], "roles": [ "companyadmin", "approver", "finance", "teammember" ], "external_user_id": null }, { "id": 41000, "email": "sam.smith@example.com", "name": "Sam Smith", "approver_name": "Sam Smith", "phone_number": "+1 555 0141", "setup_incomplete": false, "employer_id": 20000, "approval_limit": 0.0, "companies": [ { "id": 20000, "approval_limit": 0.0 } ], "roles": [ "teammember" ], "external_user_id": null } ] } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/companies/invite_limit_left": { "get": { "tags": [ "Companies" ], "operationId": "v3_companies_invite_limit_left", "summary": "Get the invite limit", "description": "Returns how many more users the company's plan allows.\n\nReports the seat usage of the header company. `active_users` counts\ndistinct users with a non-archived membership across the company's\nparent/child structure; `allowed_users` comes from the subscription\n(the trial plan allows 5). Pending invitations are not counted.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "invite_limit_left": { "type": "integer" }, "active_users": { "type": "integer" }, "allowed_users": { "type": "integer" } } }, "example": { "invite_limit_left": 1, "active_users": 4, "allowed_users": 5 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/companies/invite_limit_left": { "get": { "tags": [ "Companies" ], "operationId": "v1_companies_invite_limit_left", "summary": "Get the invite limit", "description": "Returns how many more users the company's plan allows.\n\nReports the seat usage of the header company. `active_users` counts\ndistinct users with a non-archived membership across the company's\nparent/child structure; `allowed_users` comes from the subscription\n(the trial plan allows 5). Pending invitations are not counted.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "invite_limit_left": { "type": "integer" }, "active_users": { "type": "integer" }, "allowed_users": { "type": "integer" } } }, "example": { "invite_limit_left": 1, "active_users": 4, "allowed_users": 5 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/companies/chart_of_accounts": { "get": { "tags": [ "Companies" ], "operationId": "v3_companies_chart_of_accounts", "summary": "List the company's chart of accounts", "description": "Returns every chart-of-accounts entry of the company, archived ones included.\n\nReturns all chart-of-accounts entries (imported from the accounting\nintegration or created manually) of the header company, including\narchived entries (`archived: true`) and without the per-user\naccess-rights filtering. Not paginated or filterable. For a filterable\nlist use the Chart of accounts endpoints.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "classification": { "type": "string" }, "account_type": { "type": "string" }, "currency_code": { "type": "string" }, "account_number": { "type": "string" }, "display_name": { "type": "string" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" } } } }, "example": [ { "id": 1, "name": "Office Expenses", "classification": "Expense", "account_type": "Expense", "currency_code": "USD", "account_number": "6000", "display_name": "Office Expenses - Expense", "archived": false, "company_id": 20000 }, { "id": 2, "name": "Computer Equipment", "classification": "Expense", "account_type": "Expense", "currency_code": "USD", "account_number": "6100", "display_name": "Computer Equipment - Expense", "archived": false, "company_id": 20000 } ] } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/companies/chart_of_accounts": { "get": { "tags": [ "Companies" ], "operationId": "v1_companies_chart_of_accounts", "summary": "List the company's chart of accounts", "description": "Returns every chart-of-accounts entry of the company, archived ones included.\n\nReturns all chart-of-accounts entries (imported from the accounting\nintegration or created manually) of the header company, including\narchived entries (`archived: true`) and without the per-user\naccess-rights filtering. Not paginated or filterable. For a filterable\nlist use the Chart of accounts endpoints.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "classification": { "type": "string" }, "account_type": { "type": "string" }, "currency_code": { "type": "string" }, "account_number": { "type": "string" }, "display_name": { "type": "string" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" } } } }, "example": [ { "id": 1, "name": "Office Expenses", "classification": "Expense", "account_type": "Expense", "currency_code": "USD", "account_number": "6000", "display_name": "Office Expenses - Expense", "archived": false, "company_id": 20000 }, { "id": 2, "name": "Computer Equipment", "classification": "Expense", "account_type": "Expense", "currency_code": "USD", "account_number": "6100", "display_name": "Computer Equipment - Expense", "archived": false, "company_id": 20000 } ] } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/companies/send_user_invite": { "post": { "tags": [ "Companies" ], "operationId": "v3_companies_send_user_invite", "summary": "Invite a user", "description": "Invites a person by email to join the company with the given roles, departments and approval limit.\n\nCreates a pending invitation in the header company and emails the\ninvitee (a \"join company\" email if they already have a ProcurementExpress\naccount, otherwise a sign-up invitation). The user only becomes a\nmember - and only uses a seat - once they accept.\n\n* `roles` may contain `companyadmin`, `approver`, `finance`,\n `teammember`, `rfqcaseofficer`, `batch_payment_admin`,\n `batch_payment_approver`, `supplier_admin`, `supplier_approver`.\n `sysadmin` and unknown names are dropped; if nothing valid remains the\n invitee gets `teammember`.\n* `department_ids` that are not departments of the header company are\n dropped silently.\n* `approval_limit` defaults to 0.\n* The email is stored lower-case.\n\nChecks run in this order: permission, seats, already a member, already\ninvited (a pending or accepted invitation for the same email in this\ncompany), then field validation.\n\n**Seat limit.** The company must have a free seat\n(`invite_limit_left > 0`). In V1 a company on its free trial may invite\nbeyond the limit; in V3 the seat check also applies during the trial.\nWhen there is no free seat: V1 answers `400` `You need to upgrade plan`;\nV3 answers `400` `You need to upgrade plan` during a trial and `401`\n`Unauthorized access` otherwise.\n\n\nSame request and success response. Seat-limit handling differs (code\nread): V1 refuses only when the company is out of seats **and** not in\ntrial (400 `You need to upgrade plan`); V3 runs the policy check (which\nexempts trials) and then a strict seat check, so a trial company at its\nlimit gets 400 `You need to upgrade plan` from V3 but is allowed by V1,\nand a paid company at its limit gets 401 `Unauthorized access` from V3\nbut 400 `You need to upgrade plan` from V1. All other errors verified\nidentical.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } } }, "example": { "status": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "User already invited by this company.", "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "invite_user[email]": { "type": "string", "description": "Invitee email; must be a valid address." }, "invite_user[name]": { "type": "string", "description": "Invitee full name - at least two words (`Please provide a full name` otherwise)." }, "invite_user[roles][]": { "type": "array", "items": { "type": "string" }, "description": "Roles to grant on acceptance (see description). Default `[\"teammember\"]`." }, "invite_user[department_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Departments of the header company to assign on acceptance. Other ids are ignored." }, "invite_user[approval_limit]": { "type": "number", "description": "Approval limit to set on acceptance, >= 0. Default 0." } }, "required": [ "invite_user[email]", "invite_user[name]" ] }, "example": { "invite_user": { "email": "new.hire+v3@example.com", "name": "Nora Hire", "roles": [ "approver", "teammember" ], "approval_limit": 2500, "department_ids": [ 2, 3 ] } } } } } } }, "/api/v1/companies/send_user_invite": { "post": { "tags": [ "Companies" ], "operationId": "v1_companies_send_user_invite", "summary": "Invite a user", "description": "Invites a person by email to join the company with the given roles, departments and approval limit.\n\nCreates a pending invitation in the header company and emails the\ninvitee (a \"join company\" email if they already have a ProcurementExpress\naccount, otherwise a sign-up invitation). The user only becomes a\nmember - and only uses a seat - once they accept.\n\n* `roles` may contain `companyadmin`, `approver`, `finance`,\n `teammember`, `rfqcaseofficer`, `batch_payment_admin`,\n `batch_payment_approver`, `supplier_admin`, `supplier_approver`.\n `sysadmin` and unknown names are dropped; if nothing valid remains the\n invitee gets `teammember`.\n* `department_ids` that are not departments of the header company are\n dropped silently.\n* `approval_limit` defaults to 0.\n* The email is stored lower-case.\n\nChecks run in this order: permission, seats, already a member, already\ninvited (a pending or accepted invitation for the same email in this\ncompany), then field validation.\n\n**Seat limit.** The company must have a free seat\n(`invite_limit_left > 0`). In V1 a company on its free trial may invite\nbeyond the limit; in V3 the seat check also applies during the trial.\nWhen there is no free seat: V1 answers `400` `You need to upgrade plan`;\nV3 answers `400` `You need to upgrade plan` during a trial and `401`\n`Unauthorized access` otherwise.\n\n\nSame request and success response. Seat-limit handling differs (code\nread): V1 refuses only when the company is out of seats **and** not in\ntrial (400 `You need to upgrade plan`); V3 runs the policy check (which\nexempts trials) and then a strict seat check, so a trial company at its\nlimit gets 400 `You need to upgrade plan` from V3 but is allowed by V1,\nand a paid company at its limit gets 401 `Unauthorized access` from V3\nbut 400 `You need to upgrade plan` from V1. All other errors verified\nidentical.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } } }, "example": { "status": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "User already invited by this company.", "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "invite_user[email]": { "type": "string", "description": "Invitee email; must be a valid address." }, "invite_user[name]": { "type": "string", "description": "Invitee full name - at least two words (`Please provide a full name` otherwise)." }, "invite_user[roles][]": { "type": "array", "items": { "type": "string" }, "description": "Roles to grant on acceptance (see description). Default `[\"teammember\"]`." }, "invite_user[department_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Departments of the header company to assign on acceptance. Other ids are ignored." }, "invite_user[approval_limit]": { "type": "number", "description": "Approval limit to set on acceptance, >= 0. Default 0." } }, "required": [ "invite_user[email]", "invite_user[name]" ] }, "example": { "invite_user": { "email": "new.hire+v1@example.com", "name": "Nora Hire", "roles": [ "approver", "teammember" ], "approval_limit": 2500, "department_ids": [ 2, 3 ] } } } } } } }, "/api/v1/policies": { "get": { "tags": [ "Compliance" ], "operationId": "v1_policies_list", "summary": "List policies", "description": "Returns the company's policies, most recently updated first, with optional filters.\n\nLists the policies of the company named by `app_company_id`, sorted by `updated_at`\ndescending. Archived policies are included unless you filter them out. Each item is\na policy object **without** `content`. Use `GET /policies/:id` for the text.\n\nFilters can be combined. An unknown `status`, `scope` or `category` value returns an\nempty list, not an error.\n\n\nV1 only. `GET /api/v3/policies` does not exist and returns `404 {\"error\": \"Invalid URL\"}`\n.", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "`draft` or `active`", "schema": { "type": "string" } }, { "name": "archived", "in": "query", "required": false, "description": "`true` returns only archived policies. Any other value returns only non-archived ones.", "schema": { "type": "boolean" } }, { "name": "scope", "in": "query", "required": false, "description": "`global` or `budget_specific`", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "description": "`federal_regulation`, `threshold`, `exception` or `custom`", "schema": { "type": "string" } }, { "name": "budget_id", "in": "query", "required": false, "description": "Policies that would apply to a purchase order on this budget: every global policy plus the budget-specific policies linked to it", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "required": false, "description": "Case-insensitive substring match on name or description", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "10, 20, 50 or 100. Any other value falls back to 10.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "policies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "null" }, "status": { "type": "string" }, "archived": { "type": "boolean" }, "category": { "type": "string" }, "budget_ids": { "type": "array", "items": { } }, "min_amount": { "type": "null" }, "max_amount": { "type": "null" }, "required_attachments": { "type": "array", "items": { } }, "min_quotes_required": { "type": "null" }, "source_template_id": { "type": "null" }, "versions_count": { "type": "integer" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "scope": { "type": "string" }, "budgets": { "type": "array", "items": { } } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "next_page": { "type": "null" }, "prev_page": { "type": "null" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "example": { "policies": [ { "id": 3, "name": "Sole source justification", "description": null, "status": "draft", "archived": false, "category": "exception", "budget_ids": [ ], "min_amount": null, "max_amount": null, "required_attachments": [ ], "min_quotes_required": null, "source_template_id": null, "versions_count": 1, "created_at": 1792576752, "updated_at": 1792576752, "scope": "global", "budgets": [ ] }, { "id": 2, "name": "Price reasonableness documentation", "description": "Every purchase needs evidence that the price is reasonable.", "status": "active", "archived": false, "category": "federal_regulation", "budget_ids": [ ], "min_amount": null, "max_amount": null, "required_attachments": [ ], "min_quotes_required": null, "source_template_id": null, "versions_count": 1, "created_at": 1792576752, "updated_at": 1792576752, "scope": "global", "budgets": [ ] } ], "meta": { "current_page": 1, "next_page": null, "prev_page": null, "total_pages": 1, "total_count": 3 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "error": [ "Policies feature is not enabled" ], "status": 403 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "post": { "tags": [ "Compliance" ], "operationId": "v1_policies_create", "summary": "Create a policy", "description": "Creates a policy for the company.\n\nCreates a policy in the company named by `app_company_id`. A policy starts evaluating\npurchase orders as soon as it is `active`. New scans pick it up, but existing scan results\nare not re-evaluated.\n\nTo start from a template, copy the fields of an item from `GET /policy_templates`\n(`default_thresholds` maps to `min_amount`, `max_amount` and `min_quotes_required`).\n\nValidation:\n* `name` is required (at most 255 characters).\n* `min_amount` and `max_amount` must be 0 or more, and `max_amount` must be at least\n `min_amount` when both are set.\n* `min_quotes_required` must be a whole number of 0 or more.\n* `status`, `scope` and `category` must be one of the listed values. Any other value\n currently fails with a `500` error, not a `422`.\n\nSend `budget_ids` only with `scope: budget_specific`. Sending `budget_ids` with a `global`\nscope, including the default scope, currently fails with `500`. Budget ids are not checked\nagainst your company, so only send your own.\n\n\nV1 only. `POST /api/v3/policies` returns `404 {\"error\": \"Invalid URL\"}`.", "parameters": [ ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "archived": { "type": "boolean" }, "category": { "type": "string" }, "budget_ids": { "type": "array", "items": { "type": "integer" } }, "min_amount": { "type": "string" }, "max_amount": { "type": "string" }, "required_attachments": { "type": "array", "items": { "type": "string" } }, "min_quotes_required": { "type": "integer" }, "source_template_id": { "type": "null" }, "versions_count": { "type": "integer" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "scope": { "type": "string" }, "content": { "type": "string" }, "budgets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } } } } }, "example": { "policy": { "id": 1, "name": "Competitive quotes over $5,000", "description": "Purchases between $5,000 and $250,000 need three written quotes.", "status": "active", "archived": false, "category": "threshold", "budget_ids": [ 1 ], "min_amount": "5000.0", "max_amount": "250000.0", "required_attachments": [ "quote" ], "min_quotes_required": 3, "source_template_id": null, "versions_count": 1, "created_at": 1792576744, "updated_at": 1792576744, "scope": "budget_specific", "content": "Any purchase of $5,000 or more charged to an engineering hardware budget must be supported by three written quotes from independent suppliers. Each quote must show the supplier name, item descriptions, unit prices and a validity date.", "budgets": [ { "id": 1, "name": "Engineering Hardware FY26" } ] } } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "example": { "errors": [ "Name can't be blank", "Max amount must be greater than or equal to minimum amount" ] } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "policy[name]": { "type": "string", "description": "Policy name, at most 255 characters" }, "policy[content]": { "type": "string", "description": "The rule text the AI evaluates. A policy without content is never sent to the AI and so never fails a scan, apart from the built-in SAM.gov check." }, "policy[description]": { "type": "string", "description": "Short summary for people. Not sent to the AI." }, "policy[status]": { "type": "string", "description": "`draft` or `active`" }, "policy[scope]": { "type": "string", "description": "`global` or `budget_specific`" }, "policy[category]": { "type": "string", "description": "`federal_regulation`, `threshold`, `exception` or `custom`" }, "policy[budget_ids]": { "type": "array", "items": { "type": "integer" }, "description": "Budgets of your company that a `budget_specific` policy applies to. Do not send with `global` scope." }, "policy[min_amount]": { "type": "number", "description": "Lower bound (0 or more) of the order amount for the quote-count rule" }, "policy[max_amount]": { "type": "number", "description": "Upper bound for the quote-count rule. Must be at least `min_amount`." }, "policy[min_quotes_required]": { "type": "integer", "description": "Whole number of 0 or more. Stored only. State the quote requirement in `content` for it to be checked." }, "policy[required_attachments]": { "type": "array", "items": { "type": "string" }, "description": "Labels such as `quote` or `invoice`. Stored only, not evaluated." }, "policy[archived]": { "type": "boolean", "description": "Create the policy already archived" } }, "required": [ "policy[name]" ] }, "example": { "policy": { "name": "Competitive quotes over $5,000", "description": "Purchases between $5,000 and $250,000 need three written quotes.", "status": "active", "scope": "budget_specific", "category": "threshold", "budget_ids": [ 1 ], "min_amount": 5000, "max_amount": 250000, "min_quotes_required": 3, "required_attachments": [ "quote" ], "content": "Any purchase of $5,000 or more charged to an engineering hardware budget must be supported by three written quotes from independent suppliers. Each quote must show the supplier name, item descriptions, unit prices and a validity date." } } } } } } }, "/api/v1/policies/{id}": { "get": { "tags": [ "Compliance" ], "operationId": "v1_policies_show", "summary": "Get a policy", "description": "Returns one policy, including its text and its change history.\n\nReturns the full policy, including `content`, plus `versions`: the change history\nrecorded by PaperTrail, oldest first. Each create and update adds a version that lists\nthe changed attributes. Changes to `budget_ids` are **not** recorded, because they live\nin a join table.\n\n\nV1 only. `GET /api/v3/policies/:id` returns `404 {\"error\": \"Invalid URL\"}`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Policy id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "archived": { "type": "boolean" }, "category": { "type": "string" }, "budget_ids": { "type": "array", "items": { "type": "integer" } }, "min_amount": { "type": "string" }, "max_amount": { "type": "string" }, "required_attachments": { "type": "array", "items": { "type": "string" } }, "min_quotes_required": { "type": "integer" }, "source_template_id": { "type": "null" }, "versions_count": { "type": "integer" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "scope": { "type": "string" }, "content": { "type": "string" }, "budgets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } } }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "item_type": { "type": "string" }, "item_id": { "type": "integer" }, "event": { "type": "string" }, "whodunnit": { "type": "string" }, "whodunnit_name": { "type": "string" }, "object": { "type": "null" }, "object_changes": { "type": "object", "properties": { "id": { "type": "array", "items": { "type": "null" } }, "category": { "type": "array", "items": { "type": "string" } }, "company_id": { "type": "array", "items": { "type": "null" } }, "content": { "type": "array", "items": { "type": "null" } }, "created_at": { "type": "array", "items": { "type": "null" } }, "description": { "type": "array", "items": { "type": "null" } }, "max_amount": { "type": "array", "items": { "type": "null" } }, "min_amount": { "type": "array", "items": { "type": "null" } }, "min_quotes_required": { "type": "array", "items": { "type": "null" } }, "name": { "type": "array", "items": { "type": "null" } }, "required_attachments": { "type": "array", "items": { "type": "array", "items": { } } }, "scope": { "type": "array", "items": { "type": "string" } }, "status": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": "array", "items": { "type": "null" } } } }, "created_at": { "type": "string" } } } } } }, "example": { "policy": { "id": 1, "name": "Competitive quotes over $2,500", "description": "Purchases between $2,500 and $250,000 need three written quotes.", "status": "active", "archived": false, "category": "threshold", "budget_ids": [ 1, 3 ], "min_amount": "2500.0", "max_amount": "250000.0", "required_attachments": [ "quote" ], "min_quotes_required": 3, "source_template_id": null, "versions_count": 3, "created_at": 1792576744, "updated_at": 1792576799, "scope": "budget_specific", "content": "Any purchase of $2,500 or more charged to an engineering hardware or office supplies budget must be supported by three written quotes from independent suppliers. Each quote must show the supplier name, item descriptions, unit prices and a validity date.", "budgets": [ { "id": 1, "name": "Engineering Hardware FY26" }, { "id": 3, "name": "Office Supplies" } ] }, "versions": [ { "id": 4, "item_type": "Policy", "item_id": 1, "event": "create", "whodunnit": "40000", "whodunnit_name": "Jane Doe", "object": null, "object_changes": { "id": [ null, 1 ], "category": [ "custom", "threshold" ], "company_id": [ null, 20000 ], "content": [ null, "Any purchase of $5,000 or more charged to an engineering hardware budget must be supported by three written quotes from independent suppliers. Each quote must show the supplier name, item descriptions, unit prices and a validity date." ], "created_at": [ null, "2026-10-21T04:59:04.070-05:00" ], "description": [ null, "Purchases between $5,000 and $250,000 need three written quotes." ], "max_amount": [ null, "250000.0" ], "min_amount": [ null, "5000.0" ], "min_quotes_required": [ null, 3 ], "name": [ null, "Competitive quotes over $5,000" ], "required_attachments": [ [ ], [ "quote" ] ], "scope": [ "global", "budget_specific" ], "status": [ "draft", "active" ], "updated_at": [ null, "2026-10-21T04:59:04.070-05:00" ] }, "created_at": "2026-10-21T04:59:04.070-05:00" }, { "id": 25, "item_type": "Policy", "item_id": 1, "event": "update", "whodunnit": "40000", "whodunnit_name": "Jane Doe", "object": "---\ncompany_id: 20000\ndescription: Purchases between $5,000 and $250,000 need three written quotes.\nmin_amount: !ruby/object:BigDecimal 9:0.5e4\nmax_amount: !ruby/object:BigDecimal 9:0.25e6\nmin_quotes_required: 3\nscope: 1\nid: 1\narchived: false\ncategory: 1\ncontent: Any purchase of $5,000 or more charged to an engineering hardware budget\n must be supported by three written quotes from independent suppliers. Each quote\n must show the supplier name, item descriptions, unit prices and a validity date.\ncreated_at: 2026-10-21 09:59:04.070066000 Z\ndeleted_at:\nname: Competitive quotes over $5,000\nrequired_attachments:\n- quote\nsource_template_id:\nstatus: 1\nupdated_at: 2026-10-21 09:59:04.070066000 Z\nversions_count: 1\n", "object_changes": { "description": [ "Purchases between $5,000 and $250,000 need three written quotes.", "Purchases between $2,500 and $250,000 need three written quotes." ], "min_amount": [ "5000.0", "2500.0" ], "updated_at": [ "2026-10-21T04:59:04.070-05:00", "2026-10-21T04:59:51.606-05:00" ] }, "created_at": "2026-10-21T04:59:51.606-05:00" } ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "put": { "tags": [ "Compliance" ], "operationId": "v1_policies_update", "summary": "Update a policy", "description": "Changes any attribute of a policy; only the attributes you send are changed.\n\nPartial update: send only the attributes you want to change. They take the same names\nand validation as **Create a policy**.\n\n* `budget_ids` replaces the whole list (`[]` removes every budget).\n* Changing `scope` to `global` removes the policy's budgets.\n* Set `archived: true` to retire a policy. This is the only option for a policy that\n already has violations, because such a policy cannot be deleted.\n* The change affects future scans only.\n\n\nV1 only. `PUT /api/v3/policies/:id` returns `404 {\"error\": \"Invalid URL\"}`.\nPUT and PATCH behave the same (the 422 example was sent with PATCH).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Policy id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "archived": { "type": "boolean" }, "category": { "type": "string" }, "budget_ids": { "type": "array", "items": { "type": "integer" } }, "min_amount": { "type": "string" }, "max_amount": { "type": "string" }, "required_attachments": { "type": "array", "items": { "type": "string" } }, "min_quotes_required": { "type": "integer" }, "source_template_id": { "type": "null" }, "versions_count": { "type": "integer" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "scope": { "type": "string" }, "content": { "type": "string" }, "budgets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } } } } }, "example": { "policy": { "id": 1, "name": "Competitive quotes over $2,500", "description": "Purchases between $2,500 and $250,000 need three written quotes.", "status": "active", "archived": false, "category": "threshold", "budget_ids": [ 1, 3 ], "min_amount": "2500.0", "max_amount": "250000.0", "required_attachments": [ "quote" ], "min_quotes_required": 3, "source_template_id": null, "versions_count": 3, "created_at": 1792576744, "updated_at": 1792576799, "scope": "budget_specific", "content": "Any purchase of $2,500 or more charged to an engineering hardware or office supplies budget must be supported by three written quotes from independent suppliers. Each quote must show the supplier name, item descriptions, unit prices and a validity date.", "budgets": [ { "id": 1, "name": "Engineering Hardware FY26" }, { "id": 3, "name": "Office Supplies" } ] } } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "example": { "errors": [ "Max amount must be greater than or equal to minimum amount" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "policy[name]": { "type": "string", "description": "At most 255 characters, not blank" }, "policy[content]": { "type": "string", "description": "Rule text evaluated by the AI" }, "policy[description]": { "type": "string", "description": "Short summary" }, "policy[status]": { "type": "string", "description": "`draft` or `active`" }, "policy[scope]": { "type": "string", "description": "`global` or `budget_specific`" }, "policy[category]": { "type": "string", "description": "`federal_regulation`, `threshold`, `exception` or `custom`" }, "policy[budget_ids]": { "type": "array", "items": { "type": "integer" }, "description": "Replaces the linked budgets. Ignored for global policies." }, "policy[min_amount]": { "type": "number", "description": "0 or more, or `null`" }, "policy[max_amount]": { "type": "number", "description": "At least `min_amount`, or `null`" }, "policy[min_quotes_required]": { "type": "integer", "description": "Whole number of 0 or more, or `null`" }, "policy[required_attachments]": { "type": "array", "items": { "type": "string" }, "description": "Replaces the list" }, "policy[archived]": { "type": "boolean", "description": "Archive or restore the policy" } } }, "example": { "policy": { "name": "Competitive quotes over $2,500", "min_amount": 2500, "description": "Purchases between $2,500 and $250,000 need three written quotes.", "content": "Any purchase of $2,500 or more charged to an engineering hardware or office supplies budget must be supported by three written quotes from independent suppliers. Each quote must show the supplier name, item descriptions, unit prices and a validity date.", "budget_ids": [ 1, 3 ] } } } } } }, "delete": { "tags": [ "Compliance" ], "operationId": "v1_policies_delete", "summary": "Delete a policy", "description": "Soft-deletes a policy so it is no longer listed or evaluated.\n\nSoft-deletes the policy. It disappears from the list and is never evaluated again, and\nits budget links are removed.\n\nA policy that has produced violations in past scans currently cannot be deleted: the\nrequest fails with `500`. Archive it instead (`PUT /policies/:id` with `archived: true`).\n\n\nV1 only. `DELETE /api/v3/policies/:id` returns `404 {\"error\": \"Invalid URL\"}`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Policy id", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v1/policy_templates": { "get": { "tags": [ "Compliance" ], "operationId": "v1_policy_templates_list", "summary": "List policy templates", "description": "Returns the built-in policy templates that can be copied into new policies.\n\nReturns the seven built-in templates (the same for every company). The list is static\nand not paginated. Template `id`s: `2cfr200318`, `sam_gov_debarment`, `micro_purchase`,\n`small_purchase`, `sealed_bids`, `sole_source` and `cost_reasonableness`.\n\nTo use a template, send its `name`, `category`, `description` and `content`, plus\n`default_thresholds` as `min_amount`, `max_amount` and `min_quotes_required`, to\n`POST /policies`.\n\nThere is no need to create the `sam_gov_debarment` policy by hand. SAM.gov exclusions are\nchecked automatically once SAM.gov is enabled. If you do create a policy named\n`SAM.gov Debarment Check` while no SAM.gov API key is configured, every scan reports a\n`medium` `sam_gov_exclusion` warning.\n\n\nV1 only. `GET /api/v3/policy_templates` returns `404 {\"error\": \"Invalid URL\"}`.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "content": { "type": "string" }, "default_thresholds": { "type": "null" } } } } } }, "example": { "templates": [ { "id": "2cfr200318", "name": "2 CFR 200.318 - General Procurement Standards", "category": "federal_regulation", "description": "Uniform Administrative Requirements for Federal Awards.", "content": "§ 200.318 General procurement standards.\n\n(a) The non-Federal entity must use its own documented procurement procedures\nwhich reflect applicable State, local, and tribal laws and regulations,\nprovided that the procurements conform to applicable Federal law and the\nstandards identified in this part.\n\n(b) Non-Federal entities must maintain oversight to ensure that contractors\nperform in accordance with the terms, conditions, and specifications of\ntheir contracts or purchase orders.\n\n(c) The non-Federal entity must maintain written standards of conduct\ncovering conflicts of interest and governing the actions of its employees\nengaged in the selection, award and administration of contracts.\n\n(d) The non-Federal entity's procedures must avoid acquisition of unnecessary\nor duplicative items. Consideration should be given to consolidating or\nbreaking out procurements to obtain a more economical purchase.\n\n(e) To foster greater economy and efficiency, and in accordance with efforts\nto promote cost-effective use of shared services, the non-Federal entity is\nencouraged to enter into state and local intergovernmental agreements or\ninter-entity agreements for procurement or use of common or shared goods\nand services.\n", "default_thresholds": null }, { "id": "sam_gov_debarment", "name": "SAM.gov Debarment Check", "category": "federal_regulation", "scope": "global", "description": "Automated check against the SAM.gov Exclusions API to verify suppliers are not debarred, suspended, or otherwise excluded from federal procurement.", "content": "All purchase orders must include a SAM.gov exclusion check for the\nselected supplier per FAR 9.4. Orders with flagged suppliers require\nwritten justification and manager-level approval before proceeding.\n\nReferences:\n- FAR 9.4 - Debarment, Suspension, and Ineligibility\n- 2 CFR 180 - OMB Guidelines to Agencies on Governmentwide\n Debarment and Suspension\n", "default_thresholds": null } ] } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v1/compliance/check": { "post": { "tags": [ "Compliance" ], "operationId": "v1_compliance_check", "summary": "Scan a purchase order", "description": "Starts an asynchronous compliance scan of one purchase order against the active policies.\n\nQueues a compliance scan and returns `202 Accepted` immediately. The result arrives on\n`ComplianceCheckChannel` as a `compliance_result` message, and afterwards in\n`GET /purchase_orders/:id` (`latest_compliance_check`). See *How a scan works* above.\n\n**With `purchase_order_id`** (the normal case):\n* The order must belong to the request company (`404` otherwise), and you must be able to\n collaborate on it (`403` otherwise).\n* If a scan of the order is already `running`, the request is refused with `409`.\n* The order's `compliance_status` is set to `running`, and a *scan initiated* comment is\n added to it, before the job is queued.\n* The **stored** order is evaluated: its amount, supplier, line items, line-item budgets\n and attachments. Other body fields are optional. When they disagree with the stored\n order, the difference is reported in the result's `request_mismatch` and the stored\n values are still the ones used.\n\n**Without `purchase_order_id`** (\"metadata only\"): the amount, supplier and items you send\nare evaluated against the policies that apply to `budget_id`. This mode has no documents,\nand its result cannot be received or read back through the API. It is mainly useful\ninside the web app while an order is being drafted.\n\nIf the background job keeps failing and runs out of retries (3), the order's\n`compliance_status` is reset to `null` (\"not run\") and a `compliance_error` message is pushed.\n\n\nV1 only. `POST /api/v3/compliance/check` returns `404 {\"error\": \"Invalid URL\"}`.", "parameters": [ ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "job_id": { "type": "string" }, "purchase_order_id": { "type": "integer" }, "message": { "type": "string" } } }, "example": { "status": "processing", "job_id": "e336af984fd90146fc4b9114", "purchase_order_id": 21, "message": "Compliance check started" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "example": { "error": "Compliance scan is already running for this purchase order", "status": "conflict" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Purchase order not found", "status": "not_found" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "error": "Not authorized to run a compliance check on this purchase order", "status": "forbidden" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "Required parameter are missing.", "status": 400 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "compliance_check[purchase_order_id]": { "type": "integer", "description": "Purchase order to scan. Echoed back in the response as sent." }, "compliance_check[budget_id]": { "type": "integer", "description": "Budget used to pick budget-specific policies when the order has no budgeted line items, or when no order is given" }, "compliance_check[budget_name]": { "type": "string", "description": "Budget name shown to the AI when no budget can be read from the order" }, "compliance_check[total_amount]": { "type": "number", "description": "Metadata-only mode: amount to evaluate. With an order: compared with the stored amount only." }, "compliance_check[supplier]": { "type": "string", "description": "Metadata-only mode: supplier name. With an order: compared with the stored supplier only." }, "compliance_check[items][][description]": { "type": "string", "description": "Line item description (metadata-only mode)" }, "compliance_check[items][][quantity]": { "type": "number", "description": "Line item quantity" }, "compliance_check[items][][unit_price]": { "type": "number", "description": "Line item unit price" }, "compliance_check[attachments][][name]": { "type": "string", "description": "Accepted and stored with the request, but not evaluated. Documents are read from the order's real attachments." }, "compliance_check[attachments][][type]": { "type": "string", "description": "Accepted, not evaluated" }, "compliance_check[attachments][][size]": { "type": "integer", "description": "Accepted, not evaluated" } } }, "example": { "compliance_check": { "purchase_order_id": 21, "budget_id": 1, "budget_name": "Engineering Hardware FY26", "total_amount": 12800, "supplier": "Contoso Hardware", "items": [ { "description": "14-inch developer laptop, 32GB RAM", "quantity": 4, "unit_price": 3200 } ] } } } } } } }, "/api/v1/compliance/bulk_check": { "post": { "tags": [ "Compliance" ], "operationId": "v1_compliance_bulk_check", "summary": "Scan several purchase orders", "description": "Starts one background bulk scan over a list of purchase orders, skipping orders that cannot or need not be scanned.\n\nSorts the requested orders of the request company into:\n* `already_passed`: `compliance_status` is `passed`. These are skipped. Passed orders are\n never re-scanned in bulk; use `POST /compliance/check` to re-scan one.\n* `already_scanning`: `compliance_status` is `running`. These are skipped.\n* `not_permitted`: you cannot collaborate on the order (same rule as a single scan). These are skipped.\n* the rest (never scanned, or `failed`), which are scanned.\n\nIds that do not exist or belong to another company are ignored silently. The scanned\norders are set to `running`, each gets a *scan initiated* comment, and one bulk scan\nrecord is queued. Orders are then scanned one after another, exactly like\n`POST /compliance/check` with a purchase order. Progress is pushed on\n`BulkComplianceCheckChannel` and can be polled with `GET /compliance/bulk_check_status`.\n\nYou can have only one bulk scan pending or in progress per company. Wait for it to finish\nbefore starting another (`409`).\n\n\nV1 only. `POST /api/v3/compliance/bulk_check` returns `404 {\"error\": \"Invalid URL\"}`.", "parameters": [ ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "bulk_scan_id": { "type": "integer" }, "total_count": { "type": "integer" }, "skipped": { "type": "object", "properties": { "already_passed": { "type": "array", "items": { "type": "integer" } }, "already_scanning": { "type": "array", "items": { "type": "integer" } }, "not_permitted": { "type": "array", "items": { } } } } } }, "example": { "status": "processing", "bulk_scan_id": 1, "total_count": 2, "skipped": { "already_passed": [ 23 ], "already_scanning": [ 24 ], "not_permitted": [ ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "purchase_order_ids must be a non-empty array of IDs", "status": "bad_request" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "example": { "error": "No purchase orders available to scan. All are either passed or already scanning.", "status": "unprocessable_entity" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "error": "Not authorized to run a compliance check on the selected purchase orders", "status": "forbidden" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "example": { "error": "A bulk compliance scan is already in progress", "status": "conflict" } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase_order_ids": { "type": "array", "items": { "type": "integer" }, "description": "Purchase order ids, as a JSON array (not nested under a root key)" } }, "required": [ "purchase_order_ids" ] }, "example": { "purchase_order_ids": [ 23, 24, 25, 26 ] } } } } } }, "/api/v1/compliance/bulk_check_status": { "get": { "tags": [ "Compliance" ], "operationId": "v1_compliance_bulk_check_status", "summary": "Get your latest bulk scan", "description": "Returns progress and per-order results of the most recent bulk scan you started in this company.\n\nReturns your most recent bulk scan in the request company, whatever its status. Poll it\nwhile `status` is `pending` or `in_progress`, or use `BulkComplianceCheckChannel`\ninstead. Bulk scans started by other users are not returned; see **Scan history**.\n\n\nV1 only. `GET /api/v3/compliance/bulk_check_status` returns `404 {\"error\": \"Invalid URL\"}`.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "bulk_scan_id": { "type": "integer" }, "status": { "type": "string" }, "total_count": { "type": "integer" }, "scanned_count": { "type": "integer" }, "passed_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "error_count": { "type": "integer" }, "progress_percent": { "type": "integer" }, "results_data": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "status": { "type": "string" }, "scanned_at": { "type": "string" }, "approval_key": { "type": "null" }, "supplier_name": { "type": "string" }, "purchase_order_id": { "type": "integer" }, "compliance_check_id": { "type": "integer" }, "passed_policy_count": { "type": "integer" } } } }, "started_at": { "type": "string" }, "completed_at": { "type": "null" }, "initiated_by": { "type": "string" } } }, "example": { "bulk_scan_id": 1, "status": "in_progress", "total_count": 2, "scanned_count": 1, "passed_count": 1, "failed_count": 0, "error_count": 0, "progress_percent": 50, "results_data": [ { "amount": "2250.0", "status": "passed", "scanned_at": "2026-10-21T05:06:00-05:00", "approval_key": null, "supplier_name": "Contoso Hardware", "purchase_order_id": 25, "compliance_check_id": 3, "passed_policy_count": 2 } ], "started_at": "2026-10-21T05:05:58.928-05:00", "completed_at": null, "initiated_by": "Jane Doe" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "No bulk compliance scan found", "status": "not_found" } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v1/compliance/scan_history": { "get": { "tags": [ "Compliance" ], "operationId": "v1_compliance_scan_history", "summary": "List bulk scan history", "description": "Lists the company's finished bulk scans, newest first.\n\nLists the `completed` and `failed` bulk scans of the request company, started by **any**\nuser, newest first. Scans still pending or in progress are not listed. Single-order scans\n(`POST /compliance/check`) are not bulk scans and never appear here.\n\n\nV1 only. `GET /api/v3/compliance/scan_history` returns `404 {\"error\": \"Invalid URL\"}`.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number. 0 or less is treated as 1.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "10, 20, 50 or 100", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "scans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "total_count": { "type": "integer" }, "passed_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "error_count": { "type": "integer" }, "completed_at": { "type": "string" }, "initiated_by": { "type": "string" } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" }, "next_page": { "type": "null" } } } } }, "example": { "scans": [ { "id": 4, "status": "completed", "total_count": 1, "passed_count": 0, "failed_count": 1, "error_count": 0, "completed_at": "2026-10-21T05:11:35.399-05:00", "initiated_by": "Marco Rossi" }, { "id": 1, "status": "completed", "total_count": 2, "passed_count": 1, "failed_count": 1, "error_count": 0, "completed_at": "2026-10-21T05:06:11.218-05:00", "initiated_by": "Jane Doe" } ], "meta": { "current_page": 1, "total_pages": 1, "total_count": 3, "next_page": null } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v1/compliance/scan_history/{id}": { "get": { "tags": [ "Compliance" ], "operationId": "v1_compliance_scan_history_show", "summary": "Get a bulk scan", "description": "Returns one finished bulk scan of the company with its per-order results.\n\nReturns a `completed` or `failed` bulk scan of the request company, whoever started it.\nA scan that is still `pending` or `in_progress` returns `404`. Use\n`GET /compliance/bulk_check_status` to follow a running scan.\n\n\nV1 only. `GET /api/v3/compliance/scan_history/:id` returns `404 {\"error\": \"Invalid URL\"}`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Bulk scan id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "bulk_scan_id": { "type": "integer" }, "status": { "type": "string" }, "total_count": { "type": "integer" }, "scanned_count": { "type": "integer" }, "passed_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "error_count": { "type": "integer" }, "progress_percent": { "type": "integer" }, "results_data": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "status": { "type": "string" }, "scanned_at": { "type": "string" }, "approval_key": { "type": "null" }, "supplier_name": { "type": "string" }, "purchase_order_id": { "type": "integer" }, "compliance_check_id": { "type": "integer" }, "passed_policy_count": { "type": "integer" } } } }, "started_at": { "type": "string" }, "completed_at": { "type": "string" }, "initiated_by": { "type": "string" } } }, "example": { "id": 1, "bulk_scan_id": 1, "status": "completed", "total_count": 2, "scanned_count": 2, "passed_count": 1, "failed_count": 1, "error_count": 0, "progress_percent": 100, "results_data": [ { "amount": "2250.0", "status": "passed", "scanned_at": "2026-10-21T05:06:00-05:00", "approval_key": null, "supplier_name": "Contoso Hardware", "purchase_order_id": 25, "compliance_check_id": 3, "passed_policy_count": 2 }, { "amount": "6000.0", "status": "failed", "scanned_at": "2026-10-21T05:06:11-05:00", "risk_levels": [ "high" ], "approval_key": null, "policy_names": [ "Competitive quotes over $2,500" ], "supplier_name": "Northwind Office Supplies", "violation_count": 1, "purchase_order_id": 26, "compliance_check_id": 4 } ], "started_at": "2026-10-21T05:05:58.928-05:00", "completed_at": "2026-10-21T05:06:11.218-05:00", "initiated_by": "Jane Doe" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Scan not found", "status": "not_found" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v1/compliance/justify": { "post": { "tags": [ "Compliance" ], "operationId": "v1_compliance_justify", "summary": "Justify a violation", "description": "Resolves a compliance violation with a written justification.\n\nMarks a violation as resolved (`resolution_method: \"manual_justification\"`) and records\nwho justified it, when, and why. The reason is also written to the order as a\n*violation justified* comment.\n\nAfter saving, the endpoint counts the `high` and `critical` violations of the same scan\nthat are still unresolved. When none are left (`all_justified: true`):\n* an *audit ready* comment is added to the order, and\n* the scan's evidence pack is created (or reset to `zip_pending` and rebuilt) and its ID\n returned as `evidence_pack_id`.\n\nJustifying `low` or `medium` violations is allowed but is not needed for audit-readiness.\nThe order's `compliance_status` stays `failed`.\n\nOnly violations from scans of a purchase order can be justified. Violations from\nmetadata-only scans return `404`.\n\n\nV1 only. `POST /api/v3/compliance/justify` returns `404 {\"error\": \"Invalid URL\"}`.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "violation": { "type": "object", "properties": { "id": { "type": "integer" }, "policy_id": { "type": "integer" }, "policy_name": { "type": "string" }, "policy_reference": { "type": "string" }, "violation_type": { "type": "string" }, "risk_level": { "type": "string" }, "impact": { "type": "string" }, "details": { "type": "string" }, "remediation_options": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } } } }, "resolved": { "type": "boolean" }, "resolved_at": { "type": "string" }, "resolution_method": { "type": "string" }, "justified_by_id": { "type": "integer" }, "justified_by_name": { "type": "string" }, "justification_reason": { "type": "string" }, "sam_gov_check_id": { "type": "null" }, "sam_gov_exclusion_details": { "type": "null" } } }, "all_justified": { "type": "boolean" }, "evidence_pack_id": { "type": "null" } } }, "example": { "violation": { "id": 1, "policy_id": 1, "policy_name": "Competitive quotes over $2,500", "policy_reference": "Competitive quotes over $2,500", "violation_type": "insufficient_quotes", "risk_level": "high", "impact": "Fewer quotes attached than the policy requires", "details": "Policy \"Competitive quotes over $2,500\" requires 3 quote(s); 0 attached document(s) were identified as quotes.", "remediation_options": [ { "type": "upload_documents", "label": "Upload Supporting Documents", "description": "Upload documents that satisfy the policy requirements" }, { "type": "generate_memo", "label": "Generate Justification Memo", "description": "AI will help generate documentation to address this violation" } ], "resolved": true, "resolved_at": "2026-10-21T05:06:35-05:00", "resolution_method": "manual_justification", "justified_by_id": 40000, "justified_by_name": "Jane Doe", "justification_reason": "Contoso is our sole authorised reseller for this laptop model under the 2026 hardware framework agreement, so competing quotes are not available.", "sam_gov_check_id": null, "sam_gov_exclusion_details": null }, "all_justified": false, "evidence_pack_id": null } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "violation_id parameter is required", "status": "bad_request" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "example": { "error": "Justification reason must be provided and at least 10 characters long", "status": "unprocessable_entity" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Violation not found", "status": "not_found" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "error": "Not authorized to justify violations", "status": "forbidden" } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "violation_id": { "type": "integer", "description": "Violation id (top level, no root key)" }, "justification_reason": { "type": "string", "description": "Why the purchase may proceed. Leading and trailing whitespace is trimmed. At least 10 characters (`422` JSON error otherwise) and at most 2,000 (longer reasons are rejected with a non-JSON `422` error page)." } }, "required": [ "violation_id", "justification_reason" ] }, "example": { "violation_id": 1, "justification_reason": "Contoso is our sole authorised reseller for this laptop model under the 2026 hardware framework agreement, so competing quotes are not available." } } } } } }, "/api/v1/compliance/generate_memo": { "post": { "tags": [ "Compliance" ], "operationId": "v1_compliance_generate_memo", "summary": "Generate a price reasonableness memo", "description": "Uses AI to draft a Price Reasonableness Memo from the purchase details you supply.\n\nSends the details to the AI (Gemini, with OpenAI as fallback) and returns a formal\n*Price Reasonableness Memo* in plain text, suitable for federal grant audit files\n(2 CFR 200.404). The call is synchronous and typically takes several seconds.\n\nThe memo is **not stored**: it is not attached to a violation, an order or an evidence\npack. To keep it, upload it to the order or paste it into a justification.\n\n`selection_rationale` and `market_basis` accept fixed keys, which become standard\nphrases, or free text. Prices are parsed as numbers (`$`, `,` and spaces are stripped) and\ndropped if they cannot be parsed. At most 10 alternatives are used, and each text value is\ncut to 1,000 characters.\n\n\nV1 only. `POST /api/v3/compliance/generate_memo` returns `404 {\"error\": \"Invalid URL\"}`.", "parameters": [ ], "responses": { "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": { "error": "AI service temporarily unavailable. Please try again." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "Required parameter are missing.", "status": 400 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "memo_request[item_description]": { "type": "string", "description": "What is being bought" }, "memo_request[selected_vendor]": { "type": "string", "description": "Chosen supplier" }, "memo_request[selected_price]": { "type": "number", "description": "Chosen supplier's price" }, "memo_request[selection_rationale]": { "type": "string", "description": "`lowest_price`, `best_value`, `sole_source`, `emergency`, or free text" }, "memo_request[market_basis]": { "type": "string", "description": "`catalog_pricing`, `historical_pricing`, `competitive_quotes`, `market_research`, or free text" }, "memo_request[alternatives_considered][][vendor]": { "type": "string", "description": "Alternative supplier" }, "memo_request[alternatives_considered][][price]": { "type": "number", "description": "Its price" }, "memo_request[alternatives_considered][][notes]": { "type": "string", "description": "Why it was not chosen" }, "memo_request[violation_id]": { "type": "integer", "description": "Accepted but currently ignored" } } }, "example": { "memo_request": { "violation_id": 1, "item_description": "4 x 14-inch developer laptops, 32GB RAM", "selected_vendor": "Contoso Hardware", "selected_price": 12800, "selection_rationale": "best_value", "market_basis": "competitive_quotes", "alternatives_considered": [ { "vendor": "Northwind Office Supplies", "price": 13600, "notes": "Same model, 3-week lead time" }, { "vendor": "Globex Logistics", "price": 12950, "notes": "Refurbished units only" } ] } } } } } } }, "/api/v1/compliance/evidence_packs": { "post": { "tags": [ "Compliance" ], "operationId": "v1_evidence_packs_create", "summary": "Create an evidence pack", "description": "Creates (or rebuilds) the evidence pack of a compliance check and starts building its ZIP.\n\nCreates the evidence pack for a compliance check and queues the ZIP build. If the check\nalready has a pack that is not currently being built, the pack is reset to `zip_pending`\nand rebuilt. If it is being built, the pack is returned unchanged.\n\nThe check must belong to a purchase order (`422` for metadata-only checks). The endpoint\ndoes not require the check to have passed. A pack can be built for a failed check too,\nfor example to document an exception.\n\nPacks are created automatically when a scan passes, and when the last blocking violation\nis justified. You mainly need this endpoint to build a pack on demand or to refresh one.\nPoll `GET /compliance/evidence_packs/:id` until `zip_status` is `zip_ready`, or listen for\n`evidence_pack_ready` on `ComplianceCheckChannel`.\n\n\nV1 only. `POST /api/v3/compliance/evidence_packs` returns `404 {\"error\": \"Invalid URL\"}`.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "evidence_pack": { "type": "object", "properties": { "id": { "type": "integer" }, "compliance_check_id": { "type": "integer" }, "purchase_order_id": { "type": "integer" }, "po_snapshot": { "type": "object", "properties": { } }, "attachments_metadata": { "type": "array", "items": { } }, "audit_log": { "type": "array", "items": { } }, "zip_status": { "type": "string" }, "zip_error": { "type": "null" }, "zip_file_name": { "type": "null" }, "zip_file_size": { "type": "null" }, "zip_updated_at": { "type": "null" }, "download_url": { "type": "null" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } } }, "example": { "message": "Evidence pack generation started", "evidence_pack": { "id": 4, "compliance_check_id": 4, "purchase_order_id": 26, "po_snapshot": { }, "attachments_metadata": [ ], "audit_log": [ ], "zip_status": "zip_pending", "zip_error": null, "zip_file_name": null, "zip_file_size": null, "zip_updated_at": null, "download_url": null, "created_at": "2026-10-21T05:07:15.146-05:00", "updated_at": "2026-10-21T05:07:15.146-05:00" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "example": { "error": "Cannot create evidence pack: no associated purchase order" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "compliance_check_id": { "type": "integer", "description": "Compliance check id (top level). Found in the scan result `id`, `results_data[].compliance_check_id` or `latest_compliance_check.id` on the order." } }, "required": [ "compliance_check_id" ] }, "example": { "compliance_check_id": 4 } } } } } }, "/api/v1/compliance/evidence_packs/{id}": { "get": { "tags": [ "Compliance" ], "operationId": "v1_evidence_packs_show", "summary": "Get an evidence pack", "description": "Returns an evidence pack with its purchase order snapshot and ZIP status.\n\nReturns the pack. `po_snapshot` and `attachments_metadata` describe the order at the\ntime the ZIP was last built. When `zip_status` is `zip_ready`, `download_url` is the API\npath to call for a signed download link.\n\n\nV1 only. `GET /api/v3/compliance/evidence_packs/:id` returns `404 {\"error\": \"Invalid URL\"}`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Evidence pack id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "evidence_pack": { "type": "object", "properties": { "id": { "type": "integer" }, "compliance_check_id": { "type": "integer" }, "purchase_order_id": { "type": "integer" }, "po_snapshot": { "type": "object", "properties": { "id": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "total": { "type": "number" }, "quantity": { "type": "number" }, "unit_price": { "type": "number" }, "description": { "type": "string" } } } }, "status": { "type": "string" }, "creator": { "type": "string" }, "currency": { "type": "string" }, "supplier": { "type": "string" }, "po_number": { "type": "null" }, "created_at": { "type": "string" }, "department": { "type": "string" }, "net_amount": { "type": "number" }, "approved_at": { "type": "string" }, "budget_name": { "type": "string" }, "supplier_id": { "type": "integer" }, "total_amount": { "type": "number" } } }, "attachments_metadata": { "type": "array", "items": { } }, "audit_log": { "type": "array", "items": { } }, "zip_status": { "type": "string" }, "zip_error": { "type": "null" }, "zip_file_name": { "type": "string" }, "zip_file_size": { "type": "integer" }, "zip_updated_at": { "type": "string" }, "download_url": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } } }, "example": { "evidence_pack": { "id": 1, "compliance_check_id": 2, "purchase_order_id": 23, "po_snapshot": { "id": 23, "items": [ { "total": 1800.0, "quantity": 6.0, "unit_price": 300.0, "description": "Ergonomic office chair" } ], "status": "pending", "creator": "Jane Doe", "currency": "USD", "supplier": "Northwind Office Supplies", "po_number": null, "created_at": "2026-10-21T05:01:58-05:00", "department": "Operations", "net_amount": 1800.0, "approved_at": "2026-10-21T05:08:18-05:00", "budget_name": "Office Supplies", "supplier_id": 1, "total_amount": 1800.0 }, "attachments_metadata": [ ], "audit_log": [ ], "zip_status": "zip_ready", "zip_error": null, "zip_file_name": "PO-23-20000-20261021_050818-compliance-evidence-pack.zip", "zip_file_size": 47577, "zip_updated_at": "2026-10-21T05:08:18.603-05:00", "download_url": "/api/v1/compliance/evidence_packs/1/download", "created_at": "2026-10-21T05:04:32.504-05:00", "updated_at": "2026-10-21T05:08:19.621-05:00" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v1/compliance/evidence_packs/{id}/download": { "get": { "tags": [ "Compliance" ], "operationId": "v1_evidence_packs_download", "summary": "Download an evidence pack", "description": "Returns a short-lived signed URL for the evidence pack ZIP.\n\nReturns a pre-signed storage URL for the ZIP, valid for **8 hours**. Fetch it with a\nplain `GET`, without the API headers. The file is served as an attachment\n(`application/octet-stream`).\n\nThe ZIP must be `zip_ready`. While it is pending, building or failed, the endpoint\nanswers `422`, with the current `zip_status` in the `status` field. A rebuild\n(`regenerate`, or a new justification) also makes the previous ZIP unavailable until the\nnew one is ready.\n\n\nV1 only. `GET /api/v3/compliance/evidence_packs/:id/download` returns `404 {\"error\": \"Invalid URL\"}`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Evidence pack id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "download_url": { "type": "string" }, "file_name": { "type": "string" }, "file_size": { "type": "integer" } } }, "example": { "download_url": "https://pex-files.s3.amazonaws.com/evidence_packs/1/PO-23-20000-20261021_050818-compliance-evidence-pack.zip?response-content-disposition=attachment%3B%20filename%3D%22PO-23-20000-20261021_050818-compliance-evidence-pack.zip%22%3B%20filename%2A%3DUTF-8%27%27PO-23-20000-20261021_050818-compliance-evidence-pack.zip&response-content-type=application%2Foctet-stream&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20261021%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20261021T100825Z&X-Amz-Expires=28800&X-Amz-SignedHeaders=host&X-Amz-Signature=d4a6d0e44027b962f7dca889a568d62b75bc114ce6fda6a17e26e2ad303ab582", "file_name": "PO-23-20000-20261021_050818-compliance-evidence-pack.zip", "file_size": 47577 } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "example": { "error": "Evidence pack is not ready for download", "status": "zip_pending" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v1/compliance/evidence_packs/{id}/regenerate": { "post": { "tags": [ "Compliance" ], "operationId": "v1_evidence_packs_regenerate", "summary": "Rebuild an evidence pack", "description": "Rebuilds an evidence pack's snapshot and ZIP from the current state of the purchase order.\n\nResets the pack to `zip_pending` and queues a rebuild. The rebuild takes a new snapshot\nof the order and its attachments, re-renders the PDF, includes the full scan history and\nreplaces the ZIP. Use it after attachments were added or violations were justified. No\nrequest body is needed.\n\nThe previous ZIP stays in the pack record (`zip_file_name`, `zip_file_size`), but\n`download_url` is `null` and the download endpoint answers `422` until the new ZIP is ready.\n\n\nV1 only. `POST /api/v3/compliance/evidence_packs/:id/regenerate` returns `404 {\"error\": \"Invalid URL\"}`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Evidence pack id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "evidence_pack": { "type": "object", "properties": { "id": { "type": "integer" }, "compliance_check_id": { "type": "integer" }, "purchase_order_id": { "type": "integer" }, "po_snapshot": { "type": "object", "properties": { "id": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "total": { "type": "number" }, "quantity": { "type": "number" }, "unit_price": { "type": "number" }, "description": { "type": "string" } } } }, "status": { "type": "string" }, "creator": { "type": "string" }, "currency": { "type": "string" }, "supplier": { "type": "string" }, "po_number": { "type": "null" }, "created_at": { "type": "string" }, "department": { "type": "string" }, "net_amount": { "type": "number" }, "approved_at": { "type": "string" }, "budget_name": { "type": "string" }, "supplier_id": { "type": "integer" }, "total_amount": { "type": "number" } } }, "attachments_metadata": { "type": "array", "items": { } }, "audit_log": { "type": "array", "items": { } }, "zip_status": { "type": "string" }, "zip_error": { "type": "null" }, "zip_file_name": { "type": "string" }, "zip_file_size": { "type": "integer" }, "zip_updated_at": { "type": "string" }, "download_url": { "type": "null" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } } }, "example": { "message": "Evidence pack regeneration started", "evidence_pack": { "id": 1, "compliance_check_id": 2, "purchase_order_id": 23, "po_snapshot": { "id": 23, "items": [ { "total": 1800.0, "quantity": 6.0, "unit_price": 300.0, "description": "Ergonomic office chair" } ], "status": "pending", "creator": "Jane Doe", "currency": "USD", "supplier": "Northwind Office Supplies", "po_number": null, "created_at": "2026-10-21T05:01:58-05:00", "department": "Operations", "net_amount": 1800.0, "approved_at": "2026-10-21T05:08:18-05:00", "budget_name": "Office Supplies", "supplier_id": 1, "total_amount": 1800.0 }, "attachments_metadata": [ ], "audit_log": [ ], "zip_status": "zip_pending", "zip_error": null, "zip_file_name": "PO-23-20000-20261021_050818-compliance-evidence-pack.zip", "zip_file_size": 47577, "zip_updated_at": "2026-10-21T05:08:18.603-05:00", "download_url": null, "created_at": "2026-10-21T05:04:32.504-05:00", "updated_at": "2026-10-21T05:08:40.304-05:00" } } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "example": { "error": "Evidence pack is currently being generated" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/currencies": { "get": { "tags": [ "Currencies" ], "operationId": "v3_currencies_list", "summary": "List the company's currencies", "description": "Currencies enabled for the company in app_company_id, default currency first.\n\nReturns the company's default currency followed by its other supported\ncurrencies (company settings). These are the currencies users can pick on\npurchase orders and budgets in that company.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "iso_code": { "type": "string" }, "iso_numeric": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } }, "example": [ { "id": 2000, "iso_code": "USD", "iso_numeric": "840", "name": "United States Dollar", "symbol": "$", "created_at": "2026-10-21T04:44:44.793-05:00", "updated_at": "2026-10-21T04:44:44.793-05:00" }, { "id": 1000, "iso_code": "EUR", "iso_numeric": "978", "name": "Euro", "symbol": "€", "created_at": "2026-10-21T04:44:44.790-05:00", "updated_at": "2026-10-21T04:44:44.790-05:00" } ] } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "App company id is nil", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/currencies": { "get": { "tags": [ "Currencies" ], "operationId": "v1_currencies_list", "summary": "List the company's currencies", "description": "Currencies enabled for the company in app_company_id, default currency first.\n\nReturns the company's default currency followed by its other supported\ncurrencies (company settings). These are the currencies users can pick on\npurchase orders and budgets in that company.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "iso_code": { "type": "string" }, "iso_numeric": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } }, "example": [ { "id": 2000, "iso_code": "USD", "iso_numeric": "840", "name": "United States Dollar", "symbol": "$", "created_at": "2026-10-21T04:44:44.793-05:00", "updated_at": "2026-10-21T04:44:44.793-05:00" }, { "id": 1000, "iso_code": "EUR", "iso_numeric": "978", "name": "Euro", "symbol": "€", "created_at": "2026-10-21T04:44:44.790-05:00", "updated_at": "2026-10-21T04:44:44.790-05:00" } ] } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "App company id is nil", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/all_currencies": { "get": { "tags": [ "Currencies" ], "operationId": "v3_currencies_all", "summary": "List all currencies", "description": "Every currency known to ProcurementExpress; works without authentication.\n\nReturns all currencies. No credential or company header is needed.\n\n* Anonymous (or not a live member of the `app_company_id` company): every currency,\n ordered by ISO code.\n* Authenticated **and** `app_company_id` names a company you are a live member of:\n the (up to four) currencies most used on that company's purchase orders come\n first, then the rest; both groups are ordered by ISO code.\n\nThe answer never reveals whether a company id exists.\n\n\nNone - identical request and response. (V3 additionally ignores an expired or\nrevoked bearer token, treating the request as anonymous.)", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "iso_code": { "type": "string" }, "iso_numeric": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } }, "example": [ { "id": 1000, "iso_code": "EUR", "iso_numeric": "978", "name": "Euro", "symbol": "€", "created_at": "2026-10-21T04:44:44.790-05:00", "updated_at": "2026-10-21T04:44:44.790-05:00" }, { "id": 2000, "iso_code": "USD", "iso_numeric": "840", "name": "United States Dollar", "symbol": "$", "created_at": "2026-10-21T04:44:44.793-05:00", "updated_at": "2026-10-21T04:44:44.793-05:00" } ] } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/all_currencies": { "get": { "tags": [ "Currencies" ], "operationId": "v1_currencies_all", "summary": "List all currencies", "description": "Every currency known to ProcurementExpress; works without authentication.\n\nReturns all currencies. No credential or company header is needed.\n\n* Anonymous (or not a live member of the `app_company_id` company): every currency,\n ordered by ISO code.\n* Authenticated **and** `app_company_id` names a company you are a live member of:\n the (up to four) currencies most used on that company's purchase orders come\n first, then the rest; both groups are ordered by ISO code.\n\nThe answer never reveals whether a company id exists.\n\n\nNone - identical request and response. (V3 additionally ignores an expired or\nrevoked bearer token, treating the request as anonymous.)", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "iso_code": { "type": "string" }, "iso_numeric": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } }, "example": [ { "id": 1000, "iso_code": "EUR", "iso_numeric": "978", "name": "Euro", "symbol": "€", "created_at": "2026-10-21T04:44:44.790-05:00", "updated_at": "2026-10-21T04:44:44.790-05:00" }, { "id": 2000, "iso_code": "USD", "iso_numeric": "840", "name": "United States Dollar", "symbol": "$", "created_at": "2026-10-21T04:44:44.793-05:00", "updated_at": "2026-10-21T04:44:44.793-05:00" } ] } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v1/custom_fields": { "get": { "tags": [ "Custom Fields" ], "operationId": "v1_custom_fields_list", "summary": "List custom fields", "description": "List the company's custom field definitions.\n\nReturns the company's custom field definitions ordered by `position`, without pagination.\nBy default only active and inactive **PO header** fields that are not archived are returned.\n\n\nV1 only. There is no V3 route: `GET /api/v3/custom_fields` returns\n`404 {\"error\": \"Invalid URL\"}`.", "parameters": [ { "name": "context", "in": "query", "required": false, "description": "`purchase_order` (default): PO header fields; `line_item`: PO line item fields; any other value (e.g. `all`): every field of the company, including invoice, budget, supplier, product and RFQ fields.", "schema": { "type": "string" } }, { "name": "include_archived", "in": "query", "required": false, "description": "`true` also returns archived (deleted) fields.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "field_type": { "type": "string" }, "active": { "type": "boolean" }, "required": { "type": "boolean" }, "options": { "type": "array", "items": { } }, "access_level": { "type": "string" }, "position": { "type": "integer" }, "on_line_item": { "type": "boolean" }, "display_on_pdf": { "type": "boolean" }, "default_value": { "type": "null" }, "editable_after_approval": { "type": "null" }, "readonly": { "type": "boolean" }, "archived": { "type": "boolean" }, "formula_builder": { "type": "null" }, "precision_display": { "type": "integer" }, "display_on_pdf_even_if_value_is_nil": { "type": "boolean" }, "option_list": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "webhook_enabled": { "type": "boolean" }, "response_populated": { "type": "boolean" }, "payload_included": { "type": "boolean" }, "is_auto_populated": { "type": "boolean" }, "show_on_receiving": { "type": "boolean" } } } }, "example": [ { "id": 1, "company_id": 20000, "name": "Project code", "field_type": "string", "active": true, "required": false, "options": [ ], "access_level": "everyone", "position": 0, "on_line_item": false, "display_on_pdf": true, "default_value": null, "editable_after_approval": null, "readonly": false, "archived": false, "formula_builder": null, "precision_display": 2, "display_on_pdf_even_if_value_is_nil": true, "option_list": "", "created_at": "2026-10-21T04:48:43.644-05:00", "updated_at": "2026-10-21T04:48:43.644-05:00", "webhook_enabled": false, "response_populated": false, "payload_included": false, "is_auto_populated": false, "show_on_receiving": false }, { "id": 2, "company_id": 20000, "name": "Cost center", "field_type": "select", "active": true, "required": false, "options": [ "CC-100 Engineering", "CC-200 Marketing", "CC-300 Operations" ], "access_level": "everyone", "position": 1, "on_line_item": false, "display_on_pdf": true, "default_value": null, "editable_after_approval": null, "readonly": false, "archived": false, "formula_builder": null, "precision_display": 2, "display_on_pdf_even_if_value_is_nil": true, "option_list": "CC-100 Engineering\nCC-200 Marketing\nCC-300 Operations", "created_at": "2026-10-21T04:49:01.957-05:00", "updated_at": "2026-10-21T04:49:01.957-05:00", "webhook_enabled": false, "response_populated": false, "payload_included": false, "is_auto_populated": false, "show_on_receiving": false } ] } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "post": { "tags": [ "Custom Fields" ], "operationId": "v1_custom_fields_create", "summary": "Create a custom field", "description": "Create a PO header or line item custom field.\n\nCreates a custom field at the end of the list (`position` = number of fields). Only PO header\nfields and PO line item fields (`on_line_item: true`) can be created through the API; scope\nflags such as `on_budget` or `on_invoice` are ignored.\n\nValidation (`400` with an array of messages): `name` present and unique within the scope\n(`\"Name Already exist\"`), `field_type` one of the types listed above\n(`\"Field type is not included in the list\"`), `option_list` required for `select`, each option\nmax 255 characters, `default_value` must be one of the options, `formula_builder` required\nand valid for `computed`.\n\nA new **active** header or line item field is immediately added (with its default value or\n`\"Not Set\"`) to every purchase order created afterwards; a required one blocks submitting\nPOs that do not supply it.\n\n\nV1 only; there is no V3 route (`/api/v3/custom_fields` -> `404 Invalid URL`).", "parameters": [ ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "field_type": { "type": "string" }, "active": { "type": "boolean" }, "required": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "string" } }, "access_level": { "type": "string" }, "position": { "type": "integer" }, "on_line_item": { "type": "boolean" }, "display_on_pdf": { "type": "boolean" }, "default_value": { "type": "string" }, "editable_after_approval": { "type": "boolean" }, "readonly": { "type": "boolean" }, "archived": { "type": "boolean" }, "formula_builder": { "type": "null" }, "precision_display": { "type": "integer" }, "display_on_pdf_even_if_value_is_nil": { "type": "boolean" }, "option_list": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "webhook_enabled": { "type": "boolean" }, "response_populated": { "type": "boolean" }, "payload_included": { "type": "boolean" }, "is_auto_populated": { "type": "boolean" }, "show_on_receiving": { "type": "boolean" } } }, "example": { "id": 5, "company_id": 20000, "name": "Delivery priority", "field_type": "select", "active": true, "required": true, "options": [ "Standard", "Express", "Overnight" ], "access_level": "everyone", "position": 5, "on_line_item": false, "display_on_pdf": true, "default_value": "Standard", "editable_after_approval": true, "readonly": false, "archived": false, "formula_builder": null, "precision_display": 2, "display_on_pdf_even_if_value_is_nil": true, "option_list": "Standard\nExpress\nOvernight", "created_at": "2026-10-21T05:08:04.628-05:00", "updated_at": "2026-10-21T05:08:04.628-05:00", "webhook_enabled": false, "response_populated": false, "payload_included": false, "is_auto_populated": false, "show_on_receiving": false } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Option list can't be blank (you may be seeing placeholder text instead of actual content)" ], "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "custom_field[name]": { "type": "string", "description": "Field label (truncated to 255 characters)." }, "custom_field[field_type]": { "type": "string", "description": "`label`, `string`, `select`, `date`, `tel`, `text`, `decimal`, `boolean`, `url`, `long_list` or `computed`." }, "custom_field[option_list]": { "type": "string", "description": "Options of a `select`, one per line (`\"Standard\\nExpress\\nOvernight\"`). Required for `select`." }, "custom_field[default_value]": { "type": "string", "description": "Default for new POs; must be one of the options for `select`." }, "custom_field[required]": { "type": "boolean", "description": "Value required on submit." }, "custom_field[active]": { "type": "boolean", "description": "Inactive fields are hidden and not added to new POs." }, "custom_field[access_level]": { "type": "string", "description": "`everyone`, `approvers_and_finance` or `finance_only`; any other value is ignored." }, "custom_field[on_line_item]": { "type": "boolean", "description": "`true` for a PO line item field." }, "custom_field[display_on_pdf]": { "type": "boolean", "description": "Print on the PO PDF." }, "custom_field[display_on_pdf_even_if_value_is_nil]": { "type": "boolean", "description": "Print even when empty." }, "custom_field[editable_after_approval]": { "type": "boolean", "description": "Allow changing the value after approval." }, "custom_field[formula_builder]": { "type": "string", "description": "Formula for `computed` fields, e.g. `{{Annual budget}} / 12`." }, "custom_field[precision_display]": { "type": "integer", "description": "Decimals displayed for numeric fields." }, "custom_field[show_on_receiving]": { "type": "boolean", "description": "Show on the receiving screen." }, "custom_field[archived]": { "type": "boolean", "description": "Create the field archived (rarely useful)." } }, "required": [ "custom_field[name]", "custom_field[field_type]" ] }, "example": { "custom_field": { "name": "Delivery priority", "field_type": "select", "option_list": "Standard\nExpress\nOvernight", "default_value": "Standard", "required": true, "access_level": "everyone", "on_line_item": false, "display_on_pdf": true, "editable_after_approval": true } } } } } } }, "/api/v1/custom_fields/{id}": { "get": { "tags": [ "Custom Fields" ], "operationId": "v1_custom_fields_show", "summary": "Get a custom field", "description": "Get one custom field definition (archived fields included).\n\nReturns one custom field of the company, also when it is archived.\n\n\nV1 only; `GET /api/v3/custom_fields/:id` returns `404 {\"error\": \"Invalid URL\"}`\n.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Custom field id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "field_type": { "type": "string" }, "active": { "type": "boolean" }, "required": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "string" } }, "access_level": { "type": "string" }, "position": { "type": "integer" }, "on_line_item": { "type": "boolean" }, "display_on_pdf": { "type": "boolean" }, "default_value": { "type": "null" }, "editable_after_approval": { "type": "null" }, "readonly": { "type": "boolean" }, "archived": { "type": "boolean" }, "formula_builder": { "type": "null" }, "precision_display": { "type": "integer" }, "display_on_pdf_even_if_value_is_nil": { "type": "boolean" }, "option_list": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "webhook_enabled": { "type": "boolean" }, "response_populated": { "type": "boolean" }, "payload_included": { "type": "boolean" }, "is_auto_populated": { "type": "boolean" }, "show_on_receiving": { "type": "boolean" } } }, "example": { "id": 2, "company_id": 20000, "name": "Cost center", "field_type": "select", "active": true, "required": false, "options": [ "CC-100 Engineering", "CC-200 Marketing", "CC-300 Operations" ], "access_level": "everyone", "position": 1, "on_line_item": false, "display_on_pdf": true, "default_value": null, "editable_after_approval": null, "readonly": false, "archived": false, "formula_builder": null, "precision_display": 2, "display_on_pdf_even_if_value_is_nil": true, "option_list": "CC-100 Engineering\nCC-200 Marketing\nCC-300 Operations", "created_at": "2026-10-21T04:49:01.957-05:00", "updated_at": "2026-10-21T04:49:01.957-05:00", "webhook_enabled": false, "response_populated": false, "payload_included": false, "is_auto_populated": false, "show_on_receiving": false } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "put": { "tags": [ "Custom Fields" ], "operationId": "v1_custom_fields_update", "summary": "Update a custom field", "description": "Change a custom field definition.\n\nUpdates the given attributes (same parameters and validation as create; omitted attributes\nare unchanged). Archived fields can be updated too - send `archived: false` to restore one.\nRenaming a field also renames it in the company's PO list column settings. A field used in a\ncomputed formula cannot be renamed, deactivated or change type or access level, and a field\nused in the PO number sequence cannot be made optional or inactive.\n\n\nV1 only; there is no V3 route.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Custom field id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "field_type": { "type": "string" }, "active": { "type": "boolean" }, "required": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "string" } }, "access_level": { "type": "string" }, "position": { "type": "integer" }, "on_line_item": { "type": "boolean" }, "display_on_pdf": { "type": "boolean" }, "default_value": { "type": "string" }, "editable_after_approval": { "type": "null" }, "readonly": { "type": "boolean" }, "archived": { "type": "boolean" }, "formula_builder": { "type": "null" }, "precision_display": { "type": "integer" }, "display_on_pdf_even_if_value_is_nil": { "type": "boolean" }, "option_list": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "webhook_enabled": { "type": "boolean" }, "response_populated": { "type": "boolean" }, "payload_included": { "type": "boolean" }, "is_auto_populated": { "type": "boolean" }, "show_on_receiving": { "type": "boolean" } } }, "example": { "id": 6, "company_id": 20000, "name": "Requested delivery window", "field_type": "select", "active": false, "required": false, "options": [ "Morning", "Afternoon", "Evening" ], "access_level": "approvers_and_finance", "position": 6, "on_line_item": false, "display_on_pdf": false, "default_value": "Morning", "editable_after_approval": null, "readonly": false, "archived": false, "formula_builder": null, "precision_display": 2, "display_on_pdf_even_if_value_is_nil": true, "option_list": "Morning\nAfternoon\nEvening", "created_at": "2026-10-21T05:08:40.605-05:00", "updated_at": "2026-10-21T05:09:05.856-05:00", "webhook_enabled": false, "response_populated": false, "payload_included": false, "is_auto_populated": false, "show_on_receiving": false } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Default value must be one of the options in the option list" ], "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "custom_field[...]": { "type": "object", "description": "Any of the create parameters (`name`, `field_type`, `option_list`, `default_value`, `required`, `active`, `access_level`, `on_line_item`, `display_on_pdf`, `display_on_pdf_even_if_value_is_nil`, `editable_after_approval`, `formula_builder`, `precision_display`, `show_on_receiving`, `archived`)." } }, "required": [ "custom_field[...]" ] }, "example": { "custom_field": { "name": "Requested delivery window", "field_type": "select", "option_list": "Morning\nAfternoon\nEvening", "default_value": "Morning", "access_level": "approvers_and_finance", "display_on_pdf": false } } } } } }, "delete": { "tags": [ "Custom Fields" ], "operationId": "v1_custom_fields_destroy", "summary": "Delete (archive) a custom field", "description": "Archive a custom field.\n\nSoft-deletes the field by setting `archived: true`: it disappears from the list (unless\n`include_archived=true`) and from forms, while values already stored on purchase orders are\nkept. Restore it with [Update a custom field](#update-a-custom-field) (`archived: false`).\n\n\nV1 only; `DELETE /api/v3/custom_fields/:id` returns `404 {\"error\": \"Invalid URL\"}`\n.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Custom field id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "archived": { "type": "boolean" } } }, "example": { "archived": true } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v1/custom_fields/update_positions": { "patch": { "tags": [ "Custom Fields" ], "operationId": "v1_custom_fields_update_positions", "summary": "Reorder custom fields", "description": "Set the display position of several custom fields at once.\n\nSets `position` for each field id in `positions`. Ids that are not fields of the company are\nignored; fields not listed keep their position. Only `PATCH` works - `PUT` is routed to\n[Update a custom field](#update-a-custom-field) with id `update_positions` and returns `404`.\n\n\nV1 only; `PATCH /api/v3/custom_fields/update_positions` returns `404 Invalid URL`\n.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "positions": { "type": "object", "description": "Map of custom field id to new position, e.g. `{\"6\": 5, \"5\": 6}`." } }, "required": [ "positions" ] }, "example": { "positions": { "6": 5, "5": 6 } } } } } } }, "/api/v3/custom_field_values": { "post": { "tags": [ "Custom Fields" ], "operationId": "v3_custom_field_values_create", "summary": "Set a custom field value", "description": "Set the value of one custom field on a purchase order or a PO line.\n\nWrites a single custom field value without editing the whole purchase order (the web app's\ninline editor). For a PO header field send `purchase_order_id`; for a line item field send\n`purchase_order_item_id`.\n\n**Pass the value's `id`.** Purchase orders already hold a value row for every active field\n(created with the PO), so in practice you update an existing row: take its `id` from\n`custom_field_values[]` / `purchase_order_items[].custom_field_values[]` in the PO details.\nWithout `id` a new row is created - this only works for a header field the PO has no value for\nyet (for example a field added after the PO was created); otherwise the request fails with a\n`500`. An `id` belonging to another PO or line returns `404`.\n\nValues are stored as strings; `select` values are not checked against the options. A changed\nvalue adds an audit comment to the PO (`\"Cost center changed from Not Set to CC-300 Operations\"`).\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "purchase_order_id": { "type": "integer" }, "value": { "type": "string" }, "custom_field_id": { "type": "integer" }, "purchase_order_item_id": { "type": "null" }, "date_format": { "type": "null" }, "budget_id": { "type": "null" } } }, "example": { "id": 47, "purchase_order_id": 12, "value": "CC-300 Operations", "custom_field_id": 2, "purchase_order_item_id": null, "date_format": null, "budget_id": null } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "custom_field_id is required", "status": 400 } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 403 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "custom_field_value[custom_field_id]": { "type": "integer", "description": "Custom field id (`400 \"custom_field_id is required\"` when missing/unknown)." }, "custom_field_value[purchase_order_id]": { "type": "integer", "description": "Purchase order id - required for header fields." }, "custom_field_value[purchase_order_item_id]": { "type": "integer", "description": "Purchase order item id - required for line item fields." }, "custom_field_value[id]": { "type": "integer", "description": "Existing value id to update (recommended)." }, "custom_field_value[value]": { "type": "string", "description": "New value. `string` max 255 characters; dates in the company date format; booleans `1`/`0` or `true`/`false`." } }, "required": [ "custom_field_value[custom_field_id]", "custom_field_value[value]" ] }, "example": { "custom_field_value": { "id": 47, "custom_field_id": 2, "purchase_order_id": 12, "value": "CC-300 Operations" } } } } } } }, "/api/v1/custom_field_values": { "post": { "tags": [ "Custom Fields" ], "operationId": "v1_custom_field_values_create", "summary": "Set a custom field value", "description": "Set the value of one custom field on a purchase order or a PO line.\n\nWrites a single custom field value without editing the whole purchase order (the web app's\ninline editor). For a PO header field send `purchase_order_id`; for a line item field send\n`purchase_order_item_id`.\n\n**Pass the value's `id`.** Purchase orders already hold a value row for every active field\n(created with the PO), so in practice you update an existing row: take its `id` from\n`custom_field_values[]` / `purchase_order_items[].custom_field_values[]` in the PO details.\nWithout `id` a new row is created - this only works for a header field the PO has no value for\nyet (for example a field added after the PO was created); otherwise the request fails with a\n`500`. An `id` belonging to another PO or line returns `404`.\n\nValues are stored as strings; `select` values are not checked against the options. A changed\nvalue adds an audit comment to the PO (`\"Cost center changed from Not Set to CC-300 Operations\"`).\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "purchase_order_id": { "type": "integer" }, "value": { "type": "string" }, "custom_field_id": { "type": "integer" }, "purchase_order_item_id": { "type": "null" }, "date_format": { "type": "null" }, "budget_id": { "type": "null" } } }, "example": { "id": 43, "purchase_order_id": 11, "value": "CC-300 Operations", "custom_field_id": 2, "purchase_order_item_id": null, "date_format": null, "budget_id": null } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "custom_field_id is required", "status": 400 } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 403 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "custom_field_value[custom_field_id]": { "type": "integer", "description": "Custom field id (`400 \"custom_field_id is required\"` when missing/unknown)." }, "custom_field_value[purchase_order_id]": { "type": "integer", "description": "Purchase order id - required for header fields." }, "custom_field_value[purchase_order_item_id]": { "type": "integer", "description": "Purchase order item id - required for line item fields." }, "custom_field_value[id]": { "type": "integer", "description": "Existing value id to update (recommended)." }, "custom_field_value[value]": { "type": "string", "description": "New value. `string` max 255 characters; dates in the company date format; booleans `1`/`0` or `true`/`false`." } }, "required": [ "custom_field_value[custom_field_id]", "custom_field_value[value]" ] }, "example": { "custom_field_value": { "id": 43, "custom_field_id": 2, "purchase_order_id": 11, "value": "CC-300 Operations" } } } } } } }, "/api/v3/departments": { "get": { "tags": [ "Departments" ], "operationId": "v3_departments_list", "summary": "List departments", "description": "Lists the caller's departments, or all departments of the company.\n\nBy default returns the departments the caller is assigned to in the\nheader company. With `company_specific=true` returns every department\nof the company.\n\nArchived departments are excluded unless `archived=true`, which returns\n**only** archived departments (there is no \"both\" option).\n\nWith `company_specific=true`, callers who are not `companyadmin` or\n`finance` receive only `id`, `name` and `archived` for each department.\n\nResults are sorted by name and are not paginated. There is no search\nparameter.\n\n\nNone - identical request and response.", "parameters": [ { "name": "company_specific", "in": "query", "required": false, "description": "`true` returns all departments of the company instead of only the caller's. Any other value means false.", "schema": { "type": "boolean" } }, { "name": "archived", "in": "query", "required": false, "description": "`true` returns only archived departments; anything else returns only non-archived ones.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "archived": { "type": "boolean" }, "contact_person": { "type": "null" }, "tax_number": { "type": "null" }, "phone_number": { "type": "null" }, "address": { "type": "null" }, "email": { "type": "null" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "supplier_ids": { "type": "array", "items": { } }, "budget_ids": { "type": "array", "items": { "type": "integer" } } } } }, "example": [ { "id": 5, "name": "Approval Flow Lab", "company_id": 20000, "archived": false, "contact_person": null, "tax_number": null, "phone_number": null, "address": null, "email": null, "created_at": "2026-10-21T04:58:54.413-05:00", "updated_at": "2026-10-21T04:58:54.413-05:00", "supplier_ids": [ ], "budget_ids": [ 4 ] }, { "id": 2, "name": "Engineering", "company_id": 20000, "archived": false, "contact_person": "Jane Doe", "tax_number": "US-EN-001", "phone_number": "+1 555 0110", "address": "100 Main Street, Springfield, IL 62701", "email": "engineering@example.com", "created_at": "2026-10-21T04:48:42.702-05:00", "updated_at": "2026-10-21T04:48:42.702-05:00", "supplier_ids": [ 4, 5 ], "budget_ids": [ 1, 5, 6, 10 ] } ] } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] }, "post": { "tags": [ "Departments" ], "operationId": "v3_departments_create", "summary": "Create a department", "description": "Creates a department in the header company and optionally links budgets and assigns users.\n\nCreates a department. `budget_ids` links budgets of the same company;\n`user_ids` assigns active members of the company to the new department\n(added to each user's department list).\n\nContact fields (`contact_person`, `phone_number`, `email`, `address`,\n`tax_number`) are free text - phone and email are **not**\nformat-validated (`phone_number` max 30 and `name` max 60 characters\nwhen a Sage integration is connected).\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "supplier_ids": { "type": "array", "items": { } }, "budget_ids": { "type": "array", "items": { "type": "integer" } } } }, "example": { "id": 17, "name": "Procurement", "company_id": 20000, "archived": false, "contact_person": "Jane Doe", "tax_number": "US-PR-003", "phone_number": "+1 555 0130", "address": "300 Supply Road, Springfield, IL 62701", "email": "procurement@example.com", "created_at": "2026-10-21T05:05:36.987-05:00", "updated_at": "2026-10-21T05:05:36.987-05:00", "supplier_ids": [ ], "budget_ids": [ 3 ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Name has already registered" ], "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "department[name]": { "type": "string", "description": "1-255 characters, unique in the company (case-sensitive)." }, "department[archived]": { "type": "boolean", "description": "Create already archived. Default false." }, "department[contact_person]": { "type": "string", "description": "Contact name." }, "department[phone_number]": { "type": "string", "description": "Phone number (free text)." }, "department[email]": { "type": "string", "description": "Email (free text, not validated)." }, "department[address]": { "type": "string", "description": "Address." }, "department[tax_number]": { "type": "string", "description": "Tax/VAT number." }, "department[budget_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Budgets to link; each must belong to the header company (`Budget ids is invalid` otherwise)." }, "department[user_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Users to assign; each must be an active member of the header company (`User ids is invalid` otherwise). Not returned in the response." } }, "required": [ "department[name]" ] }, "example": { "department": { "name": "Procurement", "contact_person": "Jane Doe", "phone_number": "+1 555 0130", "email": "procurement@example.com", "address": "300 Supply Road, Springfield, IL 62701", "tax_number": "US-PR-003", "budget_ids": [ 3 ], "user_ids": [ 40000 ] } } } } } } }, "/api/v1/departments": { "get": { "tags": [ "Departments" ], "operationId": "v1_departments_list", "summary": "List departments", "description": "Lists the caller's departments, or all departments of the company.\n\nBy default returns the departments the caller is assigned to in the\nheader company. With `company_specific=true` returns every department\nof the company.\n\nArchived departments are excluded unless `archived=true`, which returns\n**only** archived departments (there is no \"both\" option).\n\nWith `company_specific=true`, callers who are not `companyadmin` or\n`finance` receive only `id`, `name` and `archived` for each department.\n\nResults are sorted by name and are not paginated. There is no search\nparameter.\n\n\nNone - identical request and response.", "parameters": [ { "name": "company_specific", "in": "query", "required": false, "description": "`true` returns all departments of the company instead of only the caller's. Any other value means false.", "schema": { "type": "boolean" } }, { "name": "archived", "in": "query", "required": false, "description": "`true` returns only archived departments; anything else returns only non-archived ones.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "archived": { "type": "boolean" }, "contact_person": { "type": "null" }, "tax_number": { "type": "null" }, "phone_number": { "type": "null" }, "address": { "type": "null" }, "email": { "type": "null" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "supplier_ids": { "type": "array", "items": { } }, "budget_ids": { "type": "array", "items": { "type": "integer" } } } } }, "example": [ { "id": 5, "name": "Approval Flow Lab", "company_id": 20000, "archived": false, "contact_person": null, "tax_number": null, "phone_number": null, "address": null, "email": null, "created_at": "2026-10-21T04:58:54.413-05:00", "updated_at": "2026-10-21T04:58:54.413-05:00", "supplier_ids": [ ], "budget_ids": [ 4 ] }, { "id": 2, "name": "Engineering", "company_id": 20000, "archived": false, "contact_person": "Jane Doe", "tax_number": "US-EN-001", "phone_number": "+1 555 0110", "address": "100 Main Street, Springfield, IL 62701", "email": "engineering@example.com", "created_at": "2026-10-21T04:48:42.702-05:00", "updated_at": "2026-10-21T04:48:42.702-05:00", "supplier_ids": [ 4, 5 ], "budget_ids": [ 1, 5, 6, 10 ] } ] } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "post": { "tags": [ "Departments" ], "operationId": "v1_departments_create", "summary": "Create a department", "description": "Creates a department in the header company and optionally links budgets and assigns users.\n\nCreates a department. `budget_ids` links budgets of the same company;\n`user_ids` assigns active members of the company to the new department\n(added to each user's department list).\n\nContact fields (`contact_person`, `phone_number`, `email`, `address`,\n`tax_number`) are free text - phone and email are **not**\nformat-validated (`phone_number` max 30 and `name` max 60 characters\nwhen a Sage integration is connected).\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "supplier_ids": { "type": "array", "items": { } }, "budget_ids": { "type": "array", "items": { "type": "integer" } } } }, "example": { "id": 16, "name": "Procurement", "company_id": 20000, "archived": false, "contact_person": "Jane Doe", "tax_number": "US-PR-003", "phone_number": "+1 555 0130", "address": "300 Supply Road, Springfield, IL 62701", "email": "procurement@example.com", "created_at": "2026-10-21T05:05:36.637-05:00", "updated_at": "2026-10-21T05:05:36.637-05:00", "supplier_ids": [ ], "budget_ids": [ 3 ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Name has already registered" ], "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "department[name]": { "type": "string", "description": "1-255 characters, unique in the company (case-sensitive)." }, "department[archived]": { "type": "boolean", "description": "Create already archived. Default false." }, "department[contact_person]": { "type": "string", "description": "Contact name." }, "department[phone_number]": { "type": "string", "description": "Phone number (free text)." }, "department[email]": { "type": "string", "description": "Email (free text, not validated)." }, "department[address]": { "type": "string", "description": "Address." }, "department[tax_number]": { "type": "string", "description": "Tax/VAT number." }, "department[budget_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Budgets to link; each must belong to the header company (`Budget ids is invalid` otherwise)." }, "department[user_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Users to assign; each must be an active member of the header company (`User ids is invalid` otherwise). Not returned in the response." } }, "required": [ "department[name]" ] }, "example": { "department": { "name": "Procurement", "contact_person": "Jane Doe", "phone_number": "+1 555 0130", "email": "procurement@example.com", "address": "300 Supply Road, Springfield, IL 62701", "tax_number": "US-PR-003", "budget_ids": [ 3 ], "user_ids": [ 40000 ] } } } } } } }, "/api/v3/departments/{id}": { "get": { "tags": [ "Departments" ], "operationId": "v3_departments_show", "summary": "Get a department", "description": "Returns one department of the header company.\n\nReturns a department of the header company by id.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Department id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "supplier_ids": { "type": "array", "items": { "type": "integer" } }, "budget_ids": { "type": "array", "items": { "type": "integer" } } } }, "example": { "id": 2, "name": "Engineering", "company_id": 20000, "archived": false, "contact_person": "Jane Doe", "tax_number": "US-EN-001", "phone_number": "+1 555 0110", "address": "100 Main Street, Springfield, IL 62701", "email": "engineering@example.com", "created_at": "2026-10-21T04:48:42.702-05:00", "updated_at": "2026-10-21T04:48:42.702-05:00", "supplier_ids": [ 4, 5 ], "budget_ids": [ 1, 5, 6, 10 ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] }, "put": { "tags": [ "Departments" ], "operationId": "v3_departments_update", "summary": "Update a department", "description": "Updates a department's details, linked budgets and assigned users, or archives it.\n\nUpdates the given fields of a department of the header company. Send\n`archived: true` to archive it (there is no delete) and `archived: false`\nto restore it.\n\n`budget_ids`, when sent, replaces the complete set of linked budgets\n(send `[]` to unlink all); when omitted, links are unchanged.\n\n**`user_ids` is not a partial field.** Every update rewrites the\ndepartment's user assignments from `user_ids`; if you omit it, the\ndepartment is removed from **every** user's department list. Always\nsend the full `user_ids` list you want to keep (fetch it from the web\napp - it is not returned by the API), or `[]` deliberately.\n\nSame validation rules as [Create a department](#create-a-department).\n\n\nNone - identical request and response; both accept `PUT` and `PATCH`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Department id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "supplier_ids": { "type": "array", "items": { } }, "budget_ids": { "type": "array", "items": { } } } }, "example": { "id": 17, "name": "Procurement & Sourcing", "company_id": 20000, "archived": false, "contact_person": "Marco Rossi", "tax_number": "US-PR-003", "phone_number": "+1 555 0131", "address": "300 Supply Road, Springfield, IL 62701", "email": "procurement@example.com", "created_at": "2026-10-21T05:05:36.987-05:00", "updated_at": "2026-10-21T05:06:42.611-05:00", "supplier_ids": [ ], "budget_ids": [ ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Name has already registered" ], "status": 400 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "department[name]": { "type": "string", "description": "New name, 1-255 characters, unique in the company." }, "department[archived]": { "type": "boolean", "description": "`true` archives, `false` restores." }, "department[contact_person]": { "type": "string", "description": "Contact name." }, "department[phone_number]": { "type": "string", "description": "Phone number (free text)." }, "department[email]": { "type": "string", "description": "Email (free text, not validated)." }, "department[address]": { "type": "string", "description": "Address." }, "department[tax_number]": { "type": "string", "description": "Tax/VAT number." }, "department[budget_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Replaces the linked budgets; each must belong to the header company." }, "department[user_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Complete list of assigned users (active members of the header company). **Omitting it unassigns every user.**" } } }, "example": { "department": { "name": "Procurement & Sourcing", "contact_person": "Marco Rossi", "phone_number": "+1 555 0131", "budget_ids": [ ], "user_ids": [ 40000 ] } } } } } } }, "/api/v1/departments/{id}": { "get": { "tags": [ "Departments" ], "operationId": "v1_departments_show", "summary": "Get a department", "description": "Returns one department of the header company.\n\nReturns a department of the header company by id.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Department id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "supplier_ids": { "type": "array", "items": { "type": "integer" } }, "budget_ids": { "type": "array", "items": { "type": "integer" } } } }, "example": { "id": 2, "name": "Engineering", "company_id": 20000, "archived": false, "contact_person": "Jane Doe", "tax_number": "US-EN-001", "phone_number": "+1 555 0110", "address": "100 Main Street, Springfield, IL 62701", "email": "engineering@example.com", "created_at": "2026-10-21T04:48:42.702-05:00", "updated_at": "2026-10-21T04:48:42.702-05:00", "supplier_ids": [ 4, 5 ], "budget_ids": [ 1, 5, 6, 10 ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "put": { "tags": [ "Departments" ], "operationId": "v1_departments_update", "summary": "Update a department", "description": "Updates a department's details, linked budgets and assigned users, or archives it.\n\nUpdates the given fields of a department of the header company. Send\n`archived: true` to archive it (there is no delete) and `archived: false`\nto restore it.\n\n`budget_ids`, when sent, replaces the complete set of linked budgets\n(send `[]` to unlink all); when omitted, links are unchanged.\n\n**`user_ids` is not a partial field.** Every update rewrites the\ndepartment's user assignments from `user_ids`; if you omit it, the\ndepartment is removed from **every** user's department list. Always\nsend the full `user_ids` list you want to keep (fetch it from the web\napp - it is not returned by the API), or `[]` deliberately.\n\nSame validation rules as [Create a department](#create-a-department).\n\n\nNone - identical request and response; both accept `PUT` and `PATCH`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Department id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "supplier_ids": { "type": "array", "items": { } }, "budget_ids": { "type": "array", "items": { } } } }, "example": { "id": 16, "name": "Procurement & Sourcing", "company_id": 20000, "archived": false, "contact_person": "Marco Rossi", "tax_number": "US-PR-003", "phone_number": "+1 555 0131", "address": "300 Supply Road, Springfield, IL 62701", "email": "procurement@example.com", "created_at": "2026-10-21T05:05:36.637-05:00", "updated_at": "2026-10-21T05:06:42.385-05:00", "supplier_ids": [ ], "budget_ids": [ ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Name has already registered" ], "status": 400 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "department[name]": { "type": "string", "description": "New name, 1-255 characters, unique in the company." }, "department[archived]": { "type": "boolean", "description": "`true` archives, `false` restores." }, "department[contact_person]": { "type": "string", "description": "Contact name." }, "department[phone_number]": { "type": "string", "description": "Phone number (free text)." }, "department[email]": { "type": "string", "description": "Email (free text, not validated)." }, "department[address]": { "type": "string", "description": "Address." }, "department[tax_number]": { "type": "string", "description": "Tax/VAT number." }, "department[budget_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Replaces the linked budgets; each must belong to the header company." }, "department[user_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Complete list of assigned users (active members of the header company). **Omitting it unassigns every user.**" } } }, "example": { "department": { "name": "Procurement & Sourcing", "contact_person": "Marco Rossi", "phone_number": "+1 555 0131", "budget_ids": [ ], "user_ids": [ 40000 ] } } } } } } }, "/api/v3/invoices": { "get": { "tags": [ "Invoices" ], "operationId": "v3_invoices_list", "summary": "List invoices", "description": "Paginated, filterable list of the invoices the current user can see.\n\nReturns the invoices of the company in `app_company_id`. **Archived invoices are\nexcluded** unless `archived=true` is passed. Results are sorted by\n`invoices.created_at desc` by default.\n\nWhich invoices the user sees depends on their role:\n\n* **Company admins and finance users** see every invoice.\n* **Approvers** see the invoices linked to POs they approve, plus invoices they own\n or are mentioned on.\n* **Team members** see the invoices they own or are mentioned on.\n* When the company shares PO access by department, department members see the\n invoices of POs in their departments.\n* Admins and finance users also see every standalone `awaiting_review` invoice.\n Team members and approvers with review rights see their own.\n\nFilters can be combined. Values that do not match an allowed value are ignored,\nexcept `invoice_statuses_filter`: an unknown status returns an empty list.\n\n\nNone - identical request and response.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "One of `10`, `20`, `50`, `100`. Any other value falls back to 10.", "schema": { "type": "integer" } }, { "name": "invoice_statuses_filter", "in": "query", "required": false, "description": "One status: `awaiting_review`, `outstanding`, `ready_to_pay`, `settled` or `cancelled`. An unknown value returns no invoices.", "schema": { "type": "string" } }, { "name": "archived", "in": "query", "required": false, "description": "`true` lists only archived invoices, `false` only active ones. Any other value is treated as `false`.", "schema": { "type": "boolean" } }, { "name": "search[query]", "in": "query", "required": false, "description": "Case-insensitive substring match on `invoice_number`. A bare `search=...` also works.", "schema": { "type": "string" } }, { "name": "supplier_id[]", "in": "query", "required": false, "description": "Only invoices of these suppliers. A single `supplier_id=3` also works.", "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "supplier_exclude_id[]", "in": "query", "required": false, "description": "All invoices except those of these suppliers (invoices without a supplier stay visible). Ignored when `supplier_id` is given.", "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "supplier_external_id", "in": "query", "required": false, "description": "Only invoices whose supplier has this `external_vendor_id`.", "schema": { "type": "string" } }, { "name": "requester_id", "in": "query", "required": false, "description": "Invoices linked to POs created by this user, plus the user's own standalone `awaiting_review` invoices.", "schema": { "type": "integer" } }, { "name": "approver_id", "in": "query", "required": false, "description": "Invoices linked to POs that this user is an approver of. This is about the PO approvers, not the invoice's own approvers.", "schema": { "type": "integer" } }, { "name": "invoice_approver_id[]", "in": "query", "required": false, "description": "Invoices this user is (or was) asked to approve through an invoice approval flow. The tab matters: with `ready_to_pay` / `settled` it means the user approved it; with `awaiting_review` / `outstanding` it means the user is a pending approver.", "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "invoice_approver_exclude_id[]", "in": "query", "required": false, "description": "Opposite of `invoice_approver_id[]`.", "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "department_id", "in": "query", "required": false, "description": "Invoices linked to POs of this department.", "schema": { "type": "integer" } }, { "name": "invoice_date_filter", "in": "query", "required": false, "description": "`last 7days`, `last 30days`, `last 60days`, `last 90days`, `last 180days`, `last 1year`, `current_month`, `current_year`, `last_month`, `last_year`. The date column depends on `invoice_statuses_filter`: `issue_date` for `ready_to_pay`, `settled_date` for `settled`, `created_at` otherwise.", "schema": { "type": "string" } }, { "name": "cf__filter", "in": "query", "required": false, "description": "Invoices whose invoice-level custom field has one of these values, e.g. `cf_4_filter=AP-2026-10-B`.", "schema": { "type": "string" } }, { "name": "sage_exported", "in": "query", "required": false, "description": "Filter on `sage_exported`.", "schema": { "type": "boolean" } }, { "name": "sage300_statuses_filter", "in": "query", "required": false, "description": "`not_exported` or `exported` (Sage 300).", "schema": { "type": "string" } }, { "name": "synced_with_qbo_filter", "in": "query", "required": false, "description": "`yes`, `no` or `all` (QuickBooks).", "schema": { "type": "string" } }, { "name": "synced_with_gp_filter", "in": "query", "required": false, "description": "`success`, `failure`, `not set` or `all` (Great Plains).", "schema": { "type": "string" } }, { "name": "sage_intacct_statuses_filter", "in": "query", "required": false, "description": "`si_not_started`, `si_syncing`, `si_exported`, `si_failed`, `si_update_failed`, `si_skipped`.", "schema": { "type": "string" } }, { "name": "dynamics_statuses_filter", "in": "query", "required": false, "description": "Dynamics 365 export status, or `all`.", "schema": { "type": "string" } }, { "name": "sage200_api_statuses_filter", "in": "query", "required": false, "description": "Sage 200 export status, or `all`.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "A fully qualified invoice column such as `invoices.invoice_number`, `invoices.due_date` or `invoices.gross_amount`, or `custom_field_`. Anything else (including a bare `due_date`) silently falls back to `invoices.created_at`.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "`asc` or `desc`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "invoice_number": { "type": "string" }, "status": { "type": "string" }, "issue_date": { "type": "integer" }, "validation_date": { "type": "integer" }, "uploaded_date": { "type": "integer" }, "due_date": { "type": "integer" }, "tax_amount": { "type": "string" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "shipping_amount": { "type": "string" }, "shipping_amount_overridden": { "type": "boolean" }, "net_amount": { "type": "string" }, "gross_amount": { "type": "string" }, "balance_amount": { "type": "string" }, "supplier_id": { "type": "integer" }, "supplier_name": { "type": "string" }, "purchase_order_references": { "type": "array", "items": { "type": "string" } }, "can_accept": { "type": "boolean" }, "can_approve": { "type": "boolean" }, "can_reject": { "type": "boolean" }, "can_cancel": { "type": "boolean" }, "can_archive": { "type": "boolean" }, "can_dearchive": { "type": "boolean" }, "standalone_invoice": { "type": "boolean" }, "confidence_score": { "type": "string" }, "digital_invoice": { "type": "boolean" }, "payment_term_id": { "type": "null" }, "payment_terms_list": { "type": "null" }, "xero_export_status": { "type": "null" }, "xero_is_changed": { "type": "boolean" }, "duplicate_invoice_flag": { "type": "boolean" }, "payment_progress": { "type": "string" }, "submitted_with_unproven_supplier_email": { "type": "boolean" }, "currency": { "type": "object", "properties": { "id": { "type": "integer" }, "iso_code": { "type": "string" }, "iso_numeric": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "next_page": { "type": "null" }, "prev_page": { "type": "null" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "example": { "invoices": [ { "id": 6, "invoice_number": "CH-APV-V1", "status": "settled", "issue_date": 1792472400, "validation_date": 1792558800, "uploaded_date": 1792577150, "due_date": 1795068000, "tax_amount": "15.0", "tax_amount_overridden": false, "tax_amount_override": null, "shipping_amount": "0.0", "shipping_amount_overridden": false, "net_amount": "150.0", "gross_amount": "165.0", "balance_amount": "0.0", "supplier_id": 2, "supplier_name": "Contoso Hardware", "purchase_order_references": [ "5-10/21/2026" ], "can_accept": false, "can_approve": false, "can_reject": false, "can_cancel": true, "can_archive": true, "can_dearchive": false, "standalone_invoice": false, "confidence_score": "0.0", "digital_invoice": false, "payment_term_id": null, "payment_terms_list": null, "xero_export_status": null, "xero_is_changed": false, "duplicate_invoice_flag": false, "payment_progress": "paid", "submitted_with_unproven_supplier_email": false, "currency": { "id": 2000, "iso_code": "USD", "iso_numeric": "840", "name": "United States Dollar", "symbol": "$", "created_at": "2026-10-21T04:44:44.793-05:00", "updated_at": "2026-10-21T04:44:44.793-05:00" } }, { "id": 16, "invoice_number": "CH-PAY-V1", "status": "settled", "issue_date": 1792472400, "validation_date": 1792558800, "uploaded_date": 1792577159, "due_date": 1795068000, "tax_amount": "15.0", "tax_amount_overridden": false, "tax_amount_override": null, "shipping_amount": "0.0", "shipping_amount_overridden": false, "net_amount": "150.0", "gross_amount": "165.0", "balance_amount": "0.0", "supplier_id": 2, "supplier_name": "Contoso Hardware", "purchase_order_references": [ "9-10/21/2026" ], "can_accept": false, "can_approve": false, "can_reject": false, "can_cancel": true, "can_archive": true, "can_dearchive": false, "standalone_invoice": false, "confidence_score": "0.0", "digital_invoice": false, "payment_term_id": null, "payment_terms_list": null, "xero_export_status": null, "xero_is_changed": false, "duplicate_invoice_flag": false, "payment_progress": "paid", "submitted_with_unproven_supplier_email": false, "currency": { "id": 2000, "iso_code": "USD", "iso_numeric": "840", "name": "United States Dollar", "symbol": "$", "created_at": "2026-10-21T04:44:44.793-05:00", "updated_at": "2026-10-21T04:44:44.793-05:00" } } ], "meta": { "current_page": 1, "next_page": null, "prev_page": null, "total_pages": 1, "total_count": 3 } } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] }, "post": { "tags": [ "Invoices" ], "operationId": "v3_invoices_create", "summary": "Create an invoice", "description": "Record a supplier invoice, optionally linked to purchase order lines and with a PDF attached.\n\nCreates an invoice for the company in `app_company_id`. The current user becomes\nits owner.\n\n**Request format.** Send JSON when no file is attached. To attach the invoice PDF,\nsend `multipart/form-data` with the same field names in bracket notation (for\nexample `invoice[invoice_number]` and\n`invoice[invoice_line_items_attributes][0][quantity]`), and the file as\n`invoice[supplier_invoice_uploads_attributes][0][file]`. The file must be an\nactual file upload. A URL or string is not accepted and fails with a 500. Only\n**PDF** is accepted, up to 30 MB.\n\n**Linking to POs.** Give each line a `purchase_order_id` and\n`purchase_order_item_id` (see\n[purchase_order_item_list](#list-purchase-order-lines-to-invoice)). Lines without\nthem make a standalone invoice. A draft PO cannot be linked. Every linked PO gets\n`payment_status: invoice_received`.\n\n**Status.** The invoice is created as `outstanding`. It is created as\n`awaiting_review` instead in two cases:\n\n* The company setting `can_create_invoice_in_awaiting_review` is on.\n* The PO overrun guard is enabled and the invoice exceeds a linked PO's total.\n\n**Amounts.** `net_amount`, `tax_amount` and `gross_amount` are computed from the\nlines (line tax = `net_amount x vat / 100`). The `gross_amount` you send is\nreplaced.\n\n**Dates.** Send ISO `YYYY-MM-DD`. A date in any other format is dropped, and\n`issue_date`, `due_date` and `uploaded_date` default to the current time.\n\nProcessing is synchronous: POST /invoices does not run OCR or AI extraction. Use\n[POST /digital_invoices](#scan-an-invoice-document) for that.\n\n**V3 only, e-invoicing.** When the company has an active e-invoicing (PA)\nconnection and the upload is a Factur-X PDF, V3 hands the file to the e-invoicing\npipeline:\n\n* The file can be in `invoice[supplier_invoice_uploads_attributes][0][file]` or a\n top-level `file`.\n* A request with only the file (no invoice fields) returns the received e-invoice\n record, and the invoice is built later from the embedded XML.\n* Optional parameters: `einvoicing_format` (or the `X-Einvoicing-Format` header),\n `pa_invoice_id` (or `X-Einvoicing-Pa-Invoice-Id`) and `doc_type` (default\n `invoice`).\n\n\n* V3 ignores `invoice[payment_term_id]`. This was verified: the same request leaves\n `payment_term_id` null on V3.\n* V3 only: the e-invoicing (Factur-X) intake path described above.\n* Otherwise identical requests and responses.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "invoice_number": { "type": "string" }, "status": { "type": "string" }, "issue_date": { "type": "integer" }, "validation_date": { "type": "null" }, "uploaded_date": { "type": "integer" }, "due_date": { "type": "integer" }, "tax_amount": { "type": "string" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "shipping_amount": { "type": "string" }, "shipping_amount_overridden": { "type": "boolean" }, "net_amount": { "type": "string" }, "gross_amount": { "type": "string" }, "balance_amount": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "standalone_invoice": { "type": "boolean" }, "can_accept": { "type": "boolean" }, "can_approve": { "type": "boolean" }, "can_reject": { "type": "boolean" }, "can_cancel": { "type": "boolean" }, "can_archive": { "type": "boolean" }, "can_dearchive": { "type": "boolean" }, "sage_exported": { "type": "boolean" }, "confidence_score": { "type": "string" }, "digital_invoice": { "type": "boolean" }, "selected_purchase_order_ids": { "type": "array", "items": { } }, "payment_term_id": { "type": "null" }, "payment_terms_list": { "type": "null" }, "xero_export_status": { "type": "null" }, "xero_export_error_message": { "type": "null" }, "xero_last_export_at": { "type": "null" }, "xero_is_changed": { "type": "boolean" }, "duplicate_invoice_flag": { "type": "boolean" }, "payment_progress": { "type": "string" }, "gl_posting_date": { "type": "null" }, "submitted_with_unproven_supplier_email": { "type": "boolean" }, "currency": { "type": "object", "properties": { "id": { "type": "integer" }, "iso_code": { "type": "string" }, "iso_numeric": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "supplier": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "notes": { "type": "null" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "payment_details": { "type": "null" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "payment_terms": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "currency_id": { "type": "integer" }, "department_ids": { "type": "array", "items": { } }, "external_vendor_id": { "type": "null" }, "uei": { "type": "null" }, "cage_code": { "type": "null" }, "third_party_id_mappings": { "type": "array", "items": { } } } }, "invoice_line_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "sequence_no": { "type": "integer" }, "description": { "type": "string" }, "unit_price": { "type": "string" }, "quantity": { "type": "string" }, "vat": { "type": "string" }, "net_amount": { "type": "string" }, "base_net_amount": { "type": "string" }, "deleted_at": { "type": "null" }, "billable_status": { "type": "null" }, "tax_rate_id": { "type": "integer" }, "chart_of_account_id": { "type": "null" }, "qbo_customer_id": { "type": "null" }, "quickbooks_class_id": { "type": "null" }, "qbo_line_description": { "type": "null" }, "invoice_id": { "type": "integer" }, "purchase_order_id": { "type": "integer" }, "purchase_order_item_id": { "type": "integer" }, "product_id": { "type": "null" }, "markup_info": { "type": "null" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "tax_amount": { "type": "string" }, "calculated_gross_amount": { "type": "string" }, "tax_exception": { "type": "boolean" }, "chart_of_account": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "qbo_customer": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "quickbooks_class": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } } } } }, "purchase_orders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_key": { "type": "string" }, "creator_name": { "type": "string" }, "amount": { "type": "string" }, "status": { "type": "string" }, "supplier_name": { "type": "string" }, "supplier_id": { "type": "integer" }, "keywords": { "type": "string" }, "created_at": { "type": "integer" }, "currency_id": { "type": "integer" }, "currency_symbol": { "type": "string" }, "currency_iso_code": { "type": "string" }, "total_gross_amount": { "type": "string" }, "total_net_amount": { "type": "string" }, "base_gross_amount": { "type": "number" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "effective_tax_amount": { "type": "number" }, "shipping_amount_overridden": { "type": "boolean" }, "shipping_amount_override": { "type": "null" }, "effective_shipping_amount": { "type": "string" }, "submitted_on": { "type": "integer" }, "po_date": { "type": "null" }, "share_key": { "type": "string" }, "department_id": { "type": "integer" }, "department_name": { "type": "string" }, "budget_name": { "type": "string" }, "compliance_status": { "type": "null" }, "delivered_on": { "type": "null" }, "delivery_status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_progress": { "type": "string" }, "xero_export_status": { "type": "null" }, "synced_with_xero": { "type": "boolean" }, "xero_is_changed": { "type": "boolean" } } } }, "supplier_invoice_uploads": { "type": "array", "items": { } }, "histories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "comment": { "type": "string" }, "invoice_id": { "type": "integer" }, "creator_id": { "type": "integer" }, "creator_name": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "comment_formatted_time": { "type": "string" }, "comment_formatted_date": { "type": "string" }, "formatted_comment": { "type": "string" } } } }, "comments": { "type": "array", "items": { } }, "npayments": { "type": "array", "items": { } } } }, "example": { "id": 2, "invoice_number": "CH-2026-1002", "status": "outstanding", "issue_date": 1792472400, "validation_date": null, "uploaded_date": 1792576882, "due_date": 1795068000, "tax_amount": "90.0", "tax_amount_overridden": false, "tax_amount_override": null, "shipping_amount": "0.0", "shipping_amount_overridden": false, "net_amount": "900.0", "gross_amount": "990.0", "balance_amount": "990.0", "created_at": 1792576882, "updated_at": 1792576882, "standalone_invoice": false, "can_accept": false, "can_approve": true, "can_reject": true, "can_cancel": true, "can_archive": true, "can_dearchive": false, "sage_exported": false, "confidence_score": "0.0", "digital_invoice": false, "selected_purchase_order_ids": [ ], "payment_term_id": null, "payment_terms_list": null, "xero_export_status": null, "xero_export_error_message": null, "xero_last_export_at": null, "xero_is_changed": false, "duplicate_invoice_flag": false, "payment_progress": "unpaid", "gl_posting_date": null, "submitted_with_unproven_supplier_email": false, "currency": { "id": 2000, "iso_code": "USD", "iso_numeric": "840", "name": "United States Dollar", "symbol": "$", "created_at": "2026-10-21T04:44:44.793-05:00", "updated_at": "2026-10-21T04:44:44.793-05:00" }, "supplier": { "id": 2, "name": "Contoso Hardware", "company_id": 20000, "notes": null, "phone_number": "+1 555 0300", "address": "500 Tech Park, Austin, TX 78701", "email": "sales@contoso.example.com", "payment_details": null, "archived": false, "contact_person": "Diego Ramos", "tax_number": "74-7654321", "payment_terms": "Net 45", "created_at": "2026-10-21T04:48:43.563-05:00", "updated_at": "2026-10-21T04:48:43.563-05:00", "currency_id": 2000, "department_ids": [ ], "external_vendor_id": null, "uei": null, "cage_code": null, "third_party_id_mappings": [ ] }, "invoice_line_items": [ { "id": 3, "sequence_no": 1, "description": "USB-C dock", "unit_price": "150.0", "quantity": "2.0", "vat": "10.0", "net_amount": "300.0", "base_net_amount": "300.0", "deleted_at": null, "billable_status": null, "tax_rate_id": 4, "chart_of_account_id": null, "qbo_customer_id": null, "quickbooks_class_id": null, "qbo_line_description": null, "invoice_id": 2, "purchase_order_id": 4, "purchase_order_item_id": 6, "product_id": null, "markup_info": null, "created_at": 1792576882, "updated_at": 1792576882, "tax_amount": "30.0", "calculated_gross_amount": "330.0", "tax_exception": false, "chart_of_account": { "id": null, "name": null }, "qbo_customer": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null } }, { "id": 4, "sequence_no": 2, "description": "27in monitor", "unit_price": "300.0", "quantity": "2.0", "vat": "10.0", "net_amount": "600.0", "base_net_amount": "600.0", "deleted_at": null, "billable_status": null, "tax_rate_id": 4, "chart_of_account_id": null, "qbo_customer_id": null, "quickbooks_class_id": null, "qbo_line_description": null, "invoice_id": 2, "purchase_order_id": 4, "purchase_order_item_id": 7, "product_id": null, "markup_info": null, "created_at": 1792576882, "updated_at": 1792576882, "tax_amount": "60.0", "calculated_gross_amount": "660.0", "tax_exception": false, "chart_of_account": { "id": null, "name": null }, "qbo_customer": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null } } ], "purchase_orders": [ { "id": 4, "approval_key": "4-10/21/2026", "creator_name": "Jane Doe", "amount": "1200.0", "status": "approved", "supplier_name": "Contoso Hardware", "supplier_id": 2, "keywords": "4 Contoso Hardware Jane Doe 4-10/21/2026 approved 1306.50 Engineering Hardware FY26 USB-C dock 653.25 600.0 Engineering Hardware FY26 27in monitor 653.25 600.0 Not Set Not Set ", "created_at": 1792576811000, "currency_id": 2000, "currency_symbol": "$", "currency_iso_code": "USD", "total_gross_amount": "1306.5", "total_net_amount": "1200.0", "base_gross_amount": 1306.5, "tax_amount_overridden": false, "tax_amount_override": null, "effective_tax_amount": 106.5, "shipping_amount_overridden": false, "shipping_amount_override": null, "effective_shipping_amount": "0.0", "submitted_on": 1792576811000, "po_date": null, "share_key": "BC85C70BB47874D5FE56B85FB6FF6F65B1D13753", "department_id": 2, "department_name": "Engineering", "budget_name": "Engineering Hardware FY26", "compliance_status": null, "delivered_on": null, "delivery_status": "not_delivered", "payment_status": "invoice_received", "payment_progress": "unpaid", "xero_export_status": null, "synced_with_xero": false, "xero_is_changed": false } ], "supplier_invoice_uploads": [ ], "histories": [ { "id": 2, "comment": "has created an invoice ", "invoice_id": 2, "creator_id": 40000, "creator_name": "Jane Doe", "created_at": 1792576882, "updated_at": 1792576882, "comment_formatted_time": "05:01", "comment_formatted_date": "2026-10-21", "formatted_comment": "

has created an invoice

" } ], "comments": [ ], "npayments": [ ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": { "supplier_id": [ "can't be blank" ] }, "status": 400 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice[invoice_number]": { "type": "string", "description": "Supplier's invoice reference. Required when the company setting `invoice_reference_mandatory` is on. Must be unique per supplier among non-cancelled invoices (`Invoice reference already exists`). Max 21 characters with an active QuickBooks connection." }, "invoice[supplier_id]": { "type": "integer", "description": "Supplier id. Optional only when the invoice is created as `awaiting_review`." }, "invoice[currency_id]": { "type": "integer", "description": "Currency id (`currency_id can't be blank` otherwise)." }, "invoice[issue_date]": { "type": "string", "format": "date", "description": "Invoice date, `YYYY-MM-DD`. Defaults to now." }, "invoice[due_date]": { "type": "string", "format": "date", "description": "Due date, `YYYY-MM-DD`. Defaults to now." }, "invoice[received_date]": { "type": "string", "format": "date", "description": "Date received, `YYYY-MM-DD`. Stored but not returned by the API." }, "invoice[uploaded_date]": { "type": "string", "format": "date", "description": "Recorded date, `YYYY-MM-DD`. Defaults to now." }, "invoice[validation_date]": { "type": "string", "format": "date", "description": "Approval date. Normally set automatically when the invoice is approved." }, "invoice[gross_amount]": { "type": "number", "description": "Ignored in practice: recomputed from the line items when saved." }, "invoice[standalone_invoice]": { "type": "boolean", "description": "Mark the invoice as not PO-backed." }, "invoice[payment_term_id]": { "type": "integer", "description": "**V1 only** (V3 ignores it). Payment term id." }, "invoice[digital_invoice]": { "type": "boolean", "description": "Marks a scanned invoice. Changes the tax calculation to use the per-line tax amounts." }, "invoice[confidence_score]": { "type": "number", "description": "Extraction confidence for scanned invoices." }, "invoice[sage_exported]": { "type": "boolean", "description": "Sage export marker." }, "invoice[selected_purchase_order_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "PO ids picked on the form (informational; the PO links come from the line items)." }, "invoice[custom_field_values_attributes][][custom_field_id]": { "type": "integer", "description": "Invoice-level custom field id. Required custom fields must be filled in." }, "invoice[custom_field_values_attributes][][value]": { "type": "string", "description": "Custom field value." }, "invoice[custom_field_values_attributes][][id]": { "type": "integer", "description": "Existing value id (update only)." }, "invoice[invoice_line_items_attributes][][description]": { "type": "string", "description": "Line description." }, "invoice[invoice_line_items_attributes][][sequence_no]": { "type": "integer", "description": "Line order. Assigned automatically when missing." }, "invoice[invoice_line_items_attributes][][quantity]": { "type": "number", "description": "Quantity." }, "invoice[invoice_line_items_attributes][][unit_price]": { "type": "number", "description": "Unit price." }, "invoice[invoice_line_items_attributes][][net_amount]": { "type": "number", "description": "Line net amount (normally `quantity x unit_price`)." }, "invoice[invoice_line_items_attributes][][vat]": { "type": "number", "description": "Tax percentage of the line. This drives the invoice tax." }, "invoice[invoice_line_items_attributes][][base_net_amount]": { "type": "number", "description": "Net amount in the company base currency." }, "invoice[invoice_line_items_attributes][][tax_rate_id]": { "type": "integer", "description": "Tax rate id (stored; the tax uses `vat`)." }, "invoice[invoice_line_items_attributes][][purchase_order_id]": { "type": "integer", "description": "PO this line bills." }, "invoice[invoice_line_items_attributes][][purchase_order_item_id]": { "type": "integer", "description": "PO line this line bills." }, "invoice[invoice_line_items_attributes][][chart_of_account_id]": { "type": "integer", "description": "Chart of account id." }, "invoice[invoice_line_items_attributes][][qbo_customer_id]": { "type": "integer", "description": "QuickBooks customer id." }, "invoice[invoice_line_items_attributes][][quickbooks_class_id]": { "type": "integer", "description": "QuickBooks class id." }, "invoice[invoice_line_items_attributes][][qbo_line_description]": { "type": "string", "description": "Line description sent to QuickBooks." }, "invoice[invoice_line_items_attributes][][billable_status]": { "type": "string", "description": "QuickBooks billable status: `NotBillable`, `Billable`, `HasBeenBilled`." }, "invoice[invoice_line_items_attributes][][custom_field_values_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "Line-level custom field values: `custom_field_id`, `value`, `id`." }, "invoice[invoice_line_items_attributes][][id]": { "type": "integer", "description": "Existing line id (update only)." }, "invoice[invoice_line_items_attributes][][_destroy]": { "type": "boolean", "description": "`true` with `id` deletes the line (update only)." }, "invoice[supplier_invoice_uploads_attributes][][file]": { "type": "string", "format": "binary", "description": "The invoice PDF as a multipart file (max 30 MB). Non-PDF: `The invoice you selected has to be a .pdf file`." }, "invoice[supplier_invoice_uploads_attributes][][id]": { "type": "integer", "description": "Existing upload id (update only)." }, "invoice[supplier_invoice_uploads_attributes][][_destroy]": { "type": "boolean", "description": "`true` with `id` removes the file (update only)." }, "invoice[company_id]": { "type": "integer", "description": "Ignored: the company always comes from `app_company_id`." } }, "required": [ "invoice[supplier_id]", "invoice[currency_id]" ] }, "example": { "invoice": { "invoice_number": "CH-2026-1002", "supplier_id": 2, "currency_id": 2000, "issue_date": "2026-10-20", "received_date": "2026-10-21", "due_date": "2026-11-19", "gross_amount": "990.00", "invoice_line_items_attributes": [ { "sequence_no": 1, "description": "USB-C dock", "quantity": 2, "unit_price": 150, "vat": 10, "net_amount": 300, "tax_rate_id": 4, "purchase_order_id": 4, "purchase_order_item_id": 6 }, { "sequence_no": 2, "description": "27in monitor", "quantity": 2, "unit_price": 300, "vat": 10, "net_amount": 600, "tax_rate_id": 4, "purchase_order_id": 4, "purchase_order_item_id": 7 } ] } } } } } } }, "/api/v1/invoices": { "get": { "tags": [ "Invoices" ], "operationId": "v1_invoices_list", "summary": "List invoices", "description": "Paginated, filterable list of the invoices the current user can see.\n\nReturns the invoices of the company in `app_company_id`. **Archived invoices are\nexcluded** unless `archived=true` is passed. Results are sorted by\n`invoices.created_at desc` by default.\n\nWhich invoices the user sees depends on their role:\n\n* **Company admins and finance users** see every invoice.\n* **Approvers** see the invoices linked to POs they approve, plus invoices they own\n or are mentioned on.\n* **Team members** see the invoices they own or are mentioned on.\n* When the company shares PO access by department, department members see the\n invoices of POs in their departments.\n* Admins and finance users also see every standalone `awaiting_review` invoice.\n Team members and approvers with review rights see their own.\n\nFilters can be combined. Values that do not match an allowed value are ignored,\nexcept `invoice_statuses_filter`: an unknown status returns an empty list.\n\n\nNone - identical request and response.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "One of `10`, `20`, `50`, `100`. Any other value falls back to 10.", "schema": { "type": "integer" } }, { "name": "invoice_statuses_filter", "in": "query", "required": false, "description": "One status: `awaiting_review`, `outstanding`, `ready_to_pay`, `settled` or `cancelled`. An unknown value returns no invoices.", "schema": { "type": "string" } }, { "name": "archived", "in": "query", "required": false, "description": "`true` lists only archived invoices, `false` only active ones. Any other value is treated as `false`.", "schema": { "type": "boolean" } }, { "name": "search[query]", "in": "query", "required": false, "description": "Case-insensitive substring match on `invoice_number`. A bare `search=...` also works.", "schema": { "type": "string" } }, { "name": "supplier_id[]", "in": "query", "required": false, "description": "Only invoices of these suppliers. A single `supplier_id=3` also works.", "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "supplier_exclude_id[]", "in": "query", "required": false, "description": "All invoices except those of these suppliers (invoices without a supplier stay visible). Ignored when `supplier_id` is given.", "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "supplier_external_id", "in": "query", "required": false, "description": "Only invoices whose supplier has this `external_vendor_id`.", "schema": { "type": "string" } }, { "name": "requester_id", "in": "query", "required": false, "description": "Invoices linked to POs created by this user, plus the user's own standalone `awaiting_review` invoices.", "schema": { "type": "integer" } }, { "name": "approver_id", "in": "query", "required": false, "description": "Invoices linked to POs that this user is an approver of. This is about the PO approvers, not the invoice's own approvers.", "schema": { "type": "integer" } }, { "name": "invoice_approver_id[]", "in": "query", "required": false, "description": "Invoices this user is (or was) asked to approve through an invoice approval flow. The tab matters: with `ready_to_pay` / `settled` it means the user approved it; with `awaiting_review` / `outstanding` it means the user is a pending approver.", "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "invoice_approver_exclude_id[]", "in": "query", "required": false, "description": "Opposite of `invoice_approver_id[]`.", "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "department_id", "in": "query", "required": false, "description": "Invoices linked to POs of this department.", "schema": { "type": "integer" } }, { "name": "invoice_date_filter", "in": "query", "required": false, "description": "`last 7days`, `last 30days`, `last 60days`, `last 90days`, `last 180days`, `last 1year`, `current_month`, `current_year`, `last_month`, `last_year`. The date column depends on `invoice_statuses_filter`: `issue_date` for `ready_to_pay`, `settled_date` for `settled`, `created_at` otherwise.", "schema": { "type": "string" } }, { "name": "cf__filter", "in": "query", "required": false, "description": "Invoices whose invoice-level custom field has one of these values, e.g. `cf_4_filter=AP-2026-10-B`.", "schema": { "type": "string" } }, { "name": "sage_exported", "in": "query", "required": false, "description": "Filter on `sage_exported`.", "schema": { "type": "boolean" } }, { "name": "sage300_statuses_filter", "in": "query", "required": false, "description": "`not_exported` or `exported` (Sage 300).", "schema": { "type": "string" } }, { "name": "synced_with_qbo_filter", "in": "query", "required": false, "description": "`yes`, `no` or `all` (QuickBooks).", "schema": { "type": "string" } }, { "name": "synced_with_gp_filter", "in": "query", "required": false, "description": "`success`, `failure`, `not set` or `all` (Great Plains).", "schema": { "type": "string" } }, { "name": "sage_intacct_statuses_filter", "in": "query", "required": false, "description": "`si_not_started`, `si_syncing`, `si_exported`, `si_failed`, `si_update_failed`, `si_skipped`.", "schema": { "type": "string" } }, { "name": "dynamics_statuses_filter", "in": "query", "required": false, "description": "Dynamics 365 export status, or `all`.", "schema": { "type": "string" } }, { "name": "sage200_api_statuses_filter", "in": "query", "required": false, "description": "Sage 200 export status, or `all`.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "A fully qualified invoice column such as `invoices.invoice_number`, `invoices.due_date` or `invoices.gross_amount`, or `custom_field_`. Anything else (including a bare `due_date`) silently falls back to `invoices.created_at`.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "`asc` or `desc`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "invoice_number": { "type": "string" }, "status": { "type": "string" }, "issue_date": { "type": "integer" }, "validation_date": { "type": "integer" }, "uploaded_date": { "type": "integer" }, "due_date": { "type": "integer" }, "tax_amount": { "type": "string" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "shipping_amount": { "type": "string" }, "shipping_amount_overridden": { "type": "boolean" }, "net_amount": { "type": "string" }, "gross_amount": { "type": "string" }, "balance_amount": { "type": "string" }, "supplier_id": { "type": "integer" }, "supplier_name": { "type": "string" }, "purchase_order_references": { "type": "array", "items": { "type": "string" } }, "can_accept": { "type": "boolean" }, "can_approve": { "type": "boolean" }, "can_reject": { "type": "boolean" }, "can_cancel": { "type": "boolean" }, "can_archive": { "type": "boolean" }, "can_dearchive": { "type": "boolean" }, "standalone_invoice": { "type": "boolean" }, "confidence_score": { "type": "string" }, "digital_invoice": { "type": "boolean" }, "payment_term_id": { "type": "null" }, "payment_terms_list": { "type": "null" }, "xero_export_status": { "type": "null" }, "xero_is_changed": { "type": "boolean" }, "duplicate_invoice_flag": { "type": "boolean" }, "payment_progress": { "type": "string" }, "submitted_with_unproven_supplier_email": { "type": "boolean" }, "currency": { "type": "object", "properties": { "id": { "type": "integer" }, "iso_code": { "type": "string" }, "iso_numeric": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "next_page": { "type": "null" }, "prev_page": { "type": "null" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "example": { "invoices": [ { "id": 6, "invoice_number": "CH-APV-V1", "status": "settled", "issue_date": 1792472400, "validation_date": 1792558800, "uploaded_date": 1792577150, "due_date": 1795068000, "tax_amount": "15.0", "tax_amount_overridden": false, "tax_amount_override": null, "shipping_amount": "0.0", "shipping_amount_overridden": false, "net_amount": "150.0", "gross_amount": "165.0", "balance_amount": "0.0", "supplier_id": 2, "supplier_name": "Contoso Hardware", "purchase_order_references": [ "5-10/21/2026" ], "can_accept": false, "can_approve": false, "can_reject": false, "can_cancel": true, "can_archive": true, "can_dearchive": false, "standalone_invoice": false, "confidence_score": "0.0", "digital_invoice": false, "payment_term_id": null, "payment_terms_list": null, "xero_export_status": null, "xero_is_changed": false, "duplicate_invoice_flag": false, "payment_progress": "paid", "submitted_with_unproven_supplier_email": false, "currency": { "id": 2000, "iso_code": "USD", "iso_numeric": "840", "name": "United States Dollar", "symbol": "$", "created_at": "2026-10-21T04:44:44.793-05:00", "updated_at": "2026-10-21T04:44:44.793-05:00" } }, { "id": 16, "invoice_number": "CH-PAY-V1", "status": "settled", "issue_date": 1792472400, "validation_date": 1792558800, "uploaded_date": 1792577159, "due_date": 1795068000, "tax_amount": "15.0", "tax_amount_overridden": false, "tax_amount_override": null, "shipping_amount": "0.0", "shipping_amount_overridden": false, "net_amount": "150.0", "gross_amount": "165.0", "balance_amount": "0.0", "supplier_id": 2, "supplier_name": "Contoso Hardware", "purchase_order_references": [ "9-10/21/2026" ], "can_accept": false, "can_approve": false, "can_reject": false, "can_cancel": true, "can_archive": true, "can_dearchive": false, "standalone_invoice": false, "confidence_score": "0.0", "digital_invoice": false, "payment_term_id": null, "payment_terms_list": null, "xero_export_status": null, "xero_is_changed": false, "duplicate_invoice_flag": false, "payment_progress": "paid", "submitted_with_unproven_supplier_email": false, "currency": { "id": 2000, "iso_code": "USD", "iso_numeric": "840", "name": "United States Dollar", "symbol": "$", "created_at": "2026-10-21T04:44:44.793-05:00", "updated_at": "2026-10-21T04:44:44.793-05:00" } } ], "meta": { "current_page": 1, "next_page": null, "prev_page": null, "total_pages": 1, "total_count": 3 } } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "post": { "tags": [ "Invoices" ], "operationId": "v1_invoices_create", "summary": "Create an invoice", "description": "Record a supplier invoice, optionally linked to purchase order lines and with a PDF attached.\n\nCreates an invoice for the company in `app_company_id`. The current user becomes\nits owner.\n\n**Request format.** Send JSON when no file is attached. To attach the invoice PDF,\nsend `multipart/form-data` with the same field names in bracket notation (for\nexample `invoice[invoice_number]` and\n`invoice[invoice_line_items_attributes][0][quantity]`), and the file as\n`invoice[supplier_invoice_uploads_attributes][0][file]`. The file must be an\nactual file upload. A URL or string is not accepted and fails with a 500. Only\n**PDF** is accepted, up to 30 MB.\n\n**Linking to POs.** Give each line a `purchase_order_id` and\n`purchase_order_item_id` (see\n[purchase_order_item_list](#list-purchase-order-lines-to-invoice)). Lines without\nthem make a standalone invoice. A draft PO cannot be linked. Every linked PO gets\n`payment_status: invoice_received`.\n\n**Status.** The invoice is created as `outstanding`. It is created as\n`awaiting_review` instead in two cases:\n\n* The company setting `can_create_invoice_in_awaiting_review` is on.\n* The PO overrun guard is enabled and the invoice exceeds a linked PO's total.\n\n**Amounts.** `net_amount`, `tax_amount` and `gross_amount` are computed from the\nlines (line tax = `net_amount x vat / 100`). The `gross_amount` you send is\nreplaced.\n\n**Dates.** Send ISO `YYYY-MM-DD`. A date in any other format is dropped, and\n`issue_date`, `due_date` and `uploaded_date` default to the current time.\n\nProcessing is synchronous: POST /invoices does not run OCR or AI extraction. Use\n[POST /digital_invoices](#scan-an-invoice-document) for that.\n\n**V3 only, e-invoicing.** When the company has an active e-invoicing (PA)\nconnection and the upload is a Factur-X PDF, V3 hands the file to the e-invoicing\npipeline:\n\n* The file can be in `invoice[supplier_invoice_uploads_attributes][0][file]` or a\n top-level `file`.\n* A request with only the file (no invoice fields) returns the received e-invoice\n record, and the invoice is built later from the embedded XML.\n* Optional parameters: `einvoicing_format` (or the `X-Einvoicing-Format` header),\n `pa_invoice_id` (or `X-Einvoicing-Pa-Invoice-Id`) and `doc_type` (default\n `invoice`).\n\n\n* V3 ignores `invoice[payment_term_id]`. This was verified: the same request leaves\n `payment_term_id` null on V3.\n* V3 only: the e-invoicing (Factur-X) intake path described above.\n* Otherwise identical requests and responses.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "invoice_number": { "type": "string" }, "status": { "type": "string" }, "issue_date": { "type": "integer" }, "validation_date": { "type": "null" }, "uploaded_date": { "type": "integer" }, "due_date": { "type": "integer" }, "tax_amount": { "type": "string" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "shipping_amount": { "type": "string" }, "shipping_amount_overridden": { "type": "boolean" }, "net_amount": { "type": "string" }, "gross_amount": { "type": "string" }, "balance_amount": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "standalone_invoice": { "type": "boolean" }, "can_accept": { "type": "boolean" }, "can_approve": { "type": "boolean" }, "can_reject": { "type": "boolean" }, "can_cancel": { "type": "boolean" }, "can_archive": { "type": "boolean" }, "can_dearchive": { "type": "boolean" }, "sage_exported": { "type": "boolean" }, "confidence_score": { "type": "string" }, "digital_invoice": { "type": "boolean" }, "selected_purchase_order_ids": { "type": "array", "items": { } }, "payment_term_id": { "type": "null" }, "payment_terms_list": { "type": "null" }, "xero_export_status": { "type": "null" }, "xero_export_error_message": { "type": "null" }, "xero_last_export_at": { "type": "null" }, "xero_is_changed": { "type": "boolean" }, "duplicate_invoice_flag": { "type": "boolean" }, "payment_progress": { "type": "string" }, "gl_posting_date": { "type": "null" }, "submitted_with_unproven_supplier_email": { "type": "boolean" }, "currency": { "type": "object", "properties": { "id": { "type": "integer" }, "iso_code": { "type": "string" }, "iso_numeric": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "supplier": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "notes": { "type": "null" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "payment_details": { "type": "null" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "payment_terms": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "currency_id": { "type": "integer" }, "department_ids": { "type": "array", "items": { } }, "external_vendor_id": { "type": "null" }, "uei": { "type": "null" }, "cage_code": { "type": "null" }, "third_party_id_mappings": { "type": "array", "items": { } } } }, "invoice_line_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "sequence_no": { "type": "integer" }, "description": { "type": "string" }, "unit_price": { "type": "string" }, "quantity": { "type": "string" }, "vat": { "type": "string" }, "net_amount": { "type": "string" }, "base_net_amount": { "type": "string" }, "deleted_at": { "type": "null" }, "billable_status": { "type": "null" }, "tax_rate_id": { "type": "integer" }, "chart_of_account_id": { "type": "null" }, "qbo_customer_id": { "type": "null" }, "quickbooks_class_id": { "type": "null" }, "qbo_line_description": { "type": "null" }, "invoice_id": { "type": "integer" }, "purchase_order_id": { "type": "integer" }, "purchase_order_item_id": { "type": "integer" }, "product_id": { "type": "null" }, "markup_info": { "type": "null" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "tax_amount": { "type": "string" }, "calculated_gross_amount": { "type": "string" }, "tax_exception": { "type": "boolean" }, "chart_of_account": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "qbo_customer": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "quickbooks_class": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } } } } }, "purchase_orders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_key": { "type": "string" }, "creator_name": { "type": "string" }, "amount": { "type": "string" }, "status": { "type": "string" }, "supplier_name": { "type": "string" }, "supplier_id": { "type": "integer" }, "keywords": { "type": "string" }, "created_at": { "type": "integer" }, "currency_id": { "type": "integer" }, "currency_symbol": { "type": "string" }, "currency_iso_code": { "type": "string" }, "total_gross_amount": { "type": "string" }, "total_net_amount": { "type": "string" }, "base_gross_amount": { "type": "number" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "effective_tax_amount": { "type": "number" }, "shipping_amount_overridden": { "type": "boolean" }, "shipping_amount_override": { "type": "null" }, "effective_shipping_amount": { "type": "string" }, "submitted_on": { "type": "integer" }, "po_date": { "type": "null" }, "share_key": { "type": "string" }, "department_id": { "type": "integer" }, "department_name": { "type": "string" }, "budget_name": { "type": "string" }, "compliance_status": { "type": "null" }, "delivered_on": { "type": "null" }, "delivery_status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_progress": { "type": "string" }, "xero_export_status": { "type": "null" }, "synced_with_xero": { "type": "boolean" }, "xero_is_changed": { "type": "boolean" } } } }, "supplier_invoice_uploads": { "type": "array", "items": { } }, "histories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "comment": { "type": "string" }, "invoice_id": { "type": "integer" }, "creator_id": { "type": "integer" }, "creator_name": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "comment_formatted_time": { "type": "string" }, "comment_formatted_date": { "type": "string" }, "formatted_comment": { "type": "string" } } } }, "comments": { "type": "array", "items": { } }, "npayments": { "type": "array", "items": { } } } }, "example": { "id": 1, "invoice_number": "CH-2026-1001", "status": "outstanding", "issue_date": 1792472400, "validation_date": null, "uploaded_date": 1792576873, "due_date": 1795068000, "tax_amount": "90.0", "tax_amount_overridden": false, "tax_amount_override": null, "shipping_amount": "0.0", "shipping_amount_overridden": false, "net_amount": "900.0", "gross_amount": "990.0", "balance_amount": "990.0", "created_at": 1792576873, "updated_at": 1792576873, "standalone_invoice": false, "can_accept": false, "can_approve": true, "can_reject": true, "can_cancel": true, "can_archive": true, "can_dearchive": false, "sage_exported": false, "confidence_score": "0.0", "digital_invoice": false, "selected_purchase_order_ids": [ ], "payment_term_id": null, "payment_terms_list": null, "xero_export_status": null, "xero_export_error_message": null, "xero_last_export_at": null, "xero_is_changed": false, "duplicate_invoice_flag": false, "payment_progress": "unpaid", "gl_posting_date": null, "submitted_with_unproven_supplier_email": false, "currency": { "id": 2000, "iso_code": "USD", "iso_numeric": "840", "name": "United States Dollar", "symbol": "$", "created_at": "2026-10-21T04:44:44.793-05:00", "updated_at": "2026-10-21T04:44:44.793-05:00" }, "supplier": { "id": 2, "name": "Contoso Hardware", "company_id": 20000, "notes": null, "phone_number": "+1 555 0300", "address": "500 Tech Park, Austin, TX 78701", "email": "sales@contoso.example.com", "payment_details": null, "archived": false, "contact_person": "Diego Ramos", "tax_number": "74-7654321", "payment_terms": "Net 45", "created_at": "2026-10-21T04:48:43.563-05:00", "updated_at": "2026-10-21T04:48:43.563-05:00", "currency_id": 2000, "department_ids": [ ], "external_vendor_id": null, "uei": null, "cage_code": null, "third_party_id_mappings": [ ] }, "invoice_line_items": [ { "id": 1, "sequence_no": 1, "description": "USB-C dock", "unit_price": "150.0", "quantity": "2.0", "vat": "10.0", "net_amount": "300.0", "base_net_amount": "300.0", "deleted_at": null, "billable_status": null, "tax_rate_id": 4, "chart_of_account_id": null, "qbo_customer_id": null, "quickbooks_class_id": null, "qbo_line_description": null, "invoice_id": 1, "purchase_order_id": 1, "purchase_order_item_id": 1, "product_id": null, "markup_info": null, "created_at": 1792576873, "updated_at": 1792576873, "tax_amount": "30.0", "calculated_gross_amount": "330.0", "tax_exception": false, "chart_of_account": { "id": null, "name": null }, "qbo_customer": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null } }, { "id": 2, "sequence_no": 2, "description": "27in monitor", "unit_price": "300.0", "quantity": "2.0", "vat": "10.0", "net_amount": "600.0", "base_net_amount": "600.0", "deleted_at": null, "billable_status": null, "tax_rate_id": 4, "chart_of_account_id": null, "qbo_customer_id": null, "quickbooks_class_id": null, "qbo_line_description": null, "invoice_id": 1, "purchase_order_id": 1, "purchase_order_item_id": 2, "product_id": null, "markup_info": null, "created_at": 1792576873, "updated_at": 1792576873, "tax_amount": "60.0", "calculated_gross_amount": "660.0", "tax_exception": false, "chart_of_account": { "id": null, "name": null }, "qbo_customer": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null } } ], "purchase_orders": [ { "id": 1, "approval_key": "1-10/21/2026", "creator_name": "Jane Doe", "amount": "1200.0", "status": "approved", "supplier_name": "Contoso Hardware", "supplier_id": 2, "keywords": "1 Contoso Hardware Jane Doe 1-10/21/2026 approved 1306.50 Engineering Hardware FY26 USB-C dock 653.25 600.0 Engineering Hardware FY26 27in monitor 653.25 600.0 Not Set Not Set ", "created_at": 1792576723000, "currency_id": 2000, "currency_symbol": "$", "currency_iso_code": "USD", "total_gross_amount": "1306.5", "total_net_amount": "1200.0", "base_gross_amount": 1306.5, "tax_amount_overridden": false, "tax_amount_override": null, "effective_tax_amount": 106.5, "shipping_amount_overridden": false, "shipping_amount_override": null, "effective_shipping_amount": "0.0", "submitted_on": 1792576723000, "po_date": null, "share_key": "408EF0983EE977885C34631274E59C3B3AD1A461", "department_id": 2, "department_name": "Engineering", "budget_name": "Engineering Hardware FY26", "compliance_status": null, "delivered_on": null, "delivery_status": "not_delivered", "payment_status": "invoice_received", "payment_progress": "unpaid", "xero_export_status": null, "synced_with_xero": false, "xero_is_changed": false } ], "supplier_invoice_uploads": [ ], "histories": [ { "id": 1, "comment": "has created an invoice ", "invoice_id": 1, "creator_id": 40000, "creator_name": "Jane Doe", "created_at": 1792576873, "updated_at": 1792576873, "comment_formatted_time": "05:01", "comment_formatted_date": "2026-10-21", "formatted_comment": "

has created an invoice

" } ], "comments": [ ], "npayments": [ ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": { "supplier_id": [ "can't be blank" ] }, "status": 400 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice[invoice_number]": { "type": "string", "description": "Supplier's invoice reference. Required when the company setting `invoice_reference_mandatory` is on. Must be unique per supplier among non-cancelled invoices (`Invoice reference already exists`). Max 21 characters with an active QuickBooks connection." }, "invoice[supplier_id]": { "type": "integer", "description": "Supplier id. Optional only when the invoice is created as `awaiting_review`." }, "invoice[currency_id]": { "type": "integer", "description": "Currency id (`currency_id can't be blank` otherwise)." }, "invoice[issue_date]": { "type": "string", "format": "date", "description": "Invoice date, `YYYY-MM-DD`. Defaults to now." }, "invoice[due_date]": { "type": "string", "format": "date", "description": "Due date, `YYYY-MM-DD`. Defaults to now." }, "invoice[received_date]": { "type": "string", "format": "date", "description": "Date received, `YYYY-MM-DD`. Stored but not returned by the API." }, "invoice[uploaded_date]": { "type": "string", "format": "date", "description": "Recorded date, `YYYY-MM-DD`. Defaults to now." }, "invoice[validation_date]": { "type": "string", "format": "date", "description": "Approval date. Normally set automatically when the invoice is approved." }, "invoice[gross_amount]": { "type": "number", "description": "Ignored in practice: recomputed from the line items when saved." }, "invoice[standalone_invoice]": { "type": "boolean", "description": "Mark the invoice as not PO-backed." }, "invoice[payment_term_id]": { "type": "integer", "description": "**V1 only** (V3 ignores it). Payment term id." }, "invoice[digital_invoice]": { "type": "boolean", "description": "Marks a scanned invoice. Changes the tax calculation to use the per-line tax amounts." }, "invoice[confidence_score]": { "type": "number", "description": "Extraction confidence for scanned invoices." }, "invoice[sage_exported]": { "type": "boolean", "description": "Sage export marker." }, "invoice[selected_purchase_order_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "PO ids picked on the form (informational; the PO links come from the line items)." }, "invoice[custom_field_values_attributes][][custom_field_id]": { "type": "integer", "description": "Invoice-level custom field id. Required custom fields must be filled in." }, "invoice[custom_field_values_attributes][][value]": { "type": "string", "description": "Custom field value." }, "invoice[custom_field_values_attributes][][id]": { "type": "integer", "description": "Existing value id (update only)." }, "invoice[invoice_line_items_attributes][][description]": { "type": "string", "description": "Line description." }, "invoice[invoice_line_items_attributes][][sequence_no]": { "type": "integer", "description": "Line order. Assigned automatically when missing." }, "invoice[invoice_line_items_attributes][][quantity]": { "type": "number", "description": "Quantity." }, "invoice[invoice_line_items_attributes][][unit_price]": { "type": "number", "description": "Unit price." }, "invoice[invoice_line_items_attributes][][net_amount]": { "type": "number", "description": "Line net amount (normally `quantity x unit_price`)." }, "invoice[invoice_line_items_attributes][][vat]": { "type": "number", "description": "Tax percentage of the line. This drives the invoice tax." }, "invoice[invoice_line_items_attributes][][base_net_amount]": { "type": "number", "description": "Net amount in the company base currency." }, "invoice[invoice_line_items_attributes][][tax_rate_id]": { "type": "integer", "description": "Tax rate id (stored; the tax uses `vat`)." }, "invoice[invoice_line_items_attributes][][purchase_order_id]": { "type": "integer", "description": "PO this line bills." }, "invoice[invoice_line_items_attributes][][purchase_order_item_id]": { "type": "integer", "description": "PO line this line bills." }, "invoice[invoice_line_items_attributes][][chart_of_account_id]": { "type": "integer", "description": "Chart of account id." }, "invoice[invoice_line_items_attributes][][qbo_customer_id]": { "type": "integer", "description": "QuickBooks customer id." }, "invoice[invoice_line_items_attributes][][quickbooks_class_id]": { "type": "integer", "description": "QuickBooks class id." }, "invoice[invoice_line_items_attributes][][qbo_line_description]": { "type": "string", "description": "Line description sent to QuickBooks." }, "invoice[invoice_line_items_attributes][][billable_status]": { "type": "string", "description": "QuickBooks billable status: `NotBillable`, `Billable`, `HasBeenBilled`." }, "invoice[invoice_line_items_attributes][][custom_field_values_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "Line-level custom field values: `custom_field_id`, `value`, `id`." }, "invoice[invoice_line_items_attributes][][id]": { "type": "integer", "description": "Existing line id (update only)." }, "invoice[invoice_line_items_attributes][][_destroy]": { "type": "boolean", "description": "`true` with `id` deletes the line (update only)." }, "invoice[supplier_invoice_uploads_attributes][][file]": { "type": "string", "format": "binary", "description": "The invoice PDF as a multipart file (max 30 MB). Non-PDF: `The invoice you selected has to be a .pdf file`." }, "invoice[supplier_invoice_uploads_attributes][][id]": { "type": "integer", "description": "Existing upload id (update only)." }, "invoice[supplier_invoice_uploads_attributes][][_destroy]": { "type": "boolean", "description": "`true` with `id` removes the file (update only)." }, "invoice[company_id]": { "type": "integer", "description": "Ignored: the company always comes from `app_company_id`." } }, "required": [ "invoice[supplier_id]", "invoice[currency_id]" ] }, "example": { "invoice": { "invoice_number": "CH-2026-1001", "supplier_id": 2, "currency_id": 2000, "issue_date": "2026-10-20", "received_date": "2026-10-21", "due_date": "2026-11-19", "gross_amount": "990.00", "invoice_line_items_attributes": [ { "sequence_no": 1, "description": "USB-C dock", "quantity": 2, "unit_price": 150, "vat": 10, "net_amount": 300, "tax_rate_id": 4, "purchase_order_id": 1, "purchase_order_item_id": 1 }, { "sequence_no": 2, "description": "27in monitor", "quantity": 2, "unit_price": 300, "vat": 10, "net_amount": 600, "tax_rate_id": 4, "purchase_order_id": 1, "purchase_order_item_id": 2 } ] } } } } } } }, "/api/v3/invoices/{id}": { "get": { "tags": [ "Invoices" ], "operationId": "v3_invoices_show", "summary": "Get an invoice", "description": "Full detail of one invoice, with line items, linked POs, files, history, comments and payments.\n\nReturns the invoice in the detail format. Every field of the invoice object is\nincluded, plus `invoice_line_items`, `purchase_orders`, `supplier_invoice_uploads`\n(with signed download URLs that expire after 5 minutes), `histories`, `comments`\nand `npayments`.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "invoice_number": { "type": "string" }, "status": { "type": "string" }, "issue_date": { "type": "integer" }, "validation_date": { "type": "null" }, "uploaded_date": { "type": "integer" }, "due_date": { "type": "integer" }, "tax_amount": { "type": "string" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "shipping_amount": { "type": "string" }, "shipping_amount_overridden": { "type": "boolean" }, "net_amount": { "type": "string" }, "gross_amount": { "type": "string" }, "balance_amount": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "standalone_invoice": { "type": "boolean" }, "can_accept": { "type": "boolean" }, "can_approve": { "type": "boolean" }, "can_reject": { "type": "boolean" }, "can_cancel": { "type": "boolean" }, "can_archive": { "type": "boolean" }, "can_dearchive": { "type": "boolean" }, "sage_exported": { "type": "boolean" }, "confidence_score": { "type": "string" }, "digital_invoice": { "type": "boolean" }, "selected_purchase_order_ids": { "type": "array", "items": { } }, "payment_term_id": { "type": "integer" }, "payment_terms_list": { "type": "object", "properties": { "id": { "type": "integer" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" }, "created_at": { "type": "string" }, "day_of_month": { "type": "integer" }, "due_days": { "type": "integer" }, "name": { "type": "string" }, "term_type": { "type": "string" }, "updated_at": { "type": "string" } } }, "xero_export_status": { "type": "null" }, "xero_export_error_message": { "type": "null" }, "xero_last_export_at": { "type": "null" }, "xero_is_changed": { "type": "boolean" }, "duplicate_invoice_flag": { "type": "boolean" }, "payment_progress": { "type": "string" }, "gl_posting_date": { "type": "null" }, "submitted_with_unproven_supplier_email": { "type": "boolean" }, "currency": { "type": "object", "properties": { "id": { "type": "integer" }, "iso_code": { "type": "string" }, "iso_numeric": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "supplier": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "notes": { "type": "null" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "payment_details": { "type": "null" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "payment_terms": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "currency_id": { "type": "integer" }, "department_ids": { "type": "array", "items": { } }, "external_vendor_id": { "type": "null" }, "uei": { "type": "null" }, "cage_code": { "type": "null" }, "third_party_id_mappings": { "type": "array", "items": { } } } }, "invoice_line_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "sequence_no": { "type": "integer" }, "description": { "type": "string" }, "unit_price": { "type": "string" }, "quantity": { "type": "string" }, "vat": { "type": "string" }, "net_amount": { "type": "string" }, "base_net_amount": { "type": "string" }, "deleted_at": { "type": "null" }, "billable_status": { "type": "null" }, "tax_rate_id": { "type": "integer" }, "chart_of_account_id": { "type": "null" }, "qbo_customer_id": { "type": "null" }, "quickbooks_class_id": { "type": "null" }, "qbo_line_description": { "type": "null" }, "invoice_id": { "type": "integer" }, "purchase_order_id": { "type": "integer" }, "purchase_order_item_id": { "type": "integer" }, "product_id": { "type": "null" }, "markup_info": { "type": "null" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "tax_amount": { "type": "string" }, "calculated_gross_amount": { "type": "string" }, "tax_exception": { "type": "boolean" }, "chart_of_account": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "qbo_customer": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "quickbooks_class": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } } } } }, "purchase_orders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_key": { "type": "string" }, "creator_name": { "type": "string" }, "amount": { "type": "string" }, "status": { "type": "string" }, "supplier_name": { "type": "string" }, "supplier_id": { "type": "integer" }, "keywords": { "type": "string" }, "created_at": { "type": "integer" }, "currency_id": { "type": "integer" }, "currency_symbol": { "type": "string" }, "currency_iso_code": { "type": "string" }, "total_gross_amount": { "type": "string" }, "total_net_amount": { "type": "string" }, "base_gross_amount": { "type": "number" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "effective_tax_amount": { "type": "number" }, "shipping_amount_overridden": { "type": "boolean" }, "shipping_amount_override": { "type": "null" }, "effective_shipping_amount": { "type": "string" }, "submitted_on": { "type": "integer" }, "po_date": { "type": "null" }, "share_key": { "type": "string" }, "department_id": { "type": "integer" }, "department_name": { "type": "string" }, "budget_name": { "type": "string" }, "compliance_status": { "type": "null" }, "delivered_on": { "type": "null" }, "delivery_status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_progress": { "type": "string" }, "xero_export_status": { "type": "null" }, "synced_with_xero": { "type": "boolean" }, "xero_is_changed": { "type": "boolean" } } } }, "supplier_invoice_uploads": { "type": "array", "items": { } }, "histories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "comment": { "type": "string" }, "invoice_id": { "type": "integer" }, "creator_id": { "type": "integer" }, "creator_name": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "comment_formatted_time": { "type": "string" }, "comment_formatted_date": { "type": "string" }, "formatted_comment": { "type": "string" } } } }, "comments": { "type": "array", "items": { } }, "npayments": { "type": "array", "items": { } } } }, "example": { "id": 1, "invoice_number": "CH-2026-1001", "status": "outstanding", "issue_date": 1792472400, "validation_date": null, "uploaded_date": 1792576873, "due_date": 1796364000, "tax_amount": "45.0", "tax_amount_overridden": false, "tax_amount_override": null, "shipping_amount": "0.0", "shipping_amount_overridden": false, "net_amount": "450.0", "gross_amount": "495.0", "balance_amount": "495.0", "created_at": 1792576873, "updated_at": 1792577056, "standalone_invoice": false, "can_accept": false, "can_approve": true, "can_reject": true, "can_cancel": true, "can_archive": true, "can_dearchive": false, "sage_exported": false, "confidence_score": "0.0", "digital_invoice": false, "selected_purchase_order_ids": [ ], "payment_term_id": 3, "payment_terms_list": { "id": 3, "archived": false, "company_id": 20000, "created_at": "2026-10-21T04:44:45.145-05:00", "day_of_month": 0, "due_days": 30, "name": "Net 30", "term_type": "standard", "updated_at": "2026-10-21T04:44:45.145-05:00" }, "xero_export_status": null, "xero_export_error_message": null, "xero_last_export_at": null, "xero_is_changed": false, "duplicate_invoice_flag": false, "payment_progress": "unpaid", "gl_posting_date": null, "submitted_with_unproven_supplier_email": false, "currency": { "id": 2000, "iso_code": "USD", "iso_numeric": "840", "name": "United States Dollar", "symbol": "$", "created_at": "2026-10-21T04:44:44.793-05:00", "updated_at": "2026-10-21T04:44:44.793-05:00" }, "supplier": { "id": 2, "name": "Contoso Hardware", "company_id": 20000, "notes": null, "phone_number": "+1 555 0300", "address": "500 Tech Park, Austin, TX 78701", "email": "sales@contoso.example.com", "payment_details": null, "archived": false, "contact_person": "Diego Ramos", "tax_number": "74-7654321", "payment_terms": "Net 45", "created_at": "2026-10-21T04:48:43.563-05:00", "updated_at": "2026-10-21T04:48:43.563-05:00", "currency_id": 2000, "department_ids": [ ], "external_vendor_id": null, "uei": null, "cage_code": null, "third_party_id_mappings": [ ] }, "invoice_line_items": [ { "id": 1, "sequence_no": 1, "description": "USB-C dock", "unit_price": "150.0", "quantity": "3.0", "vat": "10.0", "net_amount": "450.0", "base_net_amount": "450.0", "deleted_at": null, "billable_status": null, "tax_rate_id": 4, "chart_of_account_id": null, "qbo_customer_id": null, "quickbooks_class_id": null, "qbo_line_description": null, "invoice_id": 1, "purchase_order_id": 1, "purchase_order_item_id": 1, "product_id": null, "markup_info": null, "created_at": 1792576873, "updated_at": 1792577056, "tax_amount": "45.0", "calculated_gross_amount": "495.0", "tax_exception": false, "chart_of_account": { "id": null, "name": null }, "qbo_customer": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null } } ], "purchase_orders": [ { "id": 1, "approval_key": "1-10/21/2026", "creator_name": "Jane Doe", "amount": "1200.0", "status": "approved", "supplier_name": "Contoso Hardware", "supplier_id": 2, "keywords": "1 Contoso Hardware Jane Doe 1-10/21/2026 approved 1306.50 Engineering Hardware FY26 USB-C dock 653.25 600.0 Engineering Hardware FY26 27in monitor 653.25 600.0 Not Set Not Set ", "created_at": 1792576723000, "currency_id": 2000, "currency_symbol": "$", "currency_iso_code": "USD", "total_gross_amount": "1306.5", "total_net_amount": "1200.0", "base_gross_amount": 1306.5, "tax_amount_overridden": false, "tax_amount_override": null, "effective_tax_amount": 106.5, "shipping_amount_overridden": false, "shipping_amount_override": null, "effective_shipping_amount": "0.0", "submitted_on": 1792576723000, "po_date": null, "share_key": "408EF0983EE977885C34631274E59C3B3AD1A461", "department_id": 2, "department_name": "Engineering", "budget_name": "Engineering Hardware FY26", "compliance_status": null, "delivered_on": null, "delivery_status": "not_delivered", "payment_status": "invoice_received", "payment_progress": "unpaid", "xero_export_status": null, "synced_with_xero": false, "xero_is_changed": false } ], "supplier_invoice_uploads": [ ], "histories": [ { "id": 1, "comment": "has created an invoice ", "invoice_id": 1, "creator_id": 40000, "creator_name": "Jane Doe", "created_at": 1792576873, "updated_at": 1792576873, "comment_formatted_time": "05:01", "comment_formatted_date": "2026-10-21", "formatted_comment": "

has created an invoice

" }, { "id": 5, "comment": "Changes made to invoice CH-2026-1001:
Line item 1 Quantity from 2.0 to 3.0
Line item 1 Net Amount from 300.0 to 450.0
Line item 1 Tax Amount from 30.0 to 45.0
Line item 1 Gross Amount from 330.0 to 495.0", "invoice_id": 1, "creator_id": 40000, "creator_name": "Jane Doe", "created_at": 1792577056, "updated_at": 1792577056, "comment_formatted_time": "05:04", "comment_formatted_date": "2026-10-21", "formatted_comment": "

Changes made to invoice CH-2026-1001:
Line item 1 Quantity from 2.0 to 3.0
Line item 1 Net Amount from 300.0 to 450.0
Line item 1 Tax Amount from 30.0 to 45.0
Line item 1 Gross Amount from 330.0 to 495.0

" } ], "comments": [ ], "npayments": [ ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] }, "put": { "tags": [ "Invoices" ], "operationId": "v3_invoices_update", "summary": "Update an invoice", "description": "Change an invoice's header fields, line items, custom fields or attached files.\n\nTakes the same `invoice[...]` parameters as [create](#create-an-invoice). Only the\nfields you send change.\n\nFor nested records:\n\n* Pass the `id` of an existing line or upload to change it.\n* Leave out `id` to add a new one.\n* Pass `id` with `_destroy: true` to delete one.\n\nAmounts are recalculated after the save. Changing `invoice_number` re-checks\nuniqueness per supplier.\n\nA history entry lists the line-level changes. The linked POs are marked\n`invoice_received`. Invoice approval flows are re-matched, and integrations\n(QuickBooks...) are updated.\n\n\nV3 ignores `invoice[payment_term_id]`: the same request sets `payment_term_id` to 3 on V1\nand leaves it null on V3. PATCH and PUT behave the same in\nboth versions.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "invoice_number": { "type": "string" }, "status": { "type": "string" }, "issue_date": { "type": "integer" }, "validation_date": { "type": "null" }, "uploaded_date": { "type": "integer" }, "due_date": { "type": "integer" }, "tax_amount": { "type": "string" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "shipping_amount": { "type": "string" }, "shipping_amount_overridden": { "type": "boolean" }, "net_amount": { "type": "string" }, "gross_amount": { "type": "string" }, "balance_amount": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "standalone_invoice": { "type": "boolean" }, "can_accept": { "type": "boolean" }, "can_approve": { "type": "boolean" }, "can_reject": { "type": "boolean" }, "can_cancel": { "type": "boolean" }, "can_archive": { "type": "boolean" }, "can_dearchive": { "type": "boolean" }, "sage_exported": { "type": "boolean" }, "confidence_score": { "type": "string" }, "digital_invoice": { "type": "boolean" }, "selected_purchase_order_ids": { "type": "array", "items": { } }, "payment_term_id": { "type": "null" }, "payment_terms_list": { "type": "null" }, "xero_export_status": { "type": "null" }, "xero_export_error_message": { "type": "null" }, "xero_last_export_at": { "type": "null" }, "xero_is_changed": { "type": "boolean" }, "duplicate_invoice_flag": { "type": "boolean" }, "payment_progress": { "type": "string" }, "gl_posting_date": { "type": "null" }, "submitted_with_unproven_supplier_email": { "type": "boolean" }, "currency": { "type": "object", "properties": { "id": { "type": "integer" }, "iso_code": { "type": "string" }, "iso_numeric": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "supplier": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "notes": { "type": "null" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "payment_details": { "type": "null" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "payment_terms": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "currency_id": { "type": "integer" }, "department_ids": { "type": "array", "items": { } }, "external_vendor_id": { "type": "null" }, "uei": { "type": "null" }, "cage_code": { "type": "null" }, "third_party_id_mappings": { "type": "array", "items": { } } } }, "invoice_line_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "sequence_no": { "type": "integer" }, "description": { "type": "string" }, "unit_price": { "type": "string" }, "quantity": { "type": "string" }, "vat": { "type": "string" }, "net_amount": { "type": "string" }, "base_net_amount": { "type": "string" }, "deleted_at": { "type": "null" }, "billable_status": { "type": "null" }, "tax_rate_id": { "type": "integer" }, "chart_of_account_id": { "type": "null" }, "qbo_customer_id": { "type": "null" }, "quickbooks_class_id": { "type": "null" }, "qbo_line_description": { "type": "null" }, "invoice_id": { "type": "integer" }, "purchase_order_id": { "type": "integer" }, "purchase_order_item_id": { "type": "integer" }, "product_id": { "type": "null" }, "markup_info": { "type": "null" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "tax_amount": { "type": "string" }, "calculated_gross_amount": { "type": "string" }, "tax_exception": { "type": "boolean" }, "chart_of_account": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "qbo_customer": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "quickbooks_class": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } } } } }, "purchase_orders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_key": { "type": "string" }, "creator_name": { "type": "string" }, "amount": { "type": "string" }, "status": { "type": "string" }, "supplier_name": { "type": "string" }, "supplier_id": { "type": "integer" }, "keywords": { "type": "string" }, "created_at": { "type": "integer" }, "currency_id": { "type": "integer" }, "currency_symbol": { "type": "string" }, "currency_iso_code": { "type": "string" }, "total_gross_amount": { "type": "string" }, "total_net_amount": { "type": "string" }, "base_gross_amount": { "type": "number" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "effective_tax_amount": { "type": "number" }, "shipping_amount_overridden": { "type": "boolean" }, "shipping_amount_override": { "type": "null" }, "effective_shipping_amount": { "type": "string" }, "submitted_on": { "type": "integer" }, "po_date": { "type": "null" }, "share_key": { "type": "string" }, "department_id": { "type": "integer" }, "department_name": { "type": "string" }, "budget_name": { "type": "string" }, "compliance_status": { "type": "null" }, "delivered_on": { "type": "null" }, "delivery_status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_progress": { "type": "string" }, "xero_export_status": { "type": "null" }, "synced_with_xero": { "type": "boolean" }, "xero_is_changed": { "type": "boolean" } } } }, "supplier_invoice_uploads": { "type": "array", "items": { } }, "histories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "comment": { "type": "string" }, "invoice_id": { "type": "integer" }, "creator_id": { "type": "integer" }, "creator_name": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "comment_formatted_time": { "type": "string" }, "comment_formatted_date": { "type": "string" }, "formatted_comment": { "type": "string" } } } }, "comments": { "type": "array", "items": { } }, "npayments": { "type": "array", "items": { } } } }, "example": { "id": 2, "invoice_number": "CH-2026-1002", "status": "outstanding", "issue_date": 1792472400, "validation_date": null, "uploaded_date": 1792576882, "due_date": 1796364000, "tax_amount": "45.0", "tax_amount_overridden": false, "tax_amount_override": null, "shipping_amount": "0.0", "shipping_amount_overridden": false, "net_amount": "450.0", "gross_amount": "495.0", "balance_amount": "495.0", "created_at": 1792576882, "updated_at": 1792577065, "standalone_invoice": false, "can_accept": false, "can_approve": true, "can_reject": true, "can_cancel": true, "can_archive": true, "can_dearchive": false, "sage_exported": false, "confidence_score": "0.0", "digital_invoice": false, "selected_purchase_order_ids": [ ], "payment_term_id": null, "payment_terms_list": null, "xero_export_status": null, "xero_export_error_message": null, "xero_last_export_at": null, "xero_is_changed": false, "duplicate_invoice_flag": false, "payment_progress": "unpaid", "gl_posting_date": null, "submitted_with_unproven_supplier_email": false, "currency": { "id": 2000, "iso_code": "USD", "iso_numeric": "840", "name": "United States Dollar", "symbol": "$", "created_at": "2026-10-21T04:44:44.793-05:00", "updated_at": "2026-10-21T04:44:44.793-05:00" }, "supplier": { "id": 2, "name": "Contoso Hardware", "company_id": 20000, "notes": null, "phone_number": "+1 555 0300", "address": "500 Tech Park, Austin, TX 78701", "email": "sales@contoso.example.com", "payment_details": null, "archived": false, "contact_person": "Diego Ramos", "tax_number": "74-7654321", "payment_terms": "Net 45", "created_at": "2026-10-21T04:48:43.563-05:00", "updated_at": "2026-10-21T04:48:43.563-05:00", "currency_id": 2000, "department_ids": [ ], "external_vendor_id": null, "uei": null, "cage_code": null, "third_party_id_mappings": [ ] }, "invoice_line_items": [ { "id": 3, "sequence_no": 1, "description": "USB-C dock", "unit_price": "150.0", "quantity": "3.0", "vat": "10.0", "net_amount": "450.0", "base_net_amount": "450.0", "deleted_at": null, "billable_status": null, "tax_rate_id": 4, "chart_of_account_id": null, "qbo_customer_id": null, "quickbooks_class_id": null, "qbo_line_description": null, "invoice_id": 2, "purchase_order_id": 4, "purchase_order_item_id": 6, "product_id": null, "markup_info": null, "created_at": 1792576882, "updated_at": 1792577065, "tax_amount": "45.0", "calculated_gross_amount": "495.0", "tax_exception": false, "chart_of_account": { "id": null, "name": null }, "qbo_customer": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null } } ], "purchase_orders": [ { "id": 4, "approval_key": "4-10/21/2026", "creator_name": "Jane Doe", "amount": "1200.0", "status": "approved", "supplier_name": "Contoso Hardware", "supplier_id": 2, "keywords": "4 Contoso Hardware Jane Doe 4-10/21/2026 approved 1306.50 Engineering Hardware FY26 USB-C dock 653.25 600.0 Engineering Hardware FY26 27in monitor 653.25 600.0 Not Set Not Set ", "created_at": 1792576811000, "currency_id": 2000, "currency_symbol": "$", "currency_iso_code": "USD", "total_gross_amount": "1306.5", "total_net_amount": "1200.0", "base_gross_amount": 1306.5, "tax_amount_overridden": false, "tax_amount_override": null, "effective_tax_amount": 106.5, "shipping_amount_overridden": false, "shipping_amount_override": null, "effective_shipping_amount": "0.0", "submitted_on": 1792576811000, "po_date": null, "share_key": "BC85C70BB47874D5FE56B85FB6FF6F65B1D13753", "department_id": 2, "department_name": "Engineering", "budget_name": "Engineering Hardware FY26", "compliance_status": null, "delivered_on": null, "delivery_status": "not_delivered", "payment_status": "invoice_received", "payment_progress": "unpaid", "xero_export_status": null, "synced_with_xero": false, "xero_is_changed": false } ], "supplier_invoice_uploads": [ ], "histories": [ { "id": 2, "comment": "has created an invoice ", "invoice_id": 2, "creator_id": 40000, "creator_name": "Jane Doe", "created_at": 1792576882, "updated_at": 1792576882, "comment_formatted_time": "05:01", "comment_formatted_date": "2026-10-21", "formatted_comment": "

has created an invoice

" }, { "id": 6, "comment": "Changes made to invoice CH-2026-1002:
Line item 1 Quantity from 2.0 to 3.0
Line item 1 Net Amount from 300.0 to 450.0
Line item 1 Tax Amount from 30.0 to 45.0
Line item 1 Gross Amount from 330.0 to 495.0", "invoice_id": 2, "creator_id": 40000, "creator_name": "Jane Doe", "created_at": 1792577065, "updated_at": 1792577065, "comment_formatted_time": "05:04", "comment_formatted_date": "2026-10-21", "formatted_comment": "

Changes made to invoice CH-2026-1002:
Line item 1 Quantity from 2.0 to 3.0
Line item 1 Net Amount from 300.0 to 450.0
Line item 1 Tax Amount from 30.0 to 45.0
Line item 1 Gross Amount from 330.0 to 495.0

" } ], "comments": [ ], "npayments": [ ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": { "invoice_number": [ "Invoice reference already exists" ] }, "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice[...]": { "type": "object", "description": "Any parameter of [create](#create-an-invoice), with the same rules (V3 again ignores `payment_term_id`)." }, "invoice[invoice_line_items_attributes][][id]": { "type": "integer", "description": "Id of the line to change or delete." }, "invoice[invoice_line_items_attributes][][_destroy]": { "type": "boolean", "description": "`true` deletes the line given by `id`." }, "invoice[supplier_invoice_uploads_attributes][][id]": { "type": "integer", "description": "Id of the file to remove (with `_destroy: true`)." }, "invoice[custom_field_values_attributes][][id]": { "type": "integer", "description": "Id of the custom field value to change." } } }, "example": { "invoice": { "due_date": "2026-12-04", "payment_term_id": 3, "custom_field_values_attributes": [ { "custom_field_id": 4, "value": "AP-2026-10-B" } ], "invoice_line_items_attributes": [ { "id": 3, "quantity": 3, "net_amount": 450 }, { "id": 4, "_destroy": true } ] } } } } } } }, "/api/v1/invoices/{id}": { "get": { "tags": [ "Invoices" ], "operationId": "v1_invoices_show", "summary": "Get an invoice", "description": "Full detail of one invoice, with line items, linked POs, files, history, comments and payments.\n\nReturns the invoice in the detail format. Every field of the invoice object is\nincluded, plus `invoice_line_items`, `purchase_orders`, `supplier_invoice_uploads`\n(with signed download URLs that expire after 5 minutes), `histories`, `comments`\nand `npayments`.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "invoice_number": { "type": "string" }, "status": { "type": "string" }, "issue_date": { "type": "integer" }, "validation_date": { "type": "null" }, "uploaded_date": { "type": "integer" }, "due_date": { "type": "integer" }, "tax_amount": { "type": "string" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "shipping_amount": { "type": "string" }, "shipping_amount_overridden": { "type": "boolean" }, "net_amount": { "type": "string" }, "gross_amount": { "type": "string" }, "balance_amount": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "standalone_invoice": { "type": "boolean" }, "can_accept": { "type": "boolean" }, "can_approve": { "type": "boolean" }, "can_reject": { "type": "boolean" }, "can_cancel": { "type": "boolean" }, "can_archive": { "type": "boolean" }, "can_dearchive": { "type": "boolean" }, "sage_exported": { "type": "boolean" }, "confidence_score": { "type": "string" }, "digital_invoice": { "type": "boolean" }, "selected_purchase_order_ids": { "type": "array", "items": { } }, "payment_term_id": { "type": "integer" }, "payment_terms_list": { "type": "object", "properties": { "id": { "type": "integer" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" }, "created_at": { "type": "string" }, "day_of_month": { "type": "integer" }, "due_days": { "type": "integer" }, "name": { "type": "string" }, "term_type": { "type": "string" }, "updated_at": { "type": "string" } } }, "xero_export_status": { "type": "null" }, "xero_export_error_message": { "type": "null" }, "xero_last_export_at": { "type": "null" }, "xero_is_changed": { "type": "boolean" }, "duplicate_invoice_flag": { "type": "boolean" }, "payment_progress": { "type": "string" }, "gl_posting_date": { "type": "null" }, "submitted_with_unproven_supplier_email": { "type": "boolean" }, "currency": { "type": "object", "properties": { "id": { "type": "integer" }, "iso_code": { "type": "string" }, "iso_numeric": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "supplier": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "notes": { "type": "null" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "payment_details": { "type": "null" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "payment_terms": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "currency_id": { "type": "integer" }, "department_ids": { "type": "array", "items": { } }, "external_vendor_id": { "type": "null" }, "uei": { "type": "null" }, "cage_code": { "type": "null" }, "third_party_id_mappings": { "type": "array", "items": { } } } }, "invoice_line_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "sequence_no": { "type": "integer" }, "description": { "type": "string" }, "unit_price": { "type": "string" }, "quantity": { "type": "string" }, "vat": { "type": "string" }, "net_amount": { "type": "string" }, "base_net_amount": { "type": "string" }, "deleted_at": { "type": "null" }, "billable_status": { "type": "null" }, "tax_rate_id": { "type": "integer" }, "chart_of_account_id": { "type": "null" }, "qbo_customer_id": { "type": "null" }, "quickbooks_class_id": { "type": "null" }, "qbo_line_description": { "type": "null" }, "invoice_id": { "type": "integer" }, "purchase_order_id": { "type": "integer" }, "purchase_order_item_id": { "type": "integer" }, "product_id": { "type": "null" }, "markup_info": { "type": "null" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "tax_amount": { "type": "string" }, "calculated_gross_amount": { "type": "string" }, "tax_exception": { "type": "boolean" }, "chart_of_account": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "qbo_customer": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "quickbooks_class": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } } } } }, "purchase_orders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_key": { "type": "string" }, "creator_name": { "type": "string" }, "amount": { "type": "string" }, "status": { "type": "string" }, "supplier_name": { "type": "string" }, "supplier_id": { "type": "integer" }, "keywords": { "type": "string" }, "created_at": { "type": "integer" }, "currency_id": { "type": "integer" }, "currency_symbol": { "type": "string" }, "currency_iso_code": { "type": "string" }, "total_gross_amount": { "type": "string" }, "total_net_amount": { "type": "string" }, "base_gross_amount": { "type": "number" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "effective_tax_amount": { "type": "number" }, "shipping_amount_overridden": { "type": "boolean" }, "shipping_amount_override": { "type": "null" }, "effective_shipping_amount": { "type": "string" }, "submitted_on": { "type": "integer" }, "po_date": { "type": "null" }, "share_key": { "type": "string" }, "department_id": { "type": "integer" }, "department_name": { "type": "string" }, "budget_name": { "type": "string" }, "compliance_status": { "type": "null" }, "delivered_on": { "type": "null" }, "delivery_status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_progress": { "type": "string" }, "xero_export_status": { "type": "null" }, "synced_with_xero": { "type": "boolean" }, "xero_is_changed": { "type": "boolean" } } } }, "supplier_invoice_uploads": { "type": "array", "items": { } }, "histories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "comment": { "type": "string" }, "invoice_id": { "type": "integer" }, "creator_id": { "type": "integer" }, "creator_name": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "comment_formatted_time": { "type": "string" }, "comment_formatted_date": { "type": "string" }, "formatted_comment": { "type": "string" } } } }, "comments": { "type": "array", "items": { } }, "npayments": { "type": "array", "items": { } } } }, "example": { "id": 1, "invoice_number": "CH-2026-1001", "status": "outstanding", "issue_date": 1792472400, "validation_date": null, "uploaded_date": 1792576873, "due_date": 1796364000, "tax_amount": "45.0", "tax_amount_overridden": false, "tax_amount_override": null, "shipping_amount": "0.0", "shipping_amount_overridden": false, "net_amount": "450.0", "gross_amount": "495.0", "balance_amount": "495.0", "created_at": 1792576873, "updated_at": 1792577056, "standalone_invoice": false, "can_accept": false, "can_approve": true, "can_reject": true, "can_cancel": true, "can_archive": true, "can_dearchive": false, "sage_exported": false, "confidence_score": "0.0", "digital_invoice": false, "selected_purchase_order_ids": [ ], "payment_term_id": 3, "payment_terms_list": { "id": 3, "archived": false, "company_id": 20000, "created_at": "2026-10-21T04:44:45.145-05:00", "day_of_month": 0, "due_days": 30, "name": "Net 30", "term_type": "standard", "updated_at": "2026-10-21T04:44:45.145-05:00" }, "xero_export_status": null, "xero_export_error_message": null, "xero_last_export_at": null, "xero_is_changed": false, "duplicate_invoice_flag": false, "payment_progress": "unpaid", "gl_posting_date": null, "submitted_with_unproven_supplier_email": false, "currency": { "id": 2000, "iso_code": "USD", "iso_numeric": "840", "name": "United States Dollar", "symbol": "$", "created_at": "2026-10-21T04:44:44.793-05:00", "updated_at": "2026-10-21T04:44:44.793-05:00" }, "supplier": { "id": 2, "name": "Contoso Hardware", "company_id": 20000, "notes": null, "phone_number": "+1 555 0300", "address": "500 Tech Park, Austin, TX 78701", "email": "sales@contoso.example.com", "payment_details": null, "archived": false, "contact_person": "Diego Ramos", "tax_number": "74-7654321", "payment_terms": "Net 45", "created_at": "2026-10-21T04:48:43.563-05:00", "updated_at": "2026-10-21T04:48:43.563-05:00", "currency_id": 2000, "department_ids": [ ], "external_vendor_id": null, "uei": null, "cage_code": null, "third_party_id_mappings": [ ] }, "invoice_line_items": [ { "id": 1, "sequence_no": 1, "description": "USB-C dock", "unit_price": "150.0", "quantity": "3.0", "vat": "10.0", "net_amount": "450.0", "base_net_amount": "450.0", "deleted_at": null, "billable_status": null, "tax_rate_id": 4, "chart_of_account_id": null, "qbo_customer_id": null, "quickbooks_class_id": null, "qbo_line_description": null, "invoice_id": 1, "purchase_order_id": 1, "purchase_order_item_id": 1, "product_id": null, "markup_info": null, "created_at": 1792576873, "updated_at": 1792577056, "tax_amount": "45.0", "calculated_gross_amount": "495.0", "tax_exception": false, "chart_of_account": { "id": null, "name": null }, "qbo_customer": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null } } ], "purchase_orders": [ { "id": 1, "approval_key": "1-10/21/2026", "creator_name": "Jane Doe", "amount": "1200.0", "status": "approved", "supplier_name": "Contoso Hardware", "supplier_id": 2, "keywords": "1 Contoso Hardware Jane Doe 1-10/21/2026 approved 1306.50 Engineering Hardware FY26 USB-C dock 653.25 600.0 Engineering Hardware FY26 27in monitor 653.25 600.0 Not Set Not Set ", "created_at": 1792576723000, "currency_id": 2000, "currency_symbol": "$", "currency_iso_code": "USD", "total_gross_amount": "1306.5", "total_net_amount": "1200.0", "base_gross_amount": 1306.5, "tax_amount_overridden": false, "tax_amount_override": null, "effective_tax_amount": 106.5, "shipping_amount_overridden": false, "shipping_amount_override": null, "effective_shipping_amount": "0.0", "submitted_on": 1792576723000, "po_date": null, "share_key": "408EF0983EE977885C34631274E59C3B3AD1A461", "department_id": 2, "department_name": "Engineering", "budget_name": "Engineering Hardware FY26", "compliance_status": null, "delivered_on": null, "delivery_status": "not_delivered", "payment_status": "invoice_received", "payment_progress": "unpaid", "xero_export_status": null, "synced_with_xero": false, "xero_is_changed": false } ], "supplier_invoice_uploads": [ ], "histories": [ { "id": 1, "comment": "has created an invoice ", "invoice_id": 1, "creator_id": 40000, "creator_name": "Jane Doe", "created_at": 1792576873, "updated_at": 1792576873, "comment_formatted_time": "05:01", "comment_formatted_date": "2026-10-21", "formatted_comment": "

has created an invoice

" }, { "id": 5, "comment": "Changes made to invoice CH-2026-1001:
Line item 1 Quantity from 2.0 to 3.0
Line item 1 Net Amount from 300.0 to 450.0
Line item 1 Tax Amount from 30.0 to 45.0
Line item 1 Gross Amount from 330.0 to 495.0", "invoice_id": 1, "creator_id": 40000, "creator_name": "Jane Doe", "created_at": 1792577056, "updated_at": 1792577056, "comment_formatted_time": "05:04", "comment_formatted_date": "2026-10-21", "formatted_comment": "

Changes made to invoice CH-2026-1001:
Line item 1 Quantity from 2.0 to 3.0
Line item 1 Net Amount from 300.0 to 450.0
Line item 1 Tax Amount from 30.0 to 45.0
Line item 1 Gross Amount from 330.0 to 495.0

" } ], "comments": [ ], "npayments": [ ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "put": { "tags": [ "Invoices" ], "operationId": "v1_invoices_update", "summary": "Update an invoice", "description": "Change an invoice's header fields, line items, custom fields or attached files.\n\nTakes the same `invoice[...]` parameters as [create](#create-an-invoice). Only the\nfields you send change.\n\nFor nested records:\n\n* Pass the `id` of an existing line or upload to change it.\n* Leave out `id` to add a new one.\n* Pass `id` with `_destroy: true` to delete one.\n\nAmounts are recalculated after the save. Changing `invoice_number` re-checks\nuniqueness per supplier.\n\nA history entry lists the line-level changes. The linked POs are marked\n`invoice_received`. Invoice approval flows are re-matched, and integrations\n(QuickBooks...) are updated.\n\n\nV3 ignores `invoice[payment_term_id]`: the same request sets `payment_term_id` to 3 on V1\nand leaves it null on V3. PATCH and PUT behave the same in\nboth versions.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "invoice_number": { "type": "string" }, "status": { "type": "string" }, "issue_date": { "type": "integer" }, "validation_date": { "type": "null" }, "uploaded_date": { "type": "integer" }, "due_date": { "type": "integer" }, "tax_amount": { "type": "string" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "shipping_amount": { "type": "string" }, "shipping_amount_overridden": { "type": "boolean" }, "net_amount": { "type": "string" }, "gross_amount": { "type": "string" }, "balance_amount": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "standalone_invoice": { "type": "boolean" }, "can_accept": { "type": "boolean" }, "can_approve": { "type": "boolean" }, "can_reject": { "type": "boolean" }, "can_cancel": { "type": "boolean" }, "can_archive": { "type": "boolean" }, "can_dearchive": { "type": "boolean" }, "sage_exported": { "type": "boolean" }, "confidence_score": { "type": "string" }, "digital_invoice": { "type": "boolean" }, "selected_purchase_order_ids": { "type": "array", "items": { } }, "payment_term_id": { "type": "integer" }, "payment_terms_list": { "type": "object", "properties": { "id": { "type": "integer" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" }, "created_at": { "type": "string" }, "day_of_month": { "type": "integer" }, "due_days": { "type": "integer" }, "name": { "type": "string" }, "term_type": { "type": "string" }, "updated_at": { "type": "string" } } }, "xero_export_status": { "type": "null" }, "xero_export_error_message": { "type": "null" }, "xero_last_export_at": { "type": "null" }, "xero_is_changed": { "type": "boolean" }, "duplicate_invoice_flag": { "type": "boolean" }, "payment_progress": { "type": "string" }, "gl_posting_date": { "type": "null" }, "submitted_with_unproven_supplier_email": { "type": "boolean" }, "currency": { "type": "object", "properties": { "id": { "type": "integer" }, "iso_code": { "type": "string" }, "iso_numeric": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "supplier": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "notes": { "type": "null" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "payment_details": { "type": "null" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "payment_terms": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "currency_id": { "type": "integer" }, "department_ids": { "type": "array", "items": { } }, "external_vendor_id": { "type": "null" }, "uei": { "type": "null" }, "cage_code": { "type": "null" }, "third_party_id_mappings": { "type": "array", "items": { } } } }, "invoice_line_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "sequence_no": { "type": "integer" }, "description": { "type": "string" }, "unit_price": { "type": "string" }, "quantity": { "type": "string" }, "vat": { "type": "string" }, "net_amount": { "type": "string" }, "base_net_amount": { "type": "string" }, "deleted_at": { "type": "null" }, "billable_status": { "type": "null" }, "tax_rate_id": { "type": "integer" }, "chart_of_account_id": { "type": "null" }, "qbo_customer_id": { "type": "null" }, "quickbooks_class_id": { "type": "null" }, "qbo_line_description": { "type": "null" }, "invoice_id": { "type": "integer" }, "purchase_order_id": { "type": "integer" }, "purchase_order_item_id": { "type": "integer" }, "product_id": { "type": "null" }, "markup_info": { "type": "null" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "tax_amount": { "type": "string" }, "calculated_gross_amount": { "type": "string" }, "tax_exception": { "type": "boolean" }, "chart_of_account": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "qbo_customer": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "quickbooks_class": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } } } } }, "purchase_orders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_key": { "type": "string" }, "creator_name": { "type": "string" }, "amount": { "type": "string" }, "status": { "type": "string" }, "supplier_name": { "type": "string" }, "supplier_id": { "type": "integer" }, "keywords": { "type": "string" }, "created_at": { "type": "integer" }, "currency_id": { "type": "integer" }, "currency_symbol": { "type": "string" }, "currency_iso_code": { "type": "string" }, "total_gross_amount": { "type": "string" }, "total_net_amount": { "type": "string" }, "base_gross_amount": { "type": "number" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "effective_tax_amount": { "type": "number" }, "shipping_amount_overridden": { "type": "boolean" }, "shipping_amount_override": { "type": "null" }, "effective_shipping_amount": { "type": "string" }, "submitted_on": { "type": "integer" }, "po_date": { "type": "null" }, "share_key": { "type": "string" }, "department_id": { "type": "integer" }, "department_name": { "type": "string" }, "budget_name": { "type": "string" }, "compliance_status": { "type": "null" }, "delivered_on": { "type": "null" }, "delivery_status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_progress": { "type": "string" }, "xero_export_status": { "type": "null" }, "synced_with_xero": { "type": "boolean" }, "xero_is_changed": { "type": "boolean" } } } }, "supplier_invoice_uploads": { "type": "array", "items": { } }, "histories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "comment": { "type": "string" }, "invoice_id": { "type": "integer" }, "creator_id": { "type": "integer" }, "creator_name": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "comment_formatted_time": { "type": "string" }, "comment_formatted_date": { "type": "string" }, "formatted_comment": { "type": "string" } } } }, "comments": { "type": "array", "items": { } }, "npayments": { "type": "array", "items": { } } } }, "example": { "id": 1, "invoice_number": "CH-2026-1001", "status": "outstanding", "issue_date": 1792472400, "validation_date": null, "uploaded_date": 1792576873, "due_date": 1796364000, "tax_amount": "45.0", "tax_amount_overridden": false, "tax_amount_override": null, "shipping_amount": "0.0", "shipping_amount_overridden": false, "net_amount": "450.0", "gross_amount": "495.0", "balance_amount": "495.0", "created_at": 1792576873, "updated_at": 1792577056, "standalone_invoice": false, "can_accept": false, "can_approve": true, "can_reject": true, "can_cancel": true, "can_archive": true, "can_dearchive": false, "sage_exported": false, "confidence_score": "0.0", "digital_invoice": false, "selected_purchase_order_ids": [ ], "payment_term_id": 3, "payment_terms_list": { "id": 3, "archived": false, "company_id": 20000, "created_at": "2026-10-21T04:44:45.145-05:00", "day_of_month": 0, "due_days": 30, "name": "Net 30", "term_type": "standard", "updated_at": "2026-10-21T04:44:45.145-05:00" }, "xero_export_status": null, "xero_export_error_message": null, "xero_last_export_at": null, "xero_is_changed": false, "duplicate_invoice_flag": false, "payment_progress": "unpaid", "gl_posting_date": null, "submitted_with_unproven_supplier_email": false, "currency": { "id": 2000, "iso_code": "USD", "iso_numeric": "840", "name": "United States Dollar", "symbol": "$", "created_at": "2026-10-21T04:44:44.793-05:00", "updated_at": "2026-10-21T04:44:44.793-05:00" }, "supplier": { "id": 2, "name": "Contoso Hardware", "company_id": 20000, "notes": null, "phone_number": "+1 555 0300", "address": "500 Tech Park, Austin, TX 78701", "email": "sales@contoso.example.com", "payment_details": null, "archived": false, "contact_person": "Diego Ramos", "tax_number": "74-7654321", "payment_terms": "Net 45", "created_at": "2026-10-21T04:48:43.563-05:00", "updated_at": "2026-10-21T04:48:43.563-05:00", "currency_id": 2000, "department_ids": [ ], "external_vendor_id": null, "uei": null, "cage_code": null, "third_party_id_mappings": [ ] }, "invoice_line_items": [ { "id": 1, "sequence_no": 1, "description": "USB-C dock", "unit_price": "150.0", "quantity": "3.0", "vat": "10.0", "net_amount": "450.0", "base_net_amount": "450.0", "deleted_at": null, "billable_status": null, "tax_rate_id": 4, "chart_of_account_id": null, "qbo_customer_id": null, "quickbooks_class_id": null, "qbo_line_description": null, "invoice_id": 1, "purchase_order_id": 1, "purchase_order_item_id": 1, "product_id": null, "markup_info": null, "created_at": 1792576873, "updated_at": 1792577056, "tax_amount": "45.0", "calculated_gross_amount": "495.0", "tax_exception": false, "chart_of_account": { "id": null, "name": null }, "qbo_customer": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null } } ], "purchase_orders": [ { "id": 1, "approval_key": "1-10/21/2026", "creator_name": "Jane Doe", "amount": "1200.0", "status": "approved", "supplier_name": "Contoso Hardware", "supplier_id": 2, "keywords": "1 Contoso Hardware Jane Doe 1-10/21/2026 approved 1306.50 Engineering Hardware FY26 USB-C dock 653.25 600.0 Engineering Hardware FY26 27in monitor 653.25 600.0 Not Set Not Set ", "created_at": 1792576723000, "currency_id": 2000, "currency_symbol": "$", "currency_iso_code": "USD", "total_gross_amount": "1306.5", "total_net_amount": "1200.0", "base_gross_amount": 1306.5, "tax_amount_overridden": false, "tax_amount_override": null, "effective_tax_amount": 106.5, "shipping_amount_overridden": false, "shipping_amount_override": null, "effective_shipping_amount": "0.0", "submitted_on": 1792576723000, "po_date": null, "share_key": "408EF0983EE977885C34631274E59C3B3AD1A461", "department_id": 2, "department_name": "Engineering", "budget_name": "Engineering Hardware FY26", "compliance_status": null, "delivered_on": null, "delivery_status": "not_delivered", "payment_status": "invoice_received", "payment_progress": "unpaid", "xero_export_status": null, "synced_with_xero": false, "xero_is_changed": false } ], "supplier_invoice_uploads": [ ], "histories": [ { "id": 1, "comment": "has created an invoice ", "invoice_id": 1, "creator_id": 40000, "creator_name": "Jane Doe", "created_at": 1792576873, "updated_at": 1792576873, "comment_formatted_time": "05:01", "comment_formatted_date": "2026-10-21", "formatted_comment": "

has created an invoice

" }, { "id": 5, "comment": "Changes made to invoice CH-2026-1001:
Line item 1 Quantity from 2.0 to 3.0
Line item 1 Net Amount from 300.0 to 450.0
Line item 1 Tax Amount from 30.0 to 45.0
Line item 1 Gross Amount from 330.0 to 495.0", "invoice_id": 1, "creator_id": 40000, "creator_name": "Jane Doe", "created_at": 1792577056, "updated_at": 1792577056, "comment_formatted_time": "05:04", "comment_formatted_date": "2026-10-21", "formatted_comment": "

Changes made to invoice CH-2026-1001:
Line item 1 Quantity from 2.0 to 3.0
Line item 1 Net Amount from 300.0 to 450.0
Line item 1 Tax Amount from 30.0 to 45.0
Line item 1 Gross Amount from 330.0 to 495.0

" } ], "comments": [ ], "npayments": [ ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": { "invoice_number": [ "Invoice reference already exists" ] }, "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice[...]": { "type": "object", "description": "Any parameter of [create](#create-an-invoice), with the same rules (V3 again ignores `payment_term_id`)." }, "invoice[invoice_line_items_attributes][][id]": { "type": "integer", "description": "Id of the line to change or delete." }, "invoice[invoice_line_items_attributes][][_destroy]": { "type": "boolean", "description": "`true` deletes the line given by `id`." }, "invoice[supplier_invoice_uploads_attributes][][id]": { "type": "integer", "description": "Id of the file to remove (with `_destroy: true`)." }, "invoice[custom_field_values_attributes][][id]": { "type": "integer", "description": "Id of the custom field value to change." } } }, "example": { "invoice": { "due_date": "2026-12-04", "payment_term_id": 3, "custom_field_values_attributes": [ { "custom_field_id": 4, "value": "AP-2026-10-B" } ], "invoice_line_items_attributes": [ { "id": 1, "quantity": 3, "net_amount": 450 }, { "id": 2, "_destroy": true } ] } } } } } } }, "/api/v3/invoices/purchase_order_list": { "get": { "tags": [ "Invoices" ], "operationId": "v3_invoices_po_list", "summary": "List purchase orders to invoice", "description": "Approved purchase orders of a supplier that still have work to invoice.\n\nUse this endpoint to pick the POs an invoice bills. It returns POs of the company\nthat match all of these conditions:\n\n* They belong to the given `supplier_id`. **This parameter is effectively\n required**: without it, only POs with no supplier are returned, which is usually\n none.\n* They use the given `currency_id` (default: the company currency).\n* They are not archived.\n* Their status is `approved`, or `draft` / `pending` / `approved` with\n `include_unapproved=true`.\n* They are not fully invoiced yet. Only invoices that are `ready_to_pay` or\n `settled` count toward that.\n\nThe results are limited to POs the user can open. POs listed in `selected_ids` are\nalways included and listed first, even when they do not match the filters.\n\n\nNone - identical request and response.", "parameters": [ { "name": "supplier_id", "in": "query", "required": true, "description": "Supplier id.", "schema": { "type": "integer" } }, { "name": "currency_id", "in": "query", "required": false, "description": "PO currency.", "schema": { "type": "integer" } }, { "name": "selected_ids", "in": "query", "required": false, "description": "Comma-separated PO ids to always include (shown first), e.g. POs already on the invoice.", "schema": { "type": "string" } }, { "name": "include_unapproved", "in": "query", "required": false, "description": "`true` also returns `draft` and `pending` POs.", "schema": { "type": "boolean" } }, { "name": "q", "in": "query", "required": false, "description": "PO search text (alias `keyword`).", "schema": { "type": "string" } }, { "name": "requester_ids", "in": "query", "required": false, "description": "Comma-separated creator ids.", "schema": { "type": "string" } }, { "name": "budget_ids", "in": "query", "required": false, "description": "Comma-separated budget ids.", "schema": { "type": "string" } }, { "name": "filter_dept_ids", "in": "query", "required": false, "description": "Comma-separated department ids.", "schema": { "type": "string" } }, { "name": "approver_ids", "in": "query", "required": false, "description": "Comma-separated approver ids.", "schema": { "type": "string" } }, { "name": "supplier_email_status", "in": "query", "required": false, "description": "Comma-separated supplier email statuses.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Allow-listed PO sort column.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "`asc` or `desc`.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Page size (any value).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase_orders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_key": { "type": "string" }, "creator_name": { "type": "string" }, "amount": { "type": "string" }, "status": { "type": "string" }, "supplier_name": { "type": "string" }, "supplier_id": { "type": "integer" }, "keywords": { "type": "string" }, "created_at": { "type": "integer" }, "currency_id": { "type": "integer" }, "currency_symbol": { "type": "string" }, "currency_iso_code": { "type": "string" }, "total_gross_amount": { "type": "string" }, "total_net_amount": { "type": "string" }, "base_gross_amount": { "type": "number" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "effective_tax_amount": { "type": "number" }, "shipping_amount_overridden": { "type": "boolean" }, "shipping_amount_override": { "type": "null" }, "effective_shipping_amount": { "type": "string" }, "submitted_on": { "type": "integer" }, "po_date": { "type": "null" }, "share_key": { "type": "string" }, "department_id": { "type": "integer" }, "department_name": { "type": "string" }, "budget_name": { "type": "string" }, "compliance_status": { "type": "null" }, "delivered_on": { "type": "null" }, "delivery_status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_progress": { "type": "string" }, "xero_export_status": { "type": "null" }, "synced_with_xero": { "type": "boolean" }, "xero_is_changed": { "type": "boolean" }, "approver_requests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "approver_name": { "type": "string" }, "approver_id": { "type": "integer" }, "delegate_id": { "type": "null" } } } } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "next_page": { "type": "integer" }, "prev_page": { "type": "null" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "example": { "purchase_orders": [ { "id": 10, "approval_key": "10-10/21/2026", "creator_name": "Jane Doe", "amount": "1200.0", "status": "approved", "supplier_name": "Contoso Hardware", "supplier_id": 2, "keywords": "10 Contoso Hardware Jane Doe 10-10/21/2026 approved 1306.50 Engineering Hardware FY26 USB-C dock 653.25 600.0 Engineering Hardware FY26 27in monitor 653.25 600.0 Not Set Not Set ", "created_at": 1792576822000, "currency_id": 2000, "currency_symbol": "$", "currency_iso_code": "USD", "total_gross_amount": "1306.5", "total_net_amount": "1200.0", "base_gross_amount": 1306.5, "tax_amount_overridden": false, "tax_amount_override": null, "effective_tax_amount": 106.5, "shipping_amount_overridden": false, "shipping_amount_override": null, "effective_shipping_amount": "0.0", "submitted_on": 1792576822000, "po_date": null, "share_key": "5731DC97332BF7369958FE78F1A077187CA1AD89", "department_id": 2, "department_name": "Engineering", "budget_name": "Engineering Hardware FY26", "compliance_status": null, "delivered_on": null, "delivery_status": "not_delivered", "payment_status": "unpaid", "payment_progress": "unpaid", "xero_export_status": null, "synced_with_xero": false, "xero_is_changed": false, "approver_requests": [ { "id": 11, "status": "approved", "approver_name": "Priya Patel", "approver_id": 50000, "delegate_id": null } ] }, { "id": 34, "approval_key": "34-10/21/2026", "creator_name": "Jane Doe", "amount": "189.5", "status": "approved", "supplier_name": "Contoso Hardware", "supplier_id": 2, "keywords": "34 Contoso Hardware Jane Doe 34-10/21/2026 approved 206.32 DOCK-USB-C Engineering Hardware FY26 USB-C docking station 206.318125 189.5 PRJ-2026-014 CC-100 Engineering ", "created_at": 1792577049000, "currency_id": 2000, "currency_symbol": "$", "currency_iso_code": "USD", "total_gross_amount": "206.32", "total_net_amount": "189.5", "base_gross_amount": 206.32, "tax_amount_overridden": false, "tax_amount_override": null, "effective_tax_amount": 16.82, "shipping_amount_overridden": false, "shipping_amount_override": null, "effective_shipping_amount": "0.0", "submitted_on": 1792577049000, "po_date": null, "share_key": "933B65C50ACBC55AD83BF85FD6CBB070CB01E89F", "department_id": 2, "department_name": "Engineering", "budget_name": "Engineering Hardware FY26", "compliance_status": null, "delivered_on": null, "delivery_status": "not_delivered", "payment_status": "unpaid", "payment_progress": "unpaid", "xero_export_status": null, "synced_with_xero": false, "xero_is_changed": false, "approver_requests": [ { "id": 34, "status": "approved", "approver_name": "Priya Patel", "approver_id": 50000, "delegate_id": null } ] } ], "meta": { "current_page": 1, "next_page": 2, "prev_page": null, "total_pages": 6, "total_count": 12 } } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/invoices/purchase_order_list": { "get": { "tags": [ "Invoices" ], "operationId": "v1_invoices_po_list", "summary": "List purchase orders to invoice", "description": "Approved purchase orders of a supplier that still have work to invoice.\n\nUse this endpoint to pick the POs an invoice bills. It returns POs of the company\nthat match all of these conditions:\n\n* They belong to the given `supplier_id`. **This parameter is effectively\n required**: without it, only POs with no supplier are returned, which is usually\n none.\n* They use the given `currency_id` (default: the company currency).\n* They are not archived.\n* Their status is `approved`, or `draft` / `pending` / `approved` with\n `include_unapproved=true`.\n* They are not fully invoiced yet. Only invoices that are `ready_to_pay` or\n `settled` count toward that.\n\nThe results are limited to POs the user can open. POs listed in `selected_ids` are\nalways included and listed first, even when they do not match the filters.\n\n\nNone - identical request and response.", "parameters": [ { "name": "supplier_id", "in": "query", "required": true, "description": "Supplier id.", "schema": { "type": "integer" } }, { "name": "currency_id", "in": "query", "required": false, "description": "PO currency.", "schema": { "type": "integer" } }, { "name": "selected_ids", "in": "query", "required": false, "description": "Comma-separated PO ids to always include (shown first), e.g. POs already on the invoice.", "schema": { "type": "string" } }, { "name": "include_unapproved", "in": "query", "required": false, "description": "`true` also returns `draft` and `pending` POs.", "schema": { "type": "boolean" } }, { "name": "q", "in": "query", "required": false, "description": "PO search text (alias `keyword`).", "schema": { "type": "string" } }, { "name": "requester_ids", "in": "query", "required": false, "description": "Comma-separated creator ids.", "schema": { "type": "string" } }, { "name": "budget_ids", "in": "query", "required": false, "description": "Comma-separated budget ids.", "schema": { "type": "string" } }, { "name": "filter_dept_ids", "in": "query", "required": false, "description": "Comma-separated department ids.", "schema": { "type": "string" } }, { "name": "approver_ids", "in": "query", "required": false, "description": "Comma-separated approver ids.", "schema": { "type": "string" } }, { "name": "supplier_email_status", "in": "query", "required": false, "description": "Comma-separated supplier email statuses.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Allow-listed PO sort column.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "`asc` or `desc`.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Page size (any value).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase_orders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_key": { "type": "string" }, "creator_name": { "type": "string" }, "amount": { "type": "string" }, "status": { "type": "string" }, "supplier_name": { "type": "string" }, "supplier_id": { "type": "integer" }, "keywords": { "type": "string" }, "created_at": { "type": "integer" }, "currency_id": { "type": "integer" }, "currency_symbol": { "type": "string" }, "currency_iso_code": { "type": "string" }, "total_gross_amount": { "type": "string" }, "total_net_amount": { "type": "string" }, "base_gross_amount": { "type": "number" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "effective_tax_amount": { "type": "number" }, "shipping_amount_overridden": { "type": "boolean" }, "shipping_amount_override": { "type": "null" }, "effective_shipping_amount": { "type": "string" }, "submitted_on": { "type": "integer" }, "po_date": { "type": "null" }, "share_key": { "type": "string" }, "department_id": { "type": "integer" }, "department_name": { "type": "string" }, "budget_name": { "type": "string" }, "compliance_status": { "type": "null" }, "delivered_on": { "type": "null" }, "delivery_status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_progress": { "type": "string" }, "xero_export_status": { "type": "null" }, "synced_with_xero": { "type": "boolean" }, "xero_is_changed": { "type": "boolean" }, "approver_requests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "approver_name": { "type": "string" }, "approver_id": { "type": "integer" }, "delegate_id": { "type": "null" } } } } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "next_page": { "type": "integer" }, "prev_page": { "type": "null" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "example": { "purchase_orders": [ { "id": 10, "approval_key": "10-10/21/2026", "creator_name": "Jane Doe", "amount": "1200.0", "status": "approved", "supplier_name": "Contoso Hardware", "supplier_id": 2, "keywords": "10 Contoso Hardware Jane Doe 10-10/21/2026 approved 1306.50 Engineering Hardware FY26 USB-C dock 653.25 600.0 Engineering Hardware FY26 27in monitor 653.25 600.0 Not Set Not Set ", "created_at": 1792576822000, "currency_id": 2000, "currency_symbol": "$", "currency_iso_code": "USD", "total_gross_amount": "1306.5", "total_net_amount": "1200.0", "base_gross_amount": 1306.5, "tax_amount_overridden": false, "tax_amount_override": null, "effective_tax_amount": 106.5, "shipping_amount_overridden": false, "shipping_amount_override": null, "effective_shipping_amount": "0.0", "submitted_on": 1792576822000, "po_date": null, "share_key": "5731DC97332BF7369958FE78F1A077187CA1AD89", "department_id": 2, "department_name": "Engineering", "budget_name": "Engineering Hardware FY26", "compliance_status": null, "delivered_on": null, "delivery_status": "not_delivered", "payment_status": "unpaid", "payment_progress": "unpaid", "xero_export_status": null, "synced_with_xero": false, "xero_is_changed": false, "approver_requests": [ { "id": 11, "status": "approved", "approver_name": "Priya Patel", "approver_id": 50000, "delegate_id": null } ] }, { "id": 34, "approval_key": "34-10/21/2026", "creator_name": "Jane Doe", "amount": "189.5", "status": "approved", "supplier_name": "Contoso Hardware", "supplier_id": 2, "keywords": "34 Contoso Hardware Jane Doe 34-10/21/2026 approved 206.32 DOCK-USB-C Engineering Hardware FY26 USB-C docking station 206.318125 189.5 PRJ-2026-014 CC-100 Engineering ", "created_at": 1792577049000, "currency_id": 2000, "currency_symbol": "$", "currency_iso_code": "USD", "total_gross_amount": "206.32", "total_net_amount": "189.5", "base_gross_amount": 206.32, "tax_amount_overridden": false, "tax_amount_override": null, "effective_tax_amount": 16.82, "shipping_amount_overridden": false, "shipping_amount_override": null, "effective_shipping_amount": "0.0", "submitted_on": 1792577049000, "po_date": null, "share_key": "933B65C50ACBC55AD83BF85FD6CBB070CB01E89F", "department_id": 2, "department_name": "Engineering", "budget_name": "Engineering Hardware FY26", "compliance_status": null, "delivered_on": null, "delivery_status": "not_delivered", "payment_status": "unpaid", "payment_progress": "unpaid", "xero_export_status": null, "synced_with_xero": false, "xero_is_changed": false, "approver_requests": [ { "id": 34, "status": "approved", "approver_name": "Priya Patel", "approver_id": 50000, "delegate_id": null } ] } ], "meta": { "current_page": 1, "next_page": 2, "prev_page": null, "total_pages": 6, "total_count": 12 } } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/invoices/purchase_order_item_list": { "get": { "tags": [ "Invoices" ], "operationId": "v3_invoices_po_item_list", "summary": "List purchase order lines to invoice", "description": "The open lines of one or more purchase orders, with the quantity and amount still to invoice.\n\nReturns one flat array with the lines of every requested PO, in PO-line order.\nEach line shows what is **still to be invoiced**: invoice lines of `ready_to_pay`\nand `settled` invoices are subtracted. When the remaining quantity is 0 or less,\nthe line comes back with `quantity: 1` and the remaining net amount as\n`unit_price`. Fully invoiced lines are left out.\n\nYou can copy the values straight into `invoice_line_items_attributes`. Pass the\nline `id` as `purchase_order_item_id` and the PO's id as `purchase_order_id`.\n\nPass the ids as an array (`purchase_order_ids[]=1&purchase_order_ids[]=5`). A\ncomma-separated value is not split. POs the user cannot open are skipped.\n\n\nNone - identical request and response.", "parameters": [ { "name": "purchase_order_ids[]", "in": "query", "required": true, "description": "PO ids.", "schema": { "type": "array", "items": { "type": "integer" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "sequence_no": { "type": "integer" }, "description": { "type": "string" }, "unit_price": { "type": "number" }, "quantity": { "type": "number" }, "vat": { "type": "string" }, "net_amount": { "type": "string" }, "gross_amount": { "type": "string" }, "budget_summary": { "type": "string" }, "budget_name": { "type": "string" }, "budget_cost_code": { "type": "string" }, "budget_cost_type": { "type": "string" }, "iso_code": { "type": "string" }, "tax_rate_id": { "type": "integer" }, "chart_of_account_id": { "type": "null" }, "qbo_customer_id": { "type": "null" }, "quickbooks_class_id": { "type": "null" }, "qbo_line_description": { "type": "null" }, "purchase_order_id": { "type": "integer" }, "approval_key": { "type": "string" }, "custom_field_values_json": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "value": { "type": "null" }, "custom_field_id": { "type": "integer" } } } } } } }, "example": [ { "id": 1, "sequence_no": 1, "description": "USB-C dock", "unit_price": 150.0, "quantity": 4.0, "vat": "8.875", "net_amount": "600.0", "gross_amount": "653.25", "budget_summary": "Engineering Hardware FY26 : ENG-HW : Capex", "budget_name": "Engineering Hardware FY26", "budget_cost_code": "ENG-HW", "budget_cost_type": "Capex", "iso_code": "$", "tax_rate_id": 4, "chart_of_account_id": null, "qbo_customer_id": null, "quickbooks_class_id": null, "qbo_line_description": null, "purchase_order_id": 1, "approval_key": "1-10/21/2026", "custom_field_values_json": [ { "id": 1, "value": null, "custom_field_id": 3 } ] }, { "id": 2, "sequence_no": 2, "description": "27in monitor", "unit_price": 300.0, "quantity": 2.0, "vat": "8.875", "net_amount": "600.0", "gross_amount": "653.25", "budget_summary": "Engineering Hardware FY26 : ENG-HW : Capex", "budget_name": "Engineering Hardware FY26", "budget_cost_code": "ENG-HW", "budget_cost_type": "Capex", "iso_code": "$", "tax_rate_id": 4, "chart_of_account_id": null, "qbo_customer_id": null, "quickbooks_class_id": null, "qbo_line_description": null, "purchase_order_id": 1, "approval_key": "1-10/21/2026", "custom_field_values_json": [ { "id": 2, "value": null, "custom_field_id": 3 } ] } ] } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/invoices/purchase_order_item_list": { "get": { "tags": [ "Invoices" ], "operationId": "v1_invoices_po_item_list", "summary": "List purchase order lines to invoice", "description": "The open lines of one or more purchase orders, with the quantity and amount still to invoice.\n\nReturns one flat array with the lines of every requested PO, in PO-line order.\nEach line shows what is **still to be invoiced**: invoice lines of `ready_to_pay`\nand `settled` invoices are subtracted. When the remaining quantity is 0 or less,\nthe line comes back with `quantity: 1` and the remaining net amount as\n`unit_price`. Fully invoiced lines are left out.\n\nYou can copy the values straight into `invoice_line_items_attributes`. Pass the\nline `id` as `purchase_order_item_id` and the PO's id as `purchase_order_id`.\n\nPass the ids as an array (`purchase_order_ids[]=1&purchase_order_ids[]=5`). A\ncomma-separated value is not split. POs the user cannot open are skipped.\n\n\nNone - identical request and response.", "parameters": [ { "name": "purchase_order_ids[]", "in": "query", "required": true, "description": "PO ids.", "schema": { "type": "array", "items": { "type": "integer" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "sequence_no": { "type": "integer" }, "description": { "type": "string" }, "unit_price": { "type": "number" }, "quantity": { "type": "number" }, "vat": { "type": "string" }, "net_amount": { "type": "string" }, "gross_amount": { "type": "string" }, "budget_summary": { "type": "string" }, "budget_name": { "type": "string" }, "budget_cost_code": { "type": "string" }, "budget_cost_type": { "type": "string" }, "iso_code": { "type": "string" }, "tax_rate_id": { "type": "integer" }, "chart_of_account_id": { "type": "null" }, "qbo_customer_id": { "type": "null" }, "quickbooks_class_id": { "type": "null" }, "qbo_line_description": { "type": "null" }, "purchase_order_id": { "type": "integer" }, "approval_key": { "type": "string" }, "custom_field_values_json": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "value": { "type": "null" }, "custom_field_id": { "type": "integer" } } } } } } }, "example": [ { "id": 1, "sequence_no": 1, "description": "USB-C dock", "unit_price": 150.0, "quantity": 4.0, "vat": "8.875", "net_amount": "600.0", "gross_amount": "653.25", "budget_summary": "Engineering Hardware FY26 : ENG-HW : Capex", "budget_name": "Engineering Hardware FY26", "budget_cost_code": "ENG-HW", "budget_cost_type": "Capex", "iso_code": "$", "tax_rate_id": 4, "chart_of_account_id": null, "qbo_customer_id": null, "quickbooks_class_id": null, "qbo_line_description": null, "purchase_order_id": 1, "approval_key": "1-10/21/2026", "custom_field_values_json": [ { "id": 1, "value": null, "custom_field_id": 3 } ] }, { "id": 2, "sequence_no": 2, "description": "27in monitor", "unit_price": 300.0, "quantity": 2.0, "vat": "8.875", "net_amount": "600.0", "gross_amount": "653.25", "budget_summary": "Engineering Hardware FY26 : ENG-HW : Capex", "budget_name": "Engineering Hardware FY26", "budget_cost_code": "ENG-HW", "budget_cost_type": "Capex", "iso_code": "$", "tax_rate_id": 4, "chart_of_account_id": null, "qbo_customer_id": null, "quickbooks_class_id": null, "qbo_line_description": null, "purchase_order_id": 1, "approval_key": "1-10/21/2026", "custom_field_values_json": [ { "id": 2, "value": null, "custom_field_id": 3 } ] } ] } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/invoices/{id}/create_comment": { "post": { "tags": [ "Invoices" ], "operationId": "v3_invoices_create_comment", "summary": "Comment on an invoice", "description": "Add a user comment to an invoice.\n\nAdds a comment to the invoice and writes it to the invoice's history. Links in the\ntext are turned into anchors in `formatted_comment`.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "comment": { "type": "string" }, "invoice_id": { "type": "integer" }, "creator_id": { "type": "integer" }, "creator_name": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "comment_formatted_time": { "type": "string" }, "comment_formatted_date": { "type": "string" }, "formatted_comment": { "type": "string" } } }, "example": { "id": 9, "comment": "Quantity corrected to 3 docks per the delivery note. See https://example.com/dn/4471", "invoice_id": 2, "creator_id": 40000, "creator_name": "Jane Doe", "created_at": 1792577124, "updated_at": 1792577124, "comment_formatted_time": "05:05", "comment_formatted_date": "2026-10-21", "formatted_comment": "

Quantity corrected to 3 docks per the delivery note. See https://example.com/dn/4471

" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "Required parameter are missing.", "status": 400 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice_comments[comment]": { "type": "string", "description": "Comment text. It must be nested under `invoice_comments`: a missing wrapper returns 400 `Required parameter are missing.` A blank comment currently returns a 500." } }, "required": [ "invoice_comments[comment]" ] }, "example": { "invoice_comments": { "comment": "Quantity corrected to 3 docks per the delivery note. See https://example.com/dn/4471" } } } } } } }, "/api/v1/invoices/{id}/create_comment": { "post": { "tags": [ "Invoices" ], "operationId": "v1_invoices_create_comment", "summary": "Comment on an invoice", "description": "Add a user comment to an invoice.\n\nAdds a comment to the invoice and writes it to the invoice's history. Links in the\ntext are turned into anchors in `formatted_comment`.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "comment": { "type": "string" }, "invoice_id": { "type": "integer" }, "creator_id": { "type": "integer" }, "creator_name": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "comment_formatted_time": { "type": "string" }, "comment_formatted_date": { "type": "string" }, "formatted_comment": { "type": "string" } } }, "example": { "id": 7, "comment": "Quantity corrected to 3 docks per the delivery note. See https://example.com/dn/4471", "invoice_id": 1, "creator_id": 40000, "creator_name": "Jane Doe", "created_at": 1792577124, "updated_at": 1792577124, "comment_formatted_time": "05:05", "comment_formatted_date": "2026-10-21", "formatted_comment": "

Quantity corrected to 3 docks per the delivery note. See https://example.com/dn/4471

" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "Required parameter are missing.", "status": 400 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice_comments[comment]": { "type": "string", "description": "Comment text. It must be nested under `invoice_comments`: a missing wrapper returns 400 `Required parameter are missing.` A blank comment currently returns a 500." } }, "required": [ "invoice_comments[comment]" ] }, "example": { "invoice_comments": { "comment": "Quantity corrected to 3 docks per the delivery note. See https://example.com/dn/4471" } } } } } } }, "/api/v3/invoices/{id}/accept": { "put": { "tags": [ "Invoices" ], "operationId": "v3_invoices_accept", "summary": "Accept an invoice awaiting review", "description": "Move an `awaiting_review` invoice to `outstanding` so it can be approved.\n\nMarks a reviewed invoice as correct: `awaiting_review` becomes `outstanding`. The\naccepting user becomes the owner of invoices captured by the system. The suppliers\nof the linked POs are notified that the invoice was received.\n\n**PO overrun guard.** When `invoice_po_overrun_enabled` is on and the invoice\nexceeds a linked PO's total:\n\n* If the overrun is within `invoice_po_overrun_pct` percent, send a justification\n in `invoice[po_overrun_reason]`. Without it the request returns `422` `A reason\n is required when accepting an invoice that exceeds the PO amount.`\n* If the overrun is above that limit, the request returns `422` `This invoice\n exceeds the PO overrun allowance. Edit the linked PO to increase its value before\n accepting.`\n\nAn invoice flagged as a duplicate returns `422` `This invoice has a duplicate\nreference number. Please cancel or resolve the duplicate before approving.`\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "example": { "error": "A reason is required when accepting an invoice that exceeds the PO amount.", "status": 422 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice[po_overrun_reason]": { "type": "string", "description": "Justification, required when the PO overrun guard asks for a reason. Saved on the invoice the first time." } } } } } } } }, "/api/v1/invoices/{id}/accept": { "put": { "tags": [ "Invoices" ], "operationId": "v1_invoices_accept", "summary": "Accept an invoice awaiting review", "description": "Move an `awaiting_review` invoice to `outstanding` so it can be approved.\n\nMarks a reviewed invoice as correct: `awaiting_review` becomes `outstanding`. The\naccepting user becomes the owner of invoices captured by the system. The suppliers\nof the linked POs are notified that the invoice was received.\n\n**PO overrun guard.** When `invoice_po_overrun_enabled` is on and the invoice\nexceeds a linked PO's total:\n\n* If the overrun is within `invoice_po_overrun_pct` percent, send a justification\n in `invoice[po_overrun_reason]`. Without it the request returns `422` `A reason\n is required when accepting an invoice that exceeds the PO amount.`\n* If the overrun is above that limit, the request returns `422` `This invoice\n exceeds the PO overrun allowance. Edit the linked PO to increase its value before\n accepting.`\n\nAn invoice flagged as a duplicate returns `422` `This invoice has a duplicate\nreference number. Please cancel or resolve the duplicate before approving.`\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "example": { "error": "A reason is required when accepting an invoice that exceeds the PO amount.", "status": 422 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice[po_overrun_reason]": { "type": "string", "description": "Justification, required when the PO overrun guard asks for a reason. Saved on the invoice the first time." } } } } } } } }, "/api/v3/invoices/{id}/approve": { "put": { "tags": [ "Invoices" ], "operationId": "v3_invoices_approve", "summary": "Approve an invoice", "description": "Approve an `outstanding` invoice (status becomes `ready_to_pay`).\n\nApproves the invoice. Its status becomes `ready_to_pay`, and `validation_date` is\nset to today. Once approved the invoice can be paid, and integrations that export\non approval pick it up.\n\nAn invoice that already has payments covering it in full settles immediately.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/invoices/{id}/approve": { "put": { "tags": [ "Invoices" ], "operationId": "v1_invoices_approve", "summary": "Approve an invoice", "description": "Approve an `outstanding` invoice (status becomes `ready_to_pay`).\n\nApproves the invoice. Its status becomes `ready_to_pay`, and `validation_date` is\nset to today. Once approved the invoice can be paid, and integrations that export\non approval pick it up.\n\nAn invoice that already has payments covering it in full settles immediately.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/invoices/{id}/reject": { "put": { "tags": [ "Invoices" ], "operationId": "v3_invoices_reject", "summary": "Reject an invoice", "description": "Reject an `awaiting_review` or `outstanding` invoice (status becomes `cancelled`).\n\nRejects the invoice, which sets its status to **`cancelled`**. There is no\nseparate rejected status, and the API takes no rejection reason. The request also\ndoes the following:\n\n* POs whose invoices are now all cancelled go back to `payment_status: unpaid`.\n* Assigned approval flows are closed.\n* The supplier is emailed when `send_invoice_rejected_email_to_supplier` is on.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/invoices/{id}/reject": { "put": { "tags": [ "Invoices" ], "operationId": "v1_invoices_reject", "summary": "Reject an invoice", "description": "Reject an `awaiting_review` or `outstanding` invoice (status becomes `cancelled`).\n\nRejects the invoice, which sets its status to **`cancelled`**. There is no\nseparate rejected status, and the API takes no rejection reason. The request also\ndoes the following:\n\n* POs whose invoices are now all cancelled go back to `payment_status: unpaid`.\n* Assigned approval flows are closed.\n* The supplier is emailed when `send_invoice_rejected_email_to_supplier` is on.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/invoices/{id}/cancel": { "put": { "tags": [ "Invoices" ], "operationId": "v3_invoices_cancel", "summary": "Cancel an invoice", "description": "Cancel an invoice in any status except `cancelled`.\n\nSets the status to `cancelled`. This works from `awaiting_review`, `outstanding`,\n`ready_to_pay` and `settled`, and also on archived invoices.\n\nCancelling also has these effects:\n\n* Payments (npayments) recorded against the invoice are deleted.\n* Amounts already booked as paid on the linked POs are reversed.\n* POs whose invoices are now all cancelled return to `payment_status: unpaid`.\n* A cancelled invoice no longer counts for duplicate detection.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/invoices/{id}/cancel": { "put": { "tags": [ "Invoices" ], "operationId": "v1_invoices_cancel", "summary": "Cancel an invoice", "description": "Cancel an invoice in any status except `cancelled`.\n\nSets the status to `cancelled`. This works from `awaiting_review`, `outstanding`,\n`ready_to_pay` and `settled`, and also on archived invoices.\n\nCancelling also has these effects:\n\n* Payments (npayments) recorded against the invoice are deleted.\n* Amounts already booked as paid on the linked POs are reversed.\n* POs whose invoices are now all cancelled return to `payment_status: unpaid`.\n* A cancelled invoice no longer counts for duplicate detection.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/invoices/{id}/archive": { "put": { "tags": [ "Invoices" ], "operationId": "v3_invoices_archive", "summary": "Archive an invoice", "description": "Hide an invoice from the default lists.\n\nSets `archived: true`. The status does not change.\n\nAn archived invoice:\n\n* Is left out of [GET /invoices](#list-invoices) unless you pass `archived=true`.\n* Cannot be edited, accepted, approved or paid. It can still be cancelled.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/invoices/{id}/archive": { "put": { "tags": [ "Invoices" ], "operationId": "v1_invoices_archive", "summary": "Archive an invoice", "description": "Hide an invoice from the default lists.\n\nSets `archived: true`. The status does not change.\n\nAn archived invoice:\n\n* Is left out of [GET /invoices](#list-invoices) unless you pass `archived=true`.\n* Cannot be edited, accepted, approved or paid. It can still be cancelled.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/invoices/{id}/dearchive": { "put": { "tags": [ "Invoices" ], "operationId": "v3_invoices_dearchive", "summary": "Unarchive an invoice", "description": "Restore an archived invoice.\n\nSets `archived: false`, so the invoice shows up in the default lists again and its\nnormal actions become available.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/invoices/{id}/dearchive": { "put": { "tags": [ "Invoices" ], "operationId": "v1_invoices_dearchive", "summary": "Unarchive an invoice", "description": "Restore an archived invoice.\n\nSets `archived: false`, so the invoice shows up in the default lists again and its\nnormal actions become available.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v1/invoices/{id}/rerun_approval_flow": { "post": { "tags": [ "Invoices" ], "operationId": "v1_invoices_rerun_approval_flow", "summary": "Rerun the approval flow of an invoice", "description": "Re-apply an edited invoice approval flow to an in-progress invoice (V1 only).\n\nWhen an invoice approval flow is edited while invoices are going through it, those\ninvoices are marked as having a changed flow. This endpoint restarts the approval\nof such an invoice:\n\n* The current approval entities are reset.\n* The published flows are matched again.\n* The approvers are attached again.\n* The invoice status is updated, and a system comment is added.\n\nPrevious approvals stay in the history.\n\nThe invoice is eligible only when all of these hold:\n\n* It is not cancelled, archived or settled.\n* The company has invoice approval flows enabled.\n* Its approval entity is in progress, and the flow has changed since it was\n assigned.\n\n\n**V1 only.** The V3 route `POST /api/v3/invoices/:id/rerun_approval_flow` exists,\nbut the V3 controller has no such action, so it answers `404`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "invoice": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "invoice_number": { "type": "string" } } } } }, "example": { "status": "success", "message": "Approval flow has been rerun successfully", "invoice": { "id": 23, "status": "outstanding", "invoice_number": "FAB-5521" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "error": [ "Not authorized to rerun approval flow" ], "status": 403 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/digital_invoices": { "post": { "tags": [ "Invoices" ], "operationId": "v3_digital_invoices_create", "summary": "Scan an invoice document", "description": "Upload an invoice (or purchase request) document for AI extraction.\n\nUploads a document for AI extraction (the *Invoice Scan and Match* feature). Send\n`multipart/form-data` with `file`. Extraction runs **synchronously** within the\nrequest: it typically takes a few seconds, and the result is in the response.\n\n**Scan & Match v2** (the current default for companies with the feature) works as\nfollows:\n\n* The file is stored and an **AP inbox document** is created.\n* The AI extraction runs (Google Gemini, with OpenAI as fallback).\n* The extracted data is written to the inbox document. Nothing is created\n automatically.\n* The response is `201` with the inbox document's id and outcome. `status` is one\n of:\n * `needs_review`: extracted, waiting for a reviewer to convert it into an invoice\n (or purchase order).\n * `ai_auto_created`: created automatically, when the company enables\n auto-creation.\n * `invalid`: not a usable invoice, or extraction failed. `invalid_reason`\n explains why.\n* Review and convert the document in the AP inbox.\n\n**Legacy path** (companies without Scan & Match v2): the extraction result is\nturned into a record straight away. The response is `200` with an invoice\n([detail format](#get-an-invoice), `digital_invoice: true`, usually\n`awaiting_review`), or with a draft purchase request (PO detail format) when\n`upload_type=request`. When extraction fails, the response is `400` with the\nextraction error.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "inbox_document_id": { "type": "integer" }, "status": { "type": "string" }, "detected_as": { "type": "null" }, "confidence_score": { "type": "number" }, "invalid_reason": { "type": "string" } } }, "example": { "inbox_document_id": 2, "status": "invalid", "detected_as": null, "confidence_score": 0.0, "invalid_reason": "The AI invoice extraction service is temporarily unavailable. Both Google Gemini and OpenAI services could not process your request. Please try again later." } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "File is required", "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The document. For `upload_type=invoice` it must be a **PDF**: any other type returns 400 `File content type The invoice you selected has to be a .pdf file ...`. With `upload_type=request`, images and office documents are accepted too. If it is missing, the response is 400 `File is required`." }, "upload_type": { "type": "string", "description": "`invoice`, or `request` to scan a quote or receipt into a purchase request (case-insensitive)." } }, "required": [ "file" ] } } } } } }, "/api/v1/digital_invoices": { "post": { "tags": [ "Invoices" ], "operationId": "v1_digital_invoices_create", "summary": "Scan an invoice document", "description": "Upload an invoice (or purchase request) document for AI extraction.\n\nUploads a document for AI extraction (the *Invoice Scan and Match* feature). Send\n`multipart/form-data` with `file`. Extraction runs **synchronously** within the\nrequest: it typically takes a few seconds, and the result is in the response.\n\n**Scan & Match v2** (the current default for companies with the feature) works as\nfollows:\n\n* The file is stored and an **AP inbox document** is created.\n* The AI extraction runs (Google Gemini, with OpenAI as fallback).\n* The extracted data is written to the inbox document. Nothing is created\n automatically.\n* The response is `201` with the inbox document's id and outcome. `status` is one\n of:\n * `needs_review`: extracted, waiting for a reviewer to convert it into an invoice\n (or purchase order).\n * `ai_auto_created`: created automatically, when the company enables\n auto-creation.\n * `invalid`: not a usable invoice, or extraction failed. `invalid_reason`\n explains why.\n* Review and convert the document in the AP inbox.\n\n**Legacy path** (companies without Scan & Match v2): the extraction result is\nturned into a record straight away. The response is `200` with an invoice\n([detail format](#get-an-invoice), `digital_invoice: true`, usually\n`awaiting_review`), or with a draft purchase request (PO detail format) when\n`upload_type=request`. When extraction fails, the response is `400` with the\nextraction error.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "inbox_document_id": { "type": "integer" }, "status": { "type": "string" }, "detected_as": { "type": "null" }, "confidence_score": { "type": "number" }, "invalid_reason": { "type": "string" } } }, "example": { "inbox_document_id": 1, "status": "invalid", "detected_as": null, "confidence_score": 0.0, "invalid_reason": "The AI invoice extraction service is temporarily unavailable. Both Google Gemini and OpenAI services could not process your request. Please try again later." } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "File is required", "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The document. For `upload_type=invoice` it must be a **PDF**: any other type returns 400 `File content type The invoice you selected has to be a .pdf file ...`. With `upload_type=request`, images and office documents are accepted too. If it is missing, the response is 400 `File is required`." }, "upload_type": { "type": "string", "description": "`invoice`, or `request` to scan a quote or receipt into a purchase request (case-insensitive)." } }, "required": [ "file" ] } } } } } }, "/api/v3/npayments/{id}": { "get": { "tags": [ "Payments" ], "operationId": "v3_npayments_show", "summary": "Get a payment", "description": "One payment with its currency, supplier, user, allocated invoices and comments.\n\nReturns a payment of the company in `app_company_id`. The `invoices` list shows the\ninvoices the payment is allocated to, with their current status and balance.\nAdvance payments (PO payments) have an empty `invoices` list. The purchase orders\nan advance payment is booked against are not included in the response.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "reference": { "type": "string" }, "status": { "type": "string" }, "ptype": { "type": "string" }, "date": { "type": "integer" }, "amount": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "payment_mode": { "type": "string" }, "archived": { "type": "boolean" }, "conversion_rate": { "type": "string" }, "currency": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "iso_code": { "type": "string" }, "symbol": { "type": "string" } } }, "supplier": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" } } }, "invoices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "invoice_number": { "type": "string" }, "status": { "type": "string" }, "issue_date": { "type": "integer" }, "validation_date": { "type": "integer" }, "uploaded_date": { "type": "integer" }, "due_date": { "type": "integer" }, "tax_amount": { "type": "string" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "shipping_amount": { "type": "string" }, "shipping_amount_overridden": { "type": "boolean" }, "net_amount": { "type": "string" }, "gross_amount": { "type": "string" }, "balance_amount": { "type": "string" }, "supplier_id": { "type": "integer" }, "supplier_name": { "type": "string" }, "purchase_order_references": { "type": "array", "items": { "type": "string" } }, "can_accept": { "type": "boolean" }, "can_approve": { "type": "boolean" }, "can_reject": { "type": "boolean" }, "can_cancel": { "type": "boolean" }, "can_archive": { "type": "boolean" }, "can_dearchive": { "type": "boolean" }, "standalone_invoice": { "type": "boolean" }, "confidence_score": { "type": "string" }, "digital_invoice": { "type": "boolean" }, "payment_term_id": { "type": "null" }, "payment_terms_list": { "type": "null" }, "xero_export_status": { "type": "null" }, "xero_is_changed": { "type": "boolean" }, "duplicate_invoice_flag": { "type": "boolean" }, "payment_progress": { "type": "string" }, "submitted_with_unproven_supplier_email": { "type": "boolean" } } } }, "npayment_comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "comment": { "type": "string" }, "creator_id": { "type": "integer" }, "system_generated": { "type": "boolean" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } } } }, "example": { "id": 2, "reference": "ACH-20261021-01", "status": "active", "ptype": "bank_transfer", "date": 1792558800, "amount": "165.0", "created_at": 1792558800, "updated_at": 1792558800, "payment_mode": "normal", "archived": false, "conversion_rate": "1.0", "currency": { "id": 2000, "name": "United States Dollar", "iso_code": "USD", "symbol": "$" }, "supplier": { "id": 2, "name": "Contoso Hardware" }, "user": { "id": 40000, "email": "jane.doe@example.com", "name": "Jane Doe" }, "invoices": [ { "id": 16, "invoice_number": "CH-PAY-V1", "status": "settled", "issue_date": 1792472400, "validation_date": 1792558800, "uploaded_date": 1792577159, "due_date": 1795068000, "tax_amount": "15.0", "tax_amount_overridden": false, "tax_amount_override": null, "shipping_amount": "0.0", "shipping_amount_overridden": false, "net_amount": "150.0", "gross_amount": "165.0", "balance_amount": "0.0", "supplier_id": 2, "supplier_name": "Contoso Hardware", "purchase_order_references": [ "9-10/21/2026" ], "can_accept": false, "can_approve": false, "can_reject": false, "can_cancel": true, "can_archive": true, "can_dearchive": false, "standalone_invoice": false, "confidence_score": "0.0", "digital_invoice": false, "payment_term_id": null, "payment_terms_list": null, "xero_export_status": null, "xero_is_changed": false, "duplicate_invoice_flag": false, "payment_progress": "paid", "submitted_with_unproven_supplier_email": false } ], "npayment_comments": [ { "id": 2, "comment": "Paid by ACH from operating account", "creator_id": 40000, "system_generated": false, "created_at": 1792577521, "updated_at": 1792577521 } ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/npayments/{id}": { "get": { "tags": [ "Payments" ], "operationId": "v1_npayments_show", "summary": "Get a payment", "description": "One payment with its currency, supplier, user, allocated invoices and comments.\n\nReturns a payment of the company in `app_company_id`. The `invoices` list shows the\ninvoices the payment is allocated to, with their current status and balance.\nAdvance payments (PO payments) have an empty `invoices` list. The purchase orders\nan advance payment is booked against are not included in the response.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "reference": { "type": "string" }, "status": { "type": "string" }, "ptype": { "type": "string" }, "date": { "type": "integer" }, "amount": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "payment_mode": { "type": "string" }, "archived": { "type": "boolean" }, "conversion_rate": { "type": "string" }, "currency": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "iso_code": { "type": "string" }, "symbol": { "type": "string" } } }, "supplier": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" } } }, "invoices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "invoice_number": { "type": "string" }, "status": { "type": "string" }, "issue_date": { "type": "integer" }, "validation_date": { "type": "integer" }, "uploaded_date": { "type": "integer" }, "due_date": { "type": "integer" }, "tax_amount": { "type": "string" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "shipping_amount": { "type": "string" }, "shipping_amount_overridden": { "type": "boolean" }, "net_amount": { "type": "string" }, "gross_amount": { "type": "string" }, "balance_amount": { "type": "string" }, "supplier_id": { "type": "integer" }, "supplier_name": { "type": "string" }, "purchase_order_references": { "type": "array", "items": { "type": "string" } }, "can_accept": { "type": "boolean" }, "can_approve": { "type": "boolean" }, "can_reject": { "type": "boolean" }, "can_cancel": { "type": "boolean" }, "can_archive": { "type": "boolean" }, "can_dearchive": { "type": "boolean" }, "standalone_invoice": { "type": "boolean" }, "confidence_score": { "type": "string" }, "digital_invoice": { "type": "boolean" }, "payment_term_id": { "type": "null" }, "payment_terms_list": { "type": "null" }, "xero_export_status": { "type": "null" }, "xero_is_changed": { "type": "boolean" }, "duplicate_invoice_flag": { "type": "boolean" }, "payment_progress": { "type": "string" }, "submitted_with_unproven_supplier_email": { "type": "boolean" } } } }, "npayment_comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "comment": { "type": "string" }, "creator_id": { "type": "integer" }, "system_generated": { "type": "boolean" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } } } }, "example": { "id": 2, "reference": "ACH-20261021-01", "status": "active", "ptype": "bank_transfer", "date": 1792558800, "amount": "165.0", "created_at": 1792558800, "updated_at": 1792558800, "payment_mode": "normal", "archived": false, "conversion_rate": "1.0", "currency": { "id": 2000, "name": "United States Dollar", "iso_code": "USD", "symbol": "$" }, "supplier": { "id": 2, "name": "Contoso Hardware" }, "user": { "id": 40000, "email": "jane.doe@example.com", "name": "Jane Doe" }, "invoices": [ { "id": 16, "invoice_number": "CH-PAY-V1", "status": "settled", "issue_date": 1792472400, "validation_date": 1792558800, "uploaded_date": 1792577159, "due_date": 1795068000, "tax_amount": "15.0", "tax_amount_overridden": false, "tax_amount_override": null, "shipping_amount": "0.0", "shipping_amount_overridden": false, "net_amount": "150.0", "gross_amount": "165.0", "balance_amount": "0.0", "supplier_id": 2, "supplier_name": "Contoso Hardware", "purchase_order_references": [ "9-10/21/2026" ], "can_accept": false, "can_approve": false, "can_reject": false, "can_cancel": true, "can_archive": true, "can_dearchive": false, "standalone_invoice": false, "confidence_score": "0.0", "digital_invoice": false, "payment_term_id": null, "payment_terms_list": null, "xero_export_status": null, "xero_is_changed": false, "duplicate_invoice_flag": false, "payment_progress": "paid", "submitted_with_unproven_supplier_email": false } ], "npayment_comments": [ { "id": 2, "comment": "Paid by ACH from operating account", "creator_id": 40000, "system_generated": false, "created_at": 1792577521, "updated_at": 1792577521 } ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/npayments": { "post": { "tags": [ "Payments" ], "operationId": "v3_npayments_create", "summary": "Record a payment", "description": "Record a payment against invoices (normal) or purchase orders (advance).\n\nCreates a payment and books it.\n\n**Normal payment** (`payment_mode: normal`, the default) is allocated to invoices.\nList each invoice with the amount paid on it in `npayment_invoices_attributes`. A\npartial amount is allowed. `amount` must equal the sum of the allocations, within\n0.01. An allocation cannot exceed what is still owed on the invoice.\n\nFor each invoice, the request:\n\n* Adds an invoice history entry (\"... recorded a payment of USD 165.00 against this\n invoice\").\n* Recalculates `balance_amount` and `payment_progress`.\n* Writes the payment to the PO lines the invoice bills, which updates the POs'\n `payment_progress` and moves a fully paid PO to `paid`.\n\nA `ready_to_pay` invoice whose balance reaches 0 becomes `settled`. Pay approved\n(`ready_to_pay`) invoices: an `outstanding` invoice is accepted too, but it only\nshows `payment_progress: paid` and stays `outstanding`.\n\n**Advance payment** (`payment_mode: advance`) is allocated to purchase orders,\nbefore any invoice exists. List each PO with the amount in\n`npayment_link_orders_attributes`. `amount` must equal the sum exactly. The POs\nmust be payable: `approved`, `delivered` or `paid`, or `pending` when the company\nsetting `allow_po_paid_before_approved` is on.\n\n**Dates.** `date` is read in the company `date_format` (e.g. `10/21/2026`). ISO\n`YYYY-MM-DD` also works.\n\n**Fields set by the server.** The user is always the token's user. Comments are\nalways stamped with the token's user and `system_generated: false`. `status` cannot\nbe set here.\n\n\n* V1 takes `supplier_id` / `currency_id` from the client. V3 derives them from the\n linked invoices and POs, and returns 422 when they disagree\n (`All linked invoices and purchase orders must belong to the same supplier` /\n `... same currency`).\n* V3 checks the linked ids up front: `Invoice(s) not found: 999999` /\n `Purchase order(s) not found: ...` (422). V1 returns\n `Npayment invoices invoice invoice does not exist` (400).\n* Overpayment: V3 refuses an allocation above the invoice's remaining\n `balance_amount` with `Payment of 200.0 exceeds the remaining balance (165.0) of\n invoice 6` (422). V1 refuses an allocation that would take the invoice's\n allocated total above its gross with `allocation of 200.0 for invoice 6 would\n take its allocated total to 200.0, outside the invoice total of 165.0` (400).\n* Success: V1 200, V3 201. Validation errors: V1 400, V3 422.\n* V3 does not accept nested `id` keys.", "parameters": [ ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "reference": { "type": "string" }, "status": { "type": "string" }, "ptype": { "type": "string" }, "date": { "type": "integer" }, "amount": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "payment_mode": { "type": "string" }, "archived": { "type": "boolean" }, "conversion_rate": { "type": "string" }, "currency": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "iso_code": { "type": "string" }, "symbol": { "type": "string" } } }, "supplier": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" } } }, "invoices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "invoice_number": { "type": "string" }, "status": { "type": "string" }, "issue_date": { "type": "integer" }, "validation_date": { "type": "integer" }, "uploaded_date": { "type": "integer" }, "due_date": { "type": "integer" }, "tax_amount": { "type": "string" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "shipping_amount": { "type": "string" }, "shipping_amount_overridden": { "type": "boolean" }, "net_amount": { "type": "string" }, "gross_amount": { "type": "string" }, "balance_amount": { "type": "string" }, "supplier_id": { "type": "integer" }, "supplier_name": { "type": "string" }, "purchase_order_references": { "type": "array", "items": { "type": "string" } }, "can_accept": { "type": "boolean" }, "can_approve": { "type": "boolean" }, "can_reject": { "type": "boolean" }, "can_cancel": { "type": "boolean" }, "can_archive": { "type": "boolean" }, "can_dearchive": { "type": "boolean" }, "standalone_invoice": { "type": "boolean" }, "confidence_score": { "type": "string" }, "digital_invoice": { "type": "boolean" }, "payment_term_id": { "type": "null" }, "payment_terms_list": { "type": "null" }, "xero_export_status": { "type": "null" }, "xero_is_changed": { "type": "boolean" }, "duplicate_invoice_flag": { "type": "boolean" }, "payment_progress": { "type": "string" }, "submitted_with_unproven_supplier_email": { "type": "boolean" } } } }, "npayment_comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "comment": { "type": "string" }, "creator_id": { "type": "integer" }, "system_generated": { "type": "boolean" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } } } }, "example": { "id": 3, "reference": "ACH-20261021-02", "status": "active", "ptype": "bank_transfer", "date": 1792558800, "amount": "165.0", "created_at": 1792558800, "updated_at": 1792558800, "payment_mode": "normal", "archived": false, "conversion_rate": "1.0", "currency": { "id": 2000, "name": "United States Dollar", "iso_code": "USD", "symbol": "$" }, "supplier": { "id": 2, "name": "Contoso Hardware" }, "user": { "id": 40000, "email": "jane.doe@example.com", "name": "Jane Doe" }, "invoices": [ { "id": 17, "invoice_number": "CH-PAY-V3", "status": "settled", "issue_date": 1792472400, "validation_date": 1792558800, "uploaded_date": 1792577160, "due_date": 1795068000, "tax_amount": "15.0", "tax_amount_overridden": false, "tax_amount_override": null, "shipping_amount": "0.0", "shipping_amount_overridden": false, "net_amount": "150.0", "gross_amount": "165.0", "balance_amount": "0.0", "supplier_id": 2, "supplier_name": "Contoso Hardware", "purchase_order_references": [ "9-10/21/2026" ], "can_accept": false, "can_approve": false, "can_reject": false, "can_cancel": true, "can_archive": true, "can_dearchive": false, "standalone_invoice": false, "confidence_score": "0.0", "digital_invoice": false, "payment_term_id": null, "payment_terms_list": null, "xero_export_status": null, "xero_is_changed": false, "duplicate_invoice_flag": false, "payment_progress": "paid", "submitted_with_unproven_supplier_email": false } ], "npayment_comments": [ { "id": 3, "comment": "Paid by ACH from operating account", "creator_id": 40000, "system_generated": false, "created_at": 1792577534, "updated_at": 1792577534 } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "example": { "error": [ "Amount payment amount and invoice amounts are different" ], "status": 422 } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "Required parameter are missing.", "status": 400 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "npayment[amount]": { "type": "number", "description": "Total paid. Must equal the sum of the invoice allocations (normal, within 0.01) or of the PO amounts (advance)." }, "npayment[date]": { "type": "string", "format": "date", "description": "Payment date, in the company date format or `YYYY-MM-DD`." }, "npayment[reference]": { "type": "string", "description": "Your payment reference." }, "npayment[ptype]": { "type": "string", "description": "Payment type: `bank_transfer`, `card`, `credit_card`, `check`, `cash`, `one_time_card`, `letter_of_credit`, `other`, `batch_payment`." }, "npayment[payment_mode]": { "type": "string", "description": "`normal` (pay invoices) or `advance` (pay POs)." }, "npayment[supplier_id]": { "type": "integer", "description": "**V1 only, required there.** Supplier paid. V1 does not check that it matches the invoices' supplier. V3 derives it from the linked invoices or POs and ignores this parameter." }, "npayment[currency_id]": { "type": "integer", "description": "**V1 only.** Payment currency. Defaults to the company currency. V3 derives it." }, "npayment[npayment_invoices_attributes][][invoice_id]": { "type": "integer", "description": "Normal payments: an invoice of the company. At least one invoice is required for a normal payment." }, "npayment[npayment_invoices_attributes][][gross_amount]": { "type": "number", "description": "The amount of this payment allocated to that invoice (not the invoice total). Each invoice may appear once." }, "npayment[npayment_invoices_attributes][][_destroy]": { "type": "boolean", "description": "Accepted for compatibility; use `false` or leave it out." }, "npayment[npayment_invoices_attributes][][id]": { "type": "integer", "description": "V1 only; not meaningful on create." }, "npayment[npayment_link_orders_attributes][][purchase_order_id]": { "type": "integer", "description": "Advance payments: a payable PO of the company. At least one PO is required for an advance payment." }, "npayment[npayment_link_orders_attributes][][budget_id]": { "type": "integer", "description": "Budget the amount is booked against (one of the PO's budgets)." }, "npayment[npayment_link_orders_attributes][][gross_amount]": { "type": "number", "description": "Amount paid on that PO (and budget)." }, "npayment[npayment_link_orders_attributes][][_destroy]": { "type": "boolean", "description": "Accepted for compatibility; leave it out." }, "npayment[npayment_link_orders_attributes][][id]": { "type": "integer", "description": "V1 only; not meaningful on create." }, "npayment[npayment_comments_attributes][][comment]": { "type": "string", "description": "A note on the payment. Blank comments are dropped." } }, "required": [ "npayment[amount]", "npayment[date]", "npayment[supplier_id]" ] }, "example": { "npayment": { "reference": "ACH-20261021-02", "ptype": "bank_transfer", "payment_mode": "normal", "date": "2026-10-21", "amount": 165.0, "npayment_invoices_attributes": [ { "invoice_id": 17, "gross_amount": 165.0 } ], "npayment_comments_attributes": [ { "comment": "Paid by ACH from operating account" } ] } } } } } } }, "/api/v1/npayments": { "post": { "tags": [ "Payments" ], "operationId": "v1_npayments_create", "summary": "Record a payment", "description": "Record a payment against invoices (normal) or purchase orders (advance).\n\nCreates a payment and books it.\n\n**Normal payment** (`payment_mode: normal`, the default) is allocated to invoices.\nList each invoice with the amount paid on it in `npayment_invoices_attributes`. A\npartial amount is allowed. `amount` must equal the sum of the allocations, within\n0.01. An allocation cannot exceed what is still owed on the invoice.\n\nFor each invoice, the request:\n\n* Adds an invoice history entry (\"... recorded a payment of USD 165.00 against this\n invoice\").\n* Recalculates `balance_amount` and `payment_progress`.\n* Writes the payment to the PO lines the invoice bills, which updates the POs'\n `payment_progress` and moves a fully paid PO to `paid`.\n\nA `ready_to_pay` invoice whose balance reaches 0 becomes `settled`. Pay approved\n(`ready_to_pay`) invoices: an `outstanding` invoice is accepted too, but it only\nshows `payment_progress: paid` and stays `outstanding`.\n\n**Advance payment** (`payment_mode: advance`) is allocated to purchase orders,\nbefore any invoice exists. List each PO with the amount in\n`npayment_link_orders_attributes`. `amount` must equal the sum exactly. The POs\nmust be payable: `approved`, `delivered` or `paid`, or `pending` when the company\nsetting `allow_po_paid_before_approved` is on.\n\n**Dates.** `date` is read in the company `date_format` (e.g. `10/21/2026`). ISO\n`YYYY-MM-DD` also works.\n\n**Fields set by the server.** The user is always the token's user. Comments are\nalways stamped with the token's user and `system_generated: false`. `status` cannot\nbe set here.\n\n\n* V1 takes `supplier_id` / `currency_id` from the client. V3 derives them from the\n linked invoices and POs, and returns 422 when they disagree\n (`All linked invoices and purchase orders must belong to the same supplier` /\n `... same currency`).\n* V3 checks the linked ids up front: `Invoice(s) not found: 999999` /\n `Purchase order(s) not found: ...` (422). V1 returns\n `Npayment invoices invoice invoice does not exist` (400).\n* Overpayment: V3 refuses an allocation above the invoice's remaining\n `balance_amount` with `Payment of 200.0 exceeds the remaining balance (165.0) of\n invoice 6` (422). V1 refuses an allocation that would take the invoice's\n allocated total above its gross with `allocation of 200.0 for invoice 6 would\n take its allocated total to 200.0, outside the invoice total of 165.0` (400).\n* Success: V1 200, V3 201. Validation errors: V1 400, V3 422.\n* V3 does not accept nested `id` keys.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "reference": { "type": "string" }, "status": { "type": "string" }, "ptype": { "type": "string" }, "date": { "type": "integer" }, "amount": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "payment_mode": { "type": "string" }, "archived": { "type": "boolean" }, "conversion_rate": { "type": "string" }, "currency": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "iso_code": { "type": "string" }, "symbol": { "type": "string" } } }, "supplier": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" } } }, "invoices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "invoice_number": { "type": "string" }, "status": { "type": "string" }, "issue_date": { "type": "integer" }, "validation_date": { "type": "integer" }, "uploaded_date": { "type": "integer" }, "due_date": { "type": "integer" }, "tax_amount": { "type": "string" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "shipping_amount": { "type": "string" }, "shipping_amount_overridden": { "type": "boolean" }, "net_amount": { "type": "string" }, "gross_amount": { "type": "string" }, "balance_amount": { "type": "string" }, "supplier_id": { "type": "integer" }, "supplier_name": { "type": "string" }, "purchase_order_references": { "type": "array", "items": { "type": "string" } }, "can_accept": { "type": "boolean" }, "can_approve": { "type": "boolean" }, "can_reject": { "type": "boolean" }, "can_cancel": { "type": "boolean" }, "can_archive": { "type": "boolean" }, "can_dearchive": { "type": "boolean" }, "standalone_invoice": { "type": "boolean" }, "confidence_score": { "type": "string" }, "digital_invoice": { "type": "boolean" }, "payment_term_id": { "type": "null" }, "payment_terms_list": { "type": "null" }, "xero_export_status": { "type": "null" }, "xero_is_changed": { "type": "boolean" }, "duplicate_invoice_flag": { "type": "boolean" }, "payment_progress": { "type": "string" }, "submitted_with_unproven_supplier_email": { "type": "boolean" } } } }, "npayment_comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "comment": { "type": "string" }, "creator_id": { "type": "integer" }, "system_generated": { "type": "boolean" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } } } }, "example": { "id": 2, "reference": "ACH-20261021-01", "status": "active", "ptype": "bank_transfer", "date": 1792558800, "amount": "165.0", "created_at": 1792558800, "updated_at": 1792558800, "payment_mode": "normal", "archived": false, "conversion_rate": "1.0", "currency": { "id": 2000, "name": "United States Dollar", "iso_code": "USD", "symbol": "$" }, "supplier": { "id": 2, "name": "Contoso Hardware" }, "user": { "id": 40000, "email": "jane.doe@example.com", "name": "Jane Doe" }, "invoices": [ { "id": 16, "invoice_number": "CH-PAY-V1", "status": "settled", "issue_date": 1792472400, "validation_date": 1792558800, "uploaded_date": 1792577159, "due_date": 1795068000, "tax_amount": "15.0", "tax_amount_overridden": false, "tax_amount_override": null, "shipping_amount": "0.0", "shipping_amount_overridden": false, "net_amount": "150.0", "gross_amount": "165.0", "balance_amount": "0.0", "supplier_id": 2, "supplier_name": "Contoso Hardware", "purchase_order_references": [ "9-10/21/2026" ], "can_accept": false, "can_approve": false, "can_reject": false, "can_cancel": true, "can_archive": true, "can_dearchive": false, "standalone_invoice": false, "confidence_score": "0.0", "digital_invoice": false, "payment_term_id": null, "payment_terms_list": null, "xero_export_status": null, "xero_is_changed": false, "duplicate_invoice_flag": false, "payment_progress": "paid", "submitted_with_unproven_supplier_email": false } ], "npayment_comments": [ { "id": 2, "comment": "Paid by ACH from operating account", "creator_id": 40000, "system_generated": false, "created_at": 1792577521, "updated_at": 1792577521 } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Amount payment amount and invoice amounts are different" ], "status": 400 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "npayment[amount]": { "type": "number", "description": "Total paid. Must equal the sum of the invoice allocations (normal, within 0.01) or of the PO amounts (advance)." }, "npayment[date]": { "type": "string", "format": "date", "description": "Payment date, in the company date format or `YYYY-MM-DD`." }, "npayment[reference]": { "type": "string", "description": "Your payment reference." }, "npayment[ptype]": { "type": "string", "description": "Payment type: `bank_transfer`, `card`, `credit_card`, `check`, `cash`, `one_time_card`, `letter_of_credit`, `other`, `batch_payment`." }, "npayment[payment_mode]": { "type": "string", "description": "`normal` (pay invoices) or `advance` (pay POs)." }, "npayment[supplier_id]": { "type": "integer", "description": "**V1 only, required there.** Supplier paid. V1 does not check that it matches the invoices' supplier. V3 derives it from the linked invoices or POs and ignores this parameter." }, "npayment[currency_id]": { "type": "integer", "description": "**V1 only.** Payment currency. Defaults to the company currency. V3 derives it." }, "npayment[npayment_invoices_attributes][][invoice_id]": { "type": "integer", "description": "Normal payments: an invoice of the company. At least one invoice is required for a normal payment." }, "npayment[npayment_invoices_attributes][][gross_amount]": { "type": "number", "description": "The amount of this payment allocated to that invoice (not the invoice total). Each invoice may appear once." }, "npayment[npayment_invoices_attributes][][_destroy]": { "type": "boolean", "description": "Accepted for compatibility; use `false` or leave it out." }, "npayment[npayment_invoices_attributes][][id]": { "type": "integer", "description": "V1 only; not meaningful on create." }, "npayment[npayment_link_orders_attributes][][purchase_order_id]": { "type": "integer", "description": "Advance payments: a payable PO of the company. At least one PO is required for an advance payment." }, "npayment[npayment_link_orders_attributes][][budget_id]": { "type": "integer", "description": "Budget the amount is booked against (one of the PO's budgets)." }, "npayment[npayment_link_orders_attributes][][gross_amount]": { "type": "number", "description": "Amount paid on that PO (and budget)." }, "npayment[npayment_link_orders_attributes][][_destroy]": { "type": "boolean", "description": "Accepted for compatibility; leave it out." }, "npayment[npayment_link_orders_attributes][][id]": { "type": "integer", "description": "V1 only; not meaningful on create." }, "npayment[npayment_comments_attributes][][comment]": { "type": "string", "description": "A note on the payment. Blank comments are dropped." } }, "required": [ "npayment[amount]", "npayment[date]", "npayment[supplier_id]" ] }, "example": { "npayment": { "reference": "ACH-20261021-01", "ptype": "bank_transfer", "payment_mode": "normal", "date": "2026-10-21", "amount": 165.0, "supplier_id": 2, "currency_id": 2000, "npayment_invoices_attributes": [ { "invoice_id": 16, "gross_amount": 165.0 } ], "npayment_comments_attributes": [ { "comment": "Paid by ACH from operating account" } ] } } } } } } }, "/api/v3/purchase_orders/{purchase_order_id}/payments": { "post": { "tags": [ "Payments" ], "operationId": "v3_payments_create", "summary": "Mark a purchase order as paid", "description": "Record a payment on a purchase order, line by line (\"mark as paid\").\n\nRecords a payment on a purchase order. **The amounts per PO line\n(`purchase_order_item_payments_attributes`) are what count.** The paid total is\nthe sum of the line amounts, and `payment[amount]` alone records nothing (the PO\ncomment then reads \"USD 0.00\"). Paying every line in full moves the PO to status\n`paid` (`payment_progress: paid`). Otherwise `payment_progress` becomes\n`partially_paid`.\n\nThe request also:\n\n* Adds a PO comment: \"Jane Doe marked a payment of USD 1,306.50 on this purchase\n order with payment terms Net 45\", followed by the note. The PO creator is\n emailed if they opted in.\n* Creates the matching [payment (npayment)](#payments). It is allocated to the\n PO's approved invoices if there are any, otherwise it is an advance payment on\n the PO's budgets.\n* Settles approved invoices once the PO is fully paid.\n\nCheck `can_mark_as_paid` on the [purchase order](#purchase-orders) first. There is\nno over-payment check: a further payment on an already `paid` PO is accepted.\n`purchase_order_id` may be the PO id or its approval key.\n\n\n* Validation errors: V1 returns `422 {\"error\": {\"purchase_order_item_payments\": [\"is invalid\"]}, \"status\": 422}`.\n V3 currently fails with a **500** (bug), so the V3 error capture is omitted.\n* V3 does not stamp the user on the line payments. V1 does.\n* Success responses are identical.", "parameters": [ { "name": "purchase_order_id", "in": "path", "required": true, "description": "Purchase order id (or approval key).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "payment[purchase_order_item_payments_attributes][][purchase_order_item_id]": { "type": "integer", "description": "A line of this PO. A line of another PO is rejected (`purchase_order_item_payments is invalid`)." }, "payment[purchase_order_item_payments_attributes][][amount]": { "type": "number", "description": "Amount paid on that line (gross)." }, "payment[amount]": { "type": "number", "description": "Total of the payment. Stored on the payment header, but the paid totals are computed from the line amounts. Send the sum of the lines." }, "payment[note]": { "type": "string", "description": "Note appended to the PO comment and saved on the created npayment." }, "payment[purchase_order_item_payments_attributes][][id]": { "type": "integer", "description": "Not meaningful on create (there is no update endpoint)." } }, "required": [ "payment[purchase_order_item_payments_attributes][][purchase_order_item_id]", "payment[purchase_order_item_payments_attributes][][amount]" ] }, "example": { "payment": { "amount": 1306.5, "note": "Paid in full by wire, ref WIRE-88214", "purchase_order_item_payments_attributes": [ { "purchase_order_item_id": 12, "amount": 653.25 }, { "purchase_order_item_id": 13, "amount": 653.25 } ] } } } } } } }, "/api/v1/purchase_orders/{purchase_order_id}/payments": { "post": { "tags": [ "Payments" ], "operationId": "v1_payments_create", "summary": "Mark a purchase order as paid", "description": "Record a payment on a purchase order, line by line (\"mark as paid\").\n\nRecords a payment on a purchase order. **The amounts per PO line\n(`purchase_order_item_payments_attributes`) are what count.** The paid total is\nthe sum of the line amounts, and `payment[amount]` alone records nothing (the PO\ncomment then reads \"USD 0.00\"). Paying every line in full moves the PO to status\n`paid` (`payment_progress: paid`). Otherwise `payment_progress` becomes\n`partially_paid`.\n\nThe request also:\n\n* Adds a PO comment: \"Jane Doe marked a payment of USD 1,306.50 on this purchase\n order with payment terms Net 45\", followed by the note. The PO creator is\n emailed if they opted in.\n* Creates the matching [payment (npayment)](#payments). It is allocated to the\n PO's approved invoices if there are any, otherwise it is an advance payment on\n the PO's budgets.\n* Settles approved invoices once the PO is fully paid.\n\nCheck `can_mark_as_paid` on the [purchase order](#purchase-orders) first. There is\nno over-payment check: a further payment on an already `paid` PO is accepted.\n`purchase_order_id` may be the PO id or its approval key.\n\n\n* Validation errors: V1 returns `422 {\"error\": {\"purchase_order_item_payments\": [\"is invalid\"]}, \"status\": 422}`.\n V3 currently fails with a **500** (bug), so the V3 error capture is omitted.\n* V3 does not stamp the user on the line payments. V1 does.\n* Success responses are identical.", "parameters": [ { "name": "purchase_order_id", "in": "path", "required": true, "description": "Purchase order id (or approval key).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "example": { "error": { "purchase_order_item_payments": [ "is invalid" ] }, "status": 422 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "payment[purchase_order_item_payments_attributes][][purchase_order_item_id]": { "type": "integer", "description": "A line of this PO. A line of another PO is rejected (`purchase_order_item_payments is invalid`)." }, "payment[purchase_order_item_payments_attributes][][amount]": { "type": "number", "description": "Amount paid on that line (gross)." }, "payment[amount]": { "type": "number", "description": "Total of the payment. Stored on the payment header, but the paid totals are computed from the line amounts. Send the sum of the lines." }, "payment[note]": { "type": "string", "description": "Note appended to the PO comment and saved on the created npayment." }, "payment[purchase_order_item_payments_attributes][][id]": { "type": "integer", "description": "Not meaningful on create (there is no update endpoint)." } }, "required": [ "payment[purchase_order_item_payments_attributes][][purchase_order_item_id]", "payment[purchase_order_item_payments_attributes][][amount]" ] }, "example": { "payment": { "amount": 1306.5, "note": "Paid in full by wire, ref WIRE-88213", "purchase_order_item_payments_attributes": [ { "purchase_order_item_id": 10, "amount": 653.25 }, { "purchase_order_item_id": 11, "amount": 653.25 } ] } } } } } } }, "/api/v3/products": { "get": { "tags": [ "Products" ], "operationId": "v3_products_list", "summary": "List products", "description": "Returns the company's active (or archived) products, optionally for one supplier.\n\nReturns products of the `app_company_id` company sorted by description.\n\n* `supplier_id`: products linked to that supplier **plus products linked to no\n supplier** (those are available for every supplier). An unknown supplier id answers `404`.\n* `archived`: `true` returns only archived products. In V1 `false`/omitted returns\n only active ones. **In V3 the parameter is treated as `true` whenever it is present,\n even `archived=false`**, so in V3 omit it to get active products.\n* V1 paginates when `page` is given (`per_page` 10/20/50/100, default 10) and then\n wraps the result as `{products, meta}`. V3 always returns every matching product as\n a bare array.\n\n\n* Pagination: V1 supports `page`/`per_page` (envelope `{products, meta}`). V3 ignores\n them and always returns the full bare array.\n* `archived`: V1 casts the value (`false` -> active products). V3 uses\n `params[:archived].present?`, so `archived=false` returns **archived** products\n (verified: `products_list_archived_false` returned only the archived product in V3\n and only active products in V1).", "parameters": [ { "name": "supplier_id", "in": "query", "required": false, "description": "Products of this supplier plus unlinked products. 404 if not a supplier of the company.", "schema": { "type": "integer" } }, { "name": "archived", "in": "query", "required": false, "description": "`true` lists archived products. V3: any value (even `false`) means archived.", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "required": false, "description": "V1 only: enables pagination and the `{products, meta}` envelope. Ignored by V3.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "V1 only, with `page`: 10, 20, 50 or 100 (others fall back to 10).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "supplier_id": { "type": "null" }, "sku": { "type": "string" }, "description": { "type": "string" }, "unit_price": { "type": "string" }, "currency_id": { "type": "null" }, "archived": { "type": "boolean" }, "tax_rate_id": { "type": "null" }, "budget_id": { "type": "null" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } }, "example": [ { "id": 14, "supplier_id": null, "sku": "HDMI-2M", "description": "HDMI 2.1 cable, 2 m", "unit_price": "9.99", "currency_id": null, "archived": false, "tax_rate_id": null, "budget_id": null, "created_at": "2026-10-21T05:05:15.724-05:00", "updated_at": "2026-10-21T05:05:15.724-05:00" }, { "id": 10, "supplier_id": null, "sku": "CABLE-USBC-2M", "description": "USB-C cable, 2 m, braided", "unit_price": "14.5", "currency_id": null, "archived": false, "tax_rate_id": 4, "budget_id": 3, "created_at": "2026-10-21T05:04:10.561-05:00", "updated_at": "2026-10-21T05:05:01.248-05:00" } ] } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] }, "post": { "tags": [ "Products" ], "operationId": "v3_products_create", "summary": "Create a product", "description": "Creates a product (V1 also links it to the given supplier).\n\nCreates a product in the `app_company_id` company and returns it (`200`).\n\n* **V1** requires `product[supplier_id]` and links the new product to that supplier.\n A missing or unknown supplier answers `404 Invalid id passed` before anything is saved.\n* **V3** accepts `product[supplier_id]` (it must still be a supplier of the company)\n but **does not link** the product to it. The new product is linked to no supplier\n and is therefore offered for every supplier. Use\n [Bulk-create products](#products) (which links) if you need the link in V3.\n\n`description` is required (trimmed, `Description can't be blank`). `budget_id` and\n`tax_rate_id` must belong to the company (404 otherwise). The response echoes the\n`supplier_id` you sent; later reads return `null`.\n\n\n* V1 links the product to `supplier_id` (a `supplier_products` row) and answers `404` when\n `supplier_id` is missing (`products_create_supplier_missing`).\n* V3 never links the product. `supplier_id` is optional and only checked for ownership.\n Verified: the V3-created product (`supplier_id: 5` sent) has no supplier link and is\n returned by `GET /products?supplier_id=4`.\n* Response shape and other validation identical.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "supplier_id": { "type": "integer" }, "sku": { "type": "string" }, "description": { "type": "string" }, "unit_price": { "type": "string" }, "currency_id": { "type": "null" }, "archived": { "type": "boolean" }, "tax_rate_id": { "type": "integer" }, "budget_id": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "example": { "id": 10, "supplier_id": 5, "sku": "CABLE-USBC-2M", "description": "USB-C cable, 2 m", "unit_price": "12.99", "currency_id": null, "archived": false, "tax_rate_id": 4, "budget_id": 1, "created_at": "2026-10-21T05:04:10.561-05:00", "updated_at": "2026-10-21T05:04:10.561-05:00" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Description can't be blank" ], "status": 400 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product[description]": { "type": "string", "description": "Description (trimmed). Max 60 characters for Sage-integrated companies." }, "product[sku]": { "type": "string", "description": "SKU. Required, unique and max 30 characters for Sage-integrated companies (Sage 50/200 also forbid some characters)." }, "product[unit_price]": { "type": "number", "description": "Unit price (decimal)." }, "product[supplier_id]": { "type": "integer", "description": "V1: required; the product is linked to this supplier. V3: optional and only validated (must be a company supplier), the product is not linked." }, "product[budget_id]": { "type": "integer", "description": "Default budget id of the company." }, "product[tax_rate_id]": { "type": "integer", "description": "Default tax rate id of the company." } }, "required": [ "product[description]", "product[supplier_id]" ] }, "example": { "product": { "sku": "CABLE-USBC-2M", "description": "USB-C cable, 2 m", "unit_price": 12.99, "supplier_id": 5, "budget_id": 1, "tax_rate_id": 4 } } } } } } }, "/api/v1/products": { "get": { "tags": [ "Products" ], "operationId": "v1_products_list", "summary": "List products", "description": "Returns the company's active (or archived) products, optionally for one supplier.\n\nReturns products of the `app_company_id` company sorted by description.\n\n* `supplier_id`: products linked to that supplier **plus products linked to no\n supplier** (those are available for every supplier). An unknown supplier id answers `404`.\n* `archived`: `true` returns only archived products. In V1 `false`/omitted returns\n only active ones. **In V3 the parameter is treated as `true` whenever it is present,\n even `archived=false`**, so in V3 omit it to get active products.\n* V1 paginates when `page` is given (`per_page` 10/20/50/100, default 10) and then\n wraps the result as `{products, meta}`. V3 always returns every matching product as\n a bare array.\n\n\n* Pagination: V1 supports `page`/`per_page` (envelope `{products, meta}`). V3 ignores\n them and always returns the full bare array.\n* `archived`: V1 casts the value (`false` -> active products). V3 uses\n `params[:archived].present?`, so `archived=false` returns **archived** products\n (verified: `products_list_archived_false` returned only the archived product in V3\n and only active products in V1).", "parameters": [ { "name": "supplier_id", "in": "query", "required": false, "description": "Products of this supplier plus unlinked products. 404 if not a supplier of the company.", "schema": { "type": "integer" } }, { "name": "archived", "in": "query", "required": false, "description": "`true` lists archived products. V3: any value (even `false`) means archived.", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "required": false, "description": "V1 only: enables pagination and the `{products, meta}` envelope. Ignored by V3.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "V1 only, with `page`: 10, 20, 50 or 100 (others fall back to 10).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "supplier_id": { "type": "null" }, "sku": { "type": "string" }, "description": { "type": "string" }, "unit_price": { "type": "string" }, "currency_id": { "type": "null" }, "archived": { "type": "boolean" }, "tax_rate_id": { "type": "null" }, "budget_id": { "type": "null" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } }, "example": [ { "id": 14, "supplier_id": null, "sku": "HDMI-2M", "description": "HDMI 2.1 cable, 2 m", "unit_price": "9.99", "currency_id": null, "archived": false, "tax_rate_id": null, "budget_id": null, "created_at": "2026-10-21T05:05:15.724-05:00", "updated_at": "2026-10-21T05:05:15.724-05:00" }, { "id": 10, "supplier_id": null, "sku": "CABLE-USBC-2M", "description": "USB-C cable, 2 m, braided", "unit_price": "14.5", "currency_id": null, "archived": false, "tax_rate_id": 4, "budget_id": 3, "created_at": "2026-10-21T05:04:10.561-05:00", "updated_at": "2026-10-21T05:05:01.248-05:00" } ] } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "post": { "tags": [ "Products" ], "operationId": "v1_products_create", "summary": "Create a product", "description": "Creates a product (V1 also links it to the given supplier).\n\nCreates a product in the `app_company_id` company and returns it (`200`).\n\n* **V1** requires `product[supplier_id]` and links the new product to that supplier.\n A missing or unknown supplier answers `404 Invalid id passed` before anything is saved.\n* **V3** accepts `product[supplier_id]` (it must still be a supplier of the company)\n but **does not link** the product to it. The new product is linked to no supplier\n and is therefore offered for every supplier. Use\n [Bulk-create products](#products) (which links) if you need the link in V3.\n\n`description` is required (trimmed, `Description can't be blank`). `budget_id` and\n`tax_rate_id` must belong to the company (404 otherwise). The response echoes the\n`supplier_id` you sent; later reads return `null`.\n\n\n* V1 links the product to `supplier_id` (a `supplier_products` row) and answers `404` when\n `supplier_id` is missing (`products_create_supplier_missing`).\n* V3 never links the product. `supplier_id` is optional and only checked for ownership.\n Verified: the V3-created product (`supplier_id: 5` sent) has no supplier link and is\n returned by `GET /products?supplier_id=4`.\n* Response shape and other validation identical.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "supplier_id": { "type": "integer" }, "sku": { "type": "string" }, "description": { "type": "string" }, "unit_price": { "type": "string" }, "currency_id": { "type": "null" }, "archived": { "type": "boolean" }, "tax_rate_id": { "type": "integer" }, "budget_id": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "example": { "id": 9, "supplier_id": 4, "sku": "CHAIR-ERG-01", "description": "Ergonomic mesh chair", "unit_price": "289.5", "currency_id": null, "archived": false, "tax_rate_id": 4, "budget_id": 3, "created_at": "2026-10-21T05:04:09.352-05:00", "updated_at": "2026-10-21T05:04:09.352-05:00" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Description can't be blank" ], "status": 400 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product[description]": { "type": "string", "description": "Description (trimmed). Max 60 characters for Sage-integrated companies." }, "product[sku]": { "type": "string", "description": "SKU. Required, unique and max 30 characters for Sage-integrated companies (Sage 50/200 also forbid some characters)." }, "product[unit_price]": { "type": "number", "description": "Unit price (decimal)." }, "product[supplier_id]": { "type": "integer", "description": "V1: required; the product is linked to this supplier. V3: optional and only validated (must be a company supplier), the product is not linked." }, "product[budget_id]": { "type": "integer", "description": "Default budget id of the company." }, "product[tax_rate_id]": { "type": "integer", "description": "Default tax rate id of the company." } }, "required": [ "product[description]", "product[supplier_id]" ] }, "example": { "product": { "sku": "CHAIR-ERG-01", "description": "Ergonomic mesh chair", "unit_price": 289.5, "supplier_id": 4, "budget_id": 3, "tax_rate_id": 4 } } } } } } }, "/api/v3/products/{id}": { "get": { "tags": [ "Products" ], "operationId": "v3_products_show", "summary": "Get a product", "description": "Returns one product of the company.\n\nReturns the product if it belongs to the `app_company_id` company (archived products\nincluded).\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Product id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "supplier_id": { "type": "null" }, "sku": { "type": "string" }, "description": { "type": "string" }, "unit_price": { "type": "string" }, "currency_id": { "type": "null" }, "archived": { "type": "boolean" }, "tax_rate_id": { "type": "integer" }, "budget_id": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "example": { "id": 9, "supplier_id": null, "sku": "CHAIR-ERG-01", "description": "Ergonomic mesh chair, black", "unit_price": "275.0", "currency_id": null, "archived": false, "tax_rate_id": 5, "budget_id": 3, "created_at": "2026-10-21T05:04:09.352-05:00", "updated_at": "2026-10-21T05:05:01.027-05:00" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] }, "put": { "tags": [ "Products" ], "operationId": "v3_products_update", "summary": "Update a product", "description": "Updates the given attributes of a product.\n\nUpdates only the attributes you send and returns the product. `supplier_id` is\naccepted (and must be a supplier of the company) but **does not change** the\nproduct's supplier links. `archived` cannot be changed through the API.\n\nFor QuickBooks Online item-based companies the change is validated against and\nsynced to QBO. A QBO rejection answers `400` with the QBO message.\n\n\nNone - identical request and response (shared implementation; PUT and PATCH accepted).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Product id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "supplier_id": { "type": "null" }, "sku": { "type": "string" }, "description": { "type": "string" }, "unit_price": { "type": "string" }, "currency_id": { "type": "null" }, "archived": { "type": "boolean" }, "tax_rate_id": { "type": "integer" }, "budget_id": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "example": { "id": 10, "supplier_id": null, "sku": "CABLE-USBC-2M", "description": "USB-C cable, 2 m, braided", "unit_price": "14.5", "currency_id": null, "archived": false, "tax_rate_id": 4, "budget_id": 3, "created_at": "2026-10-21T05:04:10.561-05:00", "updated_at": "2026-10-21T05:05:01.248-05:00" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Description can't be blank" ], "status": 400 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product[description]": { "type": "string", "description": "Description (cannot be blank)." }, "product[sku]": { "type": "string", "description": "SKU." }, "product[unit_price]": { "type": "number", "description": "Unit price." }, "product[budget_id]": { "type": "integer", "description": "Company budget id." }, "product[tax_rate_id]": { "type": "integer", "description": "Company tax rate id." }, "product[supplier_id]": { "type": "integer", "description": "Validated for ownership only; no effect on supplier links (echoed in the response)." } } }, "example": { "product": { "description": "USB-C cable, 2 m, braided", "unit_price": 14.5, "budget_id": 3 } } } } } } }, "/api/v1/products/{id}": { "get": { "tags": [ "Products" ], "operationId": "v1_products_show", "summary": "Get a product", "description": "Returns one product of the company.\n\nReturns the product if it belongs to the `app_company_id` company (archived products\nincluded).\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Product id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "supplier_id": { "type": "null" }, "sku": { "type": "string" }, "description": { "type": "string" }, "unit_price": { "type": "string" }, "currency_id": { "type": "null" }, "archived": { "type": "boolean" }, "tax_rate_id": { "type": "integer" }, "budget_id": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "example": { "id": 9, "supplier_id": null, "sku": "CHAIR-ERG-01", "description": "Ergonomic mesh chair, black", "unit_price": "275.0", "currency_id": null, "archived": false, "tax_rate_id": 5, "budget_id": 3, "created_at": "2026-10-21T05:04:09.352-05:00", "updated_at": "2026-10-21T05:05:01.027-05:00" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "put": { "tags": [ "Products" ], "operationId": "v1_products_update", "summary": "Update a product", "description": "Updates the given attributes of a product.\n\nUpdates only the attributes you send and returns the product. `supplier_id` is\naccepted (and must be a supplier of the company) but **does not change** the\nproduct's supplier links. `archived` cannot be changed through the API.\n\nFor QuickBooks Online item-based companies the change is validated against and\nsynced to QBO. A QBO rejection answers `400` with the QBO message.\n\n\nNone - identical request and response (shared implementation; PUT and PATCH accepted).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Product id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "supplier_id": { "type": "null" }, "sku": { "type": "string" }, "description": { "type": "string" }, "unit_price": { "type": "string" }, "currency_id": { "type": "null" }, "archived": { "type": "boolean" }, "tax_rate_id": { "type": "integer" }, "budget_id": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "example": { "id": 9, "supplier_id": null, "sku": "CHAIR-ERG-01", "description": "Ergonomic mesh chair, black", "unit_price": "275.0", "currency_id": null, "archived": false, "tax_rate_id": 5, "budget_id": 3, "created_at": "2026-10-21T05:04:09.352-05:00", "updated_at": "2026-10-21T05:05:01.027-05:00" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Description can't be blank" ], "status": 400 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product[description]": { "type": "string", "description": "Description (cannot be blank)." }, "product[sku]": { "type": "string", "description": "SKU." }, "product[unit_price]": { "type": "number", "description": "Unit price." }, "product[budget_id]": { "type": "integer", "description": "Company budget id." }, "product[tax_rate_id]": { "type": "integer", "description": "Company tax rate id." }, "product[supplier_id]": { "type": "integer", "description": "Validated for ownership only; no effect on supplier links (echoed in the response)." } } }, "example": { "product": { "description": "Ergonomic mesh chair, black", "unit_price": 275.0, "tax_rate_id": 5 } } } } } } }, "/api/v3/products/skus": { "get": { "tags": [ "Products" ], "operationId": "v3_products_skus", "summary": "List product SKUs", "description": "Returns the SKU strings of the company's products, optionally searched.\n\nReturns a bare array of SKU strings (products without a SKU are skipped), ordered by\nproduct description. Duplicate SKUs are not removed.\n\n* `query`: case-insensitive substring match on the SKU, **limited to 10 results**.\n* `supplier_id`: products linked to that supplier plus unlinked products (404 if unknown).\n* `archived=true`: SKUs of archived products. Combining `archived=true` with `query`\n currently always returns `[]` (see findings). In V3 any `archived` value means\n archived, as in *List products*.\n\n\nSame `archived` difference as *List products* (V1 casts `archived`, V3 treats any value as\ntrue: `archived=false` returned `[\"FOOTREST-01\"]`, the archived SKU, in V3 and all\nactive SKUs in V1). Otherwise identical.", "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Substring of the SKU (case-insensitive). At most 10 SKUs are returned when set.", "schema": { "type": "string" } }, { "name": "supplier_id", "in": "query", "required": false, "description": "Only SKUs of this supplier's products plus unlinked products.", "schema": { "type": "integer" } }, { "name": "archived", "in": "query", "required": false, "description": "`true` returns SKUs of archived products. V3: any value means archived.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "MON-27", "CHAIR-ERG-01", "HDMI-2M", "DESK-LAMP-LED", "DESK-001", "CABLE-USBC-2M", "DOCK-USB-C", "KB-WL-01" ] } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/products/skus": { "get": { "tags": [ "Products" ], "operationId": "v1_products_skus", "summary": "List product SKUs", "description": "Returns the SKU strings of the company's products, optionally searched.\n\nReturns a bare array of SKU strings (products without a SKU are skipped), ordered by\nproduct description. Duplicate SKUs are not removed.\n\n* `query`: case-insensitive substring match on the SKU, **limited to 10 results**.\n* `supplier_id`: products linked to that supplier plus unlinked products (404 if unknown).\n* `archived=true`: SKUs of archived products. Combining `archived=true` with `query`\n currently always returns `[]` (see findings). In V3 any `archived` value means\n archived, as in *List products*.\n\n\nSame `archived` difference as *List products* (V1 casts `archived`, V3 treats any value as\ntrue: `archived=false` returned `[\"FOOTREST-01\"]`, the archived SKU, in V3 and all\nactive SKUs in V1). Otherwise identical.", "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Substring of the SKU (case-insensitive). At most 10 SKUs are returned when set.", "schema": { "type": "string" } }, { "name": "supplier_id", "in": "query", "required": false, "description": "Only SKUs of this supplier's products plus unlinked products.", "schema": { "type": "integer" } }, { "name": "archived", "in": "query", "required": false, "description": "`true` returns SKUs of archived products. V3: any value means archived.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "MON-27", "CHAIR-ERG-01", "HDMI-2M", "DESK-LAMP-LED", "DESK-001", "CABLE-USBC-2M", "DOCK-USB-C", "KB-WL-01" ] } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/products/bulk_create": { "post": { "tags": [ "Products" ], "operationId": "v3_products_bulk_create", "summary": "Bulk-create products for a supplier", "description": "Creates several products linked to one supplier in a single all-or-nothing request.\n\nCreates every item in `product[product_item_attributes]` in the `app_company_id`\ncompany and links each to `supplier_id`. The whole batch runs in one transaction:\nif any item fails validation, nothing is saved and the first failing item's errors\nare returned (`400`).\n\nBulk-created products are **not** synced to QuickBooks Online or exported to Sage.\nThe response is the literal JSON `true` and does not include the new ids. Use\n`GET /products?supplier_id=` or `GET /products/skus` to find them.\n\n\nNone - identical request and response (shared implementation).", "parameters": [ ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Description can't be blank" ], "status": 400 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Supplier not found", "status": "not_found" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "supplier_id": { "type": "integer", "description": "Top-level (not inside `product`). Supplier of the company to link all products to. Unknown: `404 {\"error\": \"Supplier not found\", \"status\": \"not_found\"}`." }, "product[product_item_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "The products to create. Omitting this array while sending another `product` key currently causes a 500." }, "product[product_item_attributes][][description]": { "type": "string", "description": "Description." }, "product[product_item_attributes][][sku]": { "type": "string", "description": "SKU." }, "product[product_item_attributes][][unit_price]": { "type": "number", "description": "Unit price." } }, "required": [ "supplier_id", "product[product_item_attributes][]", "product[product_item_attributes][][description]" ] }, "example": { "supplier_id": 5, "product": { "product_item_attributes": [ { "sku": "HDMI-2M", "description": "HDMI 2.1 cable, 2 m", "unit_price": 9.99 }, { "sku": "KB-WL-01", "description": "Wireless keyboard", "unit_price": 49.0 } ] } } } } } } }, "/api/v1/products/bulk_create": { "post": { "tags": [ "Products" ], "operationId": "v1_products_bulk_create", "summary": "Bulk-create products for a supplier", "description": "Creates several products linked to one supplier in a single all-or-nothing request.\n\nCreates every item in `product[product_item_attributes]` in the `app_company_id`\ncompany and links each to `supplier_id`. The whole batch runs in one transaction:\nif any item fails validation, nothing is saved and the first failing item's errors\nare returned (`400`).\n\nBulk-created products are **not** synced to QuickBooks Online or exported to Sage.\nThe response is the literal JSON `true` and does not include the new ids. Use\n`GET /products?supplier_id=` or `GET /products/skus` to find them.\n\n\nNone - identical request and response (shared implementation).", "parameters": [ ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Description can't be blank" ], "status": 400 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Supplier not found", "status": "not_found" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "supplier_id": { "type": "integer", "description": "Top-level (not inside `product`). Supplier of the company to link all products to. Unknown: `404 {\"error\": \"Supplier not found\", \"status\": \"not_found\"}`." }, "product[product_item_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "The products to create. Omitting this array while sending another `product` key currently causes a 500." }, "product[product_item_attributes][][description]": { "type": "string", "description": "Description." }, "product[product_item_attributes][][sku]": { "type": "string", "description": "SKU." }, "product[product_item_attributes][][unit_price]": { "type": "number", "description": "Unit price." } }, "required": [ "supplier_id", "product[product_item_attributes][]", "product[product_item_attributes][][description]" ] }, "example": { "supplier_id": 4, "product": { "product_item_attributes": [ { "sku": "DESK-LAMP-LED", "description": "LED desk lamp", "unit_price": 39.0 }, { "sku": "FOOTREST-01", "description": "Adjustable footrest", "unit_price": 24.5 } ] } } } } } } }, "/api/v3/purchase_orders": { "get": { "tags": [ "Purchase Orders" ], "operationId": "v3_po_list", "summary": "List purchase orders", "description": "Returns a page of purchase orders the caller can see, with filters, search and sorting.\n\nReturns 20 purchase orders per page (fixed; `per_page` is ignored), newest first by default\n(`purchase_orders.submitted_on desc`). Archived POs are excluded unless you pass `archived`.\nDrafts are included only for their creator (and for company admins when the company opens\ndrafts to admins). Visibility follows the rules in the section intro.\n\n**Default listing differs between versions.** V3 returns every visible PO in every status.\nV1 applies the web app's \"tab\" filter to the index: without a tab parameter V1 returns only\napproved, paid and cancelled POs that have already been approved once (the \"orders\" tab), so\npending, draft and rejected POs are missing. Use these V1 tab parameters to choose a tab\n(V3 ignores them):\n\n| V1 tab parameter | Returns |\n|---|---|\n| *(none)* | approved, paid, and cancelled-after-approval POs |\n| `requests=true` | draft, pending, rejected and cancelled POs that were never approved |\n| `all=true` or `all_pos=true` | every non-archived PO |\n| `deliveries=true` | non-draft POs (any delivery status) |\n| `invoices=true` | POs with `payment_status` `invoice_received` |\n| `payments=true` | approved/paid POs awaiting payment (`payment_status=unpaid` narrows to approved, unpaid) |\n\n**POs waiting for my approval**: `requests=true&bell=true` (both versions) returns only pending\nPOs where the caller (or the delegate covering for them) holds the currently active pending\nrequest. Those rows include the caller's `accept_token`/`reject_token`.\n\n**Search**: `search=` (or `search[query]=`) first looks for PO numbers containing\nthe text; if none match, it runs a prefix full-text search over `keywords`. Words, and the parts\nof hyphenated words, are OR-ed (`PRJ-2026-022` also matches `PRJ-2026-014`), so search is broad.\n\n**Sorting**: `sort` must be `.` for a whitelisted table (`purchase_orders`,\n`budgets`, `departments`, `custom_field_values`, `companies`, `user_approval_limits`, `rfqs`,\n`approval_flows`) or `users.first_name,users.last_name`; anything else, including a bare column\nsuch as `total_gross_amount`, is silently replaced by `purchase_orders.submitted_on`.\n`direction` is `asc` or `desc` (default `desc`).\n\n**Pagination**: V3 reads only `orders_page`; V1 reads `page` or `orders_page`. Use `orders_page`\nfor code that targets both. The `meta` object carries the page numbers and totals.\n\n\nSame envelope and element shape. Behaviour differs:\n* **Default filter**: V1 applies the web \"tab\" filter (default: approved/paid/cancelled-after-approval only;\n `requests`, `all`, `all_pos`, `deliveries`, `invoices`, `payments` select other tabs). V3 applies no tab\n filter and returns all statuses; those tab parameters are no-ops on V3 (see the `status=pending&search=MON-27`\n example: empty on V1, the pending POs on V3; `requests=true` alone returns the requests tab on V1 and the\n unfiltered list on V3).\n* **Pagination**: V1 accepts `page` or `orders_page`; V3 only `orders_page` (`page=2` returns page 1 on V3).\n* **Authorization**: V3 refuses RFQ-case-officer-only accounts with 401; V1 does not.\n* `requests=true&bell=true` behaves the same in both.", "parameters": [ { "name": "orders_page", "in": "query", "required": false, "description": "Page number (both versions).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, **V1 only** (V3 ignores it).", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "required": false, "description": "Free-text search (also accepted as `search[query]`). PO number match first, then OR-ed prefix full-text search.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`
.` from the whitelist, e.g. `purchase_orders.total_gross_amount`. Invalid values fall back to the default.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "`asc` or `desc`.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Exact PO status: `draft`, `pending`, `approved`, `rejected`, `cancelled`, `paid`. On V1 combine it with a tab parameter (e.g. `requests=true&status=pending`), because the default V1 tab already limits statuses.", "schema": { "type": "string" } }, { "name": "archived", "in": "query", "required": false, "description": "When present with **any** value (even `false`), only archived POs are returned and the V1 tab filter is skipped.", "schema": { "type": "boolean" } }, { "name": "requests", "in": "query", "required": false, "description": "`true`: V1 requests tab (see table). With `bell=true`: POs waiting for the caller's approval (both versions). Alone it has no filtering effect on V3.", "schema": { "type": "boolean" } }, { "name": "bell", "in": "query", "required": false, "description": "With `requests=true`: only pending POs whose active request belongs to the caller or their delegate.", "schema": { "type": "boolean" } }, { "name": "all", "in": "query", "required": false, "description": "V1 tab: every non-archived PO. Also `all_pos`. Ignored by V3.", "schema": { "type": "boolean" } }, { "name": "deliveries", "in": "query", "required": false, "description": "V1 tab: non-draft POs. Ignored by V3.", "schema": { "type": "boolean" } }, { "name": "invoices", "in": "query", "required": false, "description": "V1 tab: POs with an invoice received. Ignored by V3.", "schema": { "type": "boolean" } }, { "name": "payments", "in": "query", "required": false, "description": "V1 tab: payment queue. Ignored by V3.", "schema": { "type": "boolean" } }, { "name": "porder", "in": "query", "required": false, "description": "Only changes eager loading, except together with `status=approved&bulk_request=true`, where approved and paid POs are returned (approved only when `hide_paid_pos_filter=true`).", "schema": { "type": "boolean" } }, { "name": "supplier_id", "in": "query", "required": false, "description": "Only these suppliers (`supplier_id=2` or `supplier_id[]=1&supplier_id[]=2`). Unknown ids are dropped.", "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "supplier_exclude_id", "in": "query", "required": false, "description": "Every supplier except these (POs without a supplier stay visible). Ignored when `supplier_id` is given.", "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "requester_id", "in": "query", "required": false, "description": "Only POs created by this user.", "schema": { "type": "integer" } }, { "name": "budget_id", "in": "query", "required": false, "description": "Only POs with a line on this budget. Note: `meta.total_count` counts one row per matching line, so it can exceed the number of POs.", "schema": { "type": "integer" } }, { "name": "filter_dept_id", "in": "query", "required": false, "description": "Only POs of this department.", "schema": { "type": "integer" } }, { "name": "approver_id", "in": "query", "required": false, "description": "Only POs that have a request for this approver (with `requests=true`, only where that request is the active one).", "schema": { "type": "integer" } }, { "name": "delivery_status", "in": "query", "required": false, "description": "`not_delivered` (or `undelivered`; approved/paid POs only), `partially_delivered` or `complete_delivered` (both exclude rejected and cancelled POs).", "schema": { "type": "string" } }, { "name": "payment_status", "in": "query", "required": false, "description": "`unpaid` (excludes paid POs), `invoice_received` or `ready_to_pay`.", "schema": { "type": "string" } }, { "name": "invoice_payments", "in": "query", "required": false, "description": "A `payment_status` value; matches that payment status or `status=paid`.", "schema": { "type": "string" } }, { "name": "pending_invoice", "in": "query", "required": false, "description": "`true`: approved POs with no linked invoice.", "schema": { "type": "boolean" } }, { "name": "compliance_status", "in": "query", "required": false, "description": "Compliance check status, e.g. `passed` or `running`, or `not_run` for POs never checked.", "schema": { "type": "string" } }, { "name": "custom_field_filter", "in": "query", "required": false, "description": "Custom field values to match, keyed `custom_field_`, e.g. `custom_field_filter[custom_field_1]=PRJ-2026-040`. All given fields must match.", "schema": { "type": "object" } }, { "name": "date_filter", "in": "query", "required": false, "description": "Submission-date range: `today`, `last 7days`, `last 30days`, `last 60days`, `last 90days`, `last 180days`, `last 1year`, `current_month`, `last_month`, `current_year`, `last_year`.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Start of a custom submission-date range in the company date format (e.g. `10/01/2026` for `%m/%d/%Y`). Needs `to`. Unparseable dates are ignored.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "End of the custom range (company date format).", "schema": { "type": "string" } }, { "name": "report_date_type", "in": "query", "required": false, "description": "`po_date` applies `date_filter`/`from`/`to` to the PO date instead of the submission date.", "schema": { "type": "string" } }, { "name": "po_date_filter", "in": "query", "required": false, "description": "PO-date range using the same named values as `date_filter`.", "schema": { "type": "string" } }, { "name": "status_v2", "in": "query", "required": false, "description": "Event filter on the PO history: `approval`, `paid`, `invoice_received`, `complete_delivered`, `send_supplier`, or another history category; combined with `date_filter`/`from`/`to` it filters by when the event happened.", "schema": { "type": "string" } }, { "name": "supplier_email_status_filter", "in": "query", "required": false, "description": "Supplier email status codes (0 not sent, 10 sent, 20 opened, 30 acknowledged, 40 failed); excludes cancelled POs.", "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "approval_flow_versions", "in": "query", "required": false, "description": "`latest`, `outdated` (flow changed since attached) or `no_approval_flow`.", "schema": { "type": "string" } }, { "name": "synced_with_qbo_filter", "in": "query", "required": false, "description": "`yes`, `no` or `all` (QuickBooks Online sync).", "schema": { "type": "string" } }, { "name": "dynamics_statuses_filter", "in": "query", "required": false, "description": "`dynamics_not_synced`, `dynamics_synced`, `dynamics_failed` or `all`.", "schema": { "type": "string" } }, { "name": "updated_after", "in": "query", "required": false, "description": "ISO-8601 timestamp; POs whose header, any line item or any custom field value changed at or after it. Useful for incremental sync.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase_orders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_key": { "type": "string" }, "creator_name": { "type": "string" }, "amount": { "type": "string" }, "status": { "type": "string" }, "supplier_name": { "type": "string" }, "supplier_id": { "type": "integer" }, "keywords": { "type": "string" }, "created_at": { "type": "integer" }, "currency_id": { "type": "integer" }, "currency_symbol": { "type": "string" }, "currency_iso_code": { "type": "string" }, "total_gross_amount": { "type": "string" }, "total_net_amount": { "type": "string" }, "base_gross_amount": { "type": "number" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "effective_tax_amount": { "type": "number" }, "shipping_amount_overridden": { "type": "boolean" }, "shipping_amount_override": { "type": "null" }, "effective_shipping_amount": { "type": "string" }, "submitted_on": { "type": "integer" }, "po_date": { "type": "null" }, "share_key": { "type": "string" }, "department_id": { "type": "integer" }, "department_name": { "type": "string" }, "budget_name": { "type": "string" }, "compliance_status": { "type": "null" }, "delivered_on": { "type": "null" }, "delivery_status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_progress": { "type": "string" }, "xero_export_status": { "type": "null" }, "synced_with_xero": { "type": "boolean" }, "xero_is_changed": { "type": "boolean" }, "approver_requests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "approver_name": { "type": "string" }, "approver_id": { "type": "integer" }, "delegate_id": { "type": "null" }, "accept_token": { "type": "string" }, "reject_token": { "type": "string" } } } } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "next_page": { "type": "null" }, "prev_page": { "type": "null" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "example": { "purchase_orders": [ { "id": 28, "approval_key": "28-10/21/2026", "creator_name": "Jane Doe", "amount": "649.0", "status": "approved", "supplier_name": "Northwind Office Supplies", "supplier_id": 1, "keywords": "28 Northwind Office Supplies Jane Doe 28-10/21/2026 approved 706.60 DESK-001 Engineering Projects Standing desk, 60 x 30 in 706.59875 649.0 PRJ-2026-022 CC-100 Engineering ", "created_at": 1792576940000, "currency_id": 2000, "currency_symbol": "$", "currency_iso_code": "USD", "total_gross_amount": "706.6", "total_net_amount": "649.0", "base_gross_amount": 706.6, "tax_amount_overridden": false, "tax_amount_override": null, "effective_tax_amount": 57.6, "shipping_amount_overridden": false, "shipping_amount_override": null, "effective_shipping_amount": "0.0", "submitted_on": 1792576940000, "po_date": null, "share_key": "1CDE72EF424384C523BB93DAB3FFEBB1371FCCCA", "department_id": 2, "department_name": "Engineering", "budget_name": "Engineering Projects", "compliance_status": null, "delivered_on": null, "delivery_status": "not_delivered", "payment_status": "unpaid", "payment_progress": "unpaid", "xero_export_status": null, "synced_with_xero": false, "xero_is_changed": false, "approver_requests": [ { "id": 28, "status": "approved", "approver_name": "Jane Doe", "approver_id": 40000, "delegate_id": null, "accept_token": "", "reject_token": "" } ] }, { "id": 27, "approval_key": "27-10/21/2026", "creator_name": "Jane Doe", "amount": "649.0", "status": "approved", "supplier_name": "Northwind Office Supplies", "supplier_id": 1, "keywords": "27 Northwind Office Supplies Jane Doe 27-10/21/2026 approved 706.60 DESK-001 Engineering Projects Standing desk, 60 x 30 in 706.59875 649.0 PRJ-2026-022 CC-100 Engineering ", "created_at": 1792576933000, "currency_id": 2000, "currency_symbol": "$", "currency_iso_code": "USD", "total_gross_amount": "706.6", "total_net_amount": "649.0", "base_gross_amount": 706.6, "tax_amount_overridden": false, "tax_amount_override": null, "effective_tax_amount": 57.6, "shipping_amount_overridden": false, "shipping_amount_override": null, "effective_shipping_amount": "0.0", "submitted_on": 1792576933000, "po_date": null, "share_key": "593C0379D2F2F566272877B3C056A901324680D4", "department_id": 2, "department_name": "Engineering", "budget_name": "Engineering Projects", "compliance_status": null, "delivered_on": null, "delivery_status": "not_delivered", "payment_status": "unpaid", "payment_progress": "unpaid", "xero_export_status": null, "synced_with_xero": false, "xero_is_changed": false, "approver_requests": [ { "id": 27, "status": "approved", "approver_name": "Jane Doe", "approver_id": 40000, "delegate_id": null, "accept_token": "", "reject_token": "" } ] } ], "meta": { "current_page": 1, "next_page": null, "prev_page": null, "total_pages": 1, "total_count": 2 } } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] }, "post": { "tags": [ "Purchase Orders" ], "operationId": "v3_po_create", "summary": "Create a purchase order", "description": "Creates a purchase order as a draft or submits it for approval in one call.\n\nCreates a purchase order for the caller (or, for company admins, on behalf of another employee).\n\n* Without `commit: \"Send\"` the PO is saved as a **draft**: no budget, approver or required-field\n checks, and no approval requests.\n* With `commit: \"Send\"` it is validated in full and routed (see *How approval routing works*):\n the response is `pending` with `approver_requests[]`, or `approved` when the requester can\n self-approve (`self_approved: true`, \"Self Approved\" history comment, PO number assigned).\n\nValidation on submit: at least one line item; every line needs `description`, `quantity`,\n`unit_price`, `budget_id` and a tax rate; required custom fields must have values; the currency must\nbe supported by the company; the department must belong to the company; approvers must be resolvable\n(in manual-routing companies pass `approver_list`) and their combined approval limit must cover the\namount; budgets may not be overrun unless the company allows budget overruns.\n\nSupplier: pass `supplier_id`, or `supplier_name`. A `supplier_name` that matches an active supplier\n(case-insensitively) links it; otherwise **a new supplier with that name is created**. When the\ncompany uses a fixed supplier list, `supplier_id` is required.\n\nAfter saving, missing PO-level custom field values are created with the field's default value or\n`Not Set`, approval flows are attached when enabled, and budget totals are recalculated.\n\n\nRequest and response are identical. One behavioural difference: the `app_source` request header is\nstored as the PO `source`. V3 falls back to `api` for an unknown value; V1 assigns it unchecked, so\nan unknown value (e.g. `app_source: acme_erp`, or `web`) makes V1 answer `500`. Allowed values:\n`website`, `mobile_ios`, `mobile_android`, `mobile_other`, `mobile_android_offline`,\n`mobile_ios_offline`, `push_cart`, `zapier`, `api`, `sage50`, `sage200`, `po_generator`,\n`xero_marketplace`, `sage200_api`.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "approval_key": { "type": "null" }, "department_id": { "type": "integer" }, "department_name": { "type": "string" }, "supplier_id": { "type": "integer" }, "supplier_name": { "type": "string" }, "external_vendor_id": { "type": "null" }, "status": { "type": "string" }, "submitted_on": { "type": "integer" }, "po_date": { "type": "null" }, "currency_id": { "type": "integer" }, "currency_iso_code": { "type": "string" }, "creator_id": { "type": "integer" }, "creator_name": { "type": "string" }, "creator_email": { "type": "string" }, "creator_network_id": { "type": "null" }, "amount": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "notes": { "type": "string" }, "total_net_amount": { "type": "string" }, "total_gross_amount": { "type": "string" }, "base_gross_amount": { "type": "number" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "base_tax_amount_override": { "type": "null" }, "effective_tax_amount": { "type": "number" }, "shipping_amount_overridden": { "type": "boolean" }, "shipping_amount_override": { "type": "null" }, "base_shipping_amount_override": { "type": "null" }, "effective_shipping_amount": { "type": "string" }, "delivery_status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_progress": { "type": "string" }, "delivered_on": { "type": "integer" }, "custom_fields": { "type": "object", "properties": { } }, "share_key": { "type": "string" }, "archived": { "type": "boolean" }, "conversion_rate": { "type": "number" }, "keywords": { "type": "string" }, "self_approved": { "type": "boolean" }, "xero_id": { "type": "null" }, "synced_with_xero": { "type": "boolean" }, "xero_export_status": { "type": "null" }, "xero_export_error_message": { "type": "null" }, "xero_last_export_at": { "type": "null" }, "xero_is_changed": { "type": "boolean" }, "can_cancel": { "type": "boolean" }, "can_archive": { "type": "boolean" }, "can_mark_as_paid": { "type": "boolean" }, "can_override": { "type": "boolean" }, "can_receive_item": { "type": "boolean" }, "can_cancel_receiving_items": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "completely_delivered": { "type": "boolean" }, "aff_link": { "type": "null" }, "statuses": { "type": "array", "items": { "type": "string" } }, "budgets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "amount": { "type": "number" }, "cost_code": { "type": "string" }, "cost_type": { "type": "string" }, "archived": { "type": "boolean" }, "currency_id": { "type": "integer" }, "base_amount": { "type": "number" }, "base_rate": { "type": "string" }, "allow_anyone_to_approve_a_po": { "type": "boolean" }, "start_date": { "type": "integer" }, "end_date": { "type": "integer" }, "summary": { "type": "string" }, "remaining_amount": { "type": "number" }, "creator_id": { "type": "integer" }, "qbo_class": { "type": "null" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "approver_ids": { "type": "array", "items": { "type": "integer" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "approved_this_month": { "type": "number" } } } }, "tax_rates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "value": { "type": "number" }, "tax_amount": { "type": "number" } } } }, "can_complete_delivery": { "type": "boolean" }, "can_copy": { "type": "boolean" }, "can_justify": { "type": "boolean" }, "approvers_with_flow": { "type": "array", "items": { } }, "latest_compliance_check": { "type": "null" }, "slug": { "type": "null" }, "has_global_policies": { "type": "boolean" }, "purchase_order_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "description": { "type": "string" }, "purchase_order_id": { "type": "integer" }, "budget_id": { "type": "integer" }, "budget_summary": { "type": "string" }, "gross_amount": { "type": "number" }, "vat": { "type": "number" }, "tax_rate": { "type": "object", "properties": { "id": { "type": "integer" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" }, "created_at": { "type": "string" }, "name": { "type": "string" }, "tax_type": { "type": "string" }, "updated_at": { "type": "string" }, "value": { "type": "number" } } }, "net_amount": { "type": "number" }, "status": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": "number" }, "item_number": { "type": "string" }, "base_net_amount": { "type": "number" }, "base_gross_amount": { "type": "number" }, "gross_usd_amount": { "type": "number" }, "product_id": { "type": "integer" }, "received_quantity": { "type": "number" }, "custom_field_values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "purchase_order_id": { "type": "null" }, "value": { "type": "string" }, "custom_field_id": { "type": "integer" }, "purchase_order_item_id": { "type": "integer" }, "date_format": { "type": "null" }, "budget_id": { "type": "null" } } } }, "sequence_no": { "type": "integer" }, "chart_of_account": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "qbo_customer": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "quickbooks_class": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "qbo_line_description": { "type": "null" } } } }, "purchase_order_comments": { "type": "array", "items": { } }, "custom_field_values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "purchase_order_id": { "type": "integer" }, "value": { "type": "string" }, "custom_field_id": { "type": "integer" }, "purchase_order_item_id": { "type": "null" }, "date_format": { "type": "null" }, "budget_id": { "type": "null" } } } }, "payments": { "type": "array", "items": { } }, "purchase_order_item_payments": { "type": "array", "items": { } }, "uploads": { "type": "array", "items": { } }, "invoices": { "type": "array", "items": { } }, "compliance_checks": { "type": "array", "items": { } }, "approver_requests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "approver_name": { "type": "string" }, "approver_id": { "type": "integer" }, "delegate_id": { "type": "null" } } } }, "supplier": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "notes": { "type": "null" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "payment_details": { "type": "null" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "payment_terms": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "currency_id": { "type": "integer" }, "department_ids": { "type": "array", "items": { } }, "external_vendor_id": { "type": "null" }, "uei": { "type": "null" }, "cage_code": { "type": "null" }, "third_party_id_mappings": { "type": "array", "items": { } } } } } }, "example": { "id": 20, "company_id": 20000, "approval_key": null, "department_id": 2, "department_name": "Engineering", "supplier_id": 2, "supplier_name": "Contoso Hardware", "external_vendor_id": null, "status": "pending", "submitted_on": 1792576856, "po_date": null, "currency_id": 2000, "currency_iso_code": "USD", "creator_id": 40000, "creator_name": "Jane Doe", "creator_email": "jane.doe@example.com", "creator_network_id": null, "amount": "2077.96", "created_at": 1792576856, "updated_at": 1792576856, "notes": "Monitors and docks for the Q4 engineering hires", "total_net_amount": "2077.96", "total_gross_amount": "2262.38", "base_gross_amount": 2262.38, "tax_amount_overridden": false, "tax_amount_override": null, "base_tax_amount_override": null, "effective_tax_amount": 184.42, "shipping_amount_overridden": false, "shipping_amount_override": null, "base_shipping_amount_override": null, "effective_shipping_amount": "0.0", "delivery_status": "not_delivered", "payment_status": "unpaid", "payment_progress": "unpaid", "delivered_on": 0, "custom_fields": { }, "share_key": "AA36A0929C95210ADAD1FA685F5508BC2106E2D4", "archived": false, "conversion_rate": 1.0, "keywords": "20 Contoso Hardware Jane Doe pending 2262.38 MON-27 Engineering Hardware FY26 27-inch 4K monitor 1437.10645 1319.96 DOCK-USB-C Engineering Hardware FY26 USB-C docking station 825.2725 758.0 PRJ-2026-014 CC-100 Engineering AT-0441 ", "self_approved": false, "xero_id": null, "synced_with_xero": false, "xero_export_status": null, "xero_export_error_message": null, "xero_last_export_at": null, "xero_is_changed": false, "can_cancel": true, "can_archive": true, "can_mark_as_paid": false, "can_override": true, "can_receive_item": true, "can_cancel_receiving_items": false, "can_edit": true, "completely_delivered": false, "aff_link": null, "statuses": [ "Pending", "Unpaid", "Undelivered" ], "budgets": [ { "id": 1, "company_id": 20000, "name": "Engineering Hardware FY26", "amount": 50000.0, "cost_code": "ENG-HW", "cost_type": "Capex", "archived": false, "currency_id": 2000, "base_amount": 50000.0, "base_rate": "1.0", "allow_anyone_to_approve_a_po": false, "start_date": 1767225600, "end_date": 1798675200, "summary": "Engineering Hardware FY26 : ENG-HW : Capex", "remaining_amount": 31695.78, "creator_id": 40000, "qbo_class": null, "department_ids": [ 2 ], "approver_ids": [ 40000, 50000 ], "created_at": "2026-10-21T04:48:43.335-05:00", "updated_at": "2026-10-21T05:00:56.319-05:00", "approved_this_month": 9600.0 } ], "tax_rates": [ { "id": 4, "name": "Sales Tax", "value": 8.875, "tax_amount": 184.42 } ], "can_complete_delivery": false, "can_copy": true, "can_justify": true, "approvers_with_flow": [ ], "latest_compliance_check": null, "slug": null, "has_global_policies": true, "purchase_order_items": [ { "id": 38, "description": "27-inch 4K monitor", "purchase_order_id": 20, "budget_id": 1, "budget_summary": "Engineering Hardware FY26 : ENG-HW : Capex", "gross_amount": 1437.10645, "vat": 8.875, "tax_rate": { "id": 4, "archived": false, "company_id": 20000, "created_at": "2026-10-21T04:48:43.422-05:00", "name": "Sales Tax", "tax_type": "single", "updated_at": "2026-10-21T04:48:43.422-05:00", "value": 8.875 }, "net_amount": 1319.96, "status": "pending", "quantity": 4.0, "unit_price": 329.99, "item_number": "MON-27", "base_net_amount": 1319.96, "base_gross_amount": 1437.11, "gross_usd_amount": 1437.10645, "product_id": 2, "received_quantity": 0.0, "custom_field_values": [ { "id": 78, "purchase_order_id": null, "value": "AT-0441", "custom_field_id": 3, "purchase_order_item_id": 38, "date_format": null, "budget_id": null } ], "sequence_no": 1, "chart_of_account": { "id": null, "name": null }, "qbo_customer": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null }, "qbo_line_description": null }, { "id": 39, "description": "USB-C docking station", "purchase_order_id": 20, "budget_id": 1, "budget_summary": "Engineering Hardware FY26 : ENG-HW : Capex", "gross_amount": 825.2725, "vat": 8.875, "tax_rate": { "id": 4, "archived": false, "company_id": 20000, "created_at": "2026-10-21T04:48:43.422-05:00", "name": "Sales Tax", "tax_type": "single", "updated_at": "2026-10-21T04:48:43.422-05:00", "value": 8.875 }, "net_amount": 758.0, "status": "pending", "quantity": 4.0, "unit_price": 189.5, "item_number": "DOCK-USB-C", "base_net_amount": 758.0, "base_gross_amount": 825.27, "gross_usd_amount": 825.2725, "product_id": 3, "received_quantity": 0.0, "custom_field_values": [ { "id": 79, "purchase_order_id": null, "value": null, "custom_field_id": 3, "purchase_order_item_id": 39, "date_format": null, "budget_id": null } ], "sequence_no": 2, "chart_of_account": { "id": null, "name": null }, "qbo_customer": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null }, "qbo_line_description": null } ], "purchase_order_comments": [ ], "custom_field_values": [ { "id": 76, "purchase_order_id": 20, "value": "PRJ-2026-014", "custom_field_id": 1, "purchase_order_item_id": null, "date_format": null, "budget_id": null }, { "id": 77, "purchase_order_id": 20, "value": "CC-100 Engineering", "custom_field_id": 2, "purchase_order_item_id": null, "date_format": null, "budget_id": null } ], "payments": [ ], "purchase_order_item_payments": [ ], "uploads": [ ], "invoices": [ ], "compliance_checks": [ ], "approver_requests": [ { "id": 22, "status": "pending", "approver_name": "Priya Patel", "approver_id": 50000, "delegate_id": null } ], "supplier": { "id": 2, "name": "Contoso Hardware", "company_id": 20000, "notes": null, "phone_number": "+1 555 0300", "address": "500 Tech Park, Austin, TX 78701", "email": "sales@contoso.example.com", "payment_details": null, "archived": false, "contact_person": "Diego Ramos", "tax_number": "74-7654321", "payment_terms": "Net 45", "created_at": "2026-10-21T04:48:43.563-05:00", "updated_at": "2026-10-21T04:48:43.563-05:00", "currency_id": 2000, "department_ids": [ ], "external_vendor_id": null, "uei": null, "cage_code": null, "third_party_id_mappings": [ ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Approvers Please select at least one or more approvers" ], "status": 400 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "commit": { "type": "string", "description": "`Send` to submit for approval (case-sensitive); anything else, or omitted, saves a draft." }, "purchase_order": { "type": "object", "description": "Root object. Missing: `400 {\"error\": \"Required parameter are missing.\"}`." }, "purchase_order[supplier_id]": { "type": "integer", "description": "Supplier id. Required when the company uses a fixed supplier list. One of `supplier_id`/`supplier_name` is required." }, "purchase_order[supplier_name]": { "type": "string", "description": "Supplier name (squished, max 255). Matched case-insensitively to an active supplier; when there is no match a new supplier is created." }, "purchase_order[new_supplier_name]": { "type": "string", "description": "Overrides `supplier_name` and creates a supplier with this name when no `supplier_id` is set." }, "purchase_order[department_id]": { "type": "integer", "description": "Department of the company (`Invalid department` otherwise)." }, "purchase_order[currency_id]": { "type": "integer", "description": "PO currency; must be a company-supported currency. Required unless `iso_code` is given (`Currency can't be blank`)." }, "purchase_order[iso_code]": { "type": "string", "description": "Create only: currency ISO code used when `currency_id` is blank, e.g. `EUR`. An unknown code currently causes a 500." }, "purchase_order[notes]": { "type": "string", "description": "Free-text notes." }, "purchase_order[submitted_on]": { "type": "string", "description": "Submission timestamp (any parseable date/time); defaults to now. Reset to now when a draft is later sent." }, "purchase_order[on_behalf_of]": { "type": "integer", "description": "Create only, company admins only: user id of an active employee to record as the requester (`creator_id`). No history comment is added." }, "purchase_order[approver_list][]": { "type": "array", "items": { "type": "integer" }, "description": "User ids of the approvers to ask (manual routing). Required on submit in manual-routing companies unless the requester can self-approve. Duplicates are removed. The approvers' combined approval limit must cover the amount. Ignored when approval flows route the PO." }, "purchase_order[aff_link]": { "type": "string", "description": "Affiliate link to store on the PO." }, "purchase_order[custom_fields]": { "type": "object", "description": "Legacy free-form key/value hash stored in `custom_fields`. Prefer `custom_field_values_attributes`." }, "purchase_order[custom_field_values_attributes][][custom_field_id]": { "type": "integer", "description": "PO-level custom field id." }, "purchase_order[custom_field_values_attributes][][value]": { "type": "string", "description": "Value (for select fields one of the options; dates in the company date format)." }, "purchase_order[custom_field_values_attributes][][id]": { "type": "integer", "description": "Existing value id (update)." }, "purchase_order[purchase_order_items_attributes][][description]": { "type": "string", "description": "Line description (required on submit). A description matching a product of the supplier links that product automatically." }, "purchase_order[purchase_order_items_attributes][][quantity]": { "type": "number", "description": "Quantity (required on submit)." }, "purchase_order[purchase_order_items_attributes][][unit_price]": { "type": "number", "description": "Unit price in the PO currency (required on submit)." }, "purchase_order[purchase_order_items_attributes][][budget_id]": { "type": "integer", "description": "Budget the line is charged to (required on submit: `Please select a budget`)." }, "purchase_order[purchase_order_items_attributes][][tax_rate_id]": { "type": "integer", "description": "Tax rate (required on submit: `Tax rate can't be blank`), unless the advanced tax model is used." }, "purchase_order[purchase_order_items_attributes][][vat]": { "type": "number", "description": "Tax percentage (< 100). Derived from `tax_rate_id` when omitted." }, "purchase_order[purchase_order_items_attributes][][net_amount]": { "type": "number", "description": "Ignored: recomputed as quantity x unit_price." }, "purchase_order[purchase_order_items_attributes][][item_number]": { "type": "string", "description": "SKU / item number." }, "purchase_order[purchase_order_items_attributes][][product_id]": { "type": "integer", "description": "Catalogue product." }, "purchase_order[purchase_order_items_attributes][][sequence_no]": { "type": "integer", "description": "Display order; assigned automatically when omitted." }, "purchase_order[purchase_order_items_attributes][][department_id]": { "type": "integer", "description": "Line-level department." }, "purchase_order[purchase_order_items_attributes][][chart_of_account_id]": { "type": "integer", "description": "GL account; required on submit when QuickBooks Online is connected (account-based)." }, "purchase_order[purchase_order_items_attributes][][qbo_customer_id]": { "type": "integer", "description": "QuickBooks customer (billable to)." }, "purchase_order[purchase_order_items_attributes][][quickbooks_class_id]": { "type": "integer", "description": "QuickBooks class." }, "purchase_order[purchase_order_items_attributes][][qbo_line_description]": { "type": "string", "description": "Description sent to QuickBooks." }, "purchase_order[purchase_order_items_attributes][][xero_id]": { "type": "string", "description": "Xero line id." }, "purchase_order[purchase_order_items_attributes][][quickbooks_id]": { "type": "string", "description": "QuickBooks line id." }, "purchase_order[purchase_order_items_attributes][][zapier_id]": { "type": "string", "description": "Zapier line id." }, "purchase_order[purchase_order_items_attributes][][archived]": { "type": "boolean", "description": "Archive flag of the line." }, "purchase_order[purchase_order_items_attributes][][custom_field_values_attributes][][custom_field_id]": { "type": "integer", "description": "Line-level custom field id." }, "purchase_order[purchase_order_items_attributes][][custom_field_values_attributes][][value]": { "type": "string", "description": "Line-level custom field value." }, "purchase_order[purchase_order_items_attributes][][custom_field_values_attributes][][id]": { "type": "integer", "description": "Existing line value id (update)." }, "purchase_order[purchase_order_items_attributes][][purchase_order_item_allocations_attributes][][department_id]": { "type": "integer", "description": "Allocation department (detailed allocations)." }, "purchase_order[purchase_order_items_attributes][][purchase_order_item_allocations_attributes][][budget_id]": { "type": "integer", "description": "Allocation budget." }, "purchase_order[purchase_order_items_attributes][][purchase_order_item_allocations_attributes][][gl_code]": { "type": "string", "description": "Allocation GL code." }, "purchase_order[purchase_order_items_attributes][][purchase_order_item_allocations_attributes][][percentage]": { "type": "number", "description": "Share of the line in percent." }, "purchase_order[purchase_order_items_attributes][][purchase_order_item_allocations_attributes][][amount]": { "type": "number", "description": "Share of the line as an amount." }, "purchase_order[purchase_order_items_attributes][][purchase_order_item_allocations_attributes][][allocation_template_name]": { "type": "string", "description": "Name of the allocation template used." }, "purchase_order[purchase_order_items_attributes][][purchase_order_item_allocations_attributes][][id]": { "type": "integer", "description": "Existing allocation id (update); `_destroy: true` removes it." }, "purchase_order[purchase_order_items_attributes][][third_party_id_mappings_attributes][][service]": { "type": "string", "description": "External system of a line id mapping (e.g. `quickbooks`)." }, "purchase_order[purchase_order_items_attributes][][third_party_id_mappings_attributes][][third_party_id]": { "type": "string", "description": "Id of the line in that system." }, "purchase_order[purchase_order_items_attributes][][third_party_id_mappings_attributes][][realm_id]": { "type": "string", "description": "Tenant/realm in that system." }, "purchase_order[third_party_id_mappings_attributes][][service]": { "type": "string", "description": "External system of a PO id mapping." }, "purchase_order[third_party_id_mappings_attributes][][third_party_id]": { "type": "string", "description": "Id of the PO in that system." }, "purchase_order[third_party_id_mappings_attributes][][realm_id]": { "type": "string", "description": "Tenant/realm in that system." }, "purchase_order[purchase_order_comments_attributes][][comment]": { "type": "string", "description": "Comment added to the PO history, authored by the caller (blank comments are skipped). Author, company and system flags cannot be set." }, "purchase_order[purchase_order_comments_attributes][][uploads_attributes][][file]": { "type": "string", "format": "binary", "description": "File attached to that comment (multipart requests only)." }, "purchase_order[uploads_attributes][][file]": { "type": "string", "format": "binary", "description": "File to attach to the PO (multipart only; for JSON clients use the Uploads endpoints)." }, "purchase_order[uploads_attributes][][id]": { "type": "integer", "description": "Existing upload; with `_destroy: true` removes it if the caller may remove attachments. Existing files cannot be replaced." }, "purchase_order[requests_attributes][][approver_id]": { "type": "integer", "description": "Low-level approval request rows (`id`, `approver_id`, `_destroy`); prefer `approver_list`." }, "purchase_order[allocations_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "Legacy allocation groups: `id`, `allocation_target_id`, `group_id`, `maybe_value`, `_destroy`; values in a group must add up to the PO total." }, "purchase_order[creator_id]": { "type": "integer", "description": "Not accepted (ignored). The requester is the caller, or `on_behalf_of`." }, "purchase_order[po_date]": { "type": "string", "format": "date", "description": "Not accepted (ignored)." } }, "required": [ "purchase_order", "purchase_order[currency_id]", "purchase_order[purchase_order_items_attributes][][description]", "purchase_order[purchase_order_items_attributes][][quantity]", "purchase_order[purchase_order_items_attributes][][unit_price]", "purchase_order[purchase_order_items_attributes][][budget_id]", "purchase_order[purchase_order_items_attributes][][tax_rate_id]" ] }, "example": { "commit": "Send", "purchase_order": { "supplier_id": 2, "department_id": 2, "currency_id": 2000, "notes": "Monitors and docks for the Q4 engineering hires", "purchase_order_items_attributes": [ { "product_id": 2, "item_number": "MON-27", "description": "27-inch 4K monitor", "quantity": 4, "unit_price": 329.99, "budget_id": 1, "tax_rate_id": 4, "vat": 8.875, "custom_field_values_attributes": [ { "custom_field_id": 3, "value": "AT-0441" } ] }, { "product_id": 3, "item_number": "DOCK-USB-C", "description": "USB-C docking station", "quantity": 4, "unit_price": 189.5, "budget_id": 1, "tax_rate_id": 4, "vat": 8.875 } ], "custom_field_values_attributes": [ { "custom_field_id": 1, "value": "PRJ-2026-014" }, { "custom_field_id": 2, "value": "CC-100 Engineering" } ], "approver_list": [ 50000 ] } } } } } } }, "/api/v1/purchase_orders": { "get": { "tags": [ "Purchase Orders" ], "operationId": "v1_po_list", "summary": "List purchase orders", "description": "Returns a page of purchase orders the caller can see, with filters, search and sorting.\n\nReturns 20 purchase orders per page (fixed; `per_page` is ignored), newest first by default\n(`purchase_orders.submitted_on desc`). Archived POs are excluded unless you pass `archived`.\nDrafts are included only for their creator (and for company admins when the company opens\ndrafts to admins). Visibility follows the rules in the section intro.\n\n**Default listing differs between versions.** V3 returns every visible PO in every status.\nV1 applies the web app's \"tab\" filter to the index: without a tab parameter V1 returns only\napproved, paid and cancelled POs that have already been approved once (the \"orders\" tab), so\npending, draft and rejected POs are missing. Use these V1 tab parameters to choose a tab\n(V3 ignores them):\n\n| V1 tab parameter | Returns |\n|---|---|\n| *(none)* | approved, paid, and cancelled-after-approval POs |\n| `requests=true` | draft, pending, rejected and cancelled POs that were never approved |\n| `all=true` or `all_pos=true` | every non-archived PO |\n| `deliveries=true` | non-draft POs (any delivery status) |\n| `invoices=true` | POs with `payment_status` `invoice_received` |\n| `payments=true` | approved/paid POs awaiting payment (`payment_status=unpaid` narrows to approved, unpaid) |\n\n**POs waiting for my approval**: `requests=true&bell=true` (both versions) returns only pending\nPOs where the caller (or the delegate covering for them) holds the currently active pending\nrequest. Those rows include the caller's `accept_token`/`reject_token`.\n\n**Search**: `search=` (or `search[query]=`) first looks for PO numbers containing\nthe text; if none match, it runs a prefix full-text search over `keywords`. Words, and the parts\nof hyphenated words, are OR-ed (`PRJ-2026-022` also matches `PRJ-2026-014`), so search is broad.\n\n**Sorting**: `sort` must be `
.` for a whitelisted table (`purchase_orders`,\n`budgets`, `departments`, `custom_field_values`, `companies`, `user_approval_limits`, `rfqs`,\n`approval_flows`) or `users.first_name,users.last_name`; anything else, including a bare column\nsuch as `total_gross_amount`, is silently replaced by `purchase_orders.submitted_on`.\n`direction` is `asc` or `desc` (default `desc`).\n\n**Pagination**: V3 reads only `orders_page`; V1 reads `page` or `orders_page`. Use `orders_page`\nfor code that targets both. The `meta` object carries the page numbers and totals.\n\n\nSame envelope and element shape. Behaviour differs:\n* **Default filter**: V1 applies the web \"tab\" filter (default: approved/paid/cancelled-after-approval only;\n `requests`, `all`, `all_pos`, `deliveries`, `invoices`, `payments` select other tabs). V3 applies no tab\n filter and returns all statuses; those tab parameters are no-ops on V3 (see the `status=pending&search=MON-27`\n example: empty on V1, the pending POs on V3; `requests=true` alone returns the requests tab on V1 and the\n unfiltered list on V3).\n* **Pagination**: V1 accepts `page` or `orders_page`; V3 only `orders_page` (`page=2` returns page 1 on V3).\n* **Authorization**: V3 refuses RFQ-case-officer-only accounts with 401; V1 does not.\n* `requests=true&bell=true` behaves the same in both.", "parameters": [ { "name": "orders_page", "in": "query", "required": false, "description": "Page number (both versions).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, **V1 only** (V3 ignores it).", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "required": false, "description": "Free-text search (also accepted as `search[query]`). PO number match first, then OR-ed prefix full-text search.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`
.` from the whitelist, e.g. `purchase_orders.total_gross_amount`. Invalid values fall back to the default.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "`asc` or `desc`.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Exact PO status: `draft`, `pending`, `approved`, `rejected`, `cancelled`, `paid`. On V1 combine it with a tab parameter (e.g. `requests=true&status=pending`), because the default V1 tab already limits statuses.", "schema": { "type": "string" } }, { "name": "archived", "in": "query", "required": false, "description": "When present with **any** value (even `false`), only archived POs are returned and the V1 tab filter is skipped.", "schema": { "type": "boolean" } }, { "name": "requests", "in": "query", "required": false, "description": "`true`: V1 requests tab (see table). With `bell=true`: POs waiting for the caller's approval (both versions). Alone it has no filtering effect on V3.", "schema": { "type": "boolean" } }, { "name": "bell", "in": "query", "required": false, "description": "With `requests=true`: only pending POs whose active request belongs to the caller or their delegate.", "schema": { "type": "boolean" } }, { "name": "all", "in": "query", "required": false, "description": "V1 tab: every non-archived PO. Also `all_pos`. Ignored by V3.", "schema": { "type": "boolean" } }, { "name": "deliveries", "in": "query", "required": false, "description": "V1 tab: non-draft POs. Ignored by V3.", "schema": { "type": "boolean" } }, { "name": "invoices", "in": "query", "required": false, "description": "V1 tab: POs with an invoice received. Ignored by V3.", "schema": { "type": "boolean" } }, { "name": "payments", "in": "query", "required": false, "description": "V1 tab: payment queue. Ignored by V3.", "schema": { "type": "boolean" } }, { "name": "porder", "in": "query", "required": false, "description": "Only changes eager loading, except together with `status=approved&bulk_request=true`, where approved and paid POs are returned (approved only when `hide_paid_pos_filter=true`).", "schema": { "type": "boolean" } }, { "name": "supplier_id", "in": "query", "required": false, "description": "Only these suppliers (`supplier_id=2` or `supplier_id[]=1&supplier_id[]=2`). Unknown ids are dropped.", "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "supplier_exclude_id", "in": "query", "required": false, "description": "Every supplier except these (POs without a supplier stay visible). Ignored when `supplier_id` is given.", "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "requester_id", "in": "query", "required": false, "description": "Only POs created by this user.", "schema": { "type": "integer" } }, { "name": "budget_id", "in": "query", "required": false, "description": "Only POs with a line on this budget. Note: `meta.total_count` counts one row per matching line, so it can exceed the number of POs.", "schema": { "type": "integer" } }, { "name": "filter_dept_id", "in": "query", "required": false, "description": "Only POs of this department.", "schema": { "type": "integer" } }, { "name": "approver_id", "in": "query", "required": false, "description": "Only POs that have a request for this approver (with `requests=true`, only where that request is the active one).", "schema": { "type": "integer" } }, { "name": "delivery_status", "in": "query", "required": false, "description": "`not_delivered` (or `undelivered`; approved/paid POs only), `partially_delivered` or `complete_delivered` (both exclude rejected and cancelled POs).", "schema": { "type": "string" } }, { "name": "payment_status", "in": "query", "required": false, "description": "`unpaid` (excludes paid POs), `invoice_received` or `ready_to_pay`.", "schema": { "type": "string" } }, { "name": "invoice_payments", "in": "query", "required": false, "description": "A `payment_status` value; matches that payment status or `status=paid`.", "schema": { "type": "string" } }, { "name": "pending_invoice", "in": "query", "required": false, "description": "`true`: approved POs with no linked invoice.", "schema": { "type": "boolean" } }, { "name": "compliance_status", "in": "query", "required": false, "description": "Compliance check status, e.g. `passed` or `running`, or `not_run` for POs never checked.", "schema": { "type": "string" } }, { "name": "custom_field_filter", "in": "query", "required": false, "description": "Custom field values to match, keyed `custom_field_`, e.g. `custom_field_filter[custom_field_1]=PRJ-2026-040`. All given fields must match.", "schema": { "type": "object" } }, { "name": "date_filter", "in": "query", "required": false, "description": "Submission-date range: `today`, `last 7days`, `last 30days`, `last 60days`, `last 90days`, `last 180days`, `last 1year`, `current_month`, `last_month`, `current_year`, `last_year`.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Start of a custom submission-date range in the company date format (e.g. `10/01/2026` for `%m/%d/%Y`). Needs `to`. Unparseable dates are ignored.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "End of the custom range (company date format).", "schema": { "type": "string" } }, { "name": "report_date_type", "in": "query", "required": false, "description": "`po_date` applies `date_filter`/`from`/`to` to the PO date instead of the submission date.", "schema": { "type": "string" } }, { "name": "po_date_filter", "in": "query", "required": false, "description": "PO-date range using the same named values as `date_filter`.", "schema": { "type": "string" } }, { "name": "status_v2", "in": "query", "required": false, "description": "Event filter on the PO history: `approval`, `paid`, `invoice_received`, `complete_delivered`, `send_supplier`, or another history category; combined with `date_filter`/`from`/`to` it filters by when the event happened.", "schema": { "type": "string" } }, { "name": "supplier_email_status_filter", "in": "query", "required": false, "description": "Supplier email status codes (0 not sent, 10 sent, 20 opened, 30 acknowledged, 40 failed); excludes cancelled POs.", "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "approval_flow_versions", "in": "query", "required": false, "description": "`latest`, `outdated` (flow changed since attached) or `no_approval_flow`.", "schema": { "type": "string" } }, { "name": "synced_with_qbo_filter", "in": "query", "required": false, "description": "`yes`, `no` or `all` (QuickBooks Online sync).", "schema": { "type": "string" } }, { "name": "dynamics_statuses_filter", "in": "query", "required": false, "description": "`dynamics_not_synced`, `dynamics_synced`, `dynamics_failed` or `all`.", "schema": { "type": "string" } }, { "name": "updated_after", "in": "query", "required": false, "description": "ISO-8601 timestamp; POs whose header, any line item or any custom field value changed at or after it. Useful for incremental sync.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase_orders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "approval_key": { "type": "string" }, "creator_name": { "type": "string" }, "amount": { "type": "string" }, "status": { "type": "string" }, "supplier_name": { "type": "string" }, "supplier_id": { "type": "integer" }, "keywords": { "type": "string" }, "created_at": { "type": "integer" }, "currency_id": { "type": "integer" }, "currency_symbol": { "type": "string" }, "currency_iso_code": { "type": "string" }, "total_gross_amount": { "type": "string" }, "total_net_amount": { "type": "string" }, "base_gross_amount": { "type": "number" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "effective_tax_amount": { "type": "number" }, "shipping_amount_overridden": { "type": "boolean" }, "shipping_amount_override": { "type": "null" }, "effective_shipping_amount": { "type": "string" }, "submitted_on": { "type": "integer" }, "po_date": { "type": "null" }, "share_key": { "type": "string" }, "department_id": { "type": "integer" }, "department_name": { "type": "string" }, "budget_name": { "type": "string" }, "compliance_status": { "type": "null" }, "delivered_on": { "type": "null" }, "delivery_status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_progress": { "type": "string" }, "xero_export_status": { "type": "null" }, "synced_with_xero": { "type": "boolean" }, "xero_is_changed": { "type": "boolean" }, "approver_requests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "approver_name": { "type": "string" }, "approver_id": { "type": "integer" }, "delegate_id": { "type": "null" }, "accept_token": { "type": "string" }, "reject_token": { "type": "string" } } } } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "next_page": { "type": "null" }, "prev_page": { "type": "null" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "example": { "purchase_orders": [ { "id": 28, "approval_key": "28-10/21/2026", "creator_name": "Jane Doe", "amount": "649.0", "status": "approved", "supplier_name": "Northwind Office Supplies", "supplier_id": 1, "keywords": "28 Northwind Office Supplies Jane Doe 28-10/21/2026 approved 706.60 DESK-001 Engineering Projects Standing desk, 60 x 30 in 706.59875 649.0 PRJ-2026-022 CC-100 Engineering ", "created_at": 1792576940000, "currency_id": 2000, "currency_symbol": "$", "currency_iso_code": "USD", "total_gross_amount": "706.6", "total_net_amount": "649.0", "base_gross_amount": 706.6, "tax_amount_overridden": false, "tax_amount_override": null, "effective_tax_amount": 57.6, "shipping_amount_overridden": false, "shipping_amount_override": null, "effective_shipping_amount": "0.0", "submitted_on": 1792576940000, "po_date": null, "share_key": "1CDE72EF424384C523BB93DAB3FFEBB1371FCCCA", "department_id": 2, "department_name": "Engineering", "budget_name": "Engineering Projects", "compliance_status": null, "delivered_on": null, "delivery_status": "not_delivered", "payment_status": "unpaid", "payment_progress": "unpaid", "xero_export_status": null, "synced_with_xero": false, "xero_is_changed": false, "approver_requests": [ { "id": 28, "status": "approved", "approver_name": "Jane Doe", "approver_id": 40000, "delegate_id": null, "accept_token": "", "reject_token": "" } ] }, { "id": 27, "approval_key": "27-10/21/2026", "creator_name": "Jane Doe", "amount": "649.0", "status": "approved", "supplier_name": "Northwind Office Supplies", "supplier_id": 1, "keywords": "27 Northwind Office Supplies Jane Doe 27-10/21/2026 approved 706.60 DESK-001 Engineering Projects Standing desk, 60 x 30 in 706.59875 649.0 PRJ-2026-022 CC-100 Engineering ", "created_at": 1792576933000, "currency_id": 2000, "currency_symbol": "$", "currency_iso_code": "USD", "total_gross_amount": "706.6", "total_net_amount": "649.0", "base_gross_amount": 706.6, "tax_amount_overridden": false, "tax_amount_override": null, "effective_tax_amount": 57.6, "shipping_amount_overridden": false, "shipping_amount_override": null, "effective_shipping_amount": "0.0", "submitted_on": 1792576933000, "po_date": null, "share_key": "593C0379D2F2F566272877B3C056A901324680D4", "department_id": 2, "department_name": "Engineering", "budget_name": "Engineering Projects", "compliance_status": null, "delivered_on": null, "delivery_status": "not_delivered", "payment_status": "unpaid", "payment_progress": "unpaid", "xero_export_status": null, "synced_with_xero": false, "xero_is_changed": false, "approver_requests": [ { "id": 27, "status": "approved", "approver_name": "Jane Doe", "approver_id": 40000, "delegate_id": null, "accept_token": "", "reject_token": "" } ] } ], "meta": { "current_page": 1, "next_page": null, "prev_page": null, "total_pages": 1, "total_count": 2 } } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "post": { "tags": [ "Purchase Orders" ], "operationId": "v1_po_create", "summary": "Create a purchase order", "description": "Creates a purchase order as a draft or submits it for approval in one call.\n\nCreates a purchase order for the caller (or, for company admins, on behalf of another employee).\n\n* Without `commit: \"Send\"` the PO is saved as a **draft**: no budget, approver or required-field\n checks, and no approval requests.\n* With `commit: \"Send\"` it is validated in full and routed (see *How approval routing works*):\n the response is `pending` with `approver_requests[]`, or `approved` when the requester can\n self-approve (`self_approved: true`, \"Self Approved\" history comment, PO number assigned).\n\nValidation on submit: at least one line item; every line needs `description`, `quantity`,\n`unit_price`, `budget_id` and a tax rate; required custom fields must have values; the currency must\nbe supported by the company; the department must belong to the company; approvers must be resolvable\n(in manual-routing companies pass `approver_list`) and their combined approval limit must cover the\namount; budgets may not be overrun unless the company allows budget overruns.\n\nSupplier: pass `supplier_id`, or `supplier_name`. A `supplier_name` that matches an active supplier\n(case-insensitively) links it; otherwise **a new supplier with that name is created**. When the\ncompany uses a fixed supplier list, `supplier_id` is required.\n\nAfter saving, missing PO-level custom field values are created with the field's default value or\n`Not Set`, approval flows are attached when enabled, and budget totals are recalculated.\n\n\nRequest and response are identical. One behavioural difference: the `app_source` request header is\nstored as the PO `source`. V3 falls back to `api` for an unknown value; V1 assigns it unchecked, so\nan unknown value (e.g. `app_source: acme_erp`, or `web`) makes V1 answer `500`. Allowed values:\n`website`, `mobile_ios`, `mobile_android`, `mobile_other`, `mobile_android_offline`,\n`mobile_ios_offline`, `push_cart`, `zapier`, `api`, `sage50`, `sage200`, `po_generator`,\n`xero_marketplace`, `sage200_api`.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "approval_key": { "type": "null" }, "department_id": { "type": "integer" }, "department_name": { "type": "string" }, "supplier_id": { "type": "integer" }, "supplier_name": { "type": "string" }, "external_vendor_id": { "type": "null" }, "status": { "type": "string" }, "submitted_on": { "type": "integer" }, "po_date": { "type": "null" }, "currency_id": { "type": "integer" }, "currency_iso_code": { "type": "string" }, "creator_id": { "type": "integer" }, "creator_name": { "type": "string" }, "creator_email": { "type": "string" }, "creator_network_id": { "type": "null" }, "amount": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "notes": { "type": "string" }, "total_net_amount": { "type": "string" }, "total_gross_amount": { "type": "string" }, "base_gross_amount": { "type": "number" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "base_tax_amount_override": { "type": "null" }, "effective_tax_amount": { "type": "number" }, "shipping_amount_overridden": { "type": "boolean" }, "shipping_amount_override": { "type": "null" }, "base_shipping_amount_override": { "type": "null" }, "effective_shipping_amount": { "type": "string" }, "delivery_status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_progress": { "type": "string" }, "delivered_on": { "type": "integer" }, "custom_fields": { "type": "object", "properties": { } }, "share_key": { "type": "string" }, "archived": { "type": "boolean" }, "conversion_rate": { "type": "number" }, "keywords": { "type": "string" }, "self_approved": { "type": "boolean" }, "xero_id": { "type": "null" }, "synced_with_xero": { "type": "boolean" }, "xero_export_status": { "type": "null" }, "xero_export_error_message": { "type": "null" }, "xero_last_export_at": { "type": "null" }, "xero_is_changed": { "type": "boolean" }, "can_cancel": { "type": "boolean" }, "can_archive": { "type": "boolean" }, "can_mark_as_paid": { "type": "boolean" }, "can_override": { "type": "boolean" }, "can_receive_item": { "type": "boolean" }, "can_cancel_receiving_items": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "completely_delivered": { "type": "boolean" }, "aff_link": { "type": "null" }, "statuses": { "type": "array", "items": { "type": "string" } }, "budgets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "amount": { "type": "number" }, "cost_code": { "type": "string" }, "cost_type": { "type": "string" }, "archived": { "type": "boolean" }, "currency_id": { "type": "integer" }, "base_amount": { "type": "number" }, "base_rate": { "type": "string" }, "allow_anyone_to_approve_a_po": { "type": "boolean" }, "start_date": { "type": "integer" }, "end_date": { "type": "integer" }, "summary": { "type": "string" }, "remaining_amount": { "type": "number" }, "creator_id": { "type": "integer" }, "qbo_class": { "type": "null" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "approver_ids": { "type": "array", "items": { "type": "integer" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "approved_this_month": { "type": "number" } } } }, "tax_rates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "value": { "type": "number" }, "tax_amount": { "type": "number" } } } }, "can_complete_delivery": { "type": "boolean" }, "can_copy": { "type": "boolean" }, "can_justify": { "type": "boolean" }, "approvers_with_flow": { "type": "array", "items": { } }, "latest_compliance_check": { "type": "null" }, "slug": { "type": "null" }, "has_global_policies": { "type": "boolean" }, "purchase_order_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "description": { "type": "string" }, "purchase_order_id": { "type": "integer" }, "budget_id": { "type": "integer" }, "budget_summary": { "type": "string" }, "gross_amount": { "type": "number" }, "vat": { "type": "number" }, "tax_rate": { "type": "object", "properties": { "id": { "type": "integer" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" }, "created_at": { "type": "string" }, "name": { "type": "string" }, "tax_type": { "type": "string" }, "updated_at": { "type": "string" }, "value": { "type": "number" } } }, "net_amount": { "type": "number" }, "status": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": "number" }, "item_number": { "type": "string" }, "base_net_amount": { "type": "number" }, "base_gross_amount": { "type": "number" }, "gross_usd_amount": { "type": "number" }, "product_id": { "type": "integer" }, "received_quantity": { "type": "number" }, "custom_field_values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "purchase_order_id": { "type": "null" }, "value": { "type": "string" }, "custom_field_id": { "type": "integer" }, "purchase_order_item_id": { "type": "integer" }, "date_format": { "type": "null" }, "budget_id": { "type": "null" } } } }, "sequence_no": { "type": "integer" }, "chart_of_account": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "qbo_customer": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "quickbooks_class": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "qbo_line_description": { "type": "null" } } } }, "purchase_order_comments": { "type": "array", "items": { } }, "custom_field_values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "purchase_order_id": { "type": "integer" }, "value": { "type": "string" }, "custom_field_id": { "type": "integer" }, "purchase_order_item_id": { "type": "null" }, "date_format": { "type": "null" }, "budget_id": { "type": "null" } } } }, "payments": { "type": "array", "items": { } }, "purchase_order_item_payments": { "type": "array", "items": { } }, "uploads": { "type": "array", "items": { } }, "invoices": { "type": "array", "items": { } }, "compliance_checks": { "type": "array", "items": { } }, "approver_requests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "approver_name": { "type": "string" }, "approver_id": { "type": "integer" }, "delegate_id": { "type": "null" } } } }, "supplier": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "notes": { "type": "null" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "payment_details": { "type": "null" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "payment_terms": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "currency_id": { "type": "integer" }, "department_ids": { "type": "array", "items": { } }, "external_vendor_id": { "type": "null" }, "uei": { "type": "null" }, "cage_code": { "type": "null" }, "third_party_id_mappings": { "type": "array", "items": { } } } } } }, "example": { "id": 19, "company_id": 20000, "approval_key": null, "department_id": 2, "department_name": "Engineering", "supplier_id": 2, "supplier_name": "Contoso Hardware", "external_vendor_id": null, "status": "pending", "submitted_on": 1792576848, "po_date": null, "currency_id": 2000, "currency_iso_code": "USD", "creator_id": 40000, "creator_name": "Jane Doe", "creator_email": "jane.doe@example.com", "creator_network_id": null, "amount": "2077.96", "created_at": 1792576848, "updated_at": 1792576848, "notes": "Monitors and docks for the Q4 engineering hires", "total_net_amount": "2077.96", "total_gross_amount": "2262.38", "base_gross_amount": 2262.38, "tax_amount_overridden": false, "tax_amount_override": null, "base_tax_amount_override": null, "effective_tax_amount": 184.42, "shipping_amount_overridden": false, "shipping_amount_override": null, "base_shipping_amount_override": null, "effective_shipping_amount": "0.0", "delivery_status": "not_delivered", "payment_status": "unpaid", "payment_progress": "unpaid", "delivered_on": 0, "custom_fields": { }, "share_key": "37365FF04971E1EBBAFF5151950E9F27FAFF8F35", "archived": false, "conversion_rate": 1.0, "keywords": "19 Contoso Hardware Jane Doe pending 2262.38 MON-27 Engineering Hardware FY26 27-inch 4K monitor 1437.10645 1319.96 DOCK-USB-C Engineering Hardware FY26 USB-C docking station 825.2725 758.0 PRJ-2026-014 CC-100 Engineering AT-0441 ", "self_approved": false, "xero_id": null, "synced_with_xero": false, "xero_export_status": null, "xero_export_error_message": null, "xero_last_export_at": null, "xero_is_changed": false, "can_cancel": true, "can_archive": true, "can_mark_as_paid": false, "can_override": true, "can_receive_item": true, "can_cancel_receiving_items": false, "can_edit": true, "completely_delivered": false, "aff_link": null, "statuses": [ "Pending", "Unpaid", "Undelivered" ], "budgets": [ { "id": 1, "company_id": 20000, "name": "Engineering Hardware FY26", "amount": 50000.0, "cost_code": "ENG-HW", "cost_type": "Capex", "archived": false, "currency_id": 2000, "base_amount": 50000.0, "base_rate": "1.0", "allow_anyone_to_approve_a_po": false, "start_date": 1767225600, "end_date": 1798675200, "summary": "Engineering Hardware FY26 : ENG-HW : Capex", "remaining_amount": 33773.74, "creator_id": 40000, "qbo_class": null, "department_ids": [ 2 ], "approver_ids": [ 40000, 50000 ], "created_at": "2026-10-21T04:48:43.335-05:00", "updated_at": "2026-10-21T05:00:48.231-05:00", "approved_this_month": 9600.0 } ], "tax_rates": [ { "id": 4, "name": "Sales Tax", "value": 8.875, "tax_amount": 184.42 } ], "can_complete_delivery": false, "can_copy": true, "can_justify": true, "approvers_with_flow": [ ], "latest_compliance_check": null, "slug": null, "has_global_policies": true, "purchase_order_items": [ { "id": 36, "description": "27-inch 4K monitor", "purchase_order_id": 19, "budget_id": 1, "budget_summary": "Engineering Hardware FY26 : ENG-HW : Capex", "gross_amount": 1437.10645, "vat": 8.875, "tax_rate": { "id": 4, "archived": false, "company_id": 20000, "created_at": "2026-10-21T04:48:43.422-05:00", "name": "Sales Tax", "tax_type": "single", "updated_at": "2026-10-21T04:48:43.422-05:00", "value": 8.875 }, "net_amount": 1319.96, "status": "pending", "quantity": 4.0, "unit_price": 329.99, "item_number": "MON-27", "base_net_amount": 1319.96, "base_gross_amount": 1437.11, "gross_usd_amount": 1437.10645, "product_id": 2, "received_quantity": 0.0, "custom_field_values": [ { "id": 74, "purchase_order_id": null, "value": "AT-0441", "custom_field_id": 3, "purchase_order_item_id": 36, "date_format": null, "budget_id": null } ], "sequence_no": 1, "chart_of_account": { "id": null, "name": null }, "qbo_customer": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null }, "qbo_line_description": null }, { "id": 37, "description": "USB-C docking station", "purchase_order_id": 19, "budget_id": 1, "budget_summary": "Engineering Hardware FY26 : ENG-HW : Capex", "gross_amount": 825.2725, "vat": 8.875, "tax_rate": { "id": 4, "archived": false, "company_id": 20000, "created_at": "2026-10-21T04:48:43.422-05:00", "name": "Sales Tax", "tax_type": "single", "updated_at": "2026-10-21T04:48:43.422-05:00", "value": 8.875 }, "net_amount": 758.0, "status": "pending", "quantity": 4.0, "unit_price": 189.5, "item_number": "DOCK-USB-C", "base_net_amount": 758.0, "base_gross_amount": 825.27, "gross_usd_amount": 825.2725, "product_id": 3, "received_quantity": 0.0, "custom_field_values": [ { "id": 75, "purchase_order_id": null, "value": null, "custom_field_id": 3, "purchase_order_item_id": 37, "date_format": null, "budget_id": null } ], "sequence_no": 2, "chart_of_account": { "id": null, "name": null }, "qbo_customer": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null }, "qbo_line_description": null } ], "purchase_order_comments": [ ], "custom_field_values": [ { "id": 72, "purchase_order_id": 19, "value": "PRJ-2026-014", "custom_field_id": 1, "purchase_order_item_id": null, "date_format": null, "budget_id": null }, { "id": 73, "purchase_order_id": 19, "value": "CC-100 Engineering", "custom_field_id": 2, "purchase_order_item_id": null, "date_format": null, "budget_id": null } ], "payments": [ ], "purchase_order_item_payments": [ ], "uploads": [ ], "invoices": [ ], "compliance_checks": [ ], "approver_requests": [ { "id": 21, "status": "pending", "approver_name": "Priya Patel", "approver_id": 50000, "delegate_id": null } ], "supplier": { "id": 2, "name": "Contoso Hardware", "company_id": 20000, "notes": null, "phone_number": "+1 555 0300", "address": "500 Tech Park, Austin, TX 78701", "email": "sales@contoso.example.com", "payment_details": null, "archived": false, "contact_person": "Diego Ramos", "tax_number": "74-7654321", "payment_terms": "Net 45", "created_at": "2026-10-21T04:48:43.563-05:00", "updated_at": "2026-10-21T04:48:43.563-05:00", "currency_id": 2000, "department_ids": [ ], "external_vendor_id": null, "uei": null, "cage_code": null, "third_party_id_mappings": [ ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Approvers Please select at least one or more approvers" ], "status": 400 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "commit": { "type": "string", "description": "`Send` to submit for approval (case-sensitive); anything else, or omitted, saves a draft." }, "purchase_order": { "type": "object", "description": "Root object. Missing: `400 {\"error\": \"Required parameter are missing.\"}`." }, "purchase_order[supplier_id]": { "type": "integer", "description": "Supplier id. Required when the company uses a fixed supplier list. One of `supplier_id`/`supplier_name` is required." }, "purchase_order[supplier_name]": { "type": "string", "description": "Supplier name (squished, max 255). Matched case-insensitively to an active supplier; when there is no match a new supplier is created." }, "purchase_order[new_supplier_name]": { "type": "string", "description": "Overrides `supplier_name` and creates a supplier with this name when no `supplier_id` is set." }, "purchase_order[department_id]": { "type": "integer", "description": "Department of the company (`Invalid department` otherwise)." }, "purchase_order[currency_id]": { "type": "integer", "description": "PO currency; must be a company-supported currency. Required unless `iso_code` is given (`Currency can't be blank`)." }, "purchase_order[iso_code]": { "type": "string", "description": "Create only: currency ISO code used when `currency_id` is blank, e.g. `EUR`. An unknown code currently causes a 500." }, "purchase_order[notes]": { "type": "string", "description": "Free-text notes." }, "purchase_order[submitted_on]": { "type": "string", "description": "Submission timestamp (any parseable date/time); defaults to now. Reset to now when a draft is later sent." }, "purchase_order[on_behalf_of]": { "type": "integer", "description": "Create only, company admins only: user id of an active employee to record as the requester (`creator_id`). No history comment is added." }, "purchase_order[approver_list][]": { "type": "array", "items": { "type": "integer" }, "description": "User ids of the approvers to ask (manual routing). Required on submit in manual-routing companies unless the requester can self-approve. Duplicates are removed. The approvers' combined approval limit must cover the amount. Ignored when approval flows route the PO." }, "purchase_order[aff_link]": { "type": "string", "description": "Affiliate link to store on the PO." }, "purchase_order[custom_fields]": { "type": "object", "description": "Legacy free-form key/value hash stored in `custom_fields`. Prefer `custom_field_values_attributes`." }, "purchase_order[custom_field_values_attributes][][custom_field_id]": { "type": "integer", "description": "PO-level custom field id." }, "purchase_order[custom_field_values_attributes][][value]": { "type": "string", "description": "Value (for select fields one of the options; dates in the company date format)." }, "purchase_order[custom_field_values_attributes][][id]": { "type": "integer", "description": "Existing value id (update)." }, "purchase_order[purchase_order_items_attributes][][description]": { "type": "string", "description": "Line description (required on submit). A description matching a product of the supplier links that product automatically." }, "purchase_order[purchase_order_items_attributes][][quantity]": { "type": "number", "description": "Quantity (required on submit)." }, "purchase_order[purchase_order_items_attributes][][unit_price]": { "type": "number", "description": "Unit price in the PO currency (required on submit)." }, "purchase_order[purchase_order_items_attributes][][budget_id]": { "type": "integer", "description": "Budget the line is charged to (required on submit: `Please select a budget`)." }, "purchase_order[purchase_order_items_attributes][][tax_rate_id]": { "type": "integer", "description": "Tax rate (required on submit: `Tax rate can't be blank`), unless the advanced tax model is used." }, "purchase_order[purchase_order_items_attributes][][vat]": { "type": "number", "description": "Tax percentage (< 100). Derived from `tax_rate_id` when omitted." }, "purchase_order[purchase_order_items_attributes][][net_amount]": { "type": "number", "description": "Ignored: recomputed as quantity x unit_price." }, "purchase_order[purchase_order_items_attributes][][item_number]": { "type": "string", "description": "SKU / item number." }, "purchase_order[purchase_order_items_attributes][][product_id]": { "type": "integer", "description": "Catalogue product." }, "purchase_order[purchase_order_items_attributes][][sequence_no]": { "type": "integer", "description": "Display order; assigned automatically when omitted." }, "purchase_order[purchase_order_items_attributes][][department_id]": { "type": "integer", "description": "Line-level department." }, "purchase_order[purchase_order_items_attributes][][chart_of_account_id]": { "type": "integer", "description": "GL account; required on submit when QuickBooks Online is connected (account-based)." }, "purchase_order[purchase_order_items_attributes][][qbo_customer_id]": { "type": "integer", "description": "QuickBooks customer (billable to)." }, "purchase_order[purchase_order_items_attributes][][quickbooks_class_id]": { "type": "integer", "description": "QuickBooks class." }, "purchase_order[purchase_order_items_attributes][][qbo_line_description]": { "type": "string", "description": "Description sent to QuickBooks." }, "purchase_order[purchase_order_items_attributes][][xero_id]": { "type": "string", "description": "Xero line id." }, "purchase_order[purchase_order_items_attributes][][quickbooks_id]": { "type": "string", "description": "QuickBooks line id." }, "purchase_order[purchase_order_items_attributes][][zapier_id]": { "type": "string", "description": "Zapier line id." }, "purchase_order[purchase_order_items_attributes][][archived]": { "type": "boolean", "description": "Archive flag of the line." }, "purchase_order[purchase_order_items_attributes][][custom_field_values_attributes][][custom_field_id]": { "type": "integer", "description": "Line-level custom field id." }, "purchase_order[purchase_order_items_attributes][][custom_field_values_attributes][][value]": { "type": "string", "description": "Line-level custom field value." }, "purchase_order[purchase_order_items_attributes][][custom_field_values_attributes][][id]": { "type": "integer", "description": "Existing line value id (update)." }, "purchase_order[purchase_order_items_attributes][][purchase_order_item_allocations_attributes][][department_id]": { "type": "integer", "description": "Allocation department (detailed allocations)." }, "purchase_order[purchase_order_items_attributes][][purchase_order_item_allocations_attributes][][budget_id]": { "type": "integer", "description": "Allocation budget." }, "purchase_order[purchase_order_items_attributes][][purchase_order_item_allocations_attributes][][gl_code]": { "type": "string", "description": "Allocation GL code." }, "purchase_order[purchase_order_items_attributes][][purchase_order_item_allocations_attributes][][percentage]": { "type": "number", "description": "Share of the line in percent." }, "purchase_order[purchase_order_items_attributes][][purchase_order_item_allocations_attributes][][amount]": { "type": "number", "description": "Share of the line as an amount." }, "purchase_order[purchase_order_items_attributes][][purchase_order_item_allocations_attributes][][allocation_template_name]": { "type": "string", "description": "Name of the allocation template used." }, "purchase_order[purchase_order_items_attributes][][purchase_order_item_allocations_attributes][][id]": { "type": "integer", "description": "Existing allocation id (update); `_destroy: true` removes it." }, "purchase_order[purchase_order_items_attributes][][third_party_id_mappings_attributes][][service]": { "type": "string", "description": "External system of a line id mapping (e.g. `quickbooks`)." }, "purchase_order[purchase_order_items_attributes][][third_party_id_mappings_attributes][][third_party_id]": { "type": "string", "description": "Id of the line in that system." }, "purchase_order[purchase_order_items_attributes][][third_party_id_mappings_attributes][][realm_id]": { "type": "string", "description": "Tenant/realm in that system." }, "purchase_order[third_party_id_mappings_attributes][][service]": { "type": "string", "description": "External system of a PO id mapping." }, "purchase_order[third_party_id_mappings_attributes][][third_party_id]": { "type": "string", "description": "Id of the PO in that system." }, "purchase_order[third_party_id_mappings_attributes][][realm_id]": { "type": "string", "description": "Tenant/realm in that system." }, "purchase_order[purchase_order_comments_attributes][][comment]": { "type": "string", "description": "Comment added to the PO history, authored by the caller (blank comments are skipped). Author, company and system flags cannot be set." }, "purchase_order[purchase_order_comments_attributes][][uploads_attributes][][file]": { "type": "string", "format": "binary", "description": "File attached to that comment (multipart requests only)." }, "purchase_order[uploads_attributes][][file]": { "type": "string", "format": "binary", "description": "File to attach to the PO (multipart only; for JSON clients use the Uploads endpoints)." }, "purchase_order[uploads_attributes][][id]": { "type": "integer", "description": "Existing upload; with `_destroy: true` removes it if the caller may remove attachments. Existing files cannot be replaced." }, "purchase_order[requests_attributes][][approver_id]": { "type": "integer", "description": "Low-level approval request rows (`id`, `approver_id`, `_destroy`); prefer `approver_list`." }, "purchase_order[allocations_attributes][]": { "type": "array", "items": { "type": "object" }, "description": "Legacy allocation groups: `id`, `allocation_target_id`, `group_id`, `maybe_value`, `_destroy`; values in a group must add up to the PO total." }, "purchase_order[creator_id]": { "type": "integer", "description": "Not accepted (ignored). The requester is the caller, or `on_behalf_of`." }, "purchase_order[po_date]": { "type": "string", "format": "date", "description": "Not accepted (ignored)." } }, "required": [ "purchase_order", "purchase_order[currency_id]", "purchase_order[purchase_order_items_attributes][][description]", "purchase_order[purchase_order_items_attributes][][quantity]", "purchase_order[purchase_order_items_attributes][][unit_price]", "purchase_order[purchase_order_items_attributes][][budget_id]", "purchase_order[purchase_order_items_attributes][][tax_rate_id]" ] }, "example": { "commit": "Send", "purchase_order": { "supplier_id": 2, "department_id": 2, "currency_id": 2000, "notes": "Monitors and docks for the Q4 engineering hires", "purchase_order_items_attributes": [ { "product_id": 2, "item_number": "MON-27", "description": "27-inch 4K monitor", "quantity": 4, "unit_price": 329.99, "budget_id": 1, "tax_rate_id": 4, "vat": 8.875, "custom_field_values_attributes": [ { "custom_field_id": 3, "value": "AT-0441" } ] }, { "product_id": 3, "item_number": "DOCK-USB-C", "description": "USB-C docking station", "quantity": 4, "unit_price": 189.5, "budget_id": 1, "tax_rate_id": 4, "vat": 8.875 } ], "custom_field_values_attributes": [ { "custom_field_id": 1, "value": "PRJ-2026-014" }, { "custom_field_id": 2, "value": "CC-100 Engineering" } ], "approver_list": [ 50000 ] } } } } } } }, "/api/v3/purchase_orders/{id}": { "get": { "tags": [ "Purchase Orders" ], "operationId": "v3_po_show", "summary": "Get a purchase order", "description": "Returns one purchase order with line items, approvals, history and permission hints.\n\nReturns the full purchase order object (see the field reference above). `:id` may be the numeric\nid, the PO number (`approval_key`) or the slug; URL-encode PO numbers that contain `/`\n(`GET /purchase_orders/32-10%2F21%2F2026`).\n\n`approver_requests[]` lists the approval requests. The `accept_token` and `reject_token` needed\nby [Approve](#approve-a-purchase-order) and [Reject](#reject-a-purchase-order) are included only\non the caller's own request (as approver or as the delegate covering for the approver) - compare\nthe primary example (requester Jane, no tokens) with the \"as approver\" example (Priya, tokens\npresent). The `can_*` booleans are evaluated for the caller.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id, PO number (URL-encoded) or slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "approval_key": { "type": "null" }, "department_id": { "type": "integer" }, "department_name": { "type": "string" }, "supplier_id": { "type": "integer" }, "supplier_name": { "type": "string" }, "external_vendor_id": { "type": "null" }, "status": { "type": "string" }, "submitted_on": { "type": "integer" }, "po_date": { "type": "null" }, "currency_id": { "type": "integer" }, "currency_iso_code": { "type": "string" }, "creator_id": { "type": "integer" }, "creator_name": { "type": "string" }, "creator_email": { "type": "string" }, "creator_network_id": { "type": "null" }, "amount": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "notes": { "type": "string" }, "total_net_amount": { "type": "string" }, "total_gross_amount": { "type": "string" }, "base_gross_amount": { "type": "number" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "base_tax_amount_override": { "type": "null" }, "effective_tax_amount": { "type": "number" }, "shipping_amount_overridden": { "type": "boolean" }, "shipping_amount_override": { "type": "null" }, "base_shipping_amount_override": { "type": "null" }, "effective_shipping_amount": { "type": "string" }, "delivery_status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_progress": { "type": "string" }, "delivered_on": { "type": "integer" }, "custom_fields": { "type": "object", "properties": { } }, "share_key": { "type": "string" }, "archived": { "type": "boolean" }, "conversion_rate": { "type": "number" }, "keywords": { "type": "string" }, "self_approved": { "type": "boolean" }, "xero_id": { "type": "null" }, "synced_with_xero": { "type": "boolean" }, "xero_export_status": { "type": "null" }, "xero_export_error_message": { "type": "null" }, "xero_last_export_at": { "type": "null" }, "xero_is_changed": { "type": "boolean" }, "can_cancel": { "type": "boolean" }, "can_archive": { "type": "boolean" }, "can_mark_as_paid": { "type": "boolean" }, "can_override": { "type": "boolean" }, "can_receive_item": { "type": "boolean" }, "can_cancel_receiving_items": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "completely_delivered": { "type": "boolean" }, "aff_link": { "type": "null" }, "statuses": { "type": "array", "items": { "type": "string" } }, "budgets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "amount": { "type": "number" }, "cost_code": { "type": "string" }, "cost_type": { "type": "string" }, "archived": { "type": "boolean" }, "currency_id": { "type": "integer" }, "base_amount": { "type": "number" }, "base_rate": { "type": "string" }, "allow_anyone_to_approve_a_po": { "type": "boolean" }, "start_date": { "type": "integer" }, "end_date": { "type": "integer" }, "summary": { "type": "string" }, "remaining_amount": { "type": "number" }, "creator_id": { "type": "integer" }, "qbo_class": { "type": "null" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "approver_ids": { "type": "array", "items": { "type": "integer" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "approved_this_month": { "type": "number" } } } }, "tax_rates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "value": { "type": "number" }, "tax_amount": { "type": "number" } } } }, "can_complete_delivery": { "type": "boolean" }, "can_copy": { "type": "boolean" }, "can_justify": { "type": "boolean" }, "approvers_with_flow": { "type": "array", "items": { } }, "latest_compliance_check": { "type": "null" }, "slug": { "type": "null" }, "has_global_policies": { "type": "boolean" }, "purchase_order_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "description": { "type": "string" }, "purchase_order_id": { "type": "integer" }, "budget_id": { "type": "integer" }, "budget_summary": { "type": "string" }, "gross_amount": { "type": "number" }, "vat": { "type": "number" }, "tax_rate": { "type": "object", "properties": { "id": { "type": "integer" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" }, "created_at": { "type": "string" }, "name": { "type": "string" }, "tax_type": { "type": "string" }, "updated_at": { "type": "string" }, "value": { "type": "number" } } }, "net_amount": { "type": "number" }, "status": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": "number" }, "item_number": { "type": "string" }, "base_net_amount": { "type": "number" }, "base_gross_amount": { "type": "number" }, "gross_usd_amount": { "type": "number" }, "product_id": { "type": "integer" }, "received_quantity": { "type": "number" }, "custom_field_values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "purchase_order_id": { "type": "null" }, "value": { "type": "string" }, "custom_field_id": { "type": "integer" }, "purchase_order_item_id": { "type": "integer" }, "date_format": { "type": "null" }, "budget_id": { "type": "null" } } } }, "sequence_no": { "type": "integer" }, "chart_of_account": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "qbo_customer": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "quickbooks_class": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "qbo_line_description": { "type": "null" } } } }, "purchase_order_comments": { "type": "array", "items": { } }, "custom_field_values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "purchase_order_id": { "type": "integer" }, "value": { "type": "string" }, "custom_field_id": { "type": "integer" }, "purchase_order_item_id": { "type": "null" }, "date_format": { "type": "null" }, "budget_id": { "type": "null" } } } }, "payments": { "type": "array", "items": { } }, "purchase_order_item_payments": { "type": "array", "items": { } }, "uploads": { "type": "array", "items": { } }, "invoices": { "type": "array", "items": { } }, "compliance_checks": { "type": "array", "items": { } }, "approver_requests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "approver_name": { "type": "string" }, "approver_id": { "type": "integer" }, "delegate_id": { "type": "null" } } } }, "supplier": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "notes": { "type": "null" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "payment_details": { "type": "null" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "payment_terms": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "currency_id": { "type": "integer" }, "department_ids": { "type": "array", "items": { } }, "external_vendor_id": { "type": "null" }, "uei": { "type": "null" }, "cage_code": { "type": "null" }, "third_party_id_mappings": { "type": "array", "items": { } } } } } }, "example": { "id": 19, "company_id": 20000, "approval_key": null, "department_id": 2, "department_name": "Engineering", "supplier_id": 2, "supplier_name": "Contoso Hardware", "external_vendor_id": null, "status": "pending", "submitted_on": 1792576848, "po_date": null, "currency_id": 2000, "currency_iso_code": "USD", "creator_id": 40000, "creator_name": "Jane Doe", "creator_email": "jane.doe@example.com", "creator_network_id": null, "amount": "2077.96", "created_at": 1792576848, "updated_at": 1792576848, "notes": "Monitors and docks for the Q4 engineering hires", "total_net_amount": "2077.96", "total_gross_amount": "2262.38", "base_gross_amount": 2262.38, "tax_amount_overridden": false, "tax_amount_override": null, "base_tax_amount_override": null, "effective_tax_amount": 184.42, "shipping_amount_overridden": false, "shipping_amount_override": null, "base_shipping_amount_override": null, "effective_shipping_amount": "0.0", "delivery_status": "not_delivered", "payment_status": "unpaid", "payment_progress": "unpaid", "delivered_on": 0, "custom_fields": { }, "share_key": "37365FF04971E1EBBAFF5151950E9F27FAFF8F35", "archived": false, "conversion_rate": 1.0, "keywords": "19 Contoso Hardware Jane Doe pending 2262.38 MON-27 Engineering Hardware FY26 27-inch 4K monitor 1437.10645 1319.96 DOCK-USB-C Engineering Hardware FY26 USB-C docking station 825.2725 758.0 PRJ-2026-014 CC-100 Engineering AT-0441 ", "self_approved": false, "xero_id": null, "synced_with_xero": false, "xero_export_status": null, "xero_export_error_message": null, "xero_last_export_at": null, "xero_is_changed": false, "can_cancel": true, "can_archive": true, "can_mark_as_paid": false, "can_override": true, "can_receive_item": true, "can_cancel_receiving_items": false, "can_edit": true, "completely_delivered": false, "aff_link": null, "statuses": [ "Pending", "Unpaid", "Undelivered" ], "budgets": [ { "id": 1, "company_id": 20000, "name": "Engineering Hardware FY26", "amount": 50000.0, "cost_code": "ENG-HW", "cost_type": "Capex", "archived": false, "currency_id": 2000, "base_amount": 50000.0, "base_rate": "1.0", "allow_anyone_to_approve_a_po": false, "start_date": 1767225600, "end_date": 1798675200, "summary": "Engineering Hardware FY26 : ENG-HW : Capex", "remaining_amount": 23182.28, "creator_id": 40000, "qbo_class": null, "department_ids": [ 2 ], "approver_ids": [ 40000, 50000 ], "created_at": "2026-10-21T04:48:43.335-05:00", "updated_at": "2026-10-21T05:07:31.670-05:00", "approved_this_month": 11963.5 } ], "tax_rates": [ { "id": 4, "name": "Sales Tax", "value": 8.875, "tax_amount": 184.42 } ], "can_complete_delivery": false, "can_copy": true, "can_justify": true, "approvers_with_flow": [ ], "latest_compliance_check": null, "slug": null, "has_global_policies": true, "purchase_order_items": [ { "id": 36, "description": "27-inch 4K monitor", "purchase_order_id": 19, "budget_id": 1, "budget_summary": "Engineering Hardware FY26 : ENG-HW : Capex", "gross_amount": 1437.10645, "vat": 8.875, "tax_rate": { "id": 4, "archived": false, "company_id": 20000, "created_at": "2026-10-21T04:48:43.422-05:00", "name": "Sales Tax", "tax_type": "single", "updated_at": "2026-10-21T04:48:43.422-05:00", "value": 8.875 }, "net_amount": 1319.96, "status": "pending", "quantity": 4.0, "unit_price": 329.99, "item_number": "MON-27", "base_net_amount": 1319.96, "base_gross_amount": 1437.11, "gross_usd_amount": 1437.10645, "product_id": 2, "received_quantity": 0.0, "custom_field_values": [ { "id": 74, "purchase_order_id": null, "value": "AT-0441", "custom_field_id": 3, "purchase_order_item_id": 36, "date_format": null, "budget_id": null } ], "sequence_no": 1, "chart_of_account": { "id": null, "name": null }, "qbo_customer": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null }, "qbo_line_description": null }, { "id": 37, "description": "USB-C docking station", "purchase_order_id": 19, "budget_id": 1, "budget_summary": "Engineering Hardware FY26 : ENG-HW : Capex", "gross_amount": 825.2725, "vat": 8.875, "tax_rate": { "id": 4, "archived": false, "company_id": 20000, "created_at": "2026-10-21T04:48:43.422-05:00", "name": "Sales Tax", "tax_type": "single", "updated_at": "2026-10-21T04:48:43.422-05:00", "value": 8.875 }, "net_amount": 758.0, "status": "pending", "quantity": 4.0, "unit_price": 189.5, "item_number": "DOCK-USB-C", "base_net_amount": 758.0, "base_gross_amount": 825.27, "gross_usd_amount": 825.2725, "product_id": 3, "received_quantity": 0.0, "custom_field_values": [ { "id": 75, "purchase_order_id": null, "value": null, "custom_field_id": 3, "purchase_order_item_id": 37, "date_format": null, "budget_id": null } ], "sequence_no": 2, "chart_of_account": { "id": null, "name": null }, "qbo_customer": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null }, "qbo_line_description": null } ], "purchase_order_comments": [ ], "custom_field_values": [ { "id": 72, "purchase_order_id": 19, "value": "PRJ-2026-014", "custom_field_id": 1, "purchase_order_item_id": null, "date_format": null, "budget_id": null }, { "id": 73, "purchase_order_id": 19, "value": "CC-100 Engineering", "custom_field_id": 2, "purchase_order_item_id": null, "date_format": null, "budget_id": null } ], "payments": [ ], "purchase_order_item_payments": [ ], "uploads": [ ], "invoices": [ ], "compliance_checks": [ ], "approver_requests": [ { "id": 21, "status": "pending", "approver_name": "Priya Patel", "approver_id": 50000, "delegate_id": null } ], "supplier": { "id": 2, "name": "Contoso Hardware", "company_id": 20000, "notes": null, "phone_number": "+1 555 0300", "address": "500 Tech Park, Austin, TX 78701", "email": "sales@contoso.example.com", "payment_details": null, "archived": false, "contact_person": "Diego Ramos", "tax_number": "74-7654321", "payment_terms": "Net 45", "created_at": "2026-10-21T04:48:43.563-05:00", "updated_at": "2026-10-21T04:48:43.563-05:00", "currency_id": 2000, "department_ids": [ ], "external_vendor_id": null, "uei": null, "cage_code": null, "third_party_id_mappings": [ ] } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] }, "put": { "tags": [ "Purchase Orders" ], "operationId": "v3_po_update", "summary": "Update a purchase order", "description": "Edits a purchase order and optionally submits a draft for approval.\n\nAccepts the same `purchase_order[...]` parameters as [Create](#create-a-purchase-order) (except the\ncreate-only `iso_code` and `on_behalf_of`). Only the attributes you send change. For line items and\ncustom field values, pass `id` to change an existing row, omit `id` to add one, and send\n`\"_destroy\": true` to delete a line; rows you do not mention are kept.\n\n`commit: \"Send\"` (or the localized \"Send\" label) on a **draft** submits it: status becomes\n`pending` (or `approved` when self-approval applies) and the PO is routed exactly as on create. The\nexample submits a draft, raising a line from 1 to 3 units, adding a monitor line, changing a PO and a\nline custom field, and naming Priya as approver.\n\nEditing a non-draft PO keeps its status. For POs that are not approved or paid, approvers are\nre-evaluated; in manual-routing companies you must resend `approver_list` on every edit of a pending\nPO. When the gross total of a submitted PO changes, an \"Edited from X to Y\" history comment is added.\nA rejected PO stays `rejected` even when updated with `commit: \"Send\"`.\n\n\nNone - identical request and response. `PATCH` is routed to the same action as `PUT` in both versions.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id, PO number (URL-encoded) or slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "approval_key": { "type": "null" }, "department_id": { "type": "integer" }, "department_name": { "type": "string" }, "supplier_id": { "type": "integer" }, "supplier_name": { "type": "string" }, "external_vendor_id": { "type": "null" }, "status": { "type": "string" }, "submitted_on": { "type": "integer" }, "po_date": { "type": "null" }, "currency_id": { "type": "integer" }, "currency_iso_code": { "type": "string" }, "creator_id": { "type": "integer" }, "creator_name": { "type": "string" }, "creator_email": { "type": "string" }, "creator_network_id": { "type": "null" }, "amount": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "notes": { "type": "string" }, "total_net_amount": { "type": "string" }, "total_gross_amount": { "type": "string" }, "base_gross_amount": { "type": "number" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "base_tax_amount_override": { "type": "null" }, "effective_tax_amount": { "type": "number" }, "shipping_amount_overridden": { "type": "boolean" }, "shipping_amount_override": { "type": "null" }, "base_shipping_amount_override": { "type": "null" }, "effective_shipping_amount": { "type": "string" }, "delivery_status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_progress": { "type": "string" }, "delivered_on": { "type": "integer" }, "custom_fields": { "type": "object", "properties": { } }, "share_key": { "type": "string" }, "archived": { "type": "boolean" }, "conversion_rate": { "type": "number" }, "keywords": { "type": "string" }, "self_approved": { "type": "boolean" }, "xero_id": { "type": "null" }, "synced_with_xero": { "type": "boolean" }, "xero_export_status": { "type": "null" }, "xero_export_error_message": { "type": "null" }, "xero_last_export_at": { "type": "null" }, "xero_is_changed": { "type": "boolean" }, "can_cancel": { "type": "boolean" }, "can_archive": { "type": "boolean" }, "can_mark_as_paid": { "type": "boolean" }, "can_override": { "type": "boolean" }, "can_receive_item": { "type": "boolean" }, "can_cancel_receiving_items": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "completely_delivered": { "type": "boolean" }, "aff_link": { "type": "null" }, "statuses": { "type": "array", "items": { "type": "string" } }, "budgets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "amount": { "type": "number" }, "cost_code": { "type": "string" }, "cost_type": { "type": "string" }, "archived": { "type": "boolean" }, "currency_id": { "type": "integer" }, "base_amount": { "type": "number" }, "base_rate": { "type": "string" }, "allow_anyone_to_approve_a_po": { "type": "boolean" }, "start_date": { "type": "integer" }, "end_date": { "type": "integer" }, "summary": { "type": "string" }, "remaining_amount": { "type": "number" }, "creator_id": { "type": "integer" }, "qbo_class": { "type": "null" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "approver_ids": { "type": "array", "items": { "type": "integer" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "approved_this_month": { "type": "number" } } } }, "tax_rates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "value": { "type": "number" }, "tax_amount": { "type": "number" } } } }, "can_complete_delivery": { "type": "boolean" }, "can_copy": { "type": "boolean" }, "can_justify": { "type": "boolean" }, "approvers_with_flow": { "type": "array", "items": { } }, "latest_compliance_check": { "type": "null" }, "slug": { "type": "null" }, "has_global_policies": { "type": "boolean" }, "purchase_order_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "description": { "type": "string" }, "purchase_order_id": { "type": "integer" }, "budget_id": { "type": "integer" }, "budget_summary": { "type": "string" }, "gross_amount": { "type": "number" }, "vat": { "type": "number" }, "tax_rate": { "type": "object", "properties": { "id": { "type": "integer" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" }, "created_at": { "type": "string" }, "name": { "type": "string" }, "tax_type": { "type": "string" }, "updated_at": { "type": "string" }, "value": { "type": "number" } } }, "net_amount": { "type": "number" }, "status": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": "number" }, "item_number": { "type": "string" }, "base_net_amount": { "type": "number" }, "base_gross_amount": { "type": "number" }, "gross_usd_amount": { "type": "number" }, "product_id": { "type": "integer" }, "received_quantity": { "type": "number" }, "custom_field_values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "purchase_order_id": { "type": "null" }, "value": { "type": "string" }, "custom_field_id": { "type": "integer" }, "purchase_order_item_id": { "type": "integer" }, "date_format": { "type": "null" }, "budget_id": { "type": "null" } } } }, "sequence_no": { "type": "integer" }, "chart_of_account": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "qbo_customer": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "quickbooks_class": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "qbo_line_description": { "type": "null" } } } }, "purchase_order_comments": { "type": "array", "items": { } }, "custom_field_values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "purchase_order_id": { "type": "integer" }, "value": { "type": "string" }, "custom_field_id": { "type": "integer" }, "purchase_order_item_id": { "type": "null" }, "date_format": { "type": "null" }, "budget_id": { "type": "null" } } } }, "payments": { "type": "array", "items": { } }, "purchase_order_item_payments": { "type": "array", "items": { } }, "uploads": { "type": "array", "items": { } }, "invoices": { "type": "array", "items": { } }, "compliance_checks": { "type": "array", "items": { } }, "approver_requests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "approver_name": { "type": "string" }, "approver_id": { "type": "integer" }, "delegate_id": { "type": "null" } } } }, "supplier": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "notes": { "type": "null" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "payment_details": { "type": "null" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "payment_terms": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "currency_id": { "type": "integer" }, "department_ids": { "type": "array", "items": { } }, "external_vendor_id": { "type": "null" }, "uei": { "type": "null" }, "cage_code": { "type": "null" }, "third_party_id_mappings": { "type": "array", "items": { } } } } } }, "example": { "id": 54, "company_id": 20000, "approval_key": null, "department_id": 2, "department_name": "Engineering", "supplier_id": 2, "supplier_name": "Contoso Hardware", "external_vendor_id": null, "status": "pending", "submitted_on": 1792577433, "po_date": null, "currency_id": 2000, "currency_iso_code": "USD", "creator_id": 40000, "creator_name": "Jane Doe", "creator_email": "jane.doe@example.com", "creator_network_id": null, "amount": "898.49", "created_at": 1792577425, "updated_at": 1792577433, "notes": "Docking stations and a monitor for the design team, submitted for approval", "total_net_amount": "898.49", "total_gross_amount": "978.23", "base_gross_amount": 978.23, "tax_amount_overridden": false, "tax_amount_override": null, "base_tax_amount_override": null, "effective_tax_amount": 79.74, "shipping_amount_overridden": false, "shipping_amount_override": null, "base_shipping_amount_override": null, "effective_shipping_amount": "0.0", "delivery_status": "not_delivered", "payment_status": "unpaid", "payment_progress": "unpaid", "delivered_on": 0, "custom_fields": { }, "share_key": "C59632C683A16AC71BE4AE2EF6B779A07CF27471", "archived": false, "conversion_rate": 1.0, "keywords": "54 Contoso Hardware Jane Doe pending 978.23 DOCK-USB-C Engineering Hardware FY26 USB-C docking station 618.954375 568.5 MON-27 Engineering Hardware FY26 27-inch 4K monitor 359.276613 329.99 PRJ-2026-031 CC-100 Engineering AT-0502 ", "self_approved": false, "xero_id": null, "synced_with_xero": false, "xero_export_status": null, "xero_export_error_message": null, "xero_last_export_at": null, "xero_is_changed": false, "can_cancel": true, "can_archive": true, "can_mark_as_paid": false, "can_override": true, "can_receive_item": true, "can_cancel_receiving_items": false, "can_edit": true, "completely_delivered": false, "aff_link": null, "statuses": [ "Pending", "Unpaid", "Undelivered" ], "budgets": [ { "id": 1, "company_id": 20000, "name": "Engineering Hardware FY26", "amount": 50000.0, "cost_code": "ENG-HW", "cost_type": "Capex", "archived": false, "currency_id": 2000, "base_amount": 50000.0, "base_rate": "1.0", "allow_anyone_to_approve_a_po": false, "start_date": 1767225600, "end_date": 1798675200, "summary": "Engineering Hardware FY26 : ENG-HW : Capex", "remaining_amount": 17586.81, "creator_id": 40000, "qbo_class": null, "department_ids": [ 2 ], "approver_ids": [ 40000, 50000 ], "created_at": "2026-10-21T04:48:43.335-05:00", "updated_at": "2026-10-21T05:10:33.664-05:00", "approved_this_month": 14863.5 } ], "tax_rates": [ { "id": 4, "name": "Sales Tax", "value": 8.875, "tax_amount": 79.74 } ], "can_complete_delivery": false, "can_copy": true, "can_justify": true, "approvers_with_flow": [ ], "latest_compliance_check": null, "slug": null, "has_global_policies": true, "purchase_order_items": [ { "id": 77, "description": "USB-C docking station", "purchase_order_id": 54, "budget_id": 1, "budget_summary": "Engineering Hardware FY26 : ENG-HW : Capex", "gross_amount": 618.954375, "vat": 8.875, "tax_rate": { "id": 4, "archived": false, "company_id": 20000, "created_at": "2026-10-21T04:48:43.422-05:00", "name": "Sales Tax", "tax_type": "single", "updated_at": "2026-10-21T04:48:43.422-05:00", "value": 8.875 }, "net_amount": 568.5, "status": "pending", "quantity": 3.0, "unit_price": 189.5, "item_number": "DOCK-USB-C", "base_net_amount": 568.5, "base_gross_amount": 618.95, "gross_usd_amount": 618.954375, "product_id": 3, "received_quantity": 0.0, "custom_field_values": [ { "id": 188, "purchase_order_id": null, "value": "AT-0502", "custom_field_id": 3, "purchase_order_item_id": 77, "date_format": null, "budget_id": null } ], "sequence_no": 1, "chart_of_account": { "id": null, "name": null }, "qbo_customer": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null }, "qbo_line_description": null }, { "id": 78, "description": "27-inch 4K monitor", "purchase_order_id": 54, "budget_id": 1, "budget_summary": "Engineering Hardware FY26 : ENG-HW : Capex", "gross_amount": 359.276613, "vat": 8.875, "tax_rate": { "id": 4, "archived": false, "company_id": 20000, "created_at": "2026-10-21T04:48:43.422-05:00", "name": "Sales Tax", "tax_type": "single", "updated_at": "2026-10-21T04:48:43.422-05:00", "value": 8.875 }, "net_amount": 329.99, "status": "pending", "quantity": 1.0, "unit_price": 329.99, "item_number": "MON-27", "base_net_amount": 329.99, "base_gross_amount": 359.28, "gross_usd_amount": 359.276613, "product_id": 2, "received_quantity": 0.0, "custom_field_values": [ { "id": 189, "purchase_order_id": null, "value": null, "custom_field_id": 3, "purchase_order_item_id": 78, "date_format": null, "budget_id": null } ], "sequence_no": 2, "chart_of_account": { "id": null, "name": null }, "qbo_customer": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null }, "qbo_line_description": null } ], "purchase_order_comments": [ ], "custom_field_values": [ { "id": 186, "purchase_order_id": 54, "value": "PRJ-2026-031", "custom_field_id": 1, "purchase_order_item_id": null, "date_format": null, "budget_id": null }, { "id": 187, "purchase_order_id": 54, "value": "CC-100 Engineering", "custom_field_id": 2, "purchase_order_item_id": null, "date_format": null, "budget_id": null } ], "payments": [ ], "purchase_order_item_payments": [ ], "uploads": [ ], "invoices": [ ], "compliance_checks": [ ], "approver_requests": [ { "id": 55, "status": "pending", "approver_name": "Priya Patel", "approver_id": 50000, "delegate_id": null } ], "supplier": { "id": 2, "name": "Contoso Hardware", "company_id": 20000, "notes": null, "phone_number": "+1 555 0300", "address": "500 Tech Park, Austin, TX 78701", "email": "sales@contoso.example.com", "payment_details": null, "archived": false, "contact_person": "Diego Ramos", "tax_number": "74-7654321", "payment_terms": "Net 45", "created_at": "2026-10-21T04:48:43.563-05:00", "updated_at": "2026-10-21T04:48:43.563-05:00", "currency_id": 2000, "department_ids": [ ], "external_vendor_id": null, "uei": null, "cage_code": null, "third_party_id_mappings": [ ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Approvers Please select at least one or more approvers", "Purchase order items budget Please select a budget" ], "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "commit": { "type": "string", "description": "`Send` submits a draft for approval. Ignored for non-drafts other than re-running approver assignment." }, "purchase_order[...]": { "type": "object", "description": "Any create parameter except `iso_code` and `on_behalf_of` (see Create for the full list)." }, "purchase_order[purchase_order_items_attributes][][id]": { "type": "integer", "description": "Existing line to change." }, "purchase_order[purchase_order_items_attributes][][_destroy]": { "type": "boolean", "description": "`true` deletes that line." }, "purchase_order[custom_field_values_attributes][][id]": { "type": "integer", "description": "Existing custom field value to change." }, "purchase_order[approver_list][]": { "type": "array", "items": { "type": "integer" }, "description": "Approvers to (re)assign; required in manual-routing companies when sending or editing a pending PO." } }, "required": [ "purchase_order[...]" ] }, "example": { "commit": "Send", "purchase_order": { "notes": "Docking stations and a monitor for the design team, submitted for approval", "approver_list": [ 50000 ], "purchase_order_items_attributes": [ { "id": 77, "quantity": 3, "custom_field_values_attributes": [ { "id": 188, "custom_field_id": 3, "value": "AT-0502" } ] }, { "product_id": 2, "item_number": "MON-27", "description": "27-inch 4K monitor", "quantity": 1, "unit_price": 329.99, "budget_id": 1, "tax_rate_id": 4, "vat": 8.875 } ], "custom_field_values_attributes": [ { "id": 186, "custom_field_id": 1, "value": "PRJ-2026-031" } ] } } } } } } }, "/api/v1/purchase_orders/{id}": { "get": { "tags": [ "Purchase Orders" ], "operationId": "v1_po_show", "summary": "Get a purchase order", "description": "Returns one purchase order with line items, approvals, history and permission hints.\n\nReturns the full purchase order object (see the field reference above). `:id` may be the numeric\nid, the PO number (`approval_key`) or the slug; URL-encode PO numbers that contain `/`\n(`GET /purchase_orders/32-10%2F21%2F2026`).\n\n`approver_requests[]` lists the approval requests. The `accept_token` and `reject_token` needed\nby [Approve](#approve-a-purchase-order) and [Reject](#reject-a-purchase-order) are included only\non the caller's own request (as approver or as the delegate covering for the approver) - compare\nthe primary example (requester Jane, no tokens) with the \"as approver\" example (Priya, tokens\npresent). The `can_*` booleans are evaluated for the caller.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id, PO number (URL-encoded) or slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "approval_key": { "type": "null" }, "department_id": { "type": "integer" }, "department_name": { "type": "string" }, "supplier_id": { "type": "integer" }, "supplier_name": { "type": "string" }, "external_vendor_id": { "type": "null" }, "status": { "type": "string" }, "submitted_on": { "type": "integer" }, "po_date": { "type": "null" }, "currency_id": { "type": "integer" }, "currency_iso_code": { "type": "string" }, "creator_id": { "type": "integer" }, "creator_name": { "type": "string" }, "creator_email": { "type": "string" }, "creator_network_id": { "type": "null" }, "amount": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "notes": { "type": "string" }, "total_net_amount": { "type": "string" }, "total_gross_amount": { "type": "string" }, "base_gross_amount": { "type": "number" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "base_tax_amount_override": { "type": "null" }, "effective_tax_amount": { "type": "number" }, "shipping_amount_overridden": { "type": "boolean" }, "shipping_amount_override": { "type": "null" }, "base_shipping_amount_override": { "type": "null" }, "effective_shipping_amount": { "type": "string" }, "delivery_status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_progress": { "type": "string" }, "delivered_on": { "type": "integer" }, "custom_fields": { "type": "object", "properties": { } }, "share_key": { "type": "string" }, "archived": { "type": "boolean" }, "conversion_rate": { "type": "number" }, "keywords": { "type": "string" }, "self_approved": { "type": "boolean" }, "xero_id": { "type": "null" }, "synced_with_xero": { "type": "boolean" }, "xero_export_status": { "type": "null" }, "xero_export_error_message": { "type": "null" }, "xero_last_export_at": { "type": "null" }, "xero_is_changed": { "type": "boolean" }, "can_cancel": { "type": "boolean" }, "can_archive": { "type": "boolean" }, "can_mark_as_paid": { "type": "boolean" }, "can_override": { "type": "boolean" }, "can_receive_item": { "type": "boolean" }, "can_cancel_receiving_items": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "completely_delivered": { "type": "boolean" }, "aff_link": { "type": "null" }, "statuses": { "type": "array", "items": { "type": "string" } }, "budgets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "amount": { "type": "number" }, "cost_code": { "type": "string" }, "cost_type": { "type": "string" }, "archived": { "type": "boolean" }, "currency_id": { "type": "integer" }, "base_amount": { "type": "number" }, "base_rate": { "type": "string" }, "allow_anyone_to_approve_a_po": { "type": "boolean" }, "start_date": { "type": "integer" }, "end_date": { "type": "integer" }, "summary": { "type": "string" }, "remaining_amount": { "type": "number" }, "creator_id": { "type": "integer" }, "qbo_class": { "type": "null" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "approver_ids": { "type": "array", "items": { "type": "integer" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "approved_this_month": { "type": "number" } } } }, "tax_rates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "value": { "type": "number" }, "tax_amount": { "type": "number" } } } }, "can_complete_delivery": { "type": "boolean" }, "can_copy": { "type": "boolean" }, "can_justify": { "type": "boolean" }, "approvers_with_flow": { "type": "array", "items": { } }, "latest_compliance_check": { "type": "null" }, "slug": { "type": "null" }, "has_global_policies": { "type": "boolean" }, "purchase_order_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "description": { "type": "string" }, "purchase_order_id": { "type": "integer" }, "budget_id": { "type": "integer" }, "budget_summary": { "type": "string" }, "gross_amount": { "type": "number" }, "vat": { "type": "number" }, "tax_rate": { "type": "object", "properties": { "id": { "type": "integer" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" }, "created_at": { "type": "string" }, "name": { "type": "string" }, "tax_type": { "type": "string" }, "updated_at": { "type": "string" }, "value": { "type": "number" } } }, "net_amount": { "type": "number" }, "status": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": "number" }, "item_number": { "type": "string" }, "base_net_amount": { "type": "number" }, "base_gross_amount": { "type": "number" }, "gross_usd_amount": { "type": "number" }, "product_id": { "type": "integer" }, "received_quantity": { "type": "number" }, "custom_field_values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "purchase_order_id": { "type": "null" }, "value": { "type": "string" }, "custom_field_id": { "type": "integer" }, "purchase_order_item_id": { "type": "integer" }, "date_format": { "type": "null" }, "budget_id": { "type": "null" } } } }, "sequence_no": { "type": "integer" }, "chart_of_account": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "qbo_customer": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "quickbooks_class": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "qbo_line_description": { "type": "null" } } } }, "purchase_order_comments": { "type": "array", "items": { } }, "custom_field_values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "purchase_order_id": { "type": "integer" }, "value": { "type": "string" }, "custom_field_id": { "type": "integer" }, "purchase_order_item_id": { "type": "null" }, "date_format": { "type": "null" }, "budget_id": { "type": "null" } } } }, "payments": { "type": "array", "items": { } }, "purchase_order_item_payments": { "type": "array", "items": { } }, "uploads": { "type": "array", "items": { } }, "invoices": { "type": "array", "items": { } }, "compliance_checks": { "type": "array", "items": { } }, "approver_requests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "approver_name": { "type": "string" }, "approver_id": { "type": "integer" }, "delegate_id": { "type": "null" } } } }, "supplier": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "notes": { "type": "null" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "payment_details": { "type": "null" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "payment_terms": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "currency_id": { "type": "integer" }, "department_ids": { "type": "array", "items": { } }, "external_vendor_id": { "type": "null" }, "uei": { "type": "null" }, "cage_code": { "type": "null" }, "third_party_id_mappings": { "type": "array", "items": { } } } } } }, "example": { "id": 19, "company_id": 20000, "approval_key": null, "department_id": 2, "department_name": "Engineering", "supplier_id": 2, "supplier_name": "Contoso Hardware", "external_vendor_id": null, "status": "pending", "submitted_on": 1792576848, "po_date": null, "currency_id": 2000, "currency_iso_code": "USD", "creator_id": 40000, "creator_name": "Jane Doe", "creator_email": "jane.doe@example.com", "creator_network_id": null, "amount": "2077.96", "created_at": 1792576848, "updated_at": 1792576848, "notes": "Monitors and docks for the Q4 engineering hires", "total_net_amount": "2077.96", "total_gross_amount": "2262.38", "base_gross_amount": 2262.38, "tax_amount_overridden": false, "tax_amount_override": null, "base_tax_amount_override": null, "effective_tax_amount": 184.42, "shipping_amount_overridden": false, "shipping_amount_override": null, "base_shipping_amount_override": null, "effective_shipping_amount": "0.0", "delivery_status": "not_delivered", "payment_status": "unpaid", "payment_progress": "unpaid", "delivered_on": 0, "custom_fields": { }, "share_key": "37365FF04971E1EBBAFF5151950E9F27FAFF8F35", "archived": false, "conversion_rate": 1.0, "keywords": "19 Contoso Hardware Jane Doe pending 2262.38 MON-27 Engineering Hardware FY26 27-inch 4K monitor 1437.10645 1319.96 DOCK-USB-C Engineering Hardware FY26 USB-C docking station 825.2725 758.0 PRJ-2026-014 CC-100 Engineering AT-0441 ", "self_approved": false, "xero_id": null, "synced_with_xero": false, "xero_export_status": null, "xero_export_error_message": null, "xero_last_export_at": null, "xero_is_changed": false, "can_cancel": true, "can_archive": true, "can_mark_as_paid": false, "can_override": true, "can_receive_item": true, "can_cancel_receiving_items": false, "can_edit": true, "completely_delivered": false, "aff_link": null, "statuses": [ "Pending", "Unpaid", "Undelivered" ], "budgets": [ { "id": 1, "company_id": 20000, "name": "Engineering Hardware FY26", "amount": 50000.0, "cost_code": "ENG-HW", "cost_type": "Capex", "archived": false, "currency_id": 2000, "base_amount": 50000.0, "base_rate": "1.0", "allow_anyone_to_approve_a_po": false, "start_date": 1767225600, "end_date": 1798675200, "summary": "Engineering Hardware FY26 : ENG-HW : Capex", "remaining_amount": 23182.28, "creator_id": 40000, "qbo_class": null, "department_ids": [ 2 ], "approver_ids": [ 40000, 50000 ], "created_at": "2026-10-21T04:48:43.335-05:00", "updated_at": "2026-10-21T05:07:31.670-05:00", "approved_this_month": 11963.5 } ], "tax_rates": [ { "id": 4, "name": "Sales Tax", "value": 8.875, "tax_amount": 184.42 } ], "can_complete_delivery": false, "can_copy": true, "can_justify": true, "approvers_with_flow": [ ], "latest_compliance_check": null, "slug": null, "has_global_policies": true, "purchase_order_items": [ { "id": 36, "description": "27-inch 4K monitor", "purchase_order_id": 19, "budget_id": 1, "budget_summary": "Engineering Hardware FY26 : ENG-HW : Capex", "gross_amount": 1437.10645, "vat": 8.875, "tax_rate": { "id": 4, "archived": false, "company_id": 20000, "created_at": "2026-10-21T04:48:43.422-05:00", "name": "Sales Tax", "tax_type": "single", "updated_at": "2026-10-21T04:48:43.422-05:00", "value": 8.875 }, "net_amount": 1319.96, "status": "pending", "quantity": 4.0, "unit_price": 329.99, "item_number": "MON-27", "base_net_amount": 1319.96, "base_gross_amount": 1437.11, "gross_usd_amount": 1437.10645, "product_id": 2, "received_quantity": 0.0, "custom_field_values": [ { "id": 74, "purchase_order_id": null, "value": "AT-0441", "custom_field_id": 3, "purchase_order_item_id": 36, "date_format": null, "budget_id": null } ], "sequence_no": 1, "chart_of_account": { "id": null, "name": null }, "qbo_customer": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null }, "qbo_line_description": null }, { "id": 37, "description": "USB-C docking station", "purchase_order_id": 19, "budget_id": 1, "budget_summary": "Engineering Hardware FY26 : ENG-HW : Capex", "gross_amount": 825.2725, "vat": 8.875, "tax_rate": { "id": 4, "archived": false, "company_id": 20000, "created_at": "2026-10-21T04:48:43.422-05:00", "name": "Sales Tax", "tax_type": "single", "updated_at": "2026-10-21T04:48:43.422-05:00", "value": 8.875 }, "net_amount": 758.0, "status": "pending", "quantity": 4.0, "unit_price": 189.5, "item_number": "DOCK-USB-C", "base_net_amount": 758.0, "base_gross_amount": 825.27, "gross_usd_amount": 825.2725, "product_id": 3, "received_quantity": 0.0, "custom_field_values": [ { "id": 75, "purchase_order_id": null, "value": null, "custom_field_id": 3, "purchase_order_item_id": 37, "date_format": null, "budget_id": null } ], "sequence_no": 2, "chart_of_account": { "id": null, "name": null }, "qbo_customer": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null }, "qbo_line_description": null } ], "purchase_order_comments": [ ], "custom_field_values": [ { "id": 72, "purchase_order_id": 19, "value": "PRJ-2026-014", "custom_field_id": 1, "purchase_order_item_id": null, "date_format": null, "budget_id": null }, { "id": 73, "purchase_order_id": 19, "value": "CC-100 Engineering", "custom_field_id": 2, "purchase_order_item_id": null, "date_format": null, "budget_id": null } ], "payments": [ ], "purchase_order_item_payments": [ ], "uploads": [ ], "invoices": [ ], "compliance_checks": [ ], "approver_requests": [ { "id": 21, "status": "pending", "approver_name": "Priya Patel", "approver_id": 50000, "delegate_id": null } ], "supplier": { "id": 2, "name": "Contoso Hardware", "company_id": 20000, "notes": null, "phone_number": "+1 555 0300", "address": "500 Tech Park, Austin, TX 78701", "email": "sales@contoso.example.com", "payment_details": null, "archived": false, "contact_person": "Diego Ramos", "tax_number": "74-7654321", "payment_terms": "Net 45", "created_at": "2026-10-21T04:48:43.563-05:00", "updated_at": "2026-10-21T04:48:43.563-05:00", "currency_id": 2000, "department_ids": [ ], "external_vendor_id": null, "uei": null, "cage_code": null, "third_party_id_mappings": [ ] } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "put": { "tags": [ "Purchase Orders" ], "operationId": "v1_po_update", "summary": "Update a purchase order", "description": "Edits a purchase order and optionally submits a draft for approval.\n\nAccepts the same `purchase_order[...]` parameters as [Create](#create-a-purchase-order) (except the\ncreate-only `iso_code` and `on_behalf_of`). Only the attributes you send change. For line items and\ncustom field values, pass `id` to change an existing row, omit `id` to add one, and send\n`\"_destroy\": true` to delete a line; rows you do not mention are kept.\n\n`commit: \"Send\"` (or the localized \"Send\" label) on a **draft** submits it: status becomes\n`pending` (or `approved` when self-approval applies) and the PO is routed exactly as on create. The\nexample submits a draft, raising a line from 1 to 3 units, adding a monitor line, changing a PO and a\nline custom field, and naming Priya as approver.\n\nEditing a non-draft PO keeps its status. For POs that are not approved or paid, approvers are\nre-evaluated; in manual-routing companies you must resend `approver_list` on every edit of a pending\nPO. When the gross total of a submitted PO changes, an \"Edited from X to Y\" history comment is added.\nA rejected PO stays `rejected` even when updated with `commit: \"Send\"`.\n\n\nNone - identical request and response. `PATCH` is routed to the same action as `PUT` in both versions.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id, PO number (URL-encoded) or slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "approval_key": { "type": "null" }, "department_id": { "type": "integer" }, "department_name": { "type": "string" }, "supplier_id": { "type": "integer" }, "supplier_name": { "type": "string" }, "external_vendor_id": { "type": "null" }, "status": { "type": "string" }, "submitted_on": { "type": "integer" }, "po_date": { "type": "null" }, "currency_id": { "type": "integer" }, "currency_iso_code": { "type": "string" }, "creator_id": { "type": "integer" }, "creator_name": { "type": "string" }, "creator_email": { "type": "string" }, "creator_network_id": { "type": "null" }, "amount": { "type": "string" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "notes": { "type": "string" }, "total_net_amount": { "type": "string" }, "total_gross_amount": { "type": "string" }, "base_gross_amount": { "type": "number" }, "tax_amount_overridden": { "type": "boolean" }, "tax_amount_override": { "type": "null" }, "base_tax_amount_override": { "type": "null" }, "effective_tax_amount": { "type": "number" }, "shipping_amount_overridden": { "type": "boolean" }, "shipping_amount_override": { "type": "null" }, "base_shipping_amount_override": { "type": "null" }, "effective_shipping_amount": { "type": "string" }, "delivery_status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_progress": { "type": "string" }, "delivered_on": { "type": "integer" }, "custom_fields": { "type": "object", "properties": { } }, "share_key": { "type": "string" }, "archived": { "type": "boolean" }, "conversion_rate": { "type": "number" }, "keywords": { "type": "string" }, "self_approved": { "type": "boolean" }, "xero_id": { "type": "null" }, "synced_with_xero": { "type": "boolean" }, "xero_export_status": { "type": "null" }, "xero_export_error_message": { "type": "null" }, "xero_last_export_at": { "type": "null" }, "xero_is_changed": { "type": "boolean" }, "can_cancel": { "type": "boolean" }, "can_archive": { "type": "boolean" }, "can_mark_as_paid": { "type": "boolean" }, "can_override": { "type": "boolean" }, "can_receive_item": { "type": "boolean" }, "can_cancel_receiving_items": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "completely_delivered": { "type": "boolean" }, "aff_link": { "type": "null" }, "statuses": { "type": "array", "items": { "type": "string" } }, "budgets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "name": { "type": "string" }, "amount": { "type": "number" }, "cost_code": { "type": "string" }, "cost_type": { "type": "string" }, "archived": { "type": "boolean" }, "currency_id": { "type": "integer" }, "base_amount": { "type": "number" }, "base_rate": { "type": "string" }, "allow_anyone_to_approve_a_po": { "type": "boolean" }, "start_date": { "type": "integer" }, "end_date": { "type": "integer" }, "summary": { "type": "string" }, "remaining_amount": { "type": "number" }, "creator_id": { "type": "integer" }, "qbo_class": { "type": "null" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "approver_ids": { "type": "array", "items": { "type": "integer" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "approved_this_month": { "type": "number" } } } }, "tax_rates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "value": { "type": "number" }, "tax_amount": { "type": "number" } } } }, "can_complete_delivery": { "type": "boolean" }, "can_copy": { "type": "boolean" }, "can_justify": { "type": "boolean" }, "approvers_with_flow": { "type": "array", "items": { } }, "latest_compliance_check": { "type": "null" }, "slug": { "type": "null" }, "has_global_policies": { "type": "boolean" }, "purchase_order_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "description": { "type": "string" }, "purchase_order_id": { "type": "integer" }, "budget_id": { "type": "integer" }, "budget_summary": { "type": "string" }, "gross_amount": { "type": "number" }, "vat": { "type": "number" }, "tax_rate": { "type": "object", "properties": { "id": { "type": "integer" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" }, "created_at": { "type": "string" }, "name": { "type": "string" }, "tax_type": { "type": "string" }, "updated_at": { "type": "string" }, "value": { "type": "number" } } }, "net_amount": { "type": "number" }, "status": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": "number" }, "item_number": { "type": "string" }, "base_net_amount": { "type": "number" }, "base_gross_amount": { "type": "number" }, "gross_usd_amount": { "type": "number" }, "product_id": { "type": "integer" }, "received_quantity": { "type": "number" }, "custom_field_values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "purchase_order_id": { "type": "null" }, "value": { "type": "string" }, "custom_field_id": { "type": "integer" }, "purchase_order_item_id": { "type": "integer" }, "date_format": { "type": "null" }, "budget_id": { "type": "null" } } } }, "sequence_no": { "type": "integer" }, "chart_of_account": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "qbo_customer": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "quickbooks_class": { "type": "object", "properties": { "id": { "type": "null" }, "name": { "type": "null" } } }, "qbo_line_description": { "type": "null" } } } }, "purchase_order_comments": { "type": "array", "items": { } }, "custom_field_values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "purchase_order_id": { "type": "integer" }, "value": { "type": "string" }, "custom_field_id": { "type": "integer" }, "purchase_order_item_id": { "type": "null" }, "date_format": { "type": "null" }, "budget_id": { "type": "null" } } } }, "payments": { "type": "array", "items": { } }, "purchase_order_item_payments": { "type": "array", "items": { } }, "uploads": { "type": "array", "items": { } }, "invoices": { "type": "array", "items": { } }, "compliance_checks": { "type": "array", "items": { } }, "approver_requests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "approver_name": { "type": "string" }, "approver_id": { "type": "integer" }, "delegate_id": { "type": "null" } } } }, "supplier": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "notes": { "type": "null" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "payment_details": { "type": "null" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "payment_terms": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "currency_id": { "type": "integer" }, "department_ids": { "type": "array", "items": { } }, "external_vendor_id": { "type": "null" }, "uei": { "type": "null" }, "cage_code": { "type": "null" }, "third_party_id_mappings": { "type": "array", "items": { } } } } } }, "example": { "id": 52, "company_id": 20000, "approval_key": null, "department_id": 2, "department_name": "Engineering", "supplier_id": 2, "supplier_name": "Contoso Hardware", "external_vendor_id": null, "status": "pending", "submitted_on": 1792577407, "po_date": null, "currency_id": 2000, "currency_iso_code": "USD", "creator_id": 40000, "creator_name": "Jane Doe", "creator_email": "jane.doe@example.com", "creator_network_id": null, "amount": "898.49", "created_at": 1792577386, "updated_at": 1792577407, "notes": "Docking stations and a monitor for the design team, submitted for approval", "total_net_amount": "898.49", "total_gross_amount": "978.23", "base_gross_amount": 978.23, "tax_amount_overridden": false, "tax_amount_override": null, "base_tax_amount_override": null, "effective_tax_amount": 79.74, "shipping_amount_overridden": false, "shipping_amount_override": null, "base_shipping_amount_override": null, "effective_shipping_amount": "0.0", "delivery_status": "not_delivered", "payment_status": "unpaid", "payment_progress": "unpaid", "delivered_on": 0, "custom_fields": { }, "share_key": "487167822F1CF3A1C121B712C7899D88B68A24F1", "archived": false, "conversion_rate": 1.0, "keywords": "52 Contoso Hardware Jane Doe pending 978.23 DOCK-USB-C Engineering Hardware FY26 USB-C docking station 618.954375 568.5 MON-27 Engineering Hardware FY26 27-inch 4K monitor 359.276613 329.99 PRJ-2026-031 CC-100 Engineering AT-0502 ", "self_approved": false, "xero_id": null, "synced_with_xero": false, "xero_export_status": null, "xero_export_error_message": null, "xero_last_export_at": null, "xero_is_changed": false, "can_cancel": true, "can_archive": true, "can_mark_as_paid": false, "can_override": true, "can_receive_item": true, "can_cancel_receiving_items": false, "can_edit": true, "completely_delivered": false, "aff_link": null, "statuses": [ "Pending", "Unpaid", "Undelivered" ], "budgets": [ { "id": 1, "company_id": 20000, "name": "Engineering Hardware FY26", "amount": 50000.0, "cost_code": "ENG-HW", "cost_type": "Capex", "archived": false, "currency_id": 2000, "base_amount": 50000.0, "base_rate": "1.0", "allow_anyone_to_approve_a_po": false, "start_date": 1767225600, "end_date": 1798675200, "summary": "Engineering Hardware FY26 : ENG-HW : Capex", "remaining_amount": 19383.79, "creator_id": 40000, "qbo_class": null, "department_ids": [ 2 ], "approver_ids": [ 40000, 50000 ], "created_at": "2026-10-21T04:48:43.335-05:00", "updated_at": "2026-10-21T05:10:07.406-05:00", "approved_this_month": 14863.5 } ], "tax_rates": [ { "id": 4, "name": "Sales Tax", "value": 8.875, "tax_amount": 79.74 } ], "can_complete_delivery": false, "can_copy": true, "can_justify": true, "approvers_with_flow": [ ], "latest_compliance_check": null, "slug": null, "has_global_policies": true, "purchase_order_items": [ { "id": 73, "description": "USB-C docking station", "purchase_order_id": 52, "budget_id": 1, "budget_summary": "Engineering Hardware FY26 : ENG-HW : Capex", "gross_amount": 618.954375, "vat": 8.875, "tax_rate": { "id": 4, "archived": false, "company_id": 20000, "created_at": "2026-10-21T04:48:43.422-05:00", "name": "Sales Tax", "tax_type": "single", "updated_at": "2026-10-21T04:48:43.422-05:00", "value": 8.875 }, "net_amount": 568.5, "status": "pending", "quantity": 3.0, "unit_price": 189.5, "item_number": "DOCK-USB-C", "base_net_amount": 568.5, "base_gross_amount": 618.95, "gross_usd_amount": 618.954375, "product_id": 3, "received_quantity": 0.0, "custom_field_values": [ { "id": 179, "purchase_order_id": null, "value": "AT-0502", "custom_field_id": 3, "purchase_order_item_id": 73, "date_format": null, "budget_id": null } ], "sequence_no": 1, "chart_of_account": { "id": null, "name": null }, "qbo_customer": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null }, "qbo_line_description": null }, { "id": 75, "description": "27-inch 4K monitor", "purchase_order_id": 52, "budget_id": 1, "budget_summary": "Engineering Hardware FY26 : ENG-HW : Capex", "gross_amount": 359.276613, "vat": 8.875, "tax_rate": { "id": 4, "archived": false, "company_id": 20000, "created_at": "2026-10-21T04:48:43.422-05:00", "name": "Sales Tax", "tax_type": "single", "updated_at": "2026-10-21T04:48:43.422-05:00", "value": 8.875 }, "net_amount": 329.99, "status": "pending", "quantity": 1.0, "unit_price": 329.99, "item_number": "MON-27", "base_net_amount": 329.99, "base_gross_amount": 359.28, "gross_usd_amount": 359.276613, "product_id": 2, "received_quantity": 0.0, "custom_field_values": [ { "id": 183, "purchase_order_id": null, "value": null, "custom_field_id": 3, "purchase_order_item_id": 75, "date_format": null, "budget_id": null } ], "sequence_no": 2, "chart_of_account": { "id": null, "name": null }, "qbo_customer": { "id": null, "name": null }, "quickbooks_class": { "id": null, "name": null }, "qbo_line_description": null } ], "purchase_order_comments": [ ], "custom_field_values": [ { "id": 177, "purchase_order_id": 52, "value": "PRJ-2026-031", "custom_field_id": 1, "purchase_order_item_id": null, "date_format": null, "budget_id": null }, { "id": 178, "purchase_order_id": 52, "value": "CC-100 Engineering", "custom_field_id": 2, "purchase_order_item_id": null, "date_format": null, "budget_id": null } ], "payments": [ ], "purchase_order_item_payments": [ ], "uploads": [ ], "invoices": [ ], "compliance_checks": [ ], "approver_requests": [ { "id": 53, "status": "pending", "approver_name": "Priya Patel", "approver_id": 50000, "delegate_id": null } ], "supplier": { "id": 2, "name": "Contoso Hardware", "company_id": 20000, "notes": null, "phone_number": "+1 555 0300", "address": "500 Tech Park, Austin, TX 78701", "email": "sales@contoso.example.com", "payment_details": null, "archived": false, "contact_person": "Diego Ramos", "tax_number": "74-7654321", "payment_terms": "Net 45", "created_at": "2026-10-21T04:48:43.563-05:00", "updated_at": "2026-10-21T04:48:43.563-05:00", "currency_id": 2000, "department_ids": [ ], "external_vendor_id": null, "uei": null, "cage_code": null, "third_party_id_mappings": [ ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Approvers Please select at least one or more approvers", "Purchase order items budget Please select a budget" ], "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "commit": { "type": "string", "description": "`Send` submits a draft for approval. Ignored for non-drafts other than re-running approver assignment." }, "purchase_order[...]": { "type": "object", "description": "Any create parameter except `iso_code` and `on_behalf_of` (see Create for the full list)." }, "purchase_order[purchase_order_items_attributes][][id]": { "type": "integer", "description": "Existing line to change." }, "purchase_order[purchase_order_items_attributes][][_destroy]": { "type": "boolean", "description": "`true` deletes that line." }, "purchase_order[custom_field_values_attributes][][id]": { "type": "integer", "description": "Existing custom field value to change." }, "purchase_order[approver_list][]": { "type": "array", "items": { "type": "integer" }, "description": "Approvers to (re)assign; required in manual-routing companies when sending or editing a pending PO." } }, "required": [ "purchase_order[...]" ] }, "example": { "commit": "Send", "purchase_order": { "notes": "Docking stations and a monitor for the design team, submitted for approval", "approver_list": [ 50000 ], "purchase_order_items_attributes": [ { "id": 73, "quantity": 3, "custom_field_values_attributes": [ { "id": 179, "custom_field_id": 3, "value": "AT-0502" } ] }, { "product_id": 2, "item_number": "MON-27", "description": "27-inch 4K monitor", "quantity": 1, "unit_price": 329.99, "budget_id": 1, "tax_rate_id": 4, "vat": 8.875 } ], "custom_field_values_attributes": [ { "id": 177, "custom_field_id": 1, "value": "PRJ-2026-031" } ] } } } } } } }, "/api/v3/purchase_orders/new": { "get": { "tags": [ "Purchase Orders" ], "operationId": "v3_po_new", "summary": "New purchase order template", "description": "Returns an unsaved purchase order pre-filled with the caller's defaults, to build a create request.\n\nBuilds (but does not save) a draft purchase order for the caller: creator, company, currency (the\ncaller's preferred currency, else the company currency), one empty line item with the company's\ndefault tax rate (`vat`), and a placeholder `custom_field_values_attributes` entry for every active\nPO-level custom field plus one per active line-item custom field on the line. The key names match\nthe create payload (`purchase_order_items_attributes`, `custom_field_values_attributes`), so a client\ncan fill the template in and post it to [Create](#create-a-purchase-order).\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "creator_id": { "type": "integer" }, "amount": { "type": "integer" }, "status": { "type": "string" }, "supplier_name": { "type": "null" }, "notes": { "type": "null" }, "company_id": { "type": "integer" }, "delivered_on": { "type": "null" }, "currency_id": { "type": "integer" }, "department_id": { "type": "null" }, "supplier_id": { "type": "null" }, "self_approved": { "type": "boolean" }, "delivery_status": { "type": "string" }, "custom_field_values_attributes": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "null" }, "custom_field_id": { "type": "integer" }, "budget_id": { "type": "null" } } } }, "purchase_order_items_attributes": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "null" }, "budget_id": { "type": "null" }, "gross_amount": { "type": "null" }, "vat": { "type": "string" }, "net_amount": { "type": "string" }, "status": { "type": "string" }, "quantity": { "type": "string" }, "unit_price": { "type": "null" }, "item_number": { "type": "null" }, "base_net_amount": { "type": "null" }, "base_gross_amount": { "type": "null" }, "gross_usd_amount": { "type": "null" }, "product_id": { "type": "null" }, "received_quantity": { "type": "null" }, "custom_field_values_attributes": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "null" }, "custom_field_id": { "type": "integer" }, "budget_id": { "type": "null" } } } } } } } } }, "example": { "creator_id": 40000, "amount": 0, "status": "draft", "supplier_name": null, "notes": null, "company_id": 20000, "delivered_on": null, "currency_id": 2000, "department_id": null, "supplier_id": null, "self_approved": false, "delivery_status": "not_delivered", "custom_field_values_attributes": [ { "value": null, "custom_field_id": 1, "budget_id": null }, { "value": null, "custom_field_id": 2, "budget_id": null } ], "purchase_order_items_attributes": [ { "description": null, "budget_id": null, "gross_amount": null, "vat": "0.0", "net_amount": "0.0", "status": "pending", "quantity": "1.0", "unit_price": null, "item_number": null, "base_net_amount": null, "base_gross_amount": null, "gross_usd_amount": null, "product_id": null, "received_quantity": null, "custom_field_values_attributes": [ { "value": null, "custom_field_id": 3, "budget_id": null } ] } ] } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/purchase_orders/new": { "get": { "tags": [ "Purchase Orders" ], "operationId": "v1_po_new", "summary": "New purchase order template", "description": "Returns an unsaved purchase order pre-filled with the caller's defaults, to build a create request.\n\nBuilds (but does not save) a draft purchase order for the caller: creator, company, currency (the\ncaller's preferred currency, else the company currency), one empty line item with the company's\ndefault tax rate (`vat`), and a placeholder `custom_field_values_attributes` entry for every active\nPO-level custom field plus one per active line-item custom field on the line. The key names match\nthe create payload (`purchase_order_items_attributes`, `custom_field_values_attributes`), so a client\ncan fill the template in and post it to [Create](#create-a-purchase-order).\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "creator_id": { "type": "integer" }, "amount": { "type": "integer" }, "status": { "type": "string" }, "supplier_name": { "type": "null" }, "notes": { "type": "null" }, "company_id": { "type": "integer" }, "delivered_on": { "type": "null" }, "currency_id": { "type": "integer" }, "department_id": { "type": "null" }, "supplier_id": { "type": "null" }, "self_approved": { "type": "boolean" }, "delivery_status": { "type": "string" }, "custom_field_values_attributes": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "null" }, "custom_field_id": { "type": "integer" }, "budget_id": { "type": "null" } } } }, "purchase_order_items_attributes": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "null" }, "budget_id": { "type": "null" }, "gross_amount": { "type": "null" }, "vat": { "type": "string" }, "net_amount": { "type": "string" }, "status": { "type": "string" }, "quantity": { "type": "string" }, "unit_price": { "type": "null" }, "item_number": { "type": "null" }, "base_net_amount": { "type": "null" }, "base_gross_amount": { "type": "null" }, "gross_usd_amount": { "type": "null" }, "product_id": { "type": "null" }, "received_quantity": { "type": "null" }, "custom_field_values_attributes": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "null" }, "custom_field_id": { "type": "integer" }, "budget_id": { "type": "null" } } } } } } } } }, "example": { "creator_id": 40000, "amount": 0, "status": "draft", "supplier_name": null, "notes": null, "company_id": 20000, "delivered_on": null, "currency_id": 2000, "department_id": null, "supplier_id": null, "self_approved": false, "delivery_status": "not_delivered", "custom_field_values_attributes": [ { "value": null, "custom_field_id": 1, "budget_id": null }, { "value": null, "custom_field_id": 2, "budget_id": null } ], "purchase_order_items_attributes": [ { "description": null, "budget_id": null, "gross_amount": null, "vat": "0.0", "net_amount": "0.0", "status": "pending", "quantity": "1.0", "unit_price": null, "item_number": null, "base_net_amount": null, "base_gross_amount": null, "gross_usd_amount": null, "product_id": null, "received_quantity": null, "custom_field_values_attributes": [ { "value": null, "custom_field_id": 3, "budget_id": null } ] } ] } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/purchase_orders/bulk_save": { "post": { "tags": [ "Purchase Orders" ], "operationId": "v3_po_bulk_save", "summary": "Create purchase orders in bulk", "description": "Creates several purchase orders in one request and reports per-row success or failure.\n\nEach element of `purchase_order[data][]` is a create payload (the same attributes as\n`purchase_order[...]` in [Create](#create-a-purchase-order), without the `purchase_order` wrapper)\nplus two bulk-only keys: `_id`, a client reference echoed back, and `commit` (`send`, any case,\nsubmits that row; anything else saves a draft). Rows are processed independently and in order; a\nfailing row does not stop the others and nothing is rolled back.\n\nDifferences from single create: the PO `source` is the `app_source` header when it is a valid source,\nelse `api`; required custom fields are not enforced on sent rows; missing custom field values are not\nback-filled; `on_behalf_of` is accepted but has no effect; archived suppliers, products, custom\nfields, budgets, tax rates and departments are rejected (mobile sync checks).\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "done": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "id": { "type": "integer" } } } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "errors": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "string" } } } } } } } } }, "example": { "done": [ { "_id": "erp-req-1001", "id": 69 }, { "_id": "erp-req-1002", "id": 70 } ], "failed": [ { "_id": "erp-req-1003", "errors": { "items": [ ": please add at least one item" ] } } ] } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase_order[data][]": { "type": "array", "items": { "type": "object" }, "description": "Rows to create." }, "purchase_order[data][][_id]": { "type": "string", "description": "Client reference echoed in `done[]._id` / `failed[]._id`." }, "purchase_order[data][][commit]": { "type": "string", "description": "`send` (case-insensitive) submits the row; otherwise draft." }, "purchase_order[data][][...]": { "type": "object", "description": "Any create attribute: `supplier_id`, `supplier_name`, `new_supplier_name`, `department_id`, `currency_id`, `notes`, `submitted_on`, `approver_list`, `purchase_order_items_attributes`, `custom_field_values_attributes`, `third_party_id_mappings_attributes`, `purchase_order_comments_attributes`, `uploads_attributes`, `requests_attributes`, `allocations_attributes`." } }, "required": [ "purchase_order[data][]" ] }, "example": { "purchase_order": { "data": [ { "_id": "erp-req-1001", "commit": "Send", "supplier_id": 2, "department_id": 2, "currency_id": 2000, "notes": "Docking stations for the support desk", "approver_list": [ 50000 ], "purchase_order_items_attributes": [ { "product_id": 3, "item_number": "DOCK-USB-C", "description": "USB-C docking station", "quantity": 2, "unit_price": 189.5, "budget_id": 1, "tax_rate_id": 4 } ], "custom_field_values_attributes": [ { "custom_field_id": 1, "value": "PRJ-2026-051" } ] }, { "_id": "erp-req-1002", "commit": "Draft", "supplier_id": 1, "department_id": 3, "currency_id": 2000, "notes": "Whiteboard markers, waiting on a quote", "purchase_order_items_attributes": [ { "description": "Whiteboard markers, pack of 12", "quantity": 4, "unit_price": 14.25, "budget_id": 2, "tax_rate_id": 4 } ] }, { "_id": "erp-req-1003", "commit": "Send", "supplier_id": 1, "department_id": 3, "currency_id": 2000, "notes": "Row with no line items", "approver_list": [ 50000 ] } ] } } } } } } }, "/api/v1/purchase_orders/bulk_save": { "post": { "tags": [ "Purchase Orders" ], "operationId": "v1_po_bulk_save", "summary": "Create purchase orders in bulk", "description": "Creates several purchase orders in one request and reports per-row success or failure.\n\nEach element of `purchase_order[data][]` is a create payload (the same attributes as\n`purchase_order[...]` in [Create](#create-a-purchase-order), without the `purchase_order` wrapper)\nplus two bulk-only keys: `_id`, a client reference echoed back, and `commit` (`send`, any case,\nsubmits that row; anything else saves a draft). Rows are processed independently and in order; a\nfailing row does not stop the others and nothing is rolled back.\n\nDifferences from single create: the PO `source` is the `app_source` header when it is a valid source,\nelse `api`; required custom fields are not enforced on sent rows; missing custom field values are not\nback-filled; `on_behalf_of` is accepted but has no effect; archived suppliers, products, custom\nfields, budgets, tax rates and departments are rejected (mobile sync checks).\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "done": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "id": { "type": "integer" } } } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "errors": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "string" } } } } } } } } }, "example": { "done": [ { "_id": "erp-req-1001", "id": 67 }, { "_id": "erp-req-1002", "id": 68 } ], "failed": [ { "_id": "erp-req-1003", "errors": { "items": [ ": please add at least one item" ] } } ] } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase_order[data][]": { "type": "array", "items": { "type": "object" }, "description": "Rows to create." }, "purchase_order[data][][_id]": { "type": "string", "description": "Client reference echoed in `done[]._id` / `failed[]._id`." }, "purchase_order[data][][commit]": { "type": "string", "description": "`send` (case-insensitive) submits the row; otherwise draft." }, "purchase_order[data][][...]": { "type": "object", "description": "Any create attribute: `supplier_id`, `supplier_name`, `new_supplier_name`, `department_id`, `currency_id`, `notes`, `submitted_on`, `approver_list`, `purchase_order_items_attributes`, `custom_field_values_attributes`, `third_party_id_mappings_attributes`, `purchase_order_comments_attributes`, `uploads_attributes`, `requests_attributes`, `allocations_attributes`." } }, "required": [ "purchase_order[data][]" ] }, "example": { "purchase_order": { "data": [ { "_id": "erp-req-1001", "commit": "Send", "supplier_id": 2, "department_id": 2, "currency_id": 2000, "notes": "Docking stations for the support desk", "approver_list": [ 50000 ], "purchase_order_items_attributes": [ { "product_id": 3, "item_number": "DOCK-USB-C", "description": "USB-C docking station", "quantity": 2, "unit_price": 189.5, "budget_id": 1, "tax_rate_id": 4 } ], "custom_field_values_attributes": [ { "custom_field_id": 1, "value": "PRJ-2026-051" } ] }, { "_id": "erp-req-1002", "commit": "Draft", "supplier_id": 1, "department_id": 3, "currency_id": 2000, "notes": "Whiteboard markers, waiting on a quote", "purchase_order_items_attributes": [ { "description": "Whiteboard markers, pack of 12", "quantity": 4, "unit_price": 14.25, "budget_id": 2, "tax_rate_id": 4 } ] }, { "_id": "erp-req-1003", "commit": "Send", "supplier_id": 1, "department_id": 3, "currency_id": 2000, "notes": "Row with no line items", "approver_list": [ 50000 ] } ] } } } } } } }, "/api/v3/purchase_orders/{id}/approve": { "post": { "tags": [ "Purchase Orders" ], "operationId": "v3_po_approve", "summary": "Approve a purchase order", "description": "Records the caller's approval of a pending purchase order using their accept token.\n\nApproves the caller's approval request on this PO. Send the request's `accept_token` (from\n`approver_requests[]`, visible only to that approver or their delegate) as `token` in the body.\nWhen this was the last outstanding approval the PO becomes `approved` and gets its PO number;\notherwise the next approver in the chain is activated and notified. An \"Approved by \n()\" history comment is added.\n\nChecks, in order:\n1. The token must be the accept token of a request **on this PO** whose approver or delegate is\n the caller; otherwise `400 \"Token you provided is not valid\"`. When the request is delegated,\n only the delegate may use it.\n2. Request already approved: `400 \"You had already approved this purchase order\"`.\n3. PO cancelled: `400 \"Purchase order was already cancelled\"`.\n4. PO rejected: `400 \"Purchase order was already rejected\"`.\n\nThe `app_source` header names the channel recorded in the history (`api` by default). Allowed:\n`api`, `website`, `web`, `push_cart`, `zapier`, `sage50`, `sage200`, `mobile_ios`,\n`mobile_android`, `mobile_other`, `mobile_android_offline`, `mobile_ios_offline`. `email` and\nunknown values are refused with `400 \"Unauthorized access\"`.\n\nSend the token in the request body of a POST or PUT, never in the URL. V1 still accepts GET with\n`?token=` as a **deprecated** path for an older mobile app: the response carries a\n`Deprecation: true` header and the path is switched off when the server sets\n`API_V1_GET_DECISIONS=off` (then `405` with `Allow: POST, PUT`). HEAD is always refused with `405`.\nV3 does not route GET at all (`404 \"Invalid URL\"`).\n\n\nSame request and response for POST and PUT. V1 also accepts GET (deprecated, `Deprecation: true`\nresponse header, retired by `API_V1_GET_DECISIONS=off`); V3 answers GET with `404 Invalid URL`.\nHEAD on V1 returns `405` with `Allow: POST, PUT`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id, PO number (URL-encoded) or slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } } }, "example": { "status": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "Token you provided is not valid", "status": 400 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid URL", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The `accept_token` of the caller's request on this PO." } }, "required": [ "token" ] }, "example": { "token": "" } } } } } }, "/api/v1/purchase_orders/{id}/approve": { "post": { "tags": [ "Purchase Orders" ], "operationId": "v1_po_approve", "summary": "Approve a purchase order", "description": "Records the caller's approval of a pending purchase order using their accept token.\n\nApproves the caller's approval request on this PO. Send the request's `accept_token` (from\n`approver_requests[]`, visible only to that approver or their delegate) as `token` in the body.\nWhen this was the last outstanding approval the PO becomes `approved` and gets its PO number;\notherwise the next approver in the chain is activated and notified. An \"Approved by \n()\" history comment is added.\n\nChecks, in order:\n1. The token must be the accept token of a request **on this PO** whose approver or delegate is\n the caller; otherwise `400 \"Token you provided is not valid\"`. When the request is delegated,\n only the delegate may use it.\n2. Request already approved: `400 \"You had already approved this purchase order\"`.\n3. PO cancelled: `400 \"Purchase order was already cancelled\"`.\n4. PO rejected: `400 \"Purchase order was already rejected\"`.\n\nThe `app_source` header names the channel recorded in the history (`api` by default). Allowed:\n`api`, `website`, `web`, `push_cart`, `zapier`, `sage50`, `sage200`, `mobile_ios`,\n`mobile_android`, `mobile_other`, `mobile_android_offline`, `mobile_ios_offline`. `email` and\nunknown values are refused with `400 \"Unauthorized access\"`.\n\nSend the token in the request body of a POST or PUT, never in the URL. V1 still accepts GET with\n`?token=` as a **deprecated** path for an older mobile app: the response carries a\n`Deprecation: true` header and the path is switched off when the server sets\n`API_V1_GET_DECISIONS=off` (then `405` with `Allow: POST, PUT`). HEAD is always refused with `405`.\nV3 does not route GET at all (`404 \"Invalid URL\"`).\n\n\nSame request and response for POST and PUT. V1 also accepts GET (deprecated, `Deprecation: true`\nresponse header, retired by `API_V1_GET_DECISIONS=off`); V3 answers GET with `404 Invalid URL`.\nHEAD on V1 returns `405` with `Allow: POST, PUT`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id, PO number (URL-encoded) or slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } } }, "example": { "status": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "Token you provided is not valid", "status": 400 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The `accept_token` of the caller's request on this PO." } }, "required": [ "token" ] }, "example": { "token": "" } } } } } }, "/api/v3/purchase_orders/{id}/reject": { "post": { "tags": [ "Purchase Orders" ], "operationId": "v3_po_reject", "summary": "Reject a purchase order", "description": "Rejects a purchase order on behalf of the caller using their reject token.\n\nRejects the caller's approval request on this PO with the request's `reject_token`. One rejection\nrejects the whole PO (`status: \"rejected\"`). A rejected PO cannot be resubmitted: raise a new one.\n\nThe API takes **no rejection reason**: only `token` is read, any other body field is ignored, and\nthe history comment is \"Purchase order rejected ().\" Add an explanation afterwards with the\nPO comments endpoint.\n\nChecks: token must be this PO's reject token for the caller (or their delegate) -\n`400 \"Token you provided is not valid\"`; request already rejected - `400 \"You had already rejected\nthis purchase order\"`; PO cancelled - `400 \"Purchase order was already cancelled\"`; PO already\nrejected by someone else - `400 \"Purchase order was already rejected\"`. The `app_source` header rules\nand the GET/HEAD rules are the same as for [Approve](#approve-a-purchase-order).\n\n\nSame for POST and PUT. V1 also accepts deprecated GET (`Deprecation: true` header); V3 answers GET\nwith `404 Invalid URL`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id, PO number (URL-encoded) or slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } } }, "example": { "status": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "Token you provided is not valid", "status": 400 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The `reject_token` of the caller's request on this PO." } }, "required": [ "token" ] }, "example": { "token": "" } } } } } }, "/api/v1/purchase_orders/{id}/reject": { "post": { "tags": [ "Purchase Orders" ], "operationId": "v1_po_reject", "summary": "Reject a purchase order", "description": "Rejects a purchase order on behalf of the caller using their reject token.\n\nRejects the caller's approval request on this PO with the request's `reject_token`. One rejection\nrejects the whole PO (`status: \"rejected\"`). A rejected PO cannot be resubmitted: raise a new one.\n\nThe API takes **no rejection reason**: only `token` is read, any other body field is ignored, and\nthe history comment is \"Purchase order rejected ().\" Add an explanation afterwards with the\nPO comments endpoint.\n\nChecks: token must be this PO's reject token for the caller (or their delegate) -\n`400 \"Token you provided is not valid\"`; request already rejected - `400 \"You had already rejected\nthis purchase order\"`; PO cancelled - `400 \"Purchase order was already cancelled\"`; PO already\nrejected by someone else - `400 \"Purchase order was already rejected\"`. The `app_source` header rules\nand the GET/HEAD rules are the same as for [Approve](#approve-a-purchase-order).\n\n\nSame for POST and PUT. V1 also accepts deprecated GET (`Deprecation: true` header); V3 answers GET\nwith `404 Invalid URL`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id, PO number (URL-encoded) or slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } } }, "example": { "status": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "Token you provided is not valid", "status": 400 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The `reject_token` of the caller's request on this PO." } }, "required": [ "token" ] }, "example": { "token": "" } } } } } }, "/api/v3/purchase_orders/{id}/override_and_approve": { "post": { "tags": [ "Purchase Orders" ], "operationId": "v3_po_override_and_approve", "summary": "Override and approve a purchase order", "description": "Lets a finance user approve a purchase order immediately, skipping the remaining approvers.\n\nApproval override: the PO becomes `approved` at once without any approver token. The caller is added\nas an approved request flagged `approval_override`, every other pending request is cancelled, attached\napproval flows are marked completed, and the history reads \"Purchase Order Approved using Approval\nOverride ...\". No body is needed.\n\nThe only refusal besides permissions is a budget overrun: when the PO would overrun a budget (and the\ncompany does not allow overruns) the override is refused with `400 \"We could not approve this purchase\norder. Please contactsupport@procurementexpress.com.\"` and a history comment explains why.\n\nUse it on `pending` POs only (the `can_override` flag in the PO detail is `true` only for pending POs).\nThe endpoint itself does not check the status (see findings).\n\n\nSame for POST and PUT. V1 also accepts deprecated GET (`Deprecation: true`); V3 answers GET with `404`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id, PO number (URL-encoded) or slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } } }, "example": { "status": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/purchase_orders/{id}/override_and_approve": { "post": { "tags": [ "Purchase Orders" ], "operationId": "v1_po_override_and_approve", "summary": "Override and approve a purchase order", "description": "Lets a finance user approve a purchase order immediately, skipping the remaining approvers.\n\nApproval override: the PO becomes `approved` at once without any approver token. The caller is added\nas an approved request flagged `approval_override`, every other pending request is cancelled, attached\napproval flows are marked completed, and the history reads \"Purchase Order Approved using Approval\nOverride ...\". No body is needed.\n\nThe only refusal besides permissions is a budget overrun: when the PO would overrun a budget (and the\ncompany does not allow overruns) the override is refused with `400 \"We could not approve this purchase\norder. Please contactsupport@procurementexpress.com.\"` and a history comment explains why.\n\nUse it on `pending` POs only (the `can_override` flag in the PO detail is `true` only for pending POs).\nThe endpoint itself does not check the status (see findings).\n\n\nSame for POST and PUT. V1 also accepts deprecated GET (`Deprecation: true`); V3 answers GET with `404`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id, PO number (URL-encoded) or slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } } }, "example": { "status": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/purchase_orders/{id}/cancel": { "post": { "tags": [ "Purchase Orders" ], "operationId": "v3_po_cancel", "summary": "Cancel a purchase order", "description": "Cancels a purchase order and its open approval requests.\n\nSets `status` to `cancelled` (skipping budget and approver validation), cancels the approval requests\nand in-progress approval flows, releases the PO's amount from its budgets, marks its line-item payment\nallocations deleted, and adds a \" cancelled the purchase order on \" history comment.\n\nAllowed from any status except `paid`, and not when an invoice linked to the PO is already settled.\nThe call is not idempotent-safe: cancelling an already-cancelled PO answers `200` again and adds\nanother history comment. Check `can_cancel` in the PO detail first.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id, PO number (URL-encoded) or slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } } }, "example": { "status": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/purchase_orders/{id}/cancel": { "post": { "tags": [ "Purchase Orders" ], "operationId": "v1_po_cancel", "summary": "Cancel a purchase order", "description": "Cancels a purchase order and its open approval requests.\n\nSets `status` to `cancelled` (skipping budget and approver validation), cancels the approval requests\nand in-progress approval flows, releases the PO's amount from its budgets, marks its line-item payment\nallocations deleted, and adds a \" cancelled the purchase order on \" history comment.\n\nAllowed from any status except `paid`, and not when an invoice linked to the PO is already settled.\nThe call is not idempotent-safe: cancelling an already-cancelled PO answers `200` again and adds\nanother history comment. Check `can_cancel` in the PO detail first.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id, PO number (URL-encoded) or slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } } }, "example": { "status": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/purchase_orders/{id}/archive": { "post": { "tags": [ "Purchase Orders" ], "operationId": "v3_po_archive", "summary": "Archive a purchase order", "description": "Toggles the archived flag of a purchase order.\n\n**Toggles** `archived`: an active PO is archived, an archived PO is restored. The response tells you\nthe new value. Archived POs disappear from the default list (use `archived=true` to list them) but\nkeep their status; archiving also marks in-progress approval flows as cancelled. A history comment\n(\"archived by\" / \"de-archived by\") is added. Archiving does not push changes to QuickBooks.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id, PO number (URL-encoded) or slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "archived": { "type": "boolean" } } }, "example": { "archived": true } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 403 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/purchase_orders/{id}/archive": { "post": { "tags": [ "Purchase Orders" ], "operationId": "v1_po_archive", "summary": "Archive a purchase order", "description": "Toggles the archived flag of a purchase order.\n\n**Toggles** `archived`: an active PO is archived, an archived PO is restored. The response tells you\nthe new value. Archived POs disappear from the default list (use `archived=true` to list them) but\nkeep their status; archiving also marks in-progress approval flows as cancelled. A history comment\n(\"archived by\" / \"de-archived by\") is added. Archiving does not push changes to QuickBooks.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id, PO number (URL-encoded) or slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "archived": { "type": "boolean" } } }, "example": { "archived": true } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 403 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/purchase_orders/{id}/delete": { "delete": { "tags": [ "Purchase Orders" ], "operationId": "v3_po_delete", "summary": "Delete a draft purchase order", "description": "Soft-deletes a draft purchase order.\n\nDeletes a **draft**. The record is soft-deleted together with its line items, comments, uploads,\ncustom field values, allocations, payments and requests, and budget totals are recalculated. It no\nlonger appears anywhere and its id answers `404`. Submitted POs cannot be deleted - cancel them instead.\n\nNote the path: `DELETE /purchase_orders/:id/delete` (there is no `DELETE /purchase_orders/:id`).\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id or slug of the draft.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } } }, "example": { "status": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/purchase_orders/{id}/delete": { "delete": { "tags": [ "Purchase Orders" ], "operationId": "v1_po_delete", "summary": "Delete a draft purchase order", "description": "Soft-deletes a draft purchase order.\n\nDeletes a **draft**. The record is soft-deleted together with its line items, comments, uploads,\ncustom field values, allocations, payments and requests, and budget totals are recalculated. It no\nlonger appears anywhere and its id answers `404`. Submitted POs cannot be deleted - cancel them instead.\n\nNote the path: `DELETE /purchase_orders/:id/delete` (there is no `DELETE /purchase_orders/:id`).\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Numeric id or slug of the draft.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } } }, "example": { "status": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/purchase_orders/pending_request_count": { "get": { "tags": [ "Purchase Orders" ], "operationId": "v3_po_pending_request_count", "summary": "Count my pending approvals", "description": "Returns how many purchase orders are waiting for the caller's approval in this company.\n\nCounts the caller's approval requests (as approver, or as the delegate covering for an approver)\nthat are pending, currently active, on non-archived `pending` POs of the company in\n`app_company_id`. It normally equals `meta.total_count` of `GET /purchase_orders?requests=true&bell=true`.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_pending_request": { "type": "integer" } } }, "example": { "total_pending_request": 16 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/purchase_orders/pending_request_count": { "get": { "tags": [ "Purchase Orders" ], "operationId": "v1_po_pending_request_count", "summary": "Count my pending approvals", "description": "Returns how many purchase orders are waiting for the caller's approval in this company.\n\nCounts the caller's approval requests (as approver, or as the delegate covering for an approver)\nthat are pending, currently active, on non-archived `pending` POs of the company in\n`app_company_id`. It normally equals `meta.total_count` of `GET /purchase_orders?requests=true&bell=true`.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_pending_request": { "type": "integer" } } }, "example": { "total_pending_request": 16 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/purchase_orders/auto_approvers_list": { "get": { "tags": [ "Purchase Orders" ], "operationId": "v3_po_auto_approvers_list", "summary": "Preview budget approvers", "description": "Returns the budget approvers a purchase order with the given budgets and amount would be routed to.\n\nRuns the budget-approver routing (see *How approval routing works*, step 2) for a hypothetical PO\nraised by the caller with the given budgets and amount, and returns the approvers in routing order.\nIt does not consider approval flows or `approver_list`; use\n[Preview approval-flow approvers](#preview-approval-flow-approvers) for flows.\n\n`gross_total` is compared with approval limits as is, so pass the amount in the company base currency\n(gross or net per the company's gross/net setting). Unknown or other-company budget ids are ignored;\nno budgets returns `[]`. The requester is excluded from their own chain unless they are the only or\nlast approver (the example above the limit, as Sam, returns Jane because only her limit covers 75,000).\n\n\nNone - identical request and response.", "parameters": [ { "name": "budget_ids[]", "in": "query", "required": false, "description": "Budgets of the PO's lines.", "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "gross_total", "in": "query", "required": false, "description": "PO amount in the company base currency.", "schema": { "type": "number" } }, { "name": "show_last_approver_on_edit", "in": "query", "required": false, "description": "`true` returns only the last approver of the chain.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "approver_name": { "type": "string" } } } }, "example": [ { "id": 50000, "first_name": "Priya", "last_name": "Patel", "name": "Priya Patel", "email": "priya.patel@example.com", "approver_name": "Priya Patel" } ] } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/purchase_orders/auto_approvers_list": { "get": { "tags": [ "Purchase Orders" ], "operationId": "v1_po_auto_approvers_list", "summary": "Preview budget approvers", "description": "Returns the budget approvers a purchase order with the given budgets and amount would be routed to.\n\nRuns the budget-approver routing (see *How approval routing works*, step 2) for a hypothetical PO\nraised by the caller with the given budgets and amount, and returns the approvers in routing order.\nIt does not consider approval flows or `approver_list`; use\n[Preview approval-flow approvers](#preview-approval-flow-approvers) for flows.\n\n`gross_total` is compared with approval limits as is, so pass the amount in the company base currency\n(gross or net per the company's gross/net setting). Unknown or other-company budget ids are ignored;\nno budgets returns `[]`. The requester is excluded from their own chain unless they are the only or\nlast approver (the example above the limit, as Sam, returns Jane because only her limit covers 75,000).\n\n\nNone - identical request and response.", "parameters": [ { "name": "budget_ids[]", "in": "query", "required": false, "description": "Budgets of the PO's lines.", "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "gross_total", "in": "query", "required": false, "description": "PO amount in the company base currency.", "schema": { "type": "number" } }, { "name": "show_last_approver_on_edit", "in": "query", "required": false, "description": "`true` returns only the last approver of the chain.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "approver_name": { "type": "string" } } } }, "example": [ { "id": 50000, "first_name": "Priya", "last_name": "Patel", "name": "Priya Patel", "email": "priya.patel@example.com", "approver_name": "Priya Patel" } ] } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/purchase_orders/approver_list": { "post": { "tags": [ "Purchase Orders" ], "operationId": "v3_po_approver_list", "summary": "Preview approval-flow approvers", "description": "Returns, grouped by approval flow, the approvers the approval flows would assign to a purchase order.\n\nBuilds an unsaved PO from `purchase_order[...]` (same attributes as create), computes its totals and\nbase-currency amounts, and evaluates the company's **published** purchase-order approval flows against\nit (department, budget, supplier, requester, amounts, custom fields). Returns the approvers of the\nmatching flows' applicable steps, grouped by flow, in step order. The caller (as requester) is left out\nunless a matching flow allows self-approval. When no published flow matches, the answer is `[]` - which\nis also the answer in companies without approval flows; use\n[Preview budget approvers](#preview-budget-approvers) there.\n\n`test_mode` with `approval_flow_id` additionally evaluates that one unpublished flow, so you can try a\nflow before publishing it (the primary example previews the unpublished \"Lab PO routing\" flow; without\ntest mode the same PO matches nothing).\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "approval_flow_name": { "type": "string" }, "approval_flow_id": { "type": "integer" }, "approvers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "id": { "type": "integer" } } } } } } }, "example": [ { "approval_flow_name": "Lab PO routing v1 - updated", "approval_flow_id": 1, "approvers": [ { "name": "Priya Patel", "email": "priya.patel@example.com", "id": 50000 } ] } ] } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "Required parameter are missing.", "status": 400 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase_order": { "type": "object", "description": "PO attributes as in Create (`supplier_id`, `department_id`, `currency_id`, `purchase_order_items_attributes`, `custom_field_values_attributes`, ...). Missing: `400 Required parameter are missing.`" }, "purchase_order[purchase_order_id]": { "type": "integer", "description": "Id of the PO being edited, if any." }, "purchase_order[total_gross_amount]": { "type": "number", "description": "Gross total to use when the lines give zero." }, "purchase_order[total_net_amount]": { "type": "number", "description": "Net total to use when the lines give zero." }, "test_mode": { "type": "boolean", "description": "Top-level. Together with `approval_flow_id`, also evaluate that unpublished flow." }, "approval_flow_id": { "type": "integer", "description": "Top-level. Flow to include in test mode." } }, "required": [ "purchase_order" ] }, "example": { "test_mode": true, "approval_flow_id": 1, "purchase_order": { "supplier_id": 2, "department_id": 5, "currency_id": 2000, "purchase_order_items_attributes": [ { "product_id": 3, "description": "USB-C docking station", "quantity": 2, "unit_price": 189.5, "budget_id": 4, "tax_rate_id": 4, "vat": 8.875 } ] } } } } } } }, "/api/v1/purchase_orders/approver_list": { "post": { "tags": [ "Purchase Orders" ], "operationId": "v1_po_approver_list", "summary": "Preview approval-flow approvers", "description": "Returns, grouped by approval flow, the approvers the approval flows would assign to a purchase order.\n\nBuilds an unsaved PO from `purchase_order[...]` (same attributes as create), computes its totals and\nbase-currency amounts, and evaluates the company's **published** purchase-order approval flows against\nit (department, budget, supplier, requester, amounts, custom fields). Returns the approvers of the\nmatching flows' applicable steps, grouped by flow, in step order. The caller (as requester) is left out\nunless a matching flow allows self-approval. When no published flow matches, the answer is `[]` - which\nis also the answer in companies without approval flows; use\n[Preview budget approvers](#preview-budget-approvers) there.\n\n`test_mode` with `approval_flow_id` additionally evaluates that one unpublished flow, so you can try a\nflow before publishing it (the primary example previews the unpublished \"Lab PO routing\" flow; without\ntest mode the same PO matches nothing).\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "approval_flow_name": { "type": "string" }, "approval_flow_id": { "type": "integer" }, "approvers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "id": { "type": "integer" } } } } } } }, "example": [ { "approval_flow_name": "Lab PO routing v1 - updated", "approval_flow_id": 1, "approvers": [ { "name": "Priya Patel", "email": "priya.patel@example.com", "id": 50000 } ] } ] } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "Required parameter are missing.", "status": 400 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase_order": { "type": "object", "description": "PO attributes as in Create (`supplier_id`, `department_id`, `currency_id`, `purchase_order_items_attributes`, `custom_field_values_attributes`, ...). Missing: `400 Required parameter are missing.`" }, "purchase_order[purchase_order_id]": { "type": "integer", "description": "Id of the PO being edited, if any." }, "purchase_order[total_gross_amount]": { "type": "number", "description": "Gross total to use when the lines give zero." }, "purchase_order[total_net_amount]": { "type": "number", "description": "Net total to use when the lines give zero." }, "test_mode": { "type": "boolean", "description": "Top-level. Together with `approval_flow_id`, also evaluate that unpublished flow." }, "approval_flow_id": { "type": "integer", "description": "Top-level. Flow to include in test mode." } }, "required": [ "purchase_order" ] }, "example": { "test_mode": true, "approval_flow_id": 1, "purchase_order": { "supplier_id": 2, "department_id": 5, "currency_id": 2000, "purchase_order_items_attributes": [ { "product_id": 3, "description": "USB-C docking station", "quantity": 2, "unit_price": 189.5, "budget_id": 4, "tax_rate_id": 4, "vat": 8.875 } ] } } } } } } }, "/api/v3/uploads/po": { "post": { "tags": [ "Purchase Orders: Attachments" ], "operationId": "v3_uploads_po", "summary": "Upload a file to a purchase order", "description": "Attach a file to an existing purchase order (multipart).\n\nStores the file and attaches it to the purchase order `po_id`. The request must be\n`multipart/form-data` with the file as a real binary part in `uploads_attributes[file]`\n(do not send JSON or base64).\n\nChecks run in this order: the upload token (`400 \"No token passed\"` when missing,\n`400 \"Token you provided is not valid\"` when shorter than 7 characters), the purchase order\n(`404` when it does not exist in the company given by `app_company_id`), your permission to\ncollaborate on it (`401`), then the file itself (presence, type, size, PDF content, token\nuniqueness) - file errors come back as `400` with an array of messages.\n\nThe file appears immediately in the PO's `uploads[]`. Nothing is e-mailed.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "file_file_name": { "type": "string" }, "file_content_type": { "type": "string" }, "url": { "type": "string" }, "upload_token": { "type": "string" } } }, "example": { "id": 5, "file_file_name": "delivery-note.pdf", "file_content_type": "application/pdf", "url": "https://pex-files.s3.amazonaws.com/uploads/files/000/000/005/original/delivery-note.pdf?response-content-disposition=attachment%3B%20filename%3D%22delivery-note.pdf%22%3B%20filename%2A%3DUTF-8%27%27delivery-note.pdf&response-content-type=application%2Foctet-stream&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20261021%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20261021T101136Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=16ebd955e754145a341ba058a2390d34bb323a2107fae2eef0dead1a65252209", "upload_token": "" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "No token passed", "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "po_id": { "type": "integer", "description": "Purchase order id (numeric)." }, "uploads_attributes[upload_token]": { "type": "string", "description": "Client-generated de-duplication token, at least 7 characters, unique among your uploads (a UUID is ideal). Reusing one returns `400 \"Upload token already synced\"`." }, "uploads_attributes[file]": { "type": "string", "format": "binary", "description": "The file part. Max 30 MB; see the accepted types above. A part declared `application/pdf` must contain PDF data." } }, "required": [ "po_id", "uploads_attributes[upload_token]", "uploads_attributes[file]" ] } } } } } }, "/api/v1/uploads/po": { "post": { "tags": [ "Purchase Orders: Attachments" ], "operationId": "v1_uploads_po", "summary": "Upload a file to a purchase order", "description": "Attach a file to an existing purchase order (multipart).\n\nStores the file and attaches it to the purchase order `po_id`. The request must be\n`multipart/form-data` with the file as a real binary part in `uploads_attributes[file]`\n(do not send JSON or base64).\n\nChecks run in this order: the upload token (`400 \"No token passed\"` when missing,\n`400 \"Token you provided is not valid\"` when shorter than 7 characters), the purchase order\n(`404` when it does not exist in the company given by `app_company_id`), your permission to\ncollaborate on it (`401`), then the file itself (presence, type, size, PDF content, token\nuniqueness) - file errors come back as `400` with an array of messages.\n\nThe file appears immediately in the PO's `uploads[]`. Nothing is e-mailed.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "file_file_name": { "type": "string" }, "file_content_type": { "type": "string" }, "url": { "type": "string" }, "upload_token": { "type": "string" } } }, "example": { "id": 4, "file_file_name": "delivery-note.pdf", "file_content_type": "application/pdf", "url": "https://pex-files.s3.amazonaws.com/uploads/files/000/000/004/original/delivery-note.pdf?response-content-disposition=attachment%3B%20filename%3D%22delivery-note.pdf%22%3B%20filename%2A%3DUTF-8%27%27delivery-note.pdf&response-content-type=application%2Foctet-stream&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20261021%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20261021T101135Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=979830cdef3d5eeca195f4c4792b8284cd74af35c1c3de7700d325fbb9195e9d", "upload_token": "" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "No token passed", "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "po_id": { "type": "integer", "description": "Purchase order id (numeric)." }, "uploads_attributes[upload_token]": { "type": "string", "description": "Client-generated de-duplication token, at least 7 characters, unique among your uploads (a UUID is ideal). Reusing one returns `400 \"Upload token already synced\"`." }, "uploads_attributes[file]": { "type": "string", "format": "binary", "description": "The file part. Max 30 MB; see the accepted types above. A part declared `application/pdf` must contain PDF data." } }, "required": [ "po_id", "uploads_attributes[upload_token]", "uploads_attributes[file]" ] } } } } } }, "/api/v3/uploads/poc": { "post": { "tags": [ "Purchase Orders: Attachments" ], "operationId": "v3_uploads_poc", "summary": "Upload a file to a PO comment", "description": "Attach a file to an existing purchase order comment (multipart).\n\nAttaches a file to the purchase order comment `poc_id` (the `id` returned by\n[Create a comment](#comment-on-a-purchase-order)). Use it to post \"comment + attachment\": create the\ncomment, then upload one or more files to it. The file is listed under that comment's\n`uploads[]` in the PO details.\n\nSame token checks, file validation and error order as\n[Upload a file to a purchase order](#upload-a-file-to-a-purchase-order). The comment must\nbelong to a purchase order of the `app_company_id` company (`404` otherwise).\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "file_file_name": { "type": "string" }, "file_content_type": { "type": "string" }, "url": { "type": "string" }, "upload_token": { "type": "string" } } }, "example": { "id": 9, "file_file_name": "damaged-box.png", "file_content_type": "image/png", "url": "https://pex-files.s3.amazonaws.com/uploads/files/000/000/009/original/damaged-box.png?response-content-disposition=attachment%3B%20filename%3D%22damaged-box.png%22%3B%20filename%2A%3DUTF-8%27%27damaged-box.png&response-content-type=application%2Foctet-stream&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20261021%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20261021T101147Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=9052bc89264a4e7498bc961590d9686e0b2579b3ab10d7c26b3d1f6db540ca33", "upload_token": "" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "No token passed", "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "poc_id": { "type": "integer", "description": "Purchase order comment id." }, "uploads_attributes[upload_token]": { "type": "string", "description": "Client-generated de-duplication token, at least 7 characters, unique among your uploads." }, "uploads_attributes[file]": { "type": "string", "format": "binary", "description": "The file part (max 30 MB)." } }, "required": [ "poc_id", "uploads_attributes[upload_token]", "uploads_attributes[file]" ] } } } } } }, "/api/v1/uploads/poc": { "post": { "tags": [ "Purchase Orders: Attachments" ], "operationId": "v1_uploads_poc", "summary": "Upload a file to a PO comment", "description": "Attach a file to an existing purchase order comment (multipart).\n\nAttaches a file to the purchase order comment `poc_id` (the `id` returned by\n[Create a comment](#comment-on-a-purchase-order)). Use it to post \"comment + attachment\": create the\ncomment, then upload one or more files to it. The file is listed under that comment's\n`uploads[]` in the PO details.\n\nSame token checks, file validation and error order as\n[Upload a file to a purchase order](#upload-a-file-to-a-purchase-order). The comment must\nbelong to a purchase order of the `app_company_id` company (`404` otherwise).\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "file_file_name": { "type": "string" }, "file_content_type": { "type": "string" }, "url": { "type": "string" }, "upload_token": { "type": "string" } } }, "example": { "id": 8, "file_file_name": "damaged-box.png", "file_content_type": "image/png", "url": "https://pex-files.s3.amazonaws.com/uploads/files/000/000/008/original/damaged-box.png?response-content-disposition=attachment%3B%20filename%3D%22damaged-box.png%22%3B%20filename%2A%3DUTF-8%27%27damaged-box.png&response-content-type=application%2Foctet-stream&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20261021%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20261021T101146Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=e28c179b825bccc2416d83f5a35caab9706afb29dbce3cd93d7e5f81bb4b7794", "upload_token": "" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "No token passed", "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "poc_id": { "type": "integer", "description": "Purchase order comment id." }, "uploads_attributes[upload_token]": { "type": "string", "description": "Client-generated de-duplication token, at least 7 characters, unique among your uploads." }, "uploads_attributes[file]": { "type": "string", "format": "binary", "description": "The file part (max 30 MB)." } }, "required": [ "poc_id", "uploads_attributes[upload_token]", "uploads_attributes[file]" ] } } } } } }, "/api/v3/uploads/status": { "get": { "tags": [ "Purchase Orders: Attachments" ], "operationId": "v3_uploads_status", "summary": "Get upload status", "description": "Look up one of your uploads by its upload token.\n\nReturns the upload that **you** created with the given `upload_token`, for example to find\nout whether an upload whose response was lost actually went through. Only the calling\nuser's own uploads are searched (another user's token answers `400`), and the token is\nmatched exactly (no length rule here).\n\n\nNone - identical request and response.", "parameters": [ { "name": "upload_token", "in": "query", "required": true, "description": "The token sent in `uploads_attributes[upload_token]`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "file_file_name": { "type": "string" }, "file_content_type": { "type": "string" }, "url": { "type": "string" }, "upload_token": { "type": "string" } } }, "example": { "id": 5, "file_file_name": "delivery-note.pdf", "file_content_type": "application/pdf", "url": "https://pex-files.s3.amazonaws.com/uploads/files/000/000/005/original/delivery-note.pdf?response-content-disposition=attachment%3B%20filename%3D%22delivery-note.pdf%22%3B%20filename%2A%3DUTF-8%27%27delivery-note.pdf&response-content-type=application%2Foctet-stream&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20261021%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20261021T101155Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=dc8e900e40b58883bb97e83c336cd0221587a91f7cc9e310271aeba81325595a", "upload_token": "" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "Token you provided is not valid", "status": 400 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/uploads/status": { "get": { "tags": [ "Purchase Orders: Attachments" ], "operationId": "v1_uploads_status", "summary": "Get upload status", "description": "Look up one of your uploads by its upload token.\n\nReturns the upload that **you** created with the given `upload_token`, for example to find\nout whether an upload whose response was lost actually went through. Only the calling\nuser's own uploads are searched (another user's token answers `400`), and the token is\nmatched exactly (no length rule here).\n\n\nNone - identical request and response.", "parameters": [ { "name": "upload_token", "in": "query", "required": true, "description": "The token sent in `uploads_attributes[upload_token]`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "file_file_name": { "type": "string" }, "file_content_type": { "type": "string" }, "url": { "type": "string" }, "upload_token": { "type": "string" } } }, "example": { "id": 4, "file_file_name": "delivery-note.pdf", "file_content_type": "application/pdf", "url": "https://pex-files.s3.amazonaws.com/uploads/files/000/000/004/original/delivery-note.pdf?response-content-disposition=attachment%3B%20filename%3D%22delivery-note.pdf%22%3B%20filename%2A%3DUTF-8%27%27delivery-note.pdf&response-content-type=application%2Foctet-stream&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20261021%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20261021T101155Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=162dd8c6f53122043d55b531ead03f281b90a2cf8455a6869b03266a092f78a2", "upload_token": "" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "Token you provided is not valid", "status": 400 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/purchase_orders/{purchase_order_id}/comments": { "post": { "tags": [ "Purchase Orders: Comments" ], "operationId": "v3_po_comment_create", "summary": "Comment on a purchase order", "description": "Add a comment to a purchase order.\n\nAdds a user comment (category `mobile_api_comment`) to the purchase order. The text is\nrequired - to attach a file, create the comment and then use\n[Upload a file to a PO comment](#upload-a-file-to-a-po-comment) with the returned `id`.\n\nE-mail addresses of active company users in the text mention those users (they gain\naccess to the PO and are notified). Send the body as JSON (`{\"comment\": \"...\"}`) or as a\nform field; the parameter is top-level, not nested.\n\n\nNone - identical request and response.", "parameters": [ { "name": "purchase_order_id", "in": "path", "required": true, "description": "Purchase order id (numeric).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "comment": { "type": "string" }, "creator_id": { "type": "integer" }, "creator_name": { "type": "string" }, "purchase_order_id": { "type": "integer" }, "status": { "type": "string" }, "created_at": { "type": "integer" }, "uploads": { "type": "array", "items": { } }, "comment_formatted_time": { "type": "string" }, "comment_formatted_date": { "type": "string" }, "comment_display_name": { "type": "string" }, "formatted_comment": { "type": "string" }, "system_generated": { "type": "boolean" }, "category": { "type": "string" } } }, "example": { "id": 54, "comment": "Paper boxes arrived slightly damaged - marco.rossi@example.com can you hold the invoice until we confirm with Northwind? See https://example.com/claims/1234", "creator_id": 40000, "creator_name": "Jane Doe", "purchase_order_id": 12, "status": "active", "created_at": 1792577000, "uploads": [ ], "comment_formatted_time": "05:03", "comment_formatted_date": "2026-10-21", "comment_display_name": "Jane Doe", "formatted_comment": "

Paper boxes arrived slightly damaged - marco.rossi@example.com can you hold the invoice until we confirm with Northwind? See https://example.com/claims/1234

", "system_generated": false, "category": "mobile_api_comment" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": { "comment": [ ": please add a comment or attach a file" ] }, "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "description": "Comment text. Plain text; links are stripped from `comment` and auto-linked in `formatted_comment`. Blank -> `400`." } }, "required": [ "comment" ] }, "example": { "comment": "Paper boxes arrived slightly damaged - marco.rossi@example.com can you hold the invoice until we confirm with Northwind? See https://example.com/claims/1234" } } } } } }, "/api/v1/purchase_orders/{purchase_order_id}/comments": { "post": { "tags": [ "Purchase Orders: Comments" ], "operationId": "v1_po_comment_create", "summary": "Comment on a purchase order", "description": "Add a comment to a purchase order.\n\nAdds a user comment (category `mobile_api_comment`) to the purchase order. The text is\nrequired - to attach a file, create the comment and then use\n[Upload a file to a PO comment](#upload-a-file-to-a-po-comment) with the returned `id`.\n\nE-mail addresses of active company users in the text mention those users (they gain\naccess to the PO and are notified). Send the body as JSON (`{\"comment\": \"...\"}`) or as a\nform field; the parameter is top-level, not nested.\n\n\nNone - identical request and response.", "parameters": [ { "name": "purchase_order_id", "in": "path", "required": true, "description": "Purchase order id (numeric).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "comment": { "type": "string" }, "creator_id": { "type": "integer" }, "creator_name": { "type": "string" }, "purchase_order_id": { "type": "integer" }, "status": { "type": "string" }, "created_at": { "type": "integer" }, "uploads": { "type": "array", "items": { } }, "comment_formatted_time": { "type": "string" }, "comment_formatted_date": { "type": "string" }, "comment_display_name": { "type": "string" }, "formatted_comment": { "type": "string" }, "system_generated": { "type": "boolean" }, "category": { "type": "string" } } }, "example": { "id": 53, "comment": "Paper boxes arrived slightly damaged - marco.rossi@example.com can you hold the invoice until we confirm with Northwind? See https://example.com/claims/1234", "creator_id": 40000, "creator_name": "Jane Doe", "purchase_order_id": 11, "status": "active", "created_at": 1792577000, "uploads": [ ], "comment_formatted_time": "05:03", "comment_formatted_date": "2026-10-21", "comment_display_name": "Jane Doe", "formatted_comment": "

Paper boxes arrived slightly damaged - marco.rossi@example.com can you hold the invoice until we confirm with Northwind? See https://example.com/claims/1234

", "system_generated": false, "category": "mobile_api_comment" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": { "comment": [ ": please add a comment or attach a file" ] }, "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "description": "Comment text. Plain text; links are stripped from `comment` and auto-linked in `formatted_comment`. Blank -> `400`." } }, "required": [ "comment" ] }, "example": { "comment": "Paper boxes arrived slightly damaged - marco.rossi@example.com can you hold the invoice until we confirm with Northwind? See https://example.com/claims/1234" } } } } } }, "/api/v3/purchase_orders/{id}/receiving_items": { "post": { "tags": [ "Purchase Orders: Receiving & Delivery" ], "operationId": "v3_po_receive_items", "summary": "Receive items", "description": "Record received quantities for one or more purchase order lines.\n\nAdds each `quantity` to the line's `received_quantity` (it is **incremental**: send what\narrived in this delivery, not the running total). Lines you do not list are unchanged. After\na successful receipt the PO's `delivery_status` is recalculated, `delivered_on` is set from\n`delivered_on`, and a history comment such as\n`\"Jane Doe received 10.0 quantity on this purchase order at 10/20/2026
Notes: ...\"` is\nadded (category `partially_delivered` or `complete_delivered`).\n\nValidation (nothing is saved when any line fails - the whole request is rejected):\n\n* `items` must be present and non-empty -> `\"Received Quantity can not be blank\"`.\n* every `quantity` must be a number -> `\"Invalid Received Quantity\"`.\n* not all quantities may be `0` -> `\"Receiving Quantity cannot be 0 for all items.\"`.\n* for a positive ordered quantity the new quantity must lie between minus the already\n received quantity and the remaining quantity -> otherwise\n `\"Received Quantity must be less than total quantity\"`. A **negative** quantity therefore\n reverses part of an earlier receipt (for example goods returned damaged).\n* line custom field validation errors are returned as their messages.\n\nLine ids that do not belong to the purchase order are ignored. Concurrent receipts of the\nsame PO are serialised; if the PO stays locked for 5 seconds the request fails with\n`400 {\"error\": [\"Please try again\"]}` and nothing is applied.\n\n\nNone - identical request and response (verified on separate POs for every success case).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Purchase order id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } } }, "example": { "status": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Received Quantity must be less than total quantity" ], "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase_order[items]": { "type": "array", "items": { "type": "object" }, "description": "Lines received in this delivery. Send as a JSON array (form-encoded bodies must use `purchase_order[items][][id]` / `[][quantity]`; indexed keys such as `items[0][id]` cause a 500)." }, "purchase_order[items][][id]": { "type": "integer", "description": "Purchase order item id (`purchase_order_items[].id`)." }, "purchase_order[items][][quantity]": { "type": "number", "description": "Quantity received now (decimals allowed; negative to reverse a previous receipt)." }, "purchase_order[delivered_on]": { "type": "string", "description": "Delivery date in the company date format (`company_setting.date_format`, e.g. `10/21/2026` for `%m/%d/%Y`). Other formats are ignored for the PO's `delivered_on`." }, "purchase_order[notes]": { "type": "string", "description": "Free text appended to the receipt history comment." } }, "required": [ "purchase_order[items]", "purchase_order[items][][id]", "purchase_order[items][][quantity]" ] }, "example": { "purchase_order": { "delivered_on": "10/20/2026", "notes": "First pallet arrived; markers complete, paper short by 6 boxes", "items": [ { "id": 22, "quantity": 4 }, { "id": 23, "quantity": 6 } ] } } } } } } }, "/api/v1/purchase_orders/{id}/receiving_items": { "post": { "tags": [ "Purchase Orders: Receiving & Delivery" ], "operationId": "v1_po_receive_items", "summary": "Receive items", "description": "Record received quantities for one or more purchase order lines.\n\nAdds each `quantity` to the line's `received_quantity` (it is **incremental**: send what\narrived in this delivery, not the running total). Lines you do not list are unchanged. After\na successful receipt the PO's `delivery_status` is recalculated, `delivered_on` is set from\n`delivered_on`, and a history comment such as\n`\"Jane Doe received 10.0 quantity on this purchase order at 10/20/2026
Notes: ...\"` is\nadded (category `partially_delivered` or `complete_delivered`).\n\nValidation (nothing is saved when any line fails - the whole request is rejected):\n\n* `items` must be present and non-empty -> `\"Received Quantity can not be blank\"`.\n* every `quantity` must be a number -> `\"Invalid Received Quantity\"`.\n* not all quantities may be `0` -> `\"Receiving Quantity cannot be 0 for all items.\"`.\n* for a positive ordered quantity the new quantity must lie between minus the already\n received quantity and the remaining quantity -> otherwise\n `\"Received Quantity must be less than total quantity\"`. A **negative** quantity therefore\n reverses part of an earlier receipt (for example goods returned damaged).\n* line custom field validation errors are returned as their messages.\n\nLine ids that do not belong to the purchase order are ignored. Concurrent receipts of the\nsame PO are serialised; if the PO stays locked for 5 seconds the request fails with\n`400 {\"error\": [\"Please try again\"]}` and nothing is applied.\n\n\nNone - identical request and response (verified on separate POs for every success case).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Purchase order id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } } }, "example": { "status": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Received Quantity must be less than total quantity" ], "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase_order[items]": { "type": "array", "items": { "type": "object" }, "description": "Lines received in this delivery. Send as a JSON array (form-encoded bodies must use `purchase_order[items][][id]` / `[][quantity]`; indexed keys such as `items[0][id]` cause a 500)." }, "purchase_order[items][][id]": { "type": "integer", "description": "Purchase order item id (`purchase_order_items[].id`)." }, "purchase_order[items][][quantity]": { "type": "number", "description": "Quantity received now (decimals allowed; negative to reverse a previous receipt)." }, "purchase_order[delivered_on]": { "type": "string", "description": "Delivery date in the company date format (`company_setting.date_format`, e.g. `10/21/2026` for `%m/%d/%Y`). Other formats are ignored for the PO's `delivered_on`." }, "purchase_order[notes]": { "type": "string", "description": "Free text appended to the receipt history comment." } }, "required": [ "purchase_order[items]", "purchase_order[items][][id]", "purchase_order[items][][quantity]" ] }, "example": { "purchase_order": { "delivered_on": "10/20/2026", "notes": "First pallet arrived; markers complete, paper short by 6 boxes", "items": [ { "id": 20, "quantity": 4 }, { "id": 21, "quantity": 6 } ] } } } } } } }, "/api/v3/purchase_orders/{id}/cancel_receiving_items": { "post": { "tags": [ "Purchase Orders: Receiving & Delivery" ], "operationId": "v3_po_cancel_receiving_items", "summary": "Cancel received items", "description": "Reverse every receipt on a purchase order and set it back to not delivered.\n\nResets `received_quantity` to `0` on every line, archives (or, with the newer delivery\nmodel, reverses) the delivery records, clears `delivered_on`, sets `delivery_status` to\n`not_delivered`, and adds a history comment listing what was removed\n(`\"Delivery items removed and purchase order set to Undelivered due to cancellation action by ...\"`).\nThere is no body and no per-line option - to undo part of a receipt, send a negative\nquantity to [Receive items](#receive-items) instead.\n\nThe web app offers this action only for fully delivered POs (`can_cancel_receiving_items`\nin the PO details is `true` only when `completely_delivered`), but the API also accepts\npartially delivered and undelivered POs and always answers `{\"status\": true}`.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Purchase order id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } } }, "example": { "status": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/purchase_orders/{id}/cancel_receiving_items": { "post": { "tags": [ "Purchase Orders: Receiving & Delivery" ], "operationId": "v1_po_cancel_receiving_items", "summary": "Cancel received items", "description": "Reverse every receipt on a purchase order and set it back to not delivered.\n\nResets `received_quantity` to `0` on every line, archives (or, with the newer delivery\nmodel, reverses) the delivery records, clears `delivered_on`, sets `delivery_status` to\n`not_delivered`, and adds a history comment listing what was removed\n(`\"Delivery items removed and purchase order set to Undelivered due to cancellation action by ...\"`).\nThere is no body and no per-line option - to undo part of a receipt, send a negative\nquantity to [Receive items](#receive-items) instead.\n\nThe web app offers this action only for fully delivered POs (`can_cancel_receiving_items`\nin the PO details is `true` only when `completely_delivered`), but the API also accepts\npartially delivered and undelivered POs and always answers `{\"status\": true}`.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Purchase order id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } } }, "example": { "status": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/purchase_orders/{id}/complete_delivery": { "post": { "tags": [ "Purchase Orders: Receiving & Delivery" ], "operationId": "v3_po_complete_delivery", "summary": "Complete delivery", "description": "Close a partially delivered purchase order at the quantities received so far.\n\nFor a PO the supplier will not finish delivering: every line's ordered `quantity` is set to\nits `received_quantity` (so line amounts and the PO totals are reduced - in the example the\nnet total went from 300.90 to 225.93), `delivery_status` becomes `complete_delivered`, and a\nhistory comment such as\n`\"Jane Doe closed delivery with total quantity of 13.0 and gross amount of $ 245.99 on 10/20/2026\"`\nis added. This cannot be undone through the API.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Purchase order id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } } }, "example": { "status": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/purchase_orders/{id}/complete_delivery": { "post": { "tags": [ "Purchase Orders: Receiving & Delivery" ], "operationId": "v1_po_complete_delivery", "summary": "Complete delivery", "description": "Close a partially delivered purchase order at the quantities received so far.\n\nFor a PO the supplier will not finish delivering: every line's ordered `quantity` is set to\nits `received_quantity` (so line amounts and the PO totals are reduced - in the example the\nnet total went from 300.90 to 225.93), `delivery_status` becomes `complete_delivered`, and a\nhistory comment such as\n`\"Jane Doe closed delivery with total quantity of 13.0 and gross amount of $ 245.99 on 10/20/2026\"`\nis added. This cannot be undone through the API.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Purchase order id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } } }, "example": { "status": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/purchase_orders/{id}/forward": { "post": { "tags": [ "Purchase Orders: Sending to Suppliers" ], "operationId": "v3_po_forward", "summary": "Send a purchase order to a supplier", "description": "E-mail an approved purchase order (and optional attachments) to the supplier.\n\nQueues the \"send to supplier\" e-mail: your message with a link to the online purchase order\n(the PO PDF is attached when the company setting *Attach PDF to e-mails to suppliers* is on)\nplus the selected attachments goes to `emails`, with `cc` in copy, and a separate copy is sent\nto the PO creator. Placeholders in `email_subject` and\n`note` (`{Supplier.Name}`, `{PurchaseOrder.Number}`, ...) are replaced when the e-mail is\nbuilt. The request returns as soon as the e-mail is queued.\n\nOn success the PO's supplier e-mail status becomes *sent* and a history comment is added,\ne.g. `\"Purchase order sent to orders@northwind.example.com and email copy sent to accounts.payable@example.com with files: delivery-note.pdf, damaged-box.png\"`\n(category `send_supplier`). Selected comment attachments are also linked to the PO's\n`uploads`.\n\nWithout `save_template`/`update_template` this endpoint sends; with one of them it manages a\ntemplate instead and sends nothing (see\n[Save or update a send-to-supplier template](#save-or-update-a-send-to-supplier-template)).\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Purchase order id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent": { "type": "boolean" } } }, "example": { "sent": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Note can't be blank" ], "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "string", "description": "Recipient address(es) as ONE string, comma-separated (e.g. `\"orders@northwind.example.com, dispatch@northwind.example.com\"`). Usually the PO's `supplier.email`. An array is not accepted (500). Max 100 recipients." }, "note": { "type": "string", "description": "E-mail body (plain text with placeholders). Blank -> `400 \"Note can't be blank\"`." }, "email_subject": { "type": "string", "description": "E-mail subject (placeholders allowed)." }, "cc": { "type": "string", "description": "CC address(es), comma-separated string or array. Defaults to the PO creator's e-mail." }, "uploads": { "type": "array", "items": { "type": "integer" }, "description": "Ids of files to attach - uploads of this PO or of its comments (`uploads[].id`, `purchase_order_comments[].uploads[].id`). Max 100; any other id -> `400 unauthorized upload id given.`" } }, "required": [ "emails", "note" ] }, "example": { "emails": "orders@northwind.example.com", "cc": "accounts.payable@example.com", "email_subject": "Purchase order {PurchaseOrder.Number} from {Company.Name}", "note": "Dear {Supplier.Name},\n\nPlease find purchase order {PurchaseOrder.Number} attached, together with our delivery note and a photo of the damaged boxes.\n\nThanks,\n{Requester.Name}", "uploads": [ 5, 9 ] } } } } } }, "/api/v1/purchase_orders/{id}/forward": { "post": { "tags": [ "Purchase Orders: Sending to Suppliers" ], "operationId": "v1_po_forward", "summary": "Send a purchase order to a supplier", "description": "E-mail an approved purchase order (and optional attachments) to the supplier.\n\nQueues the \"send to supplier\" e-mail: your message with a link to the online purchase order\n(the PO PDF is attached when the company setting *Attach PDF to e-mails to suppliers* is on)\nplus the selected attachments goes to `emails`, with `cc` in copy, and a separate copy is sent\nto the PO creator. Placeholders in `email_subject` and\n`note` (`{Supplier.Name}`, `{PurchaseOrder.Number}`, ...) are replaced when the e-mail is\nbuilt. The request returns as soon as the e-mail is queued.\n\nOn success the PO's supplier e-mail status becomes *sent* and a history comment is added,\ne.g. `\"Purchase order sent to orders@northwind.example.com and email copy sent to accounts.payable@example.com with files: delivery-note.pdf, damaged-box.png\"`\n(category `send_supplier`). Selected comment attachments are also linked to the PO's\n`uploads`.\n\nWithout `save_template`/`update_template` this endpoint sends; with one of them it manages a\ntemplate instead and sends nothing (see\n[Save or update a send-to-supplier template](#save-or-update-a-send-to-supplier-template)).\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Purchase order id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent": { "type": "boolean" } } }, "example": { "sent": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Note can't be blank" ], "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "string", "description": "Recipient address(es) as ONE string, comma-separated (e.g. `\"orders@northwind.example.com, dispatch@northwind.example.com\"`). Usually the PO's `supplier.email`. An array is not accepted (500). Max 100 recipients." }, "note": { "type": "string", "description": "E-mail body (plain text with placeholders). Blank -> `400 \"Note can't be blank\"`." }, "email_subject": { "type": "string", "description": "E-mail subject (placeholders allowed)." }, "cc": { "type": "string", "description": "CC address(es), comma-separated string or array. Defaults to the PO creator's e-mail." }, "uploads": { "type": "array", "items": { "type": "integer" }, "description": "Ids of files to attach - uploads of this PO or of its comments (`uploads[].id`, `purchase_order_comments[].uploads[].id`). Max 100; any other id -> `400 unauthorized upload id given.`" } }, "required": [ "emails", "note" ] }, "example": { "emails": "orders@northwind.example.com", "cc": "accounts.payable@example.com", "email_subject": "Purchase order {PurchaseOrder.Number} from {Company.Name}", "note": "Dear {Supplier.Name},\n\nPlease find purchase order {PurchaseOrder.Number} attached, together with our delivery note and a photo of the damaged boxes.\n\nThanks,\n{Requester.Name}", "uploads": [ 4, 8 ] } } } } } }, "/api/v3/send_to_supplier_templates": { "get": { "tags": [ "Purchase Orders: Sending to Suppliers" ], "operationId": "v3_send_to_supplier_templates_list", "summary": "List send-to-supplier templates", "description": "List the company's e-mail templates for sending purchase orders to suppliers.\n\nReturns every template of the company (no pagination, no filters, no guaranteed order). Every\ncompany starts with a \"Default Template\". `is_default` marks the template selected as the\ncompany default (none in a new company).\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "label": { "type": "string" }, "text": { "type": "string" }, "is_default": { "type": "boolean" }, "template_name": { "type": "string" } } } }, "example": [ { "id": 1, "company_id": 20000, "label": "New order from {Company.Name} - PO {PurchaseOrder.Number}", "text": "Dear {Supplier.Name}, \n\nPlease find our new purchase order attached. \n\nGet your invoice into the hands of the right people by attaching it directly into our purchase order system. \n\nClick on the link below to attach your invoice to the purchase order. \n\nThank you, \nTech Company", "is_default": false, "template_name": "Default Template" }, { "id": 2, "company_id": 20000, "label": "Standard purchase order email", "text": "Hello {{supplier_contact}},\n\nPlease find purchase order {{po_number}} attached.\n\nThanks,\n{{company_name}}", "is_default": false, "template_name": "standard_po" } ] } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/send_to_supplier_templates": { "get": { "tags": [ "Purchase Orders: Sending to Suppliers" ], "operationId": "v1_send_to_supplier_templates_list", "summary": "List send-to-supplier templates", "description": "List the company's e-mail templates for sending purchase orders to suppliers.\n\nReturns every template of the company (no pagination, no filters, no guaranteed order). Every\ncompany starts with a \"Default Template\". `is_default` marks the template selected as the\ncompany default (none in a new company).\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "label": { "type": "string" }, "text": { "type": "string" }, "is_default": { "type": "boolean" }, "template_name": { "type": "string" } } } }, "example": [ { "id": 1, "company_id": 20000, "label": "New order from {Company.Name} - PO {PurchaseOrder.Number}", "text": "Dear {Supplier.Name}, \n\nPlease find our new purchase order attached. \n\nGet your invoice into the hands of the right people by attaching it directly into our purchase order system. \n\nClick on the link below to attach your invoice to the purchase order. \n\nThank you, \nTech Company", "is_default": false, "template_name": "Default Template" }, { "id": 2, "company_id": 20000, "label": "Standard purchase order email", "text": "Hello {{supplier_contact}},\n\nPlease find purchase order {{po_number}} attached.\n\nThanks,\n{{company_name}}", "is_default": false, "template_name": "standard_po" } ] } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/purchase_orders/{id}/generate_pdf": { "get": { "tags": [ "Purchase Orders: Sending to Suppliers" ], "operationId": "v3_po_generate_pdf", "summary": "Generate a purchase order PDF", "description": "Render the purchase order PDF and return a short-lived download link.\n\nRenders the PO with the company's PDF template (any status, drafts included - draft PDFs are\nnamed `PO-Draft-...`) and returns a JSON object with `pdf_link`. The response itself is JSON,\nnot the PDF.\n\nIn production `pdf_link` is a pre-signed link to `.pdf` (`Content-Type:\napplication/pdf`) that **expires after 60 seconds** - download it immediately. The file name\nfollows the company's PDF naming setting, for example `PO-11-21102026050541-Acme Corporation`.\n\n\nNone in the response. V1 calls `authorize @purchase_order, :generate_pdf?` (same company), V3\nperforms no authorization call - with the PO already scoped to the company the outcome is the same.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Purchase order id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "pdf_link": { "type": "string" } } }, "example": { "pdf_link": "public/PO-12-21102026050554-Acme Corporation" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/purchase_orders/{id}/generate_pdf": { "get": { "tags": [ "Purchase Orders: Sending to Suppliers" ], "operationId": "v1_po_generate_pdf", "summary": "Generate a purchase order PDF", "description": "Render the purchase order PDF and return a short-lived download link.\n\nRenders the PO with the company's PDF template (any status, drafts included - draft PDFs are\nnamed `PO-Draft-...`) and returns a JSON object with `pdf_link`. The response itself is JSON,\nnot the PDF.\n\nIn production `pdf_link` is a pre-signed link to `.pdf` (`Content-Type:\napplication/pdf`) that **expires after 60 seconds** - download it immediately. The file name\nfollows the company's PDF naming setting, for example `PO-11-21102026050541-Acme Corporation`.\n\n\nNone in the response. V1 calls `authorize @purchase_order, :generate_pdf?` (same company), V3\nperforms no authorization call - with the PO already scoped to the company the outcome is the same.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Purchase order id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "pdf_link": { "type": "string" } } }, "example": { "pdf_link": "public/PO-11-21102026050541-Acme Corporation" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/chart_of_accounts": { "get": { "tags": [ "QuickBooks Online: Chart of Accounts" ], "operationId": "v3_chart_of_account_list", "summary": "List chart of accounts", "description": "Returns the active QuickBooks accounts the caller may use, paginated.\n\nReturns accounts that are active, mapped to the currently connected\nQuickBooks company and visible to one of the caller's roles (see\n[QuickBooks Online](#quickbooks-online)). Without an active QuickBooks\nconnection the list is normally empty (`total_count: 0`).\n\n* `search` - case-insensitive substring of the account number or fully\n qualified name.\n* `page` / `per_page` - `per_page` defaults to the company's results-per-page\n setting (20 by default); there is no upper limit.\n\nNo sort order is applied; sort client-side if you need one.\n\n\nNone - identical request and response.", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Substring of account number or fully qualified name.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Page size (no maximum).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "chart_of_accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "classification": { "type": "string" }, "account_type": { "type": "string" }, "currency_code": { "type": "string" }, "account_number": { "type": "string" }, "display_name": { "type": "string" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "next_page": { "type": "null" }, "prev_page": { "type": "null" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "example": { "chart_of_accounts": [ { "id": 1, "name": "Office Expenses", "classification": "Expense", "account_type": "Expense", "currency_code": "USD", "account_number": "6000", "display_name": "Office Expenses - Expense", "archived": false, "company_id": 20000 }, { "id": 3, "name": "Advertising & Marketing", "classification": "Expense", "account_type": "Expense", "currency_code": "USD", "account_number": "6200", "display_name": "Advertising & Marketing - Expense", "archived": false, "company_id": 20000 } ], "meta": { "current_page": 1, "next_page": null, "prev_page": null, "total_pages": 1, "total_count": 3 } } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/chart_of_accounts": { "get": { "tags": [ "QuickBooks Online: Chart of Accounts" ], "operationId": "v1_chart_of_account_list", "summary": "List chart of accounts", "description": "Returns the active QuickBooks accounts the caller may use, paginated.\n\nReturns accounts that are active, mapped to the currently connected\nQuickBooks company and visible to one of the caller's roles (see\n[QuickBooks Online](#quickbooks-online)). Without an active QuickBooks\nconnection the list is normally empty (`total_count: 0`).\n\n* `search` - case-insensitive substring of the account number or fully\n qualified name.\n* `page` / `per_page` - `per_page` defaults to the company's results-per-page\n setting (20 by default); there is no upper limit.\n\nNo sort order is applied; sort client-side if you need one.\n\n\nNone - identical request and response.", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Substring of account number or fully qualified name.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Page size (no maximum).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "chart_of_accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "classification": { "type": "string" }, "account_type": { "type": "string" }, "currency_code": { "type": "string" }, "account_number": { "type": "string" }, "display_name": { "type": "string" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "next_page": { "type": "null" }, "prev_page": { "type": "null" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "example": { "chart_of_accounts": [ { "id": 1, "name": "Office Expenses", "classification": "Expense", "account_type": "Expense", "currency_code": "USD", "account_number": "6000", "display_name": "Office Expenses - Expense", "archived": false, "company_id": 20000 }, { "id": 3, "name": "Advertising & Marketing", "classification": "Expense", "account_type": "Expense", "currency_code": "USD", "account_number": "6200", "display_name": "Advertising & Marketing - Expense", "archived": false, "company_id": 20000 } ], "meta": { "current_page": 1, "next_page": null, "prev_page": null, "total_pages": 1, "total_count": 3 } } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/chart_of_accounts/{id}": { "get": { "tags": [ "QuickBooks Online: Chart of Accounts" ], "operationId": "v3_chart_of_account_show", "summary": "Get a chart of account", "description": "Returns one account of the company by id, archived included.\n\nReturns any chart of account of the company by id - archived accounts,\naccounts of a previously connected QuickBooks company and accounts hidden\nfrom the caller's roles included (the list filters do not apply).\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Chart of account id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "classification": { "type": "string" }, "account_type": { "type": "string" }, "currency_code": { "type": "string" }, "account_number": { "type": "string" }, "display_name": { "type": "string" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" } } }, "example": { "id": 2, "name": "Computer Equipment", "classification": "Expense", "account_type": "Expense", "currency_code": "USD", "account_number": "6100", "display_name": "Computer Equipment - Expense", "archived": false, "company_id": 20000 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/chart_of_accounts/{id}": { "get": { "tags": [ "QuickBooks Online: Chart of Accounts" ], "operationId": "v1_chart_of_account_show", "summary": "Get a chart of account", "description": "Returns one account of the company by id, archived included.\n\nReturns any chart of account of the company by id - archived accounts,\naccounts of a previously connected QuickBooks company and accounts hidden\nfrom the caller's roles included (the list filters do not apply).\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Chart of account id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "classification": { "type": "string" }, "account_type": { "type": "string" }, "currency_code": { "type": "string" }, "account_number": { "type": "string" }, "display_name": { "type": "string" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" } } }, "example": { "id": 2, "name": "Computer Equipment", "classification": "Expense", "account_type": "Expense", "currency_code": "USD", "account_number": "6100", "display_name": "Computer Equipment - Expense", "archived": false, "company_id": 20000 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/qbo_classes": { "get": { "tags": [ "QuickBooks Online: Classes" ], "operationId": "v3_qbo_class_list", "summary": "List QuickBooks classes", "description": "Returns the active QuickBooks classes the caller may use, paginated.\n\nSame filters as the chart of accounts list: active, mapped to the connected\nQuickBooks company, visible to one of the caller's roles. `search` matches a\nsubstring of `fully_qualified_name` (case-insensitive). `per_page` defaults\nto the company's results-per-page setting, no maximum. No sort order.\n\n\nNone - identical request and response.", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Substring of the fully qualified name.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Page size (no maximum).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "quickbooks_classes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "fully_qualified_name": { "type": "string" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "next_page": { "type": "null" }, "prev_page": { "type": "null" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "example": { "quickbooks_classes": [ { "id": 1, "fully_qualified_name": "Northeast", "archived": false, "company_id": 20000 }, { "id": 2, "fully_qualified_name": "West Coast", "archived": false, "company_id": 20000 } ], "meta": { "current_page": 1, "next_page": null, "prev_page": null, "total_pages": 1, "total_count": 2 } } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/qbo_classes": { "get": { "tags": [ "QuickBooks Online: Classes" ], "operationId": "v1_qbo_class_list", "summary": "List QuickBooks classes", "description": "Returns the active QuickBooks classes the caller may use, paginated.\n\nSame filters as the chart of accounts list: active, mapped to the connected\nQuickBooks company, visible to one of the caller's roles. `search` matches a\nsubstring of `fully_qualified_name` (case-insensitive). `per_page` defaults\nto the company's results-per-page setting, no maximum. No sort order.\n\n\nNone - identical request and response.", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Substring of the fully qualified name.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Page size (no maximum).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "quickbooks_classes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "fully_qualified_name": { "type": "string" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "next_page": { "type": "null" }, "prev_page": { "type": "null" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "example": { "quickbooks_classes": [ { "id": 1, "fully_qualified_name": "Northeast", "archived": false, "company_id": 20000 }, { "id": 2, "fully_qualified_name": "West Coast", "archived": false, "company_id": 20000 } ], "meta": { "current_page": 1, "next_page": null, "prev_page": null, "total_pages": 1, "total_count": 2 } } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/qbo_classes/{id}": { "get": { "tags": [ "QuickBooks Online: Classes" ], "operationId": "v3_qbo_class_show", "summary": "Get a QuickBooks class", "description": "Returns one QuickBooks class of the company by id.\n\nReturns any class of the company by id, archived or restricted ones included.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "QuickBooks class id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "fully_qualified_name": { "type": "string" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" } } }, "example": { "id": 1, "fully_qualified_name": "Northeast", "archived": false, "company_id": 20000 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/qbo_classes/{id}": { "get": { "tags": [ "QuickBooks Online: Classes" ], "operationId": "v1_qbo_class_show", "summary": "Get a QuickBooks class", "description": "Returns one QuickBooks class of the company by id.\n\nReturns any class of the company by id, archived or restricted ones included.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "QuickBooks class id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "fully_qualified_name": { "type": "string" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" } } }, "example": { "id": 1, "fully_qualified_name": "Northeast", "archived": false, "company_id": 20000 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/qbo_customers": { "get": { "tags": [ "QuickBooks Online: Customers" ], "operationId": "v3_qbo_customer_list", "summary": "List QuickBooks customers", "description": "Returns the active QuickBooks customers / projects the caller may use, paginated.\n\nSame filters as the chart of accounts list: active, mapped to the connected\nQuickBooks company, visible to one of the caller's roles. `search` matches a\nsubstring of `fully_qualified_name` (case-insensitive). `per_page` defaults\nto the company's results-per-page setting (20 when unset), no maximum.\n\n\nNone - identical request and response (the V3 controller computes the default\npage size slightly differently in code, with the same result).", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Substring of the fully qualified name.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Page size (no maximum).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "qbo_customers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "fully_qualified_name": { "type": "string" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "next_page": { "type": "null" }, "prev_page": { "type": "null" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "example": { "qbo_customers": [ { "id": 1, "fully_qualified_name": "Initech LLC", "archived": false, "company_id": 20000 }, { "id": 2, "fully_qualified_name": "Umbrella Corporation", "archived": false, "company_id": 20000 } ], "meta": { "current_page": 1, "next_page": null, "prev_page": null, "total_pages": 1, "total_count": 2 } } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/qbo_customers": { "get": { "tags": [ "QuickBooks Online: Customers" ], "operationId": "v1_qbo_customer_list", "summary": "List QuickBooks customers", "description": "Returns the active QuickBooks customers / projects the caller may use, paginated.\n\nSame filters as the chart of accounts list: active, mapped to the connected\nQuickBooks company, visible to one of the caller's roles. `search` matches a\nsubstring of `fully_qualified_name` (case-insensitive). `per_page` defaults\nto the company's results-per-page setting (20 when unset), no maximum.\n\n\nNone - identical request and response (the V3 controller computes the default\npage size slightly differently in code, with the same result).", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Substring of the fully qualified name.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Page size (no maximum).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "qbo_customers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "fully_qualified_name": { "type": "string" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "next_page": { "type": "null" }, "prev_page": { "type": "null" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "example": { "qbo_customers": [ { "id": 1, "fully_qualified_name": "Initech LLC", "archived": false, "company_id": 20000 }, { "id": 2, "fully_qualified_name": "Umbrella Corporation", "archived": false, "company_id": 20000 } ], "meta": { "current_page": 1, "next_page": null, "prev_page": null, "total_pages": 1, "total_count": 2 } } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/qbo_customers/{id}": { "get": { "tags": [ "QuickBooks Online: Customers" ], "operationId": "v3_qbo_customer_show", "summary": "Get a QuickBooks customer", "description": "Returns one QuickBooks customer of the company by id.\n\nReturns any customer of the company by id, archived or restricted ones\nincluded.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "QuickBooks customer id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "fully_qualified_name": { "type": "string" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" } } }, "example": { "id": 1, "fully_qualified_name": "Initech LLC", "archived": false, "company_id": 20000 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/qbo_customers/{id}": { "get": { "tags": [ "QuickBooks Online: Customers" ], "operationId": "v1_qbo_customer_show", "summary": "Get a QuickBooks customer", "description": "Returns one QuickBooks customer of the company by id.\n\nReturns any customer of the company by id, archived or restricted ones\nincluded.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "QuickBooks customer id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "fully_qualified_name": { "type": "string" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" } } }, "example": { "id": 1, "fully_qualified_name": "Initech LLC", "archived": false, "company_id": 20000 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/qbo_item_budget_mappings": { "get": { "tags": [ "QuickBooks Online: Item Budget Mappings" ], "operationId": "v3_qbo_item_budget_mapping_list", "summary": "List item budget mappings", "description": "Returns the company's product/department -> budget mappings, paginated.\n\nLists mappings of the company, optionally filtered by `product_id` and/or\n`department_id`. Paginated: `per_page` defaults to 50, max 100.\n\n\nV3 only; `GET /api/v1/qbo_item_budget_mappings` answers 404 `Invalid URL`.", "parameters": [ { "name": "product_id", "in": "query", "required": false, "description": "Only mappings of this product.", "schema": { "type": "integer" } }, { "name": "department_id", "in": "query", "required": false, "description": "Only mappings of this department.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Page size, max 100.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "qbo_item_budget_mappings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "product_id": { "type": "integer" }, "department_id": { "type": "integer" }, "budget_id": { "type": "integer" }, "company_id": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "product_name": { "type": "string" }, "department_name": { "type": "string" }, "budget_name": { "type": "string" } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "next_page": { "type": "null" }, "prev_page": { "type": "null" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "example": { "qbo_item_budget_mappings": [ { "id": 1, "product_id": 2, "department_id": 2, "budget_id": 1, "company_id": 20000, "created_at": "2026-10-21T05:08:21.338-05:00", "updated_at": "2026-10-21T05:08:21.338-05:00", "product_name": "27-inch monitor", "department_name": "Engineering", "budget_name": "Engineering Hardware FY26" }, { "id": 2, "product_id": 1, "department_id": 4, "budget_id": 3, "company_id": 20000, "created_at": "2026-10-21T05:08:29.845-05:00", "updated_at": "2026-10-21T05:08:29.845-05:00", "product_name": "Standing desk", "department_name": "Operations", "budget_name": "Office Supplies" } ], "meta": { "current_page": 1, "next_page": null, "prev_page": null, "total_pages": 1, "total_count": 3 } } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "example": { "error": [ "Item-based mode is not enabled for this account" ], "status": 422 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] }, "post": { "tags": [ "QuickBooks Online: Item Budget Mappings" ], "operationId": "v3_qbo_item_budget_mapping_create", "summary": "Create an item budget mapping", "description": "Maps a product, for one department, to a budget.\n\nCreates a mapping. The product/department pair must not be mapped yet (use\nupdate or bulk update to change an existing pair), the budget must be linked\nto the department, and all three records must belong to the company.\n\n\nV3 only; V1 answers 404 `Invalid URL`.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "product_id": { "type": "integer" }, "department_id": { "type": "integer" }, "budget_id": { "type": "integer" }, "company_id": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "product_name": { "type": "string" }, "department_name": { "type": "string" }, "budget_name": { "type": "string" } } }, "example": { "id": 1, "product_id": 2, "department_id": 2, "budget_id": 1, "company_id": 20000, "created_at": "2026-10-21T05:08:21.338-05:00", "updated_at": "2026-10-21T05:08:21.338-05:00", "product_name": "27-inch monitor", "department_name": "Engineering", "budget_name": "Engineering Hardware FY26" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Product already has a budget mapping for this department" ], "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "example": { "error": [ "Item-based mode is not enabled for this account" ], "status": 422 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "qbo_item_budget_mapping[product_id]": { "type": "integer", "description": "Product of the company." }, "qbo_item_budget_mapping[department_id]": { "type": "integer", "description": "Department of the company." }, "qbo_item_budget_mapping[budget_id]": { "type": "integer", "description": "Budget linked to that department." } }, "required": [ "qbo_item_budget_mapping[product_id]", "qbo_item_budget_mapping[department_id]", "qbo_item_budget_mapping[budget_id]" ] }, "example": { "qbo_item_budget_mapping": { "product_id": 2, "department_id": 2, "budget_id": 1 } } } } } } }, "/api/v3/qbo_item_budget_mappings/{id}": { "get": { "tags": [ "QuickBooks Online: Item Budget Mappings" ], "operationId": "v3_qbo_item_budget_mapping_show", "summary": "Get an item budget mapping", "description": "Returns one mapping by id.\n\nReturns a mapping of the company by id.\n\n\nV3 only; V1 answers 404 `Invalid URL`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Mapping id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "product_id": { "type": "integer" }, "department_id": { "type": "integer" }, "budget_id": { "type": "integer" }, "company_id": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "product_name": { "type": "string" }, "department_name": { "type": "string" }, "budget_name": { "type": "string" } } }, "example": { "id": 1, "product_id": 2, "department_id": 2, "budget_id": 1, "company_id": 20000, "created_at": "2026-10-21T05:08:21.338-05:00", "updated_at": "2026-10-21T05:08:21.338-05:00", "product_name": "27-inch monitor", "department_name": "Engineering", "budget_name": "Engineering Hardware FY26" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "example": { "error": [ "Item-based mode is not enabled for this account" ], "status": 422 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] }, "put": { "tags": [ "QuickBooks Online: Item Budget Mappings" ], "operationId": "v3_qbo_item_budget_mapping_update", "summary": "Update an item budget mapping", "description": "Changes the product, department or budget of a mapping.\n\nPartial update; the same validations as create apply to the resulting\nmapping.\n\n\nV3 only; V1 answers 404 `Invalid URL`. PUT and PATCH both accepted.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Mapping id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "product_id": { "type": "integer" }, "department_id": { "type": "integer" }, "budget_id": { "type": "integer" }, "company_id": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "product_name": { "type": "string" }, "department_name": { "type": "string" }, "budget_name": { "type": "string" } } }, "example": { "id": 3, "product_id": 3, "department_id": 2, "budget_id": 1, "company_id": 20000, "created_at": "2026-10-21T05:08:29.872-05:00", "updated_at": "2026-10-21T05:08:37.425-05:00", "product_name": "USB-C dock", "department_name": "Engineering", "budget_name": "Engineering Hardware FY26" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Budget must belong to the selected department" ], "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "example": { "error": [ "Item-based mode is not enabled for this account" ], "status": 422 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "qbo_item_budget_mapping[product_id]": { "type": "integer", "description": "Product of the company." }, "qbo_item_budget_mapping[department_id]": { "type": "integer", "description": "Department of the company." }, "qbo_item_budget_mapping[budget_id]": { "type": "integer", "description": "Budget linked to the (new) department." } } }, "example": { "qbo_item_budget_mapping": { "budget_id": 1 } } } } } }, "delete": { "tags": [ "QuickBooks Online: Item Budget Mappings" ], "operationId": "v3_qbo_item_budget_mapping_delete", "summary": "Delete an item budget mapping", "description": "Permanently deletes a mapping.\n\nDeletes the mapping; the product falls back to its default budget / manual\nselection on new POs.\n\n\nV3 only; V1 answers 404 `Invalid URL`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Mapping id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "example": { "deleted": true } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "example": { "error": [ "Item-based mode is not enabled for this account" ], "status": 422 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v3/qbo_item_budget_mappings/bulk_update": { "put": { "tags": [ "QuickBooks Online: Item Budget Mappings" ], "operationId": "v3_qbo_item_budget_mapping_bulk_update", "summary": "Bulk create or update item budget mappings", "description": "Upserts many mappings at once, keyed by product and department.\n\nFor each entry of `mappings`, finds the mapping for (`product_id`,\n`department_id`) or creates it, and sets its `budget_id`.\n\n* An entry identical to an existing mapping is not re-validated; it is\n returned in `updated`, and listed in `stale` when its budget no longer\n belongs to the department, so you can flag it.\n* Entries that fail validation are collected; the response is then **400**\n with all their messages (flattened, without saying which entry failed).\n* **Partial writes:** the batch is rolled back only when more than 10\n entries fail. With 1-10 failures the valid entries **are saved** even\n though the response is 400 - re-read the list after an error.\n* `mappings` must be a non-empty array (an empty or missing array -> 400\n `Required parameter are missing.`).\n\n\nV3 only; `PUT /api/v1/qbo_item_budget_mappings/bulk_update` answers 404\n`Invalid URL`.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "product_id": { "type": "integer" }, "department_id": { "type": "integer" }, "budget_id": { "type": "integer" }, "company_id": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "product_name": { "type": "string" }, "department_name": { "type": "string" }, "budget_name": { "type": "string" } } } }, "updated": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "product_id": { "type": "integer" }, "department_id": { "type": "integer" }, "budget_id": { "type": "integer" }, "company_id": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "product_name": { "type": "string" }, "department_name": { "type": "string" }, "budget_name": { "type": "string" } } } }, "stale": { "type": "array", "items": { } } } }, "example": { "created": [ { "id": 2, "product_id": 1, "department_id": 4, "budget_id": 3, "company_id": 20000, "created_at": "2026-10-21T05:08:29.845-05:00", "updated_at": "2026-10-21T05:08:29.845-05:00", "product_name": "Standing desk", "department_name": "Operations", "budget_name": "Office Supplies" }, { "id": 3, "product_id": 3, "department_id": 2, "budget_id": 5, "company_id": 20000, "created_at": "2026-10-21T05:08:29.872-05:00", "updated_at": "2026-10-21T05:08:29.872-05:00", "product_name": "USB-C dock", "department_name": "Engineering", "budget_name": "Facilities FY27" } ], "updated": [ { "id": 1, "product_id": 2, "department_id": 2, "budget_id": 1, "company_id": 20000, "created_at": "2026-10-21T05:08:21.338-05:00", "updated_at": "2026-10-21T05:08:21.338-05:00", "product_name": "27-inch monitor", "department_name": "Engineering", "budget_name": "Engineering Hardware FY26" } ], "stale": [ ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Budget must belong to the selected department" ], "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "example": { "error": [ "Item-based mode is not enabled for this account" ], "status": 422 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mappings[]": { "type": "array", "items": { "type": "object" }, "description": "Non-empty list of entries." }, "mappings[][product_id]": { "type": "integer", "description": "Product of the company." }, "mappings[][department_id]": { "type": "integer", "description": "Department of the company." }, "mappings[][budget_id]": { "type": "integer", "description": "Budget linked to that department." } }, "required": [ "mappings[]", "mappings[][product_id]", "mappings[][department_id]", "mappings[][budget_id]" ] }, "example": { "mappings": [ { "product_id": 1, "department_id": 4, "budget_id": 3 }, { "product_id": 3, "department_id": 2, "budget_id": 5 }, { "product_id": 2, "department_id": 2, "budget_id": 1 } ] } } } } } }, "/api/v3/sam_gov/check": { "post": { "tags": [ "SAM.gov Supplier Audit" ], "operationId": "v3_sam_gov_check", "summary": "Check a supplier against SAM.gov", "description": "Returns a fresh SAM.gov exclusions check for the supplier, calling SAM.gov when no recent result exists.\n\nRuns (or re-uses) a SAM.gov Exclusions check for a supplier of the company, following\nthe caching rules in the section intro:\n\n1. If prerequisites are not met (Policies module, SAM.gov opt-in, API key), it returns\n `200 {\"status\": \"unchecked\", \"supplier_id\": }` and stores nothing.\n2. Without `force`: the latest `clear`/`flagged` check younger than 24 h is returned,\n else an `error` check younger than 5 minutes is returned.\n3. Otherwise SAM.gov is queried synchronously (name, then UEI and CAGE code when set;\n 8 s timeout, one retry on timeout), a new check is stored and returned, and a\n screenshot capture is queued.\n\nSAM.gov failures that the client recognises (rate limit, rejected key, bad request,\nHTTP 5xx, timeout) are stored as an `error` check and returned with HTTP `200`.\nCheck `status`, not the HTTP code. Connection-level failures (connection refused,\nDNS or TLS errors) are currently not caught and answer `500`.\n\n\nNone - identical request and response (the V3 controller is a copy of V1).", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "supplier_id": { "type": "integer" }, "supplier_name": { "type": "string" }, "uei": { "type": "string" }, "status": { "type": "string" }, "total_records": { "type": "integer" }, "has_active_exclusions": { "type": "boolean" }, "exclusions": { "type": "array", "items": { } }, "search_params": { "type": "object", "properties": { "uei": { "type": "string" }, "methods": { "type": "array", "items": { "type": "string" } }, "cage_code": { "type": "string" }, "supplier_name": { "type": "string" } } }, "checked_at": { "type": "string" }, "fresh": { "type": "boolean" }, "verification_screenshot_url": { "type": "string" }, "sam_gov_search_url": { "type": "string" } } }, "example": { "id": 1, "supplier_id": 4, "supplier_name": "Fabrikam Furniture", "uei": "FABRK1234567", "status": "clear", "total_records": 0, "has_active_exclusions": false, "exclusions": [ ], "search_params": { "uei": "FABRK1234567", "methods": [ "name", "uei", "cage_code" ], "cage_code": "1ABC2", "supplier_name": "Fabrikam Furniture" }, "checked_at": "2026-10-21T03:09:15-05:00", "fresh": true, "verification_screenshot_url": "https://app.procurementexpress.com/sam-gov-evidence/download?token=eyJfcmFpbHMiOnsibWVzc2FnZSI6ImV5SjJaWEp6YVc5dUlqb3hMQ0poZFdScFpXNWpaU0k2SW1Gd2FTSXNJblZ6WlhKZmFXUWlPalF3TURBd0xDSmpiMjF3WVc1NVgybGtJam95TURBd01Dd2ljM1Z3Y0d4cFpYSmZhV1FpT2pRc0ltTm9aV05yWDJsa0lqb3hMQ0ptYVd4bFgzWmxjbk5wYjI0aU9pSXlZMk5oWXpreFpHVmpNMlprWlRnd1lXUTROREZtTVRNeFlUYzFNREpsTjJJNE9UZzBOMkk1Wm1Oa1l6WTBZelJoT0RkbVkySmhaV00wWXpFNFpqTXhJaXdpYVhOemRXVmtYMkYwSWpveE56a3lOVGMzTXpVM0xDSmxlSEJwY21WelgyRjBJam94TnpreU5UYzNOalUzZlE9PSIsImV4cCI6IjIwMjYtMTAtMjFUMTA6MTQ6MTcuODg5WiIsInB1ciI6InNhbS1nb3YtZXZpZGVuY2Uuc2NyZWVuc2hvdC1kb3dubG9hZC52MSJ9fQ%3D%3D--e01620cd8326c5e5782cd7cc2a00e0aedd57a35516dde8031a5a6ab5668864fc", "sam_gov_search_url": "https://sam.gov/search/?page=1&pageSize=25&sfm%5BsimpleSearch%5D%5BkeywordRadio%5D=ALL&sfm%5BsimpleSearch%5D%5BkeywordTags%5D%5B0%5D%5Bkey%5D=FABRK1234567&sfm%5BsimpleSearch%5D%5BkeywordTags%5D%5B0%5D%5Bvalue%5D=FABRK1234567&sfm%5Bstatus%5D%5Bis_active%5D=true&sfm%5Bstatus%5D%5Bis_inactive%5D=false&sort=-modifiedDate" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "supplier_id": { "type": "integer", "description": "Supplier of the company. Unknown or missing: 404 (when the Policies module is on)." }, "force": { "type": "boolean", "description": "`true` ignores stored results and always queries SAM.gov." } }, "required": [ "supplier_id" ] }, "example": { "supplier_id": 4, "force": false } } } } } }, "/api/v1/sam_gov/check": { "post": { "tags": [ "SAM.gov Supplier Audit" ], "operationId": "v1_sam_gov_check", "summary": "Check a supplier against SAM.gov", "description": "Returns a fresh SAM.gov exclusions check for the supplier, calling SAM.gov when no recent result exists.\n\nRuns (or re-uses) a SAM.gov Exclusions check for a supplier of the company, following\nthe caching rules in the section intro:\n\n1. If prerequisites are not met (Policies module, SAM.gov opt-in, API key), it returns\n `200 {\"status\": \"unchecked\", \"supplier_id\": }` and stores nothing.\n2. Without `force`: the latest `clear`/`flagged` check younger than 24 h is returned,\n else an `error` check younger than 5 minutes is returned.\n3. Otherwise SAM.gov is queried synchronously (name, then UEI and CAGE code when set;\n 8 s timeout, one retry on timeout), a new check is stored and returned, and a\n screenshot capture is queued.\n\nSAM.gov failures that the client recognises (rate limit, rejected key, bad request,\nHTTP 5xx, timeout) are stored as an `error` check and returned with HTTP `200`.\nCheck `status`, not the HTTP code. Connection-level failures (connection refused,\nDNS or TLS errors) are currently not caught and answer `500`.\n\n\nNone - identical request and response (the V3 controller is a copy of V1).", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "supplier_id": { "type": "integer" }, "supplier_name": { "type": "string" }, "uei": { "type": "string" }, "status": { "type": "string" }, "total_records": { "type": "integer" }, "has_active_exclusions": { "type": "boolean" }, "exclusions": { "type": "array", "items": { } }, "search_params": { "type": "object", "properties": { "uei": { "type": "string" }, "methods": { "type": "array", "items": { "type": "string" } }, "cage_code": { "type": "string" }, "supplier_name": { "type": "string" } } }, "checked_at": { "type": "string" }, "fresh": { "type": "boolean" }, "verification_screenshot_url": { "type": "string" }, "sam_gov_search_url": { "type": "string" } } }, "example": { "id": 1, "supplier_id": 4, "supplier_name": "Fabrikam Furniture", "uei": "FABRK1234567", "status": "clear", "total_records": 0, "has_active_exclusions": false, "exclusions": [ ], "search_params": { "uei": "FABRK1234567", "methods": [ "name", "uei", "cage_code" ], "cage_code": "1ABC2", "supplier_name": "Fabrikam Furniture" }, "checked_at": "2026-10-21T03:09:15-05:00", "fresh": true, "verification_screenshot_url": "https://app.procurementexpress.com/sam-gov-evidence/download?token=eyJfcmFpbHMiOnsibWVzc2FnZSI6ImV5SjJaWEp6YVc5dUlqb3hMQ0poZFdScFpXNWpaU0k2SW1Gd2FTSXNJblZ6WlhKZmFXUWlPalF3TURBd0xDSmpiMjF3WVc1NVgybGtJam95TURBd01Dd2ljM1Z3Y0d4cFpYSmZhV1FpT2pRc0ltTm9aV05yWDJsa0lqb3hMQ0ptYVd4bFgzWmxjbk5wYjI0aU9pSXlZMk5oWXpreFpHVmpNMlprWlRnd1lXUTROREZtTVRNeFlUYzFNREpsTjJJNE9UZzBOMkk1Wm1Oa1l6WTBZelJoT0RkbVkySmhaV00wWXpFNFpqTXhJaXdpYVhOemRXVmtYMkYwSWpveE56a3lOVGMzTXpVM0xDSmxlSEJwY21WelgyRjBJam94TnpreU5UYzNOalUzZlE9PSIsImV4cCI6IjIwMjYtMTAtMjFUMTA6MTQ6MTcuODA0WiIsInB1ciI6InNhbS1nb3YtZXZpZGVuY2Uuc2NyZWVuc2hvdC1kb3dubG9hZC52MSJ9fQ%3D%3D--c5ce646fdb8a5504243bd0e69a83e51c9f7ab8c12871624f6d8a2fc9b50d879a", "sam_gov_search_url": "https://sam.gov/search/?page=1&pageSize=25&sfm%5BsimpleSearch%5D%5BkeywordRadio%5D=ALL&sfm%5BsimpleSearch%5D%5BkeywordTags%5D%5B0%5D%5Bkey%5D=FABRK1234567&sfm%5BsimpleSearch%5D%5BkeywordTags%5D%5B0%5D%5Bvalue%5D=FABRK1234567&sfm%5Bstatus%5D%5Bis_active%5D=true&sfm%5Bstatus%5D%5Bis_inactive%5D=false&sort=-modifiedDate" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "supplier_id": { "type": "integer", "description": "Supplier of the company. Unknown or missing: 404 (when the Policies module is on)." }, "force": { "type": "boolean", "description": "`true` ignores stored results and always queries SAM.gov." } }, "required": [ "supplier_id" ] }, "example": { "supplier_id": 4, "force": false } } } } } }, "/api/v3/sam_gov/status/{supplier_id}": { "get": { "tags": [ "SAM.gov Supplier Audit" ], "operationId": "v3_sam_gov_status", "summary": "Get a supplier's latest SAM.gov check", "description": "Returns the most recent stored SAM.gov check for a supplier without calling SAM.gov.\n\nReturns the most recent stored check (any status, including `error`) for the supplier\nin this company, or `{\"status\": \"unchecked\", \"supplier_id\": }` when there is none.\nNever calls SAM.gov. Only the Policies module needs to be on: it answers even if the\ncompany is not (or no longer) opted in to SAM.gov.\n\n\nNone - identical request and response.", "parameters": [ { "name": "supplier_id", "in": "path", "required": true, "description": "Supplier id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "supplier_id": { "type": "integer" }, "supplier_name": { "type": "string" }, "uei": { "type": "string" }, "status": { "type": "string" }, "total_records": { "type": "integer" }, "has_active_exclusions": { "type": "boolean" }, "exclusions": { "type": "array", "items": { } }, "search_params": { "type": "object", "properties": { "uei": { "type": "string" }, "methods": { "type": "array", "items": { "type": "string" } }, "cage_code": { "type": "string" }, "supplier_name": { "type": "string" } } }, "checked_at": { "type": "string" }, "fresh": { "type": "boolean" }, "verification_screenshot_url": { "type": "string" }, "sam_gov_search_url": { "type": "string" } } }, "example": { "id": 1, "supplier_id": 4, "supplier_name": "Fabrikam Furniture", "uei": "FABRK1234567", "status": "clear", "total_records": 0, "has_active_exclusions": false, "exclusions": [ ], "search_params": { "uei": "FABRK1234567", "methods": [ "name", "uei", "cage_code" ], "cage_code": "1ABC2", "supplier_name": "Fabrikam Furniture" }, "checked_at": "2026-10-21T03:09:15-05:00", "fresh": true, "verification_screenshot_url": "https://app.procurementexpress.com/sam-gov-evidence/download?token=eyJfcmFpbHMiOnsibWVzc2FnZSI6ImV5SjJaWEp6YVc5dUlqb3hMQ0poZFdScFpXNWpaU0k2SW1Gd2FTSXNJblZ6WlhKZmFXUWlPalF3TURBd0xDSmpiMjF3WVc1NVgybGtJam95TURBd01Dd2ljM1Z3Y0d4cFpYSmZhV1FpT2pRc0ltTm9aV05yWDJsa0lqb3hMQ0ptYVd4bFgzWmxjbk5wYjI0aU9pSXlZMk5oWXpreFpHVmpNMlprWlRnd1lXUTROREZtTVRNeFlUYzFNREpsTjJJNE9UZzBOMkk1Wm1Oa1l6WTBZelJoT0RkbVkySmhaV00wWXpFNFpqTXhJaXdpYVhOemRXVmtYMkYwSWpveE56a3lOVGMzTXpVM0xDSmxlSEJwY21WelgyRjBJam94TnpreU5UYzNOalUzZlE9PSIsImV4cCI6IjIwMjYtMTAtMjFUMTA6MTQ6MTcuMzQ1WiIsInB1ciI6InNhbS1nb3YtZXZpZGVuY2Uuc2NyZWVuc2hvdC1kb3dubG9hZC52MSJ9fQ%3D%3D--00481ad98f7f647aaa6e0c43716d88da938e4e984b9de8706970321bc1891fe4", "sam_gov_search_url": "https://sam.gov/search/?page=1&pageSize=25&sfm%5BsimpleSearch%5D%5BkeywordRadio%5D=ALL&sfm%5BsimpleSearch%5D%5BkeywordTags%5D%5B0%5D%5Bkey%5D=FABRK1234567&sfm%5BsimpleSearch%5D%5BkeywordTags%5D%5B0%5D%5Bvalue%5D=FABRK1234567&sfm%5Bstatus%5D%5Bis_active%5D=true&sfm%5Bstatus%5D%5Bis_inactive%5D=false&sort=-modifiedDate" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/sam_gov/status/{supplier_id}": { "get": { "tags": [ "SAM.gov Supplier Audit" ], "operationId": "v1_sam_gov_status", "summary": "Get a supplier's latest SAM.gov check", "description": "Returns the most recent stored SAM.gov check for a supplier without calling SAM.gov.\n\nReturns the most recent stored check (any status, including `error`) for the supplier\nin this company, or `{\"status\": \"unchecked\", \"supplier_id\": }` when there is none.\nNever calls SAM.gov. Only the Policies module needs to be on: it answers even if the\ncompany is not (or no longer) opted in to SAM.gov.\n\n\nNone - identical request and response.", "parameters": [ { "name": "supplier_id", "in": "path", "required": true, "description": "Supplier id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "supplier_id": { "type": "integer" }, "supplier_name": { "type": "string" }, "uei": { "type": "string" }, "status": { "type": "string" }, "total_records": { "type": "integer" }, "has_active_exclusions": { "type": "boolean" }, "exclusions": { "type": "array", "items": { } }, "search_params": { "type": "object", "properties": { "uei": { "type": "string" }, "methods": { "type": "array", "items": { "type": "string" } }, "cage_code": { "type": "string" }, "supplier_name": { "type": "string" } } }, "checked_at": { "type": "string" }, "fresh": { "type": "boolean" }, "verification_screenshot_url": { "type": "string" }, "sam_gov_search_url": { "type": "string" } } }, "example": { "id": 1, "supplier_id": 4, "supplier_name": "Fabrikam Furniture", "uei": "FABRK1234567", "status": "clear", "total_records": 0, "has_active_exclusions": false, "exclusions": [ ], "search_params": { "uei": "FABRK1234567", "methods": [ "name", "uei", "cage_code" ], "cage_code": "1ABC2", "supplier_name": "Fabrikam Furniture" }, "checked_at": "2026-10-21T03:09:15-05:00", "fresh": true, "verification_screenshot_url": "https://app.procurementexpress.com/sam-gov-evidence/download?token=eyJfcmFpbHMiOnsibWVzc2FnZSI6ImV5SjJaWEp6YVc5dUlqb3hMQ0poZFdScFpXNWpaU0k2SW1Gd2FTSXNJblZ6WlhKZmFXUWlPalF3TURBd0xDSmpiMjF3WVc1NVgybGtJam95TURBd01Dd2ljM1Z3Y0d4cFpYSmZhV1FpT2pRc0ltTm9aV05yWDJsa0lqb3hMQ0ptYVd4bFgzWmxjbk5wYjI0aU9pSXlZMk5oWXpreFpHVmpNMlprWlRnd1lXUTROREZtTVRNeFlUYzFNREpsTjJJNE9UZzBOMkk1Wm1Oa1l6WTBZelJoT0RkbVkySmhaV00wWXpFNFpqTXhJaXdpYVhOemRXVmtYMkYwSWpveE56a3lOVGMzTXpVM0xDSmxlSEJwY21WelgyRjBJam94TnpreU5UYzNOalUzZlE9PSIsImV4cCI6IjIwMjYtMTAtMjFUMTA6MTQ6MTcuMjMzWiIsInB1ciI6InNhbS1nb3YtZXZpZGVuY2Uuc2NyZWVuc2hvdC1kb3dubG9hZC52MSJ9fQ%3D%3D--38678cdfb768867c7d63326e9d0fd49c30a131627af101c21323b424c1551f2e", "sam_gov_search_url": "https://sam.gov/search/?page=1&pageSize=25&sfm%5BsimpleSearch%5D%5BkeywordRadio%5D=ALL&sfm%5BsimpleSearch%5D%5BkeywordTags%5D%5B0%5D%5Bkey%5D=FABRK1234567&sfm%5BsimpleSearch%5D%5BkeywordTags%5D%5B0%5D%5Bvalue%5D=FABRK1234567&sfm%5Bstatus%5D%5Bis_active%5D=true&sfm%5Bstatus%5D%5Bis_inactive%5D=false&sort=-modifiedDate" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/suppliers": { "get": { "tags": [ "Suppliers" ], "operationId": "v3_suppliers_list", "summary": "List suppliers", "description": "Returns the company's active (or archived) suppliers, sorted by name.\n\nReturns suppliers of the `app_company_id` company sorted case-insensitively by name.\n\n* **Archived:** only active suppliers by default; `archived=true` returns only archived ones.\n* **Search:** `search` is a case-insensitive substring match on name, email **or** phone number.\n* **Department:** `department_id` returns suppliers linked to that department plus\n suppliers with no department. An unknown department id answers `404`.\n* **Pagination** differs by version (see *Version differences*). V1 returns a bare\n array of every matching supplier unless `page` is given; then it returns\n `{suppliers: [...], meta: {...}}` with `per_page` records per page. V3 always paginates,\n 20 per page.\n\n\n* **V1** returns a bare array (all records, no limit) unless `page` is passed. With\n `page`, it returns the `{suppliers, meta}` envelope with `per_page` (10/20/50/100,\n default 10) records per page.\n* **V3** always returns the `{suppliers, meta}` envelope with a fixed 20 records per\n page and ignores `per_page`.\n* Filters, ordering, fields and errors are identical.", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Case-insensitive substring match on name, email or phone number.", "schema": { "type": "string" } }, { "name": "archived", "in": "query", "required": false, "description": "`true` returns only archived suppliers; otherwise only active ones.", "schema": { "type": "boolean" } }, { "name": "department_id", "in": "query", "required": false, "description": "Only suppliers linked to this department, plus suppliers with no department. Must be a department of the company (else 404).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "V1: enables pagination and the `{suppliers, meta}` envelope. V3: page number (default 1).", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "V1 only, with `page`: one of 10, 20, 50, 100. Any other value falls back to 10. Ignored by V3 (always 20).", "schema": { "type": "integer" } }, { "name": "show_mappings", "in": "query", "required": false, "description": "Accepted for backwards compatibility; has no effect (`third_party_id_mappings` is always included).", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "suppliers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "notes": { "type": "string" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "payment_details": { "type": "null" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "payment_terms": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "currency_id": { "type": "integer" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "external_vendor_id": { "type": "string" }, "uei": { "type": "string" }, "cage_code": { "type": "string" }, "third_party_id_mappings": { "type": "array", "items": { } } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "next_page": { "type": "null" }, "prev_page": { "type": "null" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "example": { "suppliers": [ { "id": 4, "name": "Fabrikam Furniture", "company_id": 20000, "notes": "Office furniture and fit-out", "phone_number": "+1 555 0501", "address": "12 Industrial Ave, Grand Rapids, MI 49503", "email": "orders@fabrikam.example.com", "payment_details": null, "archived": false, "contact_person": "Ana Trujillo-Reyes", "tax_number": "38-2223334", "payment_terms": "Net 60", "created_at": "2026-10-21T05:00:12.451-05:00", "updated_at": "2026-10-21T05:00:45.684-05:00", "currency_id": 2000, "department_ids": [ 2 ], "external_vendor_id": "VEND-1001", "uei": "FABRK1234567", "cage_code": "1ABC2", "third_party_id_mappings": [ ] }, { "id": 6, "name": "Litware Stationery", "company_id": 20000, "notes": null, "phone_number": null, "address": null, "email": null, "payment_details": null, "archived": false, "contact_person": null, "tax_number": null, "payment_terms": null, "created_at": "2026-10-21T05:00:20.013-05:00", "updated_at": "2026-10-21T05:00:46.216-05:00", "currency_id": null, "department_ids": [ ], "external_vendor_id": null, "uei": null, "cage_code": null, "third_party_id_mappings": [ ] } ], "meta": { "current_page": 1, "next_page": null, "prev_page": null, "total_pages": 1, "total_count": 3 } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] }, "post": { "tags": [ "Suppliers" ], "operationId": "v3_suppliers_create", "summary": "Create a supplier", "description": "Creates a supplier, or files a supplier approval request when the approval workflow is on.\n\nCreates a supplier in the `app_company_id` company and returns it (`200`).\n\n**Supplier approval workflow.** When the company setting `add_supplier_approval` is\non and the caller is **not** the user configured as `supplier_approver`, no supplier\nis created. A supplier approval request is filed and the approver(s) are emailed.\nThe response is then `200` with only a message (and, in V1, `pending_approval: true`)\nand no supplier id (`suppliers_create_pending_approval`). The request shows up in\n[GET /supplier_approvals](#suppliers-approvals).\n\n**Validation** (`400`, `error` is an array of messages):\n\n* `name` required, 1-255 characters, unique per company (case-insensitive, among\n suppliers with the same archived state): `Name must be unique.`\n* `external_vendor_id` unique per company (`External vendor has already registered`), max 64 characters.\n* `cc_emails` comma-separated valid emails, max 255 characters in total.\n* Fields listed in the company's *Mandatory supplier fields* setting, and `tax_number`\n when *Supplier tax number required* is on.\n* In approval mode the name must also not match an existing active supplier\n (`Name Supplier name must be unique.`) or another non-rejected request\n (`Name has already been taken`, from code).\n\n**Request format.** Send the attributes under a `supplier` object. With a JSON body,\ntop-level keys that are supplier attribute names are also wrapped into `supplier`\nautomatically, but always send the `supplier` wrapper. A body without any supplier\nattributes answers `400 Required parameter are missing.`\n\n**Source.** The record's `source` is taken from the optional `APP_SOURCE` header\n(default `api`). An unrecognised value currently causes a `500`.\n\n**Side effects.** Queues exports to connected accounting systems (Great Plains,\nSage 50/200, Sage Intacct). Paper-trail audit entry. In approval mode, approval\nemails are sent.\n\n\n* Approval-mode success: V1 returns `{message, pending_approval: true}`, V3 returns `{message}` only.\n* Validation errors: both `400`. V1 adds `pending_approval` (`false` for a normal create,\n `true` when the failed record was an approval request). V3 has no such key.\n* Permitted parameters, validation and permissions are identical.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "notes": { "type": "string" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "payment_details": { "type": "null" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "payment_terms": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "currency_id": { "type": "integer" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "external_vendor_id": { "type": "string" }, "uei": { "type": "string" }, "cage_code": { "type": "string" }, "third_party_id_mappings": { "type": "array", "items": { } } } }, "example": { "id": 5, "name": "Tailspin Electronics", "company_id": 20000, "notes": "Peripherals and cabling", "phone_number": "+1 555 0600", "address": "88 Circuit Blvd, San Jose, CA 95134", "email": "sales@tailspin.example.com", "payment_details": null, "archived": false, "contact_person": "Mei Chen", "tax_number": "77-4445556", "payment_terms": "Net 30", "created_at": "2026-10-21T05:00:12.726-05:00", "updated_at": "2026-10-21T05:00:12.726-05:00", "currency_id": 2000, "department_ids": [ 2 ], "external_vendor_id": "VEND-1002", "uei": "TAILS7654321", "cage_code": "9XYZ8", "third_party_id_mappings": [ ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Name must be unique.", "External vendor has already registered", "Cc emails does not appear to be a valid e-mail address" ], "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "supplier[name]": { "type": "string", "description": "Name, 1-255 characters, unique per company (case-insensitive)." }, "supplier[email]": { "type": "string", "description": "Main email (the PO is sent here). Must be a valid address. Required when listed in mandatory supplier fields." }, "supplier[cc_emails]": { "type": "string", "description": "Comma-separated CC addresses, max 255 characters. Not returned in the response." }, "supplier[address]": { "type": "string", "description": "Free-text address." }, "supplier[notes]": { "type": "string", "description": "Notes." }, "supplier[payment_details]": { "type": "string", "description": "Free-text payment details." }, "supplier[phone_number]": { "type": "string", "description": "Phone number, max 255." }, "supplier[contact_person]": { "type": "string", "description": "Contact name, max 255." }, "supplier[tax_number]": { "type": "string", "description": "Tax/VAT number, max 255. Required when the company requires tax numbers." }, "supplier[currency_id]": { "type": "integer", "description": "Default currency id. Must be an existing currency (an unknown id currently causes a 500)." }, "supplier[payment_terms]": { "type": "string", "description": "Free-text payment terms label, returned as `payment_terms`." }, "supplier[payment_term_id]": { "type": "integer", "description": "Id of one of the company's payment terms. Not returned in the response. This is the field checked when `payment_terms` is a mandatory field." }, "supplier[archived]": { "type": "boolean", "description": "Create directly as archived." }, "supplier[external_vendor_id]": { "type": "string", "description": "ERP vendor number, unique per company, max 64." }, "supplier[uei]": { "type": "string", "description": "SAM.gov Unique Entity Identifier (12 characters)." }, "supplier[cage_code]": { "type": "string", "description": "CAGE code (5 characters)." }, "supplier[department_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Departments to restrict the supplier to. Empty or omitted = available to all departments. An unknown id answers 404." }, "supplier[third_party_id_mappings_attributes][][service]": { "type": "string", "description": "Integration service: `xero`, `zapier`, `quickbooks`, `sage50`, `sage200`, `sage200_api`, `mindee`, `llm`, `greatplains`, `sage_intacct` or `lightyear` (else 400 `... is not a valid service`)." }, "supplier[third_party_id_mappings_attributes][][third_party_id]": { "type": "string", "description": "The supplier's id in that service." }, "supplier[third_party_id_mappings_attributes][][realm_id]": { "type": "string", "description": "Realm / tenant id in that service (e.g. QuickBooks realm)." }, "supplier[xero_id]": { "type": "string", "description": "Shortcut: adds a `xero` mapping with this id." }, "supplier[zapier_id]": { "type": "string", "description": "Shortcut: adds a `zapier` mapping with this id." }, "supplier[quickbooks_id]": { "type": "string", "description": "Shortcut: adds a `quickbooks` mapping with this id." }, "supplier[supplier_payment_details_attributes][][bank_name]": { "type": "string", "description": "Bank details for batch payments (sensitive; never echoed back). Also accepted: `beneficiary_id`, `bank_account_number`, `bank_country`, `bank_address_line1`, `bank_address_line2`, `bank_city`, `national_clearing_code`, `branch_name`, `sort_code`, `swift_code`, `payment_reference`, `beneficiary_classification`, and `id` (to update an existing entry)." }, "supplier[supplier_payment_details_attributes][][payment_provider_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Payment providers configured in the company. At least one is required as soon as any bank field is sent (`Supplier payment details payment provider ids required at least one provider`). Each provider decides which bank fields are then required." } }, "required": [ "supplier[name]" ] }, "example": { "supplier": { "name": "Tailspin Electronics", "email": "sales@tailspin.example.com", "cc_emails": "ar@tailspin.example.com", "address": "88 Circuit Blvd, San Jose, CA 95134", "contact_person": "Mei Chen", "phone_number": "+1 555 0600", "tax_number": "77-4445556", "currency_id": 2000, "payment_term_id": 3, "payment_terms": "Net 30", "notes": "Peripherals and cabling", "external_vendor_id": "VEND-1002", "department_ids": [ 2 ], "uei": "TAILS7654321", "cage_code": "9XYZ8" } } } } } } }, "/api/v1/suppliers": { "get": { "tags": [ "Suppliers" ], "operationId": "v1_suppliers_list", "summary": "List suppliers", "description": "Returns the company's active (or archived) suppliers, sorted by name.\n\nReturns suppliers of the `app_company_id` company sorted case-insensitively by name.\n\n* **Archived:** only active suppliers by default; `archived=true` returns only archived ones.\n* **Search:** `search` is a case-insensitive substring match on name, email **or** phone number.\n* **Department:** `department_id` returns suppliers linked to that department plus\n suppliers with no department. An unknown department id answers `404`.\n* **Pagination** differs by version (see *Version differences*). V1 returns a bare\n array of every matching supplier unless `page` is given; then it returns\n `{suppliers: [...], meta: {...}}` with `per_page` records per page. V3 always paginates,\n 20 per page.\n\n\n* **V1** returns a bare array (all records, no limit) unless `page` is passed. With\n `page`, it returns the `{suppliers, meta}` envelope with `per_page` (10/20/50/100,\n default 10) records per page.\n* **V3** always returns the `{suppliers, meta}` envelope with a fixed 20 records per\n page and ignores `per_page`.\n* Filters, ordering, fields and errors are identical.", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Case-insensitive substring match on name, email or phone number.", "schema": { "type": "string" } }, { "name": "archived", "in": "query", "required": false, "description": "`true` returns only archived suppliers; otherwise only active ones.", "schema": { "type": "boolean" } }, { "name": "department_id", "in": "query", "required": false, "description": "Only suppliers linked to this department, plus suppliers with no department. Must be a department of the company (else 404).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "V1: enables pagination and the `{suppliers, meta}` envelope. V3: page number (default 1).", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "V1 only, with `page`: one of 10, 20, 50, 100. Any other value falls back to 10. Ignored by V3 (always 20).", "schema": { "type": "integer" } }, { "name": "show_mappings", "in": "query", "required": false, "description": "Accepted for backwards compatibility; has no effect (`third_party_id_mappings` is always included).", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "notes": { "type": "string" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "payment_details": { "type": "null" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "payment_terms": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "currency_id": { "type": "integer" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "external_vendor_id": { "type": "string" }, "uei": { "type": "string" }, "cage_code": { "type": "string" }, "third_party_id_mappings": { "type": "array", "items": { } } } } }, "example": [ { "id": 4, "name": "Fabrikam Furniture", "company_id": 20000, "notes": "Office furniture and fit-out", "phone_number": "+1 555 0501", "address": "12 Industrial Ave, Grand Rapids, MI 49503", "email": "orders@fabrikam.example.com", "payment_details": null, "archived": false, "contact_person": "Ana Trujillo-Reyes", "tax_number": "38-2223334", "payment_terms": "Net 60", "created_at": "2026-10-21T05:00:12.451-05:00", "updated_at": "2026-10-21T05:00:45.684-05:00", "currency_id": 2000, "department_ids": [ 2 ], "external_vendor_id": "VEND-1001", "uei": "FABRK1234567", "cage_code": "1ABC2", "third_party_id_mappings": [ ] }, { "id": 6, "name": "Litware Stationery", "company_id": 20000, "notes": null, "phone_number": null, "address": null, "email": null, "payment_details": null, "archived": false, "contact_person": null, "tax_number": null, "payment_terms": null, "created_at": "2026-10-21T05:00:20.013-05:00", "updated_at": "2026-10-21T05:00:46.216-05:00", "currency_id": null, "department_ids": [ ], "external_vendor_id": null, "uei": null, "cage_code": null, "third_party_id_mappings": [ ] } ] } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "post": { "tags": [ "Suppliers" ], "operationId": "v1_suppliers_create", "summary": "Create a supplier", "description": "Creates a supplier, or files a supplier approval request when the approval workflow is on.\n\nCreates a supplier in the `app_company_id` company and returns it (`200`).\n\n**Supplier approval workflow.** When the company setting `add_supplier_approval` is\non and the caller is **not** the user configured as `supplier_approver`, no supplier\nis created. A supplier approval request is filed and the approver(s) are emailed.\nThe response is then `200` with only a message (and, in V1, `pending_approval: true`)\nand no supplier id (`suppliers_create_pending_approval`). The request shows up in\n[GET /supplier_approvals](#suppliers-approvals).\n\n**Validation** (`400`, `error` is an array of messages):\n\n* `name` required, 1-255 characters, unique per company (case-insensitive, among\n suppliers with the same archived state): `Name must be unique.`\n* `external_vendor_id` unique per company (`External vendor has already registered`), max 64 characters.\n* `cc_emails` comma-separated valid emails, max 255 characters in total.\n* Fields listed in the company's *Mandatory supplier fields* setting, and `tax_number`\n when *Supplier tax number required* is on.\n* In approval mode the name must also not match an existing active supplier\n (`Name Supplier name must be unique.`) or another non-rejected request\n (`Name has already been taken`, from code).\n\n**Request format.** Send the attributes under a `supplier` object. With a JSON body,\ntop-level keys that are supplier attribute names are also wrapped into `supplier`\nautomatically, but always send the `supplier` wrapper. A body without any supplier\nattributes answers `400 Required parameter are missing.`\n\n**Source.** The record's `source` is taken from the optional `APP_SOURCE` header\n(default `api`). An unrecognised value currently causes a `500`.\n\n**Side effects.** Queues exports to connected accounting systems (Great Plains,\nSage 50/200, Sage Intacct). Paper-trail audit entry. In approval mode, approval\nemails are sent.\n\n\n* Approval-mode success: V1 returns `{message, pending_approval: true}`, V3 returns `{message}` only.\n* Validation errors: both `400`. V1 adds `pending_approval` (`false` for a normal create,\n `true` when the failed record was an approval request). V3 has no such key.\n* Permitted parameters, validation and permissions are identical.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "notes": { "type": "string" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "payment_details": { "type": "null" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "payment_terms": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "currency_id": { "type": "integer" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "external_vendor_id": { "type": "string" }, "uei": { "type": "string" }, "cage_code": { "type": "string" }, "third_party_id_mappings": { "type": "array", "items": { } } } }, "example": { "id": 4, "name": "Fabrikam Furniture", "company_id": 20000, "notes": "Office furniture and fit-out", "phone_number": "+1 555 0500", "address": "12 Industrial Ave, Grand Rapids, MI 49503", "email": "orders@fabrikam.example.com", "payment_details": null, "archived": false, "contact_person": "Ana Trujillo", "tax_number": "38-2223334", "payment_terms": "Net 30", "created_at": "2026-10-21T05:00:12.451-05:00", "updated_at": "2026-10-21T05:00:12.451-05:00", "currency_id": 2000, "department_ids": [ 2, 4 ], "external_vendor_id": "VEND-1001", "uei": "FABRK1234567", "cage_code": "1ABC2", "third_party_id_mappings": [ ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Name must be unique.", "External vendor has already registered", "Cc emails does not appear to be a valid e-mail address" ], "pending_approval": false, "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "supplier[name]": { "type": "string", "description": "Name, 1-255 characters, unique per company (case-insensitive)." }, "supplier[email]": { "type": "string", "description": "Main email (the PO is sent here). Must be a valid address. Required when listed in mandatory supplier fields." }, "supplier[cc_emails]": { "type": "string", "description": "Comma-separated CC addresses, max 255 characters. Not returned in the response." }, "supplier[address]": { "type": "string", "description": "Free-text address." }, "supplier[notes]": { "type": "string", "description": "Notes." }, "supplier[payment_details]": { "type": "string", "description": "Free-text payment details." }, "supplier[phone_number]": { "type": "string", "description": "Phone number, max 255." }, "supplier[contact_person]": { "type": "string", "description": "Contact name, max 255." }, "supplier[tax_number]": { "type": "string", "description": "Tax/VAT number, max 255. Required when the company requires tax numbers." }, "supplier[currency_id]": { "type": "integer", "description": "Default currency id. Must be an existing currency (an unknown id currently causes a 500)." }, "supplier[payment_terms]": { "type": "string", "description": "Free-text payment terms label, returned as `payment_terms`." }, "supplier[payment_term_id]": { "type": "integer", "description": "Id of one of the company's payment terms. Not returned in the response. This is the field checked when `payment_terms` is a mandatory field." }, "supplier[archived]": { "type": "boolean", "description": "Create directly as archived." }, "supplier[external_vendor_id]": { "type": "string", "description": "ERP vendor number, unique per company, max 64." }, "supplier[uei]": { "type": "string", "description": "SAM.gov Unique Entity Identifier (12 characters)." }, "supplier[cage_code]": { "type": "string", "description": "CAGE code (5 characters)." }, "supplier[department_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Departments to restrict the supplier to. Empty or omitted = available to all departments. An unknown id answers 404." }, "supplier[third_party_id_mappings_attributes][][service]": { "type": "string", "description": "Integration service: `xero`, `zapier`, `quickbooks`, `sage50`, `sage200`, `sage200_api`, `mindee`, `llm`, `greatplains`, `sage_intacct` or `lightyear` (else 400 `... is not a valid service`)." }, "supplier[third_party_id_mappings_attributes][][third_party_id]": { "type": "string", "description": "The supplier's id in that service." }, "supplier[third_party_id_mappings_attributes][][realm_id]": { "type": "string", "description": "Realm / tenant id in that service (e.g. QuickBooks realm)." }, "supplier[xero_id]": { "type": "string", "description": "Shortcut: adds a `xero` mapping with this id." }, "supplier[zapier_id]": { "type": "string", "description": "Shortcut: adds a `zapier` mapping with this id." }, "supplier[quickbooks_id]": { "type": "string", "description": "Shortcut: adds a `quickbooks` mapping with this id." }, "supplier[supplier_payment_details_attributes][][bank_name]": { "type": "string", "description": "Bank details for batch payments (sensitive; never echoed back). Also accepted: `beneficiary_id`, `bank_account_number`, `bank_country`, `bank_address_line1`, `bank_address_line2`, `bank_city`, `national_clearing_code`, `branch_name`, `sort_code`, `swift_code`, `payment_reference`, `beneficiary_classification`, and `id` (to update an existing entry)." }, "supplier[supplier_payment_details_attributes][][payment_provider_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Payment providers configured in the company. At least one is required as soon as any bank field is sent (`Supplier payment details payment provider ids required at least one provider`). Each provider decides which bank fields are then required." } }, "required": [ "supplier[name]" ] }, "example": { "supplier": { "name": "Fabrikam Furniture", "email": "orders@fabrikam.example.com", "cc_emails": "ap@fabrikam.example.com, sales@fabrikam.example.com", "address": "12 Industrial Ave, Grand Rapids, MI 49503", "contact_person": "Ana Trujillo", "phone_number": "+1 555 0500", "tax_number": "38-2223334", "currency_id": 2000, "payment_term_id": 3, "payment_terms": "Net 30", "notes": "Office furniture and fit-out", "external_vendor_id": "VEND-1001", "department_ids": [ 2, 4 ], "uei": "FABRK1234567", "cage_code": "1ABC2" } } } } } } }, "/api/v3/suppliers/top": { "get": { "tags": [ "Suppliers" ], "operationId": "v3_suppliers_top", "summary": "List the caller's most used suppliers", "description": "Returns up to `top` suppliers the calling user has raised the most purchase orders with.\n\nRanks the company's suppliers by the number of purchase orders **the calling user\ncreated** with each one, and returns at most `top` of them, most used first. The\nlist is **not** padded: a user with POs to two suppliers gets two suppliers even with\n`top=5`.\n\nIf the user has no such purchase orders, it falls back to the first `top`\nsuppliers in name order, using the same `search`, `archived` and `department_id`\nfilters as [List suppliers](#suppliers) (see `suppliers_top_fallback`).\n`department_id` also applies to the ranked list. `search` applies only to the fallback.\n\n\nNone - identical request and response (V3 casts `top` to an integer before use; V1\npasses it through; both behave the same for numeric values).", "parameters": [ { "name": "top", "in": "query", "required": false, "description": "Maximum number of suppliers.", "schema": { "type": "integer" } }, { "name": "archived", "in": "query", "required": false, "description": "`true` ranks/returns archived suppliers only.", "schema": { "type": "boolean" } }, { "name": "department_id", "in": "query", "required": false, "description": "Restrict to suppliers of this department plus suppliers with no department (404 if unknown).", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "required": false, "description": "Only used by the fallback (user has no POs): substring match on name, email or phone.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "notes": { "type": "null" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "payment_details": { "type": "null" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "payment_terms": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "currency_id": { "type": "integer" }, "department_ids": { "type": "array", "items": { } }, "external_vendor_id": { "type": "null" }, "uei": { "type": "null" }, "cage_code": { "type": "null" }, "third_party_id_mappings": { "type": "array", "items": { } } } } }, "example": [ { "id": 2, "name": "Contoso Hardware", "company_id": 20000, "notes": null, "phone_number": "+1 555 0300", "address": "500 Tech Park, Austin, TX 78701", "email": "sales@contoso.example.com", "payment_details": null, "archived": false, "contact_person": "Diego Ramos", "tax_number": "74-7654321", "payment_terms": "Net 45", "created_at": "2026-10-21T04:48:43.563-05:00", "updated_at": "2026-10-21T04:48:43.563-05:00", "currency_id": 2000, "department_ids": [ ], "external_vendor_id": null, "uei": null, "cage_code": null, "third_party_id_mappings": [ ] }, { "id": 1, "name": "Northwind Office Supplies", "company_id": 20000, "notes": "Preferred stationery vendor", "phone_number": "+1 555 0200", "address": "1 Commerce Way, Chicago, IL 60601", "email": "orders@northwind.example.com", "payment_details": null, "archived": false, "contact_person": "Laura Callahan", "tax_number": "36-1234567", "payment_terms": "Net 30", "created_at": "2026-10-21T04:48:43.487-05:00", "updated_at": "2026-10-21T04:48:43.487-05:00", "currency_id": 2000, "department_ids": [ ], "external_vendor_id": null, "uei": null, "cage_code": null, "third_party_id_mappings": [ ] } ] } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] } }, "/api/v1/suppliers/top": { "get": { "tags": [ "Suppliers" ], "operationId": "v1_suppliers_top", "summary": "List the caller's most used suppliers", "description": "Returns up to `top` suppliers the calling user has raised the most purchase orders with.\n\nRanks the company's suppliers by the number of purchase orders **the calling user\ncreated** with each one, and returns at most `top` of them, most used first. The\nlist is **not** padded: a user with POs to two suppliers gets two suppliers even with\n`top=5`.\n\nIf the user has no such purchase orders, it falls back to the first `top`\nsuppliers in name order, using the same `search`, `archived` and `department_id`\nfilters as [List suppliers](#suppliers) (see `suppliers_top_fallback`).\n`department_id` also applies to the ranked list. `search` applies only to the fallback.\n\n\nNone - identical request and response (V3 casts `top` to an integer before use; V1\npasses it through; both behave the same for numeric values).", "parameters": [ { "name": "top", "in": "query", "required": false, "description": "Maximum number of suppliers.", "schema": { "type": "integer" } }, { "name": "archived", "in": "query", "required": false, "description": "`true` ranks/returns archived suppliers only.", "schema": { "type": "boolean" } }, { "name": "department_id", "in": "query", "required": false, "description": "Restrict to suppliers of this department plus suppliers with no department (404 if unknown).", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "required": false, "description": "Only used by the fallback (user has no POs): substring match on name, email or phone.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "notes": { "type": "null" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "payment_details": { "type": "null" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "payment_terms": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "currency_id": { "type": "integer" }, "department_ids": { "type": "array", "items": { } }, "external_vendor_id": { "type": "null" }, "uei": { "type": "null" }, "cage_code": { "type": "null" }, "third_party_id_mappings": { "type": "array", "items": { } } } } }, "example": [ { "id": 2, "name": "Contoso Hardware", "company_id": 20000, "notes": null, "phone_number": "+1 555 0300", "address": "500 Tech Park, Austin, TX 78701", "email": "sales@contoso.example.com", "payment_details": null, "archived": false, "contact_person": "Diego Ramos", "tax_number": "74-7654321", "payment_terms": "Net 45", "created_at": "2026-10-21T04:48:43.563-05:00", "updated_at": "2026-10-21T04:48:43.563-05:00", "currency_id": 2000, "department_ids": [ ], "external_vendor_id": null, "uei": null, "cage_code": null, "third_party_id_mappings": [ ] }, { "id": 1, "name": "Northwind Office Supplies", "company_id": 20000, "notes": "Preferred stationery vendor", "phone_number": "+1 555 0200", "address": "1 Commerce Way, Chicago, IL 60601", "email": "orders@northwind.example.com", "payment_details": null, "archived": false, "contact_person": "Laura Callahan", "tax_number": "36-1234567", "payment_terms": "Net 30", "created_at": "2026-10-21T04:48:43.487-05:00", "updated_at": "2026-10-21T04:48:43.487-05:00", "currency_id": 2000, "department_ids": [ ], "external_vendor_id": null, "uei": null, "cage_code": null, "third_party_id_mappings": [ ] } ] } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/suppliers/{id}": { "get": { "tags": [ "Suppliers" ], "operationId": "v3_suppliers_show", "summary": "Get a supplier", "description": "Returns one supplier of the company.\n\nReturns the supplier with the given id if it belongs to the `app_company_id` company\n(archived suppliers included).\n\n\nNone - identical request and response. (Authentication failures differ as for every\nendpoint: V1 answers `401 {\"error\": \"Authentication token is invalid\"}`; V3 answers\n`401` with an empty body and a `WWW-Authenticate` header.)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Supplier id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "notes": { "type": "string" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "payment_details": { "type": "null" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "payment_terms": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "currency_id": { "type": "integer" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "external_vendor_id": { "type": "string" }, "uei": { "type": "string" }, "cage_code": { "type": "string" }, "third_party_id_mappings": { "type": "array", "items": { } } } }, "example": { "id": 4, "name": "Fabrikam Furniture", "company_id": 20000, "notes": "Office furniture and fit-out", "phone_number": "+1 555 0501", "address": "12 Industrial Ave, Grand Rapids, MI 49503", "email": "orders@fabrikam.example.com", "payment_details": null, "archived": false, "contact_person": "Ana Trujillo-Reyes", "tax_number": "38-2223334", "payment_terms": "Net 60", "created_at": "2026-10-21T05:00:12.451-05:00", "updated_at": "2026-10-21T05:00:45.684-05:00", "currency_id": 2000, "department_ids": [ 2 ], "external_vendor_id": "VEND-1001", "uei": "FABRK1234567", "cage_code": "1ABC2", "third_party_id_mappings": [ ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "App company id is nil", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] }, "put": { "tags": [ "Suppliers" ], "operationId": "v3_suppliers_update", "summary": "Update a supplier", "description": "Updates the given attributes of a supplier; also used to archive and restore.\n\nUpdates only the attributes you send and returns the full supplier. Archive with\n`{\"supplier\": {\"archived\": true}}`, restore with `false` (restoring fails with\n`Name must be unique.` if an active supplier already has the same name).\n\n`supplier[department_ids][]` replaces the whole department list (send `[]` to make the\nsupplier available to all departments). `third_party_id_mappings_attributes` entries\nare **added**; existing mappings cannot be changed or removed through the API.\n\n**Supplier approval.** When the company has the multi-approver supplier approval\nfeature with at least one selected supplier approver, and the caller does not hold\nthe `supplier_admin` role, the update is refused: `403` with\n`code: \"supplier_approval_required\"`. Such edits (for example bank details) must be\nmade in the web app, where they go through approval.\n\nValidation is the same as on create, including mandatory supplier fields.\n\n\nNone - identical request and response (PUT and PATCH accepted in both).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Supplier id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "notes": { "type": "string" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "payment_details": { "type": "null" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "payment_terms": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "currency_id": { "type": "integer" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "external_vendor_id": { "type": "string" }, "uei": { "type": "string" }, "cage_code": { "type": "string" }, "third_party_id_mappings": { "type": "array", "items": { } } } }, "example": { "id": 5, "name": "Tailspin Electronics", "company_id": 20000, "notes": "Peripherals and cabling", "phone_number": "+1 555 0601", "address": "88 Circuit Blvd, San Jose, CA 95134", "email": "sales@tailspin.example.com", "payment_details": null, "archived": false, "contact_person": "Mei Chen", "tax_number": "77-4445556", "payment_terms": "Net 60", "created_at": "2026-10-21T05:00:12.726-05:00", "updated_at": "2026-10-21T05:00:45.947-05:00", "currency_id": 2000, "department_ids": [ 2, 3 ], "external_vendor_id": "VEND-1002", "uei": "TAILS7654321", "cage_code": "9XYZ8", "third_party_id_mappings": [ ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Name must be unique." ], "status": 400 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "error": "Supplier changes need approval; please edit on the web.", "code": "supplier_approval_required", "status": 403 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "supplier[...]": { "type": "object", "description": "Any of the attributes accepted by [Create a supplier](#suppliers) (same names, types and rules): `name`, `email`, `cc_emails`, `address`, `notes`, `payment_details`, `phone_number`, `archived`, `tax_number`, `contact_person`, `currency_id`, `payment_terms`, `payment_term_id`, `external_vendor_id`, `uei`, `cage_code`, `xero_id`, `zapier_id`, `quickbooks_id`, `department_ids[]`, `third_party_id_mappings_attributes[]`, `supplier_payment_details_attributes[]` (pass `id` to update an existing bank-detail entry)." }, "supplier[archived]": { "type": "boolean", "description": "`true` archives, `false` restores." }, "supplier[department_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Replaces the department list." } }, "required": [ "supplier[...]" ] }, "example": { "supplier": { "contact_person": "Mei Chen", "phone_number": "+1 555 0601", "payment_term_id": 4, "payment_terms": "Net 60", "department_ids": [ 2, 3 ] } } } } } } }, "/api/v1/suppliers/{id}": { "get": { "tags": [ "Suppliers" ], "operationId": "v1_suppliers_show", "summary": "Get a supplier", "description": "Returns one supplier of the company.\n\nReturns the supplier with the given id if it belongs to the `app_company_id` company\n(archived suppliers included).\n\n\nNone - identical request and response. (Authentication failures differ as for every\nendpoint: V1 answers `401 {\"error\": \"Authentication token is invalid\"}`; V3 answers\n`401` with an empty body and a `WWW-Authenticate` header.)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Supplier id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "notes": { "type": "string" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "payment_details": { "type": "null" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "payment_terms": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "currency_id": { "type": "integer" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "external_vendor_id": { "type": "string" }, "uei": { "type": "string" }, "cage_code": { "type": "string" }, "third_party_id_mappings": { "type": "array", "items": { } } } }, "example": { "id": 4, "name": "Fabrikam Furniture", "company_id": 20000, "notes": "Office furniture and fit-out", "phone_number": "+1 555 0501", "address": "12 Industrial Ave, Grand Rapids, MI 49503", "email": "orders@fabrikam.example.com", "payment_details": null, "archived": false, "contact_person": "Ana Trujillo-Reyes", "tax_number": "38-2223334", "payment_terms": "Net 60", "created_at": "2026-10-21T05:00:12.451-05:00", "updated_at": "2026-10-21T05:00:45.684-05:00", "currency_id": 2000, "department_ids": [ 2 ], "external_vendor_id": "VEND-1001", "uei": "FABRK1234567", "cage_code": "1ABC2", "third_party_id_mappings": [ ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "App company id is nil", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "put": { "tags": [ "Suppliers" ], "operationId": "v1_suppliers_update", "summary": "Update a supplier", "description": "Updates the given attributes of a supplier; also used to archive and restore.\n\nUpdates only the attributes you send and returns the full supplier. Archive with\n`{\"supplier\": {\"archived\": true}}`, restore with `false` (restoring fails with\n`Name must be unique.` if an active supplier already has the same name).\n\n`supplier[department_ids][]` replaces the whole department list (send `[]` to make the\nsupplier available to all departments). `third_party_id_mappings_attributes` entries\nare **added**; existing mappings cannot be changed or removed through the API.\n\n**Supplier approval.** When the company has the multi-approver supplier approval\nfeature with at least one selected supplier approver, and the caller does not hold\nthe `supplier_admin` role, the update is refused: `403` with\n`code: \"supplier_approval_required\"`. Such edits (for example bank details) must be\nmade in the web app, where they go through approval.\n\nValidation is the same as on create, including mandatory supplier fields.\n\n\nNone - identical request and response (PUT and PATCH accepted in both).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Supplier id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company_id": { "type": "integer" }, "notes": { "type": "string" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "payment_details": { "type": "null" }, "archived": { "type": "boolean" }, "contact_person": { "type": "string" }, "tax_number": { "type": "string" }, "payment_terms": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "currency_id": { "type": "integer" }, "department_ids": { "type": "array", "items": { "type": "integer" } }, "external_vendor_id": { "type": "string" }, "uei": { "type": "string" }, "cage_code": { "type": "string" }, "third_party_id_mappings": { "type": "array", "items": { } } } }, "example": { "id": 4, "name": "Fabrikam Furniture", "company_id": 20000, "notes": "Office furniture and fit-out", "phone_number": "+1 555 0501", "address": "12 Industrial Ave, Grand Rapids, MI 49503", "email": "orders@fabrikam.example.com", "payment_details": null, "archived": false, "contact_person": "Ana Trujillo-Reyes", "tax_number": "38-2223334", "payment_terms": "Net 60", "created_at": "2026-10-21T05:00:12.451-05:00", "updated_at": "2026-10-21T05:00:45.684-05:00", "currency_id": 2000, "department_ids": [ 2 ], "external_vendor_id": "VEND-1001", "uei": "FABRK1234567", "cage_code": "1ABC2", "third_party_id_mappings": [ ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Name must be unique." ], "status": 400 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "error": "Supplier changes need approval; please edit on the web.", "code": "supplier_approval_required", "status": 403 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "supplier[...]": { "type": "object", "description": "Any of the attributes accepted by [Create a supplier](#suppliers) (same names, types and rules): `name`, `email`, `cc_emails`, `address`, `notes`, `payment_details`, `phone_number`, `archived`, `tax_number`, `contact_person`, `currency_id`, `payment_terms`, `payment_term_id`, `external_vendor_id`, `uei`, `cage_code`, `xero_id`, `zapier_id`, `quickbooks_id`, `department_ids[]`, `third_party_id_mappings_attributes[]`, `supplier_payment_details_attributes[]` (pass `id` to update an existing bank-detail entry)." }, "supplier[archived]": { "type": "boolean", "description": "`true` archives, `false` restores." }, "supplier[department_ids][]": { "type": "array", "items": { "type": "integer" }, "description": "Replaces the department list." } }, "required": [ "supplier[...]" ] }, "example": { "supplier": { "contact_person": "Ana Trujillo-Reyes", "phone_number": "+1 555 0501", "payment_term_id": 4, "payment_terms": "Net 60", "department_ids": [ 2 ] } } } } } } }, "/api/v1/supplier_approvals": { "get": { "tags": [ "Suppliers: Approvals" ], "operationId": "v1_supplier_approvals_list", "summary": "List supplier approval requests", "description": "Returns the company's supplier approval requests (all statuses), 10 per page.\n\nLists every supplier approval request of the company (pending, approved and rejected),\noldest `updated_at` first, paginated with a fixed 10 records per page.\n\nRequires the **Supplier approval** company setting and API access enabled by support\n(see the section intro). Otherwise the endpoint answers `400` with the messages\nshown in the errors table.\n\nThe `search` parameter is currently broken and answers `500` for any non-empty\nvalue (see `supplier_approvals_list_search`). Do not send it.\n\n\nV1 only. The route does not exist in V3: `GET /api/v3/supplier_approvals` answers\n`404 {\"error\": \"Invalid URL\"}` (`supplier_approvals_list_v3_absent`).", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number (10 per page, not configurable).", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "required": false, "description": "Intended to filter by name/email/phone. Currently answers 500 (bug), do not use.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "supplier_approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "notes": { "type": "null" }, "phone_number": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "status": { "type": "string" }, "requester": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string" } } } }, "approver": { "type": "object", "properties": { } }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "uei": { "type": "string" }, "cage_code": { "type": "null" } } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "next_page": { "type": "null" }, "prev_page": { "type": "null" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } } } }, "example": { "supplier_approvals": [ { "id": 1, "name": "Proseware Labs", "notes": null, "phone_number": "+1 555 0700", "address": "5 Research Park, Durham, NC 27709", "email": "accounts@proseware.example.com", "status": "pending", "requester": { "id": 41000, "email": "sam.smith@example.com", "name": "Sam Smith", "roles": [ "teammember" ] }, "approver": { }, "created_at": 1792576974, "updated_at": 1792576974, "uei": "PROSE1234567", "cage_code": null }, { "id": 2, "name": "Adventure Works Cycles", "notes": null, "phone_number": "+1 555 0800", "address": "1 Trail Road, Bend, OR 97701", "email": "b2b@adventure-works.example.com", "status": "pending", "requester": { "id": 41000, "email": "sam.smith@example.com", "name": "Sam Smith", "roles": [ "teammember" ] }, "approver": { }, "created_at": 1792576974, "updated_at": 1792576974, "uei": null, "cage_code": null } ], "meta": { "current_page": 1, "next_page": null, "prev_page": null, "total_pages": 1, "total_count": 2 } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "Please enable supplier approval setting from your company setting, Supplier tab.", "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] } }, "/api/v3/tax_rates": { "get": { "tags": [ "Tax Rates" ], "operationId": "v3_tax_rate_list", "summary": "List tax rates", "description": "Returns all active (or archived) tax rates of the company.\n\nReturns every tax rate of the company, ordered by name, not paginated.\nBy default only active rates are returned; `archived` switches to archived\nrates - but the two versions parse it differently:\n\n* **V1** casts it as a boolean: `true`/`1` -> archived, `false`/`0` or\n absent -> active.\n* **V3** checks only whether the parameter is present: **any** value,\n including `archived=false`, returns the archived rates. Omit the parameter\n to get active rates.\n\n\nSame envelope and fields. `archived=false` differs: V1 returns active rates,\nV3 returns archived rates (see `tax_rate_list_archived_false`).", "parameters": [ { "name": "archived", "in": "query", "required": false, "description": "Archived instead of active rates. V3: any non-empty value (even `false`) means archived - omit it for active rates.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "value": { "type": "number" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" }, "tax_type": { "type": "string" }, "tax_rate_items": { "type": "null" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } }, "example": [ { "id": 4, "name": "Sales Tax", "value": 8.875, "archived": false, "company_id": 20000, "tax_type": "single", "tax_rate_items": null, "created_at": "2026-10-21T04:48:43.422-05:00", "updated_at": "2026-10-21T04:48:43.422-05:00" }, { "id": 5, "name": "Zero Rated", "value": 0.0, "archived": false, "company_id": 20000, "tax_type": "single", "tax_rate_items": null, "created_at": "2026-10-21T04:48:43.426-05:00", "updated_at": "2026-10-21T04:48:43.426-05:00" } ] } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] }, "post": { "tags": [ "Tax Rates" ], "operationId": "v3_tax_rate_create", "summary": "Create a tax rate", "description": "Creates a single tax rate.\n\nCreates a `single` tax rate in the header company. Combined rates cannot be\ncreated through the API (`tax_type` and component ids are not accepted).\nCreation is refused while the company has an active QuickBooks Online\nconnection or Sage 50 / Sage 200 is connected, because rates are then\nsynced from the accounting system.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "value": { "type": "number" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" }, "tax_type": { "type": "string" }, "tax_rate_items": { "type": "null" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "example": { "id": 27, "name": "City Tax", "value": 2.5, "archived": false, "company_id": 20000, "tax_type": "single", "tax_rate_items": null, "created_at": "2026-10-21T05:04:59.768-05:00", "updated_at": "2026-10-21T05:04:59.768-05:00" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Name can't be blank", "Value Not greater than 100" ], "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tax_rate[name]": { "type": "string", "description": "Display name." }, "tax_rate[value]": { "type": "number", "description": "Percentage, at most 100 (`Value Not greater than 100`)." }, "tax_rate[archived]": { "type": "boolean", "description": "Create the rate already archived." }, "tax_rate[company_id]": { "type": "integer", "description": "Ignored - the company always comes from the `app_company_id` header." } }, "required": [ "tax_rate[name]", "tax_rate[value]" ] }, "example": { "tax_rate": { "name": "City Tax", "value": 2.5 } } } } } } }, "/api/v1/tax_rates": { "get": { "tags": [ "Tax Rates" ], "operationId": "v1_tax_rate_list", "summary": "List tax rates", "description": "Returns all active (or archived) tax rates of the company.\n\nReturns every tax rate of the company, ordered by name, not paginated.\nBy default only active rates are returned; `archived` switches to archived\nrates - but the two versions parse it differently:\n\n* **V1** casts it as a boolean: `true`/`1` -> archived, `false`/`0` or\n absent -> active.\n* **V3** checks only whether the parameter is present: **any** value,\n including `archived=false`, returns the archived rates. Omit the parameter\n to get active rates.\n\n\nSame envelope and fields. `archived=false` differs: V1 returns active rates,\nV3 returns archived rates (see `tax_rate_list_archived_false`).", "parameters": [ { "name": "archived", "in": "query", "required": false, "description": "Archived instead of active rates. V3: any non-empty value (even `false`) means archived - omit it for active rates.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "value": { "type": "number" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" }, "tax_type": { "type": "string" }, "tax_rate_items": { "type": "null" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } }, "example": [ { "id": 4, "name": "Sales Tax", "value": 8.875, "archived": false, "company_id": 20000, "tax_type": "single", "tax_rate_items": null, "created_at": "2026-10-21T04:48:43.422-05:00", "updated_at": "2026-10-21T04:48:43.422-05:00" }, { "id": 5, "name": "Zero Rated", "value": 0.0, "archived": false, "company_id": 20000, "tax_type": "single", "tax_rate_items": null, "created_at": "2026-10-21T04:48:43.426-05:00", "updated_at": "2026-10-21T04:48:43.426-05:00" } ] } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "post": { "tags": [ "Tax Rates" ], "operationId": "v1_tax_rate_create", "summary": "Create a tax rate", "description": "Creates a single tax rate.\n\nCreates a `single` tax rate in the header company. Combined rates cannot be\ncreated through the API (`tax_type` and component ids are not accepted).\nCreation is refused while the company has an active QuickBooks Online\nconnection or Sage 50 / Sage 200 is connected, because rates are then\nsynced from the accounting system.\n\n\nNone - identical request and response.", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "value": { "type": "number" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" }, "tax_type": { "type": "string" }, "tax_rate_items": { "type": "null" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "example": { "id": 26, "name": "State Tax", "value": 6.25, "archived": false, "company_id": 20000, "tax_type": "single", "tax_rate_items": null, "created_at": "2026-10-21T05:04:59.495-05:00", "updated_at": "2026-10-21T05:04:59.495-05:00" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Name can't be blank", "Value Not greater than 100" ], "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tax_rate[name]": { "type": "string", "description": "Display name." }, "tax_rate[value]": { "type": "number", "description": "Percentage, at most 100 (`Value Not greater than 100`)." }, "tax_rate[archived]": { "type": "boolean", "description": "Create the rate already archived." }, "tax_rate[company_id]": { "type": "integer", "description": "Ignored - the company always comes from the `app_company_id` header." } }, "required": [ "tax_rate[name]", "tax_rate[value]" ] }, "example": { "tax_rate": { "name": "State Tax", "value": 6.25 } } } } } } }, "/api/v3/tax_rates/{id}": { "get": { "tags": [ "Tax Rates" ], "operationId": "v3_tax_rate_show", "summary": "Get a tax rate", "description": "Returns one tax rate, including archived ones and combined-rate components.\n\nReturns a tax rate of the company by id (archived included). For a combined\nrate, `tax_rate_items` lists the component rates.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tax rate id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "value": { "type": "number" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" }, "tax_type": { "type": "string" }, "tax_rate_items": { "type": "null" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "example": { "id": 4, "name": "Sales Tax", "value": 8.875, "archived": false, "company_id": 20000, "tax_type": "single", "tax_rate_items": null, "created_at": "2026-10-21T04:48:43.422-05:00", "updated_at": "2026-10-21T04:48:43.422-05:00" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] }, "put": { "tags": [ "Tax Rates" ], "operationId": "v3_tax_rate_update", "summary": "Update a tax rate", "description": "Renames, re-values or (un)archives a tax rate.\n\nPartial update of `name`, `value` and `archived`. Archiving is done here\n(`archived: true`); the company's default tax rate cannot be archived\n(400 `The default tax rate cannot be archived as at least one tax rate must\nbe available to create a new purchase order.`). For a combined rate a sent\n`value` is ignored: the value is always recomputed from the components.\nChanging the name or value of a rate synced to Xero removes its Xero mapping.\nAllowed even while an accounting system is connected.\n\n\nNone - identical request and response; PUT and PATCH both accepted.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tax rate id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "value": { "type": "number" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" }, "tax_type": { "type": "string" }, "tax_rate_items": { "type": "null" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "example": { "id": 27, "name": "City Tax 2.75%", "value": 2.75, "archived": false, "company_id": 20000, "tax_type": "single", "tax_rate_items": null, "created_at": "2026-10-21T05:04:59.768-05:00", "updated_at": "2026-10-21T05:05:26.074-05:00" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Value Not greater than 100" ], "status": 400 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tax_rate[name]": { "type": "string", "description": "Display name (cannot be blank)." }, "tax_rate[value]": { "type": "number", "description": "Percentage, at most 100. Ignored for combined rates." }, "tax_rate[archived]": { "type": "boolean", "description": "`true` archives, `false` restores. Not allowed for the company default rate." }, "tax_rate[company_id]": { "type": "integer", "description": "Ignored." } } }, "example": { "tax_rate": { "name": "City Tax 2.75%", "value": 2.75 } } } } } } }, "/api/v1/tax_rates/{id}": { "get": { "tags": [ "Tax Rates" ], "operationId": "v1_tax_rate_show", "summary": "Get a tax rate", "description": "Returns one tax rate, including archived ones and combined-rate components.\n\nReturns a tax rate of the company by id (archived included). For a combined\nrate, `tax_rate_items` lists the component rates.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tax rate id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "value": { "type": "number" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" }, "tax_type": { "type": "string" }, "tax_rate_items": { "type": "null" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "example": { "id": 4, "name": "Sales Tax", "value": 8.875, "archived": false, "company_id": 20000, "tax_type": "single", "tax_rate_items": null, "created_at": "2026-10-21T04:48:43.422-05:00", "updated_at": "2026-10-21T04:48:43.422-05:00" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "put": { "tags": [ "Tax Rates" ], "operationId": "v1_tax_rate_update", "summary": "Update a tax rate", "description": "Renames, re-values or (un)archives a tax rate.\n\nPartial update of `name`, `value` and `archived`. Archiving is done here\n(`archived: true`); the company's default tax rate cannot be archived\n(400 `The default tax rate cannot be archived as at least one tax rate must\nbe available to create a new purchase order.`). For a combined rate a sent\n`value` is ignored: the value is always recomputed from the components.\nChanging the name or value of a rate synced to Xero removes its Xero mapping.\nAllowed even while an accounting system is connected.\n\n\nNone - identical request and response; PUT and PATCH both accepted.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tax rate id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "value": { "type": "number" }, "archived": { "type": "boolean" }, "company_id": { "type": "integer" }, "tax_type": { "type": "string" }, "tax_rate_items": { "type": "null" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "example": { "id": 26, "name": "State Tax 6.5%", "value": 6.5, "archived": false, "company_id": 20000, "tax_type": "single", "tax_rate_items": null, "created_at": "2026-10-21T05:04:59.495-05:00", "updated_at": "2026-10-21T05:05:25.862-05:00" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Value Not greater than 100" ], "status": 400 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tax_rate[name]": { "type": "string", "description": "Display name (cannot be blank)." }, "tax_rate[value]": { "type": "number", "description": "Percentage, at most 100. Ignored for combined rates." }, "tax_rate[archived]": { "type": "boolean", "description": "`true` archives, `false` restores. Not allowed for the company default rate." }, "tax_rate[company_id]": { "type": "integer", "description": "Ignored." } } }, "example": { "tax_rate": { "name": "State Tax 6.5%", "value": 6.5 } } } } } } }, "/api/v3/currentuser": { "get": { "tags": [ "Users" ], "operationId": "v3_users_current", "summary": "Get the current user", "description": "Returns the user the credential acts as, with every company membership and the roles in each.\n\nFor a V3 client credentials token this is the owner of the OAuth application.\n`app_company_id` is optional (when sent it only selects which company's 2FA rule\napplies). The response never contains the `authentication_token`.\n\nTo check whether the company you act in is the user's default company, compare\n`employer_id` with your `app_company_id`.\n\n\nSame body. V3 ignores `slim_companies` (always full company entries - see the\n`users_current_slim_companies` pair).", "parameters": [ { "name": "slim_companies", "in": "query", "required": false, "description": "V1 only: any non-empty value reduces every company except `employer_id` to `{id, name, is_removed}`. Ignored by V3.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" }, "approver_name": { "type": "string" }, "phone_number": { "type": "string" }, "setup_incomplete": { "type": "boolean" }, "employer_id": { "type": "integer" }, "approval_limit": { "type": "number" }, "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "external_user_id": { "type": "null" }, "membership_archived": { "type": "boolean" }, "is_locked": { "type": "boolean" }, "is_removed": { "type": "boolean" }, "approval_limit": { "type": "number" }, "in_trial": { "type": "boolean" }, "trial_expired": { "type": "boolean" }, "remaining_trial_days": { "type": "integer" }, "roles": { "type": "array", "items": { "type": "string" } }, "has_unassigned_budgets": { "type": "boolean" } } } }, "roles": { "type": "null" }, "external_user_id": { "type": "null" } } }, "example": { "id": 40000, "email": "jane.doe@example.com", "name": "Jane Doe", "approver_name": "Jane Doe", "phone_number": "+1 555 0140", "setup_incomplete": false, "employer_id": 20000, "approval_limit": 1000000.0, "companies": [ { "id": 20000, "name": "Acme Corporation", "external_user_id": null, "membership_archived": false, "is_locked": false, "is_removed": false, "approval_limit": 1000000.0, "in_trial": true, "trial_expired": false, "remaining_trial_days": 365, "roles": [ "companyadmin", "approver", "finance", "teammember" ], "has_unassigned_budgets": true } ], "roles": null, "external_user_id": null } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] }, "put": { "tags": [ "Users" ], "operationId": "v3_users_current_update", "summary": "Update the current user", "description": "Change the current user's name, phone number, password or e-mail address.\n\nUpdates only the fields you send. Rules:\n\n* **Password**: send `password`, `password_confirmation` and `current_password`.\n Without a correct `current_password`: `422 Current password is incorrect.`\n (counts towards lockout). Accounts that never set a password need no current\n password.\n* **E-mail**: not changed directly. A confirmation link is e-mailed to the new\n address; the response shows the current address and has the header\n `X-Email-Change-Pending: true`. Sending the current address is a no-op. An invalid\n address or a second request within a minute answers `422 This email change is\n invalid or has expired. Please start a new request.`\n* `name` is split on spaces into first and last name (only the first two words are\n kept); prefer `first_name` / `last_name`.\n* Validation errors answer 400 with the first message, e.g.\n `Last name can't be blank`.\n\n\nNone - identical request and response (both accept PUT and POST).", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" }, "approver_name": { "type": "string" }, "phone_number": { "type": "string" }, "setup_incomplete": { "type": "boolean" }, "employer_id": { "type": "integer" }, "approval_limit": { "type": "number" }, "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "external_user_id": { "type": "null" }, "membership_archived": { "type": "boolean" }, "is_locked": { "type": "boolean" }, "is_removed": { "type": "boolean" }, "approval_limit": { "type": "number" }, "in_trial": { "type": "boolean" }, "trial_expired": { "type": "boolean" }, "remaining_trial_days": { "type": "integer" }, "roles": { "type": "array", "items": { "type": "string" } }, "has_unassigned_budgets": { "type": "boolean" } } } }, "roles": { "type": "null" }, "external_user_id": { "type": "null" } } }, "example": { "id": 4, "email": "lee.login@example.com", "name": "Lee Login", "approver_name": "Lee Login", "phone_number": "+15550102", "setup_incomplete": false, "employer_id": 3, "approval_limit": 1000000.0, "companies": [ { "id": 3, "name": "Lee Workshop", "external_user_id": null, "membership_archived": false, "is_locked": false, "is_removed": false, "approval_limit": 1000000.0, "in_trial": true, "trial_expired": false, "remaining_trial_days": 365, "roles": [ "companyadmin", "approver", "finance", "teammember" ], "has_unassigned_budgets": false } ], "roles": null, "external_user_id": null } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "Last name can't be blank", "status": 400 } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "example": { "error": "Current password is incorrect.", "status": 422 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Two-factor authentication is required for this company. Sign in again with your one-time code.", "otp_required": true, "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "description": "Max 80 characters; HTML is stripped." }, "last_name": { "type": "string", "description": "Max 80 characters; cannot be blank." }, "name": { "type": "string", "description": "Full name, split into first and last name." }, "phone_number": { "type": "string", "description": "Max 30 characters; stored in E.164 form." }, "email": { "type": "string", "description": "New e-mail address; starts the confirmation flow (see description)." }, "password": { "type": "string", "description": "New password (min 9 characters, lowercase letter, digit, uppercase or special character)." }, "password_confirmation": { "type": "string", "description": "Must equal `password`." }, "current_password": { "type": "string", "description": "Required with `password` / `password_confirmation`." }, "country": { "type": "string", "description": "Country code." }, "terms_of_service": { "type": "string", "description": "Accepted but not meaningful after sign-up." }, "ip": { "type": "string", "description": "Accepted (stored)." }, "user_policy_time": { "type": "string", "description": "Accepted (policy acceptance time)." }, "user_policy_url[]": { "type": "array", "items": { "type": "string" }, "description": "Accepted (accepted policy URLs)." } } }, "example": { "first_name": "Lee", "last_name": "Login", "phone_number": "+1 555 0102" } } } } } }, "/api/v1/currentuser": { "get": { "tags": [ "Users" ], "operationId": "v1_users_current", "summary": "Get the current user", "description": "Returns the user the credential acts as, with every company membership and the roles in each.\n\nFor a V3 client credentials token this is the owner of the OAuth application.\n`app_company_id` is optional (when sent it only selects which company's 2FA rule\napplies). The response never contains the `authentication_token`.\n\nTo check whether the company you act in is the user's default company, compare\n`employer_id` with your `app_company_id`.\n\n\nSame body. V3 ignores `slim_companies` (always full company entries - see the\n`users_current_slim_companies` pair).", "parameters": [ { "name": "slim_companies", "in": "query", "required": false, "description": "V1 only: any non-empty value reduces every company except `employer_id` to `{id, name, is_removed}`. Ignored by V3.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" }, "approver_name": { "type": "string" }, "phone_number": { "type": "string" }, "setup_incomplete": { "type": "boolean" }, "employer_id": { "type": "integer" }, "approval_limit": { "type": "number" }, "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "external_user_id": { "type": "null" }, "membership_archived": { "type": "boolean" }, "is_locked": { "type": "boolean" }, "is_removed": { "type": "boolean" }, "approval_limit": { "type": "number" }, "in_trial": { "type": "boolean" }, "trial_expired": { "type": "boolean" }, "remaining_trial_days": { "type": "integer" }, "roles": { "type": "array", "items": { "type": "string" } }, "has_unassigned_budgets": { "type": "boolean" } } } }, "roles": { "type": "null" }, "external_user_id": { "type": "null" } } }, "example": { "id": 40000, "email": "jane.doe@example.com", "name": "Jane Doe", "approver_name": "Jane Doe", "phone_number": "+1 555 0140", "setup_incomplete": false, "employer_id": 20000, "approval_limit": 1000000.0, "companies": [ { "id": 20000, "name": "Acme Corporation", "external_user_id": null, "membership_archived": false, "is_locked": false, "is_removed": false, "approval_limit": 1000000.0, "in_trial": true, "trial_expired": false, "remaining_trial_days": 365, "roles": [ "companyadmin", "approver", "finance", "teammember" ], "has_unassigned_budgets": true } ], "roles": null, "external_user_id": null } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Authentication token is nil", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "put": { "tags": [ "Users" ], "operationId": "v1_users_current_update", "summary": "Update the current user", "description": "Change the current user's name, phone number, password or e-mail address.\n\nUpdates only the fields you send. Rules:\n\n* **Password**: send `password`, `password_confirmation` and `current_password`.\n Without a correct `current_password`: `422 Current password is incorrect.`\n (counts towards lockout). Accounts that never set a password need no current\n password.\n* **E-mail**: not changed directly. A confirmation link is e-mailed to the new\n address; the response shows the current address and has the header\n `X-Email-Change-Pending: true`. Sending the current address is a no-op. An invalid\n address or a second request within a minute answers `422 This email change is\n invalid or has expired. Please start a new request.`\n* `name` is split on spaces into first and last name (only the first two words are\n kept); prefer `first_name` / `last_name`.\n* Validation errors answer 400 with the first message, e.g.\n `Last name can't be blank`.\n\n\nNone - identical request and response (both accept PUT and POST).", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" }, "approver_name": { "type": "string" }, "phone_number": { "type": "string" }, "setup_incomplete": { "type": "boolean" }, "employer_id": { "type": "integer" }, "approval_limit": { "type": "number" }, "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "external_user_id": { "type": "null" }, "membership_archived": { "type": "boolean" }, "is_locked": { "type": "boolean" }, "is_removed": { "type": "boolean" }, "approval_limit": { "type": "number" }, "in_trial": { "type": "boolean" }, "trial_expired": { "type": "boolean" }, "remaining_trial_days": { "type": "integer" }, "roles": { "type": "array", "items": { "type": "string" } }, "has_unassigned_budgets": { "type": "boolean" } } } }, "roles": { "type": "null" }, "external_user_id": { "type": "null" } } }, "example": { "id": 4, "email": "lee.login@example.com", "name": "Leland Login", "approver_name": "Leland Login", "phone_number": "+15550101", "setup_incomplete": false, "employer_id": 3, "approval_limit": 1000000.0, "companies": [ { "id": 3, "name": "Lee Workshop", "external_user_id": null, "membership_archived": false, "is_locked": false, "is_removed": false, "approval_limit": 1000000.0, "in_trial": true, "trial_expired": false, "remaining_trial_days": 365, "roles": [ "companyadmin", "approver", "finance", "teammember" ], "has_unassigned_budgets": false } ], "roles": null, "external_user_id": null } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": "Last name can't be blank", "status": 400 } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "example": { "error": "Current password is incorrect.", "status": 422 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "description": "Max 80 characters; HTML is stripped." }, "last_name": { "type": "string", "description": "Max 80 characters; cannot be blank." }, "name": { "type": "string", "description": "Full name, split into first and last name." }, "phone_number": { "type": "string", "description": "Max 30 characters; stored in E.164 form." }, "email": { "type": "string", "description": "New e-mail address; starts the confirmation flow (see description)." }, "password": { "type": "string", "description": "New password (min 9 characters, lowercase letter, digit, uppercase or special character)." }, "password_confirmation": { "type": "string", "description": "Must equal `password`." }, "current_password": { "type": "string", "description": "Required with `password` / `password_confirmation`." }, "country": { "type": "string", "description": "Country code." }, "terms_of_service": { "type": "string", "description": "Accepted but not meaningful after sign-up." }, "ip": { "type": "string", "description": "Accepted (stored)." }, "user_policy_time": { "type": "string", "description": "Accepted (policy acceptance time)." }, "user_policy_url[]": { "type": "array", "items": { "type": "string" }, "description": "Accepted (accepted policy URLs)." } } }, "example": { "first_name": "Leland", "last_name": "Login", "phone_number": "+1 555 0101" } } } } } }, "/api/v3/users/{id}": { "put": { "tags": [ "Users" ], "operationId": "v3_users_update", "summary": "Update the current user (by id)", "description": "Alias of PUT /currentuser; the id in the path is ignored.\n\nRuns exactly the same action as `PUT /currentuser` (same parameters, rules and\nresponse). The `:id` path segment is **not used**: the request always updates the\nuser the credential acts as, even if another user's id is given. Prefer\n`PUT /currentuser`.\n\n\nNone - identical request and response (PUT and PATCH in both).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ignored; pass the current user's id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" }, "approver_name": { "type": "string" }, "phone_number": { "type": "string" }, "setup_incomplete": { "type": "boolean" }, "employer_id": { "type": "integer" }, "approval_limit": { "type": "number" }, "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "external_user_id": { "type": "null" }, "membership_archived": { "type": "boolean" }, "is_locked": { "type": "boolean" }, "is_removed": { "type": "boolean" }, "approval_limit": { "type": "number" }, "in_trial": { "type": "boolean" }, "trial_expired": { "type": "boolean" }, "remaining_trial_days": { "type": "integer" }, "roles": { "type": "array", "items": { "type": "string" } }, "has_unassigned_budgets": { "type": "boolean" } } } }, "roles": { "type": "null" }, "external_user_id": { "type": "null" } } }, "example": { "id": 4, "email": "lee.login@example.com", "name": "Lee Login", "approver_name": "Lee Login", "phone_number": "+15550104", "setup_incomplete": false, "employer_id": 3, "approval_limit": 1000000.0, "companies": [ { "id": 3, "name": "Lee Workshop", "external_user_id": null, "membership_archived": false, "is_locked": false, "is_removed": false, "approval_limit": 1000000.0, "in_trial": true, "trial_expired": false, "remaining_trial_days": 365, "roles": [ "companyadmin", "approver", "finance", "teammember" ], "has_unassigned_budgets": false } ], "roles": null, "external_user_id": null } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "description": "See `PUT /currentuser` for every accepted field." }, "last_name": { "type": "string", "description": "See `PUT /currentuser`." }, "phone_number": { "type": "string", "description": "See `PUT /currentuser`." } } }, "example": { "phone_number": "+1 555 0104" } } } } } }, "/api/v1/users/{id}": { "put": { "tags": [ "Users" ], "operationId": "v1_users_update", "summary": "Update the current user (by id)", "description": "Alias of PUT /currentuser; the id in the path is ignored.\n\nRuns exactly the same action as `PUT /currentuser` (same parameters, rules and\nresponse). The `:id` path segment is **not used**: the request always updates the\nuser the credential acts as, even if another user's id is given. Prefer\n`PUT /currentuser`.\n\n\nNone - identical request and response (PUT and PATCH in both).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ignored; pass the current user's id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" }, "approver_name": { "type": "string" }, "phone_number": { "type": "string" }, "setup_incomplete": { "type": "boolean" }, "employer_id": { "type": "integer" }, "approval_limit": { "type": "number" }, "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "external_user_id": { "type": "null" }, "membership_archived": { "type": "boolean" }, "is_locked": { "type": "boolean" }, "is_removed": { "type": "boolean" }, "approval_limit": { "type": "number" }, "in_trial": { "type": "boolean" }, "trial_expired": { "type": "boolean" }, "remaining_trial_days": { "type": "integer" }, "roles": { "type": "array", "items": { "type": "string" } }, "has_unassigned_budgets": { "type": "boolean" } } } }, "roles": { "type": "null" }, "external_user_id": { "type": "null" } } }, "example": { "id": 4, "email": "lee.login@example.com", "name": "Lee Login", "approver_name": "Lee Login", "phone_number": "+15550103", "setup_incomplete": false, "employer_id": 3, "approval_limit": 1000000.0, "companies": [ { "id": 3, "name": "Lee Workshop", "external_user_id": null, "membership_archived": false, "is_locked": false, "is_removed": false, "approval_limit": 1000000.0, "in_trial": true, "trial_expired": false, "remaining_trial_days": 365, "roles": [ "companyadmin", "approver", "finance", "teammember" ], "has_unassigned_budgets": false } ], "roles": null, "external_user_id": null } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "description": "See `PUT /currentuser` for every accepted field." }, "last_name": { "type": "string", "description": "See `PUT /currentuser`." }, "phone_number": { "type": "string", "description": "See `PUT /currentuser`." } } }, "example": { "phone_number": "+1 555 0103" } } } } } }, "/api/v3/webhooks": { "get": { "tags": [ "Webhooks" ], "operationId": "v3_webhook_list", "summary": "List webhook subscriptions", "description": "Returns the company's webhook subscriptions, non-archived by default.\n\nReturns every subscription of the company in the `app_company_id` header in one unpaginated\narray, **newest first** (by creation time). By default only active (non-archived)\nsubscriptions are listed; use `archived` to list the disabled ones.\n\nThe list items are the short form of the subscription (no `send_as_text`,\n`basic_auth_uname` or `webhook_attributes` – use `GET /webhooks/:id` for those).\n\n\nSame response shape and status codes. Only the `archived` query parameter differs: V1 casts\nit to a boolean, V3 treats any non-empty value as `true` (captured: `archived=false` returns\nactive subscriptions on V1 but archived ones on V3).", "parameters": [ { "name": "archived", "in": "query", "required": false, "description": "`true` lists archived subscriptions instead of active ones. **V1** parses the value as a\nboolean (`archived=false` → active list). **V3** only checks that the parameter is present:\n*any* non-empty value, including `archived=false`, returns the archived list – omit the\nparameter to list active subscriptions.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" }, "archived": { "type": "boolean" }, "event_type": { "type": "array", "items": { "type": "string" } }, "tested": { "type": "boolean" }, "response_code": { "type": "null" }, "json_wrapper": { "type": "string" } } } }, "example": [ { "id": 3, "name": "ERP purchase order feed (v3, webhooks_internal) - approvals only", "url": "https://erp.acme.test/pex/webhooks", "archived": false, "event_type": [ "po_approved", "po_cancelled" ], "tested": false, "response_code": null, "json_wrapper": "data" }, { "id": 2, "name": "ERP purchase order feed (v1, webhooks_internal) - approvals only", "url": "https://erp.acme.test/pex/webhooks", "archived": false, "event_type": [ "po_approved", "po_cancelled" ], "tested": false, "response_code": null, "json_wrapper": "data" } ] } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] }, "post": { "tags": [ "Webhooks" ], "operationId": "v3_webhook_create", "summary": "Create a webhook subscription", "description": "Creates a subscription that will receive the selected events.\n\nCreates a subscription for the company in `app_company_id`. Deliveries start with the next\nmatching event; nothing is sent at creation time (use the web app's *Test* button to send a\n`TestWebhook`).\n\nValidation:\n* `name` and `url` are required; `url` must satisfy the destination rules (HTTPS on port 443,\n public host – see the section intro). Errors are returned together, e.g.\n `Url must use https://`, `Url points at an address that is not allowed`,\n `Url must use an allowed port (https on 443)`.\n* `event_type` must be a non-empty array of known keys from a single family; otherwise\n `Event type is invalid`.\n* `basic_auth_uname` and `basic_auth_pword` must be given together.\n\nThe authentication type cannot be set through the API: Basic credentials sent here are stored\nencrypted but are **not used** until an admin selects *Basic* in the web app; `auth_type`,\n`client_id`, `client_secret` and `token_url` are silently ignored.\n\nJSON bodies may omit the `webhook` root (Rails wraps top-level attributes into `webhook`\nautomatically); an empty body → `400` `Required parameter are missing.`.\n\n\nNone - identical request and response (same controller code in both versions apart from the\nlist filter).", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" }, "archived": { "type": "boolean" }, "event_type": { "type": "array", "items": { "type": "string" } }, "tested": { "type": "boolean" }, "response_code": { "type": "null" }, "json_wrapper": { "type": "string" }, "send_as_text": { "type": "boolean" }, "basic_auth_uname": { "type": "string" }, "webhook_attributes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "attrib_type": { "type": "string" }, "key": { "type": "string" }, "value": { "type": "string" } } } } } }, "example": { "id": 3, "name": "ERP purchase order feed (v3, webhooks_internal)", "url": "https://erp.acme.test/pex/webhooks", "archived": false, "event_type": [ "new_po", "po_approved", "po_delivered", "po_paid", "po_cancelled", "po_update" ], "tested": false, "response_code": null, "json_wrapper": "data", "send_as_text": false, "basic_auth_uname": "pex-sync", "webhook_attributes": [ { "id": 3, "attrib_type": "header", "key": "X-Source-System", "value": "procurementexpress" }, { "id": 4, "attrib_type": "root", "key": "tenant", "value": "acme-corp" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Url must use https://" ], "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook[name]": { "type": "string", "description": "Display name." }, "webhook[url]": { "type": "string", "description": "HTTPS destination URL, port 443 (or 8443), public host, no credentials/fragment, ≤ 2000 chars." }, "webhook[event_type][]": { "type": "array", "items": { "type": "string" }, "description": "Event keys, all from one family: PO (`new_po`, `po_approved`, `po_delivered`, `po_paid`, `po_cancelled`, `po_update`), invoice (`new_invoice`, `invoice_approved`), report (`report_completed`) or e-invoicing (`invoice_received_pa`, `invoice_validated_pa`, `invoice_rejected_syntax`, `invoice_delivered_pa`, `invoice_accepted_pa`, `invoice_rejected_business`, `invoice_payment_status`, `invoice_received_pex`, `invoice_accepted_pex`, `invoice_approved_pex`, `e_reporting_submitted`, `e_reporting_ack_received`). Empty strings are not stripped – a form-encoded `webhook[event_type][]=` makes the request invalid." }, "webhook[json_wrapper]": { "type": "string", "description": "Key that holds the object in the envelope. Default `payload`. Do not use `event` or `object`." }, "webhook[send_as_text]": { "type": "boolean", "description": "Default `false`. `true` sends the object as a JSON string (for chat tools)." }, "webhook[archived]": { "type": "boolean", "description": "Default `false`. `true` creates the subscription disabled." }, "webhook[basic_auth_uname]": { "type": "string", "description": "Basic username; required when `basic_auth_pword` is given. Only used once Basic auth is selected in the web app. Returned in responses." }, "webhook[basic_auth_pword]": { "type": "string", "description": "Basic password; required when `basic_auth_uname` is given. Stored encrypted, never returned. Only used once Basic auth is selected in the web app." }, "webhook[webhook_attributes_attributes][][attrib_type]": { "type": "string", "description": "`header` (HTTP request header) or `root` (extra top-level key in the JSON envelope). Default `header`." }, "webhook[webhook_attributes_attributes][][key]": { "type": "string", "description": "Header name or root key. Rows with a blank key are ignored. Header names must be valid HTTP tokens and not reserved (`Host`, `Content-Length`, `Connection`, `Transfer-Encoding`, `Proxy-*`, …) or every delivery fails." }, "webhook[webhook_attributes_attributes][][value]": { "type": "string", "description": "Header value / root value (always a string). Returned in clear text by the API." }, "webhook[authentication_header]": { "type": "string", "description": "Accepted by the parameter filter but there is no such attribute: sending it fails with HTTP 500. Do not send." } }, "required": [ "webhook[name]", "webhook[url]", "webhook[event_type][]" ] }, "example": { "webhook": { "name": "ERP purchase order feed (v3, webhooks_internal)", "url": "https://erp.acme.test/pex/webhooks", "event_type": [ "new_po", "po_approved", "po_delivered", "po_paid", "po_cancelled", "po_update" ], "json_wrapper": "data", "send_as_text": false, "basic_auth_uname": "pex-sync", "basic_auth_pword": "s3cr3t-basic-pass", "webhook_attributes_attributes": [ { "attrib_type": "header", "key": "X-Source-System", "value": "procurementexpress" }, { "attrib_type": "root", "key": "tenant", "value": "acme-corp" } ] } } } } } } }, "/api/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "operationId": "v1_webhook_list", "summary": "List webhook subscriptions", "description": "Returns the company's webhook subscriptions, non-archived by default.\n\nReturns every subscription of the company in the `app_company_id` header in one unpaginated\narray, **newest first** (by creation time). By default only active (non-archived)\nsubscriptions are listed; use `archived` to list the disabled ones.\n\nThe list items are the short form of the subscription (no `send_as_text`,\n`basic_auth_uname` or `webhook_attributes` – use `GET /webhooks/:id` for those).\n\n\nSame response shape and status codes. Only the `archived` query parameter differs: V1 casts\nit to a boolean, V3 treats any non-empty value as `true` (captured: `archived=false` returns\nactive subscriptions on V1 but archived ones on V3).", "parameters": [ { "name": "archived", "in": "query", "required": false, "description": "`true` lists archived subscriptions instead of active ones. **V1** parses the value as a\nboolean (`archived=false` → active list). **V3** only checks that the parameter is present:\n*any* non-empty value, including `archived=false`, returns the archived list – omit the\nparameter to list active subscriptions.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" }, "archived": { "type": "boolean" }, "event_type": { "type": "array", "items": { "type": "string" } }, "tested": { "type": "boolean" }, "response_code": { "type": "null" }, "json_wrapper": { "type": "string" } } } }, "example": [ { "id": 3, "name": "ERP purchase order feed (v3, webhooks_internal) - approvals only", "url": "https://erp.acme.test/pex/webhooks", "archived": false, "event_type": [ "po_approved", "po_cancelled" ], "tested": false, "response_code": null, "json_wrapper": "data" }, { "id": 2, "name": "ERP purchase order feed (v1, webhooks_internal) - approvals only", "url": "https://erp.acme.test/pex/webhooks", "archived": false, "event_type": [ "po_approved", "po_cancelled" ], "tested": false, "response_code": null, "json_wrapper": "data" } ] } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "post": { "tags": [ "Webhooks" ], "operationId": "v1_webhook_create", "summary": "Create a webhook subscription", "description": "Creates a subscription that will receive the selected events.\n\nCreates a subscription for the company in `app_company_id`. Deliveries start with the next\nmatching event; nothing is sent at creation time (use the web app's *Test* button to send a\n`TestWebhook`).\n\nValidation:\n* `name` and `url` are required; `url` must satisfy the destination rules (HTTPS on port 443,\n public host – see the section intro). Errors are returned together, e.g.\n `Url must use https://`, `Url points at an address that is not allowed`,\n `Url must use an allowed port (https on 443)`.\n* `event_type` must be a non-empty array of known keys from a single family; otherwise\n `Event type is invalid`.\n* `basic_auth_uname` and `basic_auth_pword` must be given together.\n\nThe authentication type cannot be set through the API: Basic credentials sent here are stored\nencrypted but are **not used** until an admin selects *Basic* in the web app; `auth_type`,\n`client_id`, `client_secret` and `token_url` are silently ignored.\n\nJSON bodies may omit the `webhook` root (Rails wraps top-level attributes into `webhook`\nautomatically); an empty body → `400` `Required parameter are missing.`.\n\n\nNone - identical request and response (same controller code in both versions apart from the\nlist filter).", "parameters": [ ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" }, "archived": { "type": "boolean" }, "event_type": { "type": "array", "items": { "type": "string" } }, "tested": { "type": "boolean" }, "response_code": { "type": "null" }, "json_wrapper": { "type": "string" }, "send_as_text": { "type": "boolean" }, "basic_auth_uname": { "type": "string" }, "webhook_attributes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "attrib_type": { "type": "string" }, "key": { "type": "string" }, "value": { "type": "string" } } } } } }, "example": { "id": 2, "name": "ERP purchase order feed (v1, webhooks_internal)", "url": "https://erp.acme.test/pex/webhooks", "archived": false, "event_type": [ "new_po", "po_approved", "po_delivered", "po_paid", "po_cancelled", "po_update" ], "tested": false, "response_code": null, "json_wrapper": "data", "send_as_text": false, "basic_auth_uname": "pex-sync", "webhook_attributes": [ { "id": 1, "attrib_type": "header", "key": "X-Source-System", "value": "procurementexpress" }, { "id": 2, "attrib_type": "root", "key": "tenant", "value": "acme-corp" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Url must use https://" ], "status": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook[name]": { "type": "string", "description": "Display name." }, "webhook[url]": { "type": "string", "description": "HTTPS destination URL, port 443 (or 8443), public host, no credentials/fragment, ≤ 2000 chars." }, "webhook[event_type][]": { "type": "array", "items": { "type": "string" }, "description": "Event keys, all from one family: PO (`new_po`, `po_approved`, `po_delivered`, `po_paid`, `po_cancelled`, `po_update`), invoice (`new_invoice`, `invoice_approved`), report (`report_completed`) or e-invoicing (`invoice_received_pa`, `invoice_validated_pa`, `invoice_rejected_syntax`, `invoice_delivered_pa`, `invoice_accepted_pa`, `invoice_rejected_business`, `invoice_payment_status`, `invoice_received_pex`, `invoice_accepted_pex`, `invoice_approved_pex`, `e_reporting_submitted`, `e_reporting_ack_received`). Empty strings are not stripped – a form-encoded `webhook[event_type][]=` makes the request invalid." }, "webhook[json_wrapper]": { "type": "string", "description": "Key that holds the object in the envelope. Default `payload`. Do not use `event` or `object`." }, "webhook[send_as_text]": { "type": "boolean", "description": "Default `false`. `true` sends the object as a JSON string (for chat tools)." }, "webhook[archived]": { "type": "boolean", "description": "Default `false`. `true` creates the subscription disabled." }, "webhook[basic_auth_uname]": { "type": "string", "description": "Basic username; required when `basic_auth_pword` is given. Only used once Basic auth is selected in the web app. Returned in responses." }, "webhook[basic_auth_pword]": { "type": "string", "description": "Basic password; required when `basic_auth_uname` is given. Stored encrypted, never returned. Only used once Basic auth is selected in the web app." }, "webhook[webhook_attributes_attributes][][attrib_type]": { "type": "string", "description": "`header` (HTTP request header) or `root` (extra top-level key in the JSON envelope). Default `header`." }, "webhook[webhook_attributes_attributes][][key]": { "type": "string", "description": "Header name or root key. Rows with a blank key are ignored. Header names must be valid HTTP tokens and not reserved (`Host`, `Content-Length`, `Connection`, `Transfer-Encoding`, `Proxy-*`, …) or every delivery fails." }, "webhook[webhook_attributes_attributes][][value]": { "type": "string", "description": "Header value / root value (always a string). Returned in clear text by the API." }, "webhook[authentication_header]": { "type": "string", "description": "Accepted by the parameter filter but there is no such attribute: sending it fails with HTTP 500. Do not send." } }, "required": [ "webhook[name]", "webhook[url]", "webhook[event_type][]" ] }, "example": { "webhook": { "name": "ERP purchase order feed (v1, webhooks_internal)", "url": "https://erp.acme.test/pex/webhooks", "event_type": [ "new_po", "po_approved", "po_delivered", "po_paid", "po_cancelled", "po_update" ], "json_wrapper": "data", "send_as_text": false, "basic_auth_uname": "pex-sync", "basic_auth_pword": "s3cr3t-basic-pass", "webhook_attributes_attributes": [ { "attrib_type": "header", "key": "X-Source-System", "value": "procurementexpress" }, { "attrib_type": "root", "key": "tenant", "value": "acme-corp" } ] } } } } } } }, "/api/v3/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "operationId": "v3_webhook_show", "summary": "Retrieve a webhook subscription", "description": "Returns one subscription with its delivery options and custom attributes.\n\nReturns the full subscription, including `send_as_text`, `basic_auth_uname` and the custom\n`webhook_attributes`. Archived subscriptions can be retrieved too. Write-only secrets\n(`basic_auth_pword`, and the web-app-only OAuth2 client secret/access token) are never\nreturned, and neither are the web-app-only settings `auth_type`, `client_id` and `token_url` –\nthe API cannot tell you whether Basic or OAuth2 authentication is active.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Subscription id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" }, "archived": { "type": "boolean" }, "event_type": { "type": "array", "items": { "type": "string" } }, "tested": { "type": "boolean" }, "response_code": { "type": "null" }, "json_wrapper": { "type": "string" }, "send_as_text": { "type": "boolean" }, "basic_auth_uname": { "type": "string" }, "webhook_attributes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "attrib_type": { "type": "string" }, "key": { "type": "string" }, "value": { "type": "string" } } } } } }, "example": { "id": 3, "name": "ERP purchase order feed (v3, webhooks_internal)", "url": "https://erp.acme.test/pex/webhooks", "archived": false, "event_type": [ "new_po", "po_approved", "po_delivered", "po_paid", "po_cancelled", "po_update" ], "tested": false, "response_code": null, "json_wrapper": "data", "send_as_text": false, "basic_auth_uname": "pex-sync", "webhook_attributes": [ { "id": 3, "attrib_type": "header", "key": "X-Source-System", "value": "procurementexpress" }, { "id": 4, "attrib_type": "root", "key": "tenant", "value": "acme-corp" } ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ] }, "put": { "tags": [ "Webhooks" ], "operationId": "v3_webhook_update", "summary": "Update or archive a webhook subscription", "description": "Changes a subscription's settings, or disables it with archived=true.\n\nUpdates only the attributes you send; the same validation as create runs on the resulting\nrecord. `event_type` **replaces** the whole list.\n\n* **Disable / enable:** there is no delete endpoint. Send `{\"webhook\": {\"archived\": true}}` to\n stop deliveries (queued deliveries are dropped too); `archived: false` re-enables after full\n validation. Hard deletion is only possible in the web app.\n* **Secrets:** a blank `basic_auth_pword` keeps the stored password; clearing\n `basic_auth_uname` together with a blank password removes Basic credentials.\n* **Custom attributes:** add rows without `id`; change a row by sending its `id` **together with\n its `key`** (a row update without `key` is silently ignored); remove a row with\n `{\"id\": 5, \"_destroy\": true}`.\n* Any change to a subscription (even a rename) immediately invalidates all attachment download\n links it has already delivered.\n\n\nNone - identical request and response. `PATCH` behaves like `PUT` in both versions.\n`DELETE /webhooks/:id` is not routed in either version (`404 Invalid URL`).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Subscription id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" }, "archived": { "type": "boolean" }, "event_type": { "type": "array", "items": { "type": "string" } }, "tested": { "type": "boolean" }, "response_code": { "type": "null" }, "json_wrapper": { "type": "string" }, "send_as_text": { "type": "boolean" }, "basic_auth_uname": { "type": "string" }, "webhook_attributes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "attrib_type": { "type": "string" }, "key": { "type": "string" }, "value": { "type": "string" } } } } } }, "example": { "id": 3, "name": "ERP purchase order feed (v3, webhooks_internal) - approvals only", "url": "https://erp.acme.test/pex/webhooks", "archived": false, "event_type": [ "po_approved", "po_cancelled" ], "tested": false, "response_code": null, "json_wrapper": "data", "send_as_text": false, "basic_auth_uname": "pex-sync", "webhook_attributes": [ { "id": 3, "attrib_type": "header", "key": "X-Source-System", "value": "pex-production" }, { "id": 6, "attrib_type": "header", "key": "X-Api-Key", "value": "demo-key-not-real" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Event type is invalid" ], "status": 400 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "oauth2": [ "public" ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook[name]": { "type": "string", "description": "Display name (cannot be blank)." }, "webhook[url]": { "type": "string", "description": "New HTTPS destination (re-validated)." }, "webhook[event_type][]": { "type": "array", "items": { "type": "string" }, "description": "Replaces the subscribed events; one family only." }, "webhook[json_wrapper]": { "type": "string", "description": "Envelope key for the object; blank resets to `payload`." }, "webhook[send_as_text]": { "type": "boolean", "description": "Send the object as a JSON string." }, "webhook[archived]": { "type": "boolean", "description": "`true` disables delivery, `false` re-enables (re-validated)." }, "webhook[basic_auth_uname]": { "type": "string", "description": "Basic username (only used when Basic auth is selected in the web app)." }, "webhook[basic_auth_pword]": { "type": "string", "description": "Basic password; blank keeps the stored one. Never returned." }, "webhook[webhook_attributes_attributes][][id]": { "type": "integer", "description": "Existing attribute to change or delete." }, "webhook[webhook_attributes_attributes][][attrib_type]": { "type": "string", "description": "`header` or `root`." }, "webhook[webhook_attributes_attributes][][key]": { "type": "string", "description": "Required for new rows **and** for updates of existing rows (rows without a key are ignored)." }, "webhook[webhook_attributes_attributes][][value]": { "type": "string", "description": "Attribute value." }, "webhook[webhook_attributes_attributes][][_destroy]": { "type": "boolean", "description": "`true` removes the attribute with that `id`." } } }, "example": { "webhook": { "name": "ERP purchase order feed (v3, webhooks_internal) - approvals only", "event_type": [ "po_approved", "po_cancelled" ], "basic_auth_pword": "", "webhook_attributes_attributes": [ { "id": 3, "attrib_type": "header", "key": "X-Source-System", "value": "pex-production" }, { "attrib_type": "root", "key": "tenant", "value": "acme-corp" } ] } } } } } } }, "/api/v1/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "operationId": "v1_webhook_show", "summary": "Retrieve a webhook subscription", "description": "Returns one subscription with its delivery options and custom attributes.\n\nReturns the full subscription, including `send_as_text`, `basic_auth_uname` and the custom\n`webhook_attributes`. Archived subscriptions can be retrieved too. Write-only secrets\n(`basic_auth_pword`, and the web-app-only OAuth2 client secret/access token) are never\nreturned, and neither are the web-app-only settings `auth_type`, `client_id` and `token_url` –\nthe API cannot tell you whether Basic or OAuth2 authentication is active.\n\n\nNone - identical request and response.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Subscription id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" }, "archived": { "type": "boolean" }, "event_type": { "type": "array", "items": { "type": "string" } }, "tested": { "type": "boolean" }, "response_code": { "type": "null" }, "json_wrapper": { "type": "string" }, "send_as_text": { "type": "boolean" }, "basic_auth_uname": { "type": "string" }, "webhook_attributes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "attrib_type": { "type": "string" }, "key": { "type": "string" }, "value": { "type": "string" } } } } } }, "example": { "id": 3, "name": "ERP purchase order feed (v3, webhooks_internal)", "url": "https://erp.acme.test/pex/webhooks", "archived": false, "event_type": [ "new_po", "po_approved", "po_delivered", "po_paid", "po_cancelled", "po_update" ], "tested": false, "response_code": null, "json_wrapper": "data", "send_as_text": false, "basic_auth_uname": "pex-sync", "webhook_attributes": [ { "id": 3, "attrib_type": "header", "key": "X-Source-System", "value": "procurementexpress" }, { "id": 4, "attrib_type": "root", "key": "tenant", "value": "acme-corp" } ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "error": "Unauthorized access", "status": 401 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ] }, "put": { "tags": [ "Webhooks" ], "operationId": "v1_webhook_update", "summary": "Update or archive a webhook subscription", "description": "Changes a subscription's settings, or disables it with archived=true.\n\nUpdates only the attributes you send; the same validation as create runs on the resulting\nrecord. `event_type` **replaces** the whole list.\n\n* **Disable / enable:** there is no delete endpoint. Send `{\"webhook\": {\"archived\": true}}` to\n stop deliveries (queued deliveries are dropped too); `archived: false` re-enables after full\n validation. Hard deletion is only possible in the web app.\n* **Secrets:** a blank `basic_auth_pword` keeps the stored password; clearing\n `basic_auth_uname` together with a blank password removes Basic credentials.\n* **Custom attributes:** add rows without `id`; change a row by sending its `id` **together with\n its `key`** (a row update without `key` is silently ignored); remove a row with\n `{\"id\": 5, \"_destroy\": true}`.\n* Any change to a subscription (even a rename) immediately invalidates all attachment download\n links it has already delivered.\n\n\nNone - identical request and response. `PATCH` behaves like `PUT` in both versions.\n`DELETE /webhooks/:id` is not routed in either version (`404 Invalid URL`).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Subscription id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" }, "archived": { "type": "boolean" }, "event_type": { "type": "array", "items": { "type": "string" } }, "tested": { "type": "boolean" }, "response_code": { "type": "null" }, "json_wrapper": { "type": "string" }, "send_as_text": { "type": "boolean" }, "basic_auth_uname": { "type": "string" }, "webhook_attributes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "attrib_type": { "type": "string" }, "key": { "type": "string" }, "value": { "type": "string" } } } } } }, "example": { "id": 2, "name": "ERP purchase order feed (v1, webhooks_internal) - approvals only", "url": "https://erp.acme.test/pex/webhooks", "archived": false, "event_type": [ "po_approved", "po_cancelled" ], "tested": false, "response_code": null, "json_wrapper": "data", "send_as_text": false, "basic_auth_uname": "pex-sync", "webhook_attributes": [ { "id": 1, "attrib_type": "header", "key": "X-Source-System", "value": "pex-production" }, { "id": 5, "attrib_type": "header", "key": "X-Api-Key", "value": "demo-key-not-real" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "error": [ "Event type is invalid" ], "status": 400 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "error": "Invalid id passed", "status": 404 } } } } }, "security": [ { "v1Token": [ ], "companyId": [ ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook[name]": { "type": "string", "description": "Display name (cannot be blank)." }, "webhook[url]": { "type": "string", "description": "New HTTPS destination (re-validated)." }, "webhook[event_type][]": { "type": "array", "items": { "type": "string" }, "description": "Replaces the subscribed events; one family only." }, "webhook[json_wrapper]": { "type": "string", "description": "Envelope key for the object; blank resets to `payload`." }, "webhook[send_as_text]": { "type": "boolean", "description": "Send the object as a JSON string." }, "webhook[archived]": { "type": "boolean", "description": "`true` disables delivery, `false` re-enables (re-validated)." }, "webhook[basic_auth_uname]": { "type": "string", "description": "Basic username (only used when Basic auth is selected in the web app)." }, "webhook[basic_auth_pword]": { "type": "string", "description": "Basic password; blank keeps the stored one. Never returned." }, "webhook[webhook_attributes_attributes][][id]": { "type": "integer", "description": "Existing attribute to change or delete." }, "webhook[webhook_attributes_attributes][][attrib_type]": { "type": "string", "description": "`header` or `root`." }, "webhook[webhook_attributes_attributes][][key]": { "type": "string", "description": "Required for new rows **and** for updates of existing rows (rows without a key are ignored)." }, "webhook[webhook_attributes_attributes][][value]": { "type": "string", "description": "Attribute value." }, "webhook[webhook_attributes_attributes][][_destroy]": { "type": "boolean", "description": "`true` removes the attribute with that `id`." } } }, "example": { "webhook": { "name": "ERP purchase order feed (v1, webhooks_internal) - approvals only", "event_type": [ "po_approved", "po_cancelled" ], "basic_auth_pword": "", "webhook_attributes_attributes": [ { "id": 1, "attrib_type": "header", "key": "X-Source-System", "value": "pex-production" }, { "attrib_type": "root", "key": "tenant", "value": "acme-corp" } ] } } } } } } } }, "components": { "securitySchemes": { "oauth2": { "type": "oauth2", "description": "OAuth2 client credentials. The token acts as the user who registered the OAuth application.", "flows": { "clientCredentials": { "tokenUrl": "https://app.procurementexpress.com/oauth/token", "scopes": { "public": "Access the V3 API" } } } }, "v1Token": { "type": "apiKey", "in": "header", "name": "authentication_token", "description": "V1 user token from POST /api/v1/login." }, "companyId": { "type": "apiKey", "in": "header", "name": "app_company_id", "description": "Id of the company the request acts in." } } } }