{ "openapi": "3.1.0", "info": { "title": "Nummio API", "version": "v1", "description": "Read and write your Nummio books from your own software. Every call carries an API key you create in Settings, and every write goes through the same posting engine the app itself uses. A request body larger than 1,048,576 bytes is refused. A request body with anything in it needs `Content-Type: application/json`. A POST that sends no body at all needs no content type. A path parameter repeated in the query or the body is refused, rather than one of the two quietly winning. An `Idempotency-Key` header on a GET is ignored. A field the endpoint does not know is refused, never ignored. JSON field names are camelCase, in both directions. A `PUT`, `PATCH` or `DELETE`, and a `GET` or `POST` on a path that does not take it, are all 404, the same as a path that does not exist." }, "servers": [ { "url": "https://www.numm.io/api/v1" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "businesses", "description": "Your account, and the businesses inside it.", "x-displayName": "Businesses" }, { "name": "accounts", "description": "The accounts you can post to on a business's chart of accounts.", "x-displayName": "Accounts" }, { "name": "customers", "description": "The people and companies you bill, and how to add one.", "x-displayName": "Customers" }, { "name": "vendors", "description": "The people and companies you pay.", "x-displayName": "Vendors" }, { "name": "transactions", "description": "Money you have spent, and how each one was recorded in the books.", "x-displayName": "Transactions" }, { "name": "expenses", "description": "Spending you record yourself, posted the moment you send it.", "x-displayName": "Expenses" }, { "name": "invoices", "description": "Invoices you bill customers for, from draft to paid.", "x-displayName": "Invoices" }, { "name": "review-queue", "description": "Receipts and bills waiting for someone to confirm the category, and the call that confirms one.", "x-displayName": "Review queue" }, { "name": "today", "description": "The one screen that says what needs attention right now.", "x-displayName": "Today" }, { "name": "reports", "description": "The five statements an owner or an accountant asks for.", "x-displayName": "Reports" } ], "paths": { "/businesses": { "get": { "operationId": "businesses.list", "summary": "Lists the businesses in your account that this key may use.", "description": "A key always belongs to exactly one account. Each `id` in `businesses` is what `entityId` takes elsewhere. A key limited to particular businesses sees only those.", "tags": [ "businesses" ], "x-required-scope": "businesses:read", "parameters": [], "responses": { "200": { "description": "Lists the businesses in your account that this key may use.", "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountName": { "type": "string" }, "businesses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } } }, "required": [ "accountName", "businesses" ], "additionalProperties": false }, "example": { "accountName": "Acme Bookkeeping", "businesses": [ { "id": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1002", "name": "Acme Co" } ] } } } }, "401": { "description": "The key is missing, malformed, revoked, or expired.", "x-error-codes": [ "invalid_key" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_key" ] } } } } } ] }, "example": { "error": { "code": "invalid_key", "message": "The key is missing, malformed, revoked, or expired.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "403": { "description": "The key does not carry the scope this endpoint needs.", "x-error-codes": [ "insufficient_scope" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "insufficient_scope" ] } } } } } ] }, "example": { "error": { "code": "insufficient_scope", "message": "The key does not carry the scope this endpoint needs.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "422": { "description": "Something in the path, the query, or the body did not pass the schema.", "x-error-codes": [ "validation_failed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "example": { "error": { "code": "validation_failed", "message": "Something in the path, the query, or the body did not pass the schema.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "429": { "description": "Too many requests for this key. The retry-after header says how long to wait.", "x-error-codes": [ "rate_limited" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "retry-after": { "description": "How many seconds to wait before trying again.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "example": { "error": { "code": "rate_limited", "message": "Too many requests for this key. The retry-after header says how long to wait.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "500": { "description": "Something went wrong on our side.", "x-error-codes": [ "internal_error" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } } } } } ] }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } } } } }, "/accounts": { "get": { "operationId": "accounts.list", "summary": "Lists the accounts you can post to, each with its place in the chart of accounts.", "description": "These are the leaves of the chart of accounts, each with its full `path`. Parent and heading accounts are not returned, and neither are archived ones. The list is not paged. Leave `entityId` out only when this key can reach exactly one business. When it can reach several, a call that omits it is refused; call `GET /businesses` for the ids.", "tags": [ "accounts" ], "x-required-scope": "accounts:read", "parameters": [ { "name": "entityId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1002" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asset", "liability", "equity", "revenue", "expense" ] }, "example": "expense" } ], "responses": { "200": { "description": "Lists the accounts you can post to, each with its place in the chart of accounts.", "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "code": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "asset", "liability", "equity", "revenue", "expense" ] }, "path": { "type": "string" } }, "required": [ "id", "code", "name", "type", "path" ], "additionalProperties": false } } }, "required": [ "accounts" ], "additionalProperties": false }, "example": { "accounts": [ { "id": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1003", "code": "5010", "name": "Office Expense", "type": "expense", "path": "Expenses > Office Expense" } ] } } } }, "401": { "description": "The key is missing, malformed, revoked, or expired.", "x-error-codes": [ "invalid_key" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_key" ] } } } } } ] }, "example": { "error": { "code": "invalid_key", "message": "The key is missing, malformed, revoked, or expired.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "403": { "description": "The key does not carry the scope this endpoint needs. The key is limited to certain businesses, and this is not one of them.", "x-error-codes": [ "insufficient_scope", "entity_not_allowed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "insufficient_scope", "entity_not_allowed" ] } } } } } ] }, "example": { "error": { "code": "insufficient_scope", "message": "The key does not carry the scope this endpoint needs.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "404": { "description": "There is no such record, or none this key is allowed to reach.", "x-error-codes": [ "not_found" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "example": { "error": { "code": "not_found", "message": "There is no such record, or none this key is allowed to reach.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "422": { "description": "Something in the path, the query, or the body did not pass the schema.", "x-error-codes": [ "validation_failed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "example": { "error": { "code": "validation_failed", "message": "Something in the path, the query, or the body did not pass the schema.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "429": { "description": "Too many requests for this key. The retry-after header says how long to wait.", "x-error-codes": [ "rate_limited" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "retry-after": { "description": "How many seconds to wait before trying again.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "example": { "error": { "code": "rate_limited", "message": "Too many requests for this key. The retry-after header says how long to wait.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "500": { "description": "Something went wrong on our side.", "x-error-codes": [ "internal_error" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } } } } } ] }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } } } } }, "/customers": { "get": { "operationId": "customers.list", "summary": "Lists the customers in your account, the billing contacts invoices go to.", "description": "A key limited to certain businesses still sees every customer: customers belong to your account, not to one business. In `search`, `%` and `_` are wildcards, because the match runs as a SQL `ilike`. To read the next page, pass the previous response's `nextCursor`. A `null` there means you already have everything.", "tags": [ "customers" ], "x-required-scope": "customers:read", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "example": "Acme" }, { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Lists the customers in your account, the billing contacts invoices go to.", "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "customers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string", "enum": [ "USD", "CAD", "EUR", "GBP", "MXN" ] }, "paymentTermsDays": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "name", "email", "currency", "paymentTermsDays" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] } }, "required": [ "customers", "nextCursor" ], "additionalProperties": false }, "example": { "customers": [ { "id": "0190a1b2-c3d4-7e5f-9a9b-0c1d2e3f1005", "name": "Acme Co", "email": "ap@acme.example", "currency": "USD", "paymentTermsDays": 30 } ], "nextCursor": null } } } }, "401": { "description": "The key is missing, malformed, revoked, or expired.", "x-error-codes": [ "invalid_key" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_key" ] } } } } } ] }, "example": { "error": { "code": "invalid_key", "message": "The key is missing, malformed, revoked, or expired.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "403": { "description": "The key does not carry the scope this endpoint needs.", "x-error-codes": [ "insufficient_scope" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "insufficient_scope" ] } } } } } ] }, "example": { "error": { "code": "insufficient_scope", "message": "The key does not carry the scope this endpoint needs.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "422": { "description": "Something in the path, the query, or the body did not pass the schema.", "x-error-codes": [ "validation_failed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "example": { "error": { "code": "validation_failed", "message": "Something in the path, the query, or the body did not pass the schema.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "429": { "description": "Too many requests for this key. The retry-after header says how long to wait.", "x-error-codes": [ "rate_limited" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "retry-after": { "description": "How many seconds to wait before trying again.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "example": { "error": { "code": "rate_limited", "message": "Too many requests for this key. The retry-after header says how long to wait.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "500": { "description": "Something went wrong on our side.", "x-error-codes": [ "internal_error" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } } } } } ] }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } } } }, "post": { "operationId": "customers.create", "summary": "Creates a customer, a billing contact invoices go to.", "description": "If a customer with this name already exists, that one is returned and nothing is changed: `created` is `false` and the other fields you sent are ignored. The match ignores case and skips archived customers. A customer that was created answers 201. One that already existed answers 200.", "tags": [ "customers" ], "x-required-scope": "customers:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Send the same key again to replay the original result instead of running the write a second time. Kept for 24 hours.", "schema": { "type": "string", "pattern": "^[\\x20-\\x7E]{1,200}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "phone": { "type": "string", "maxLength": 40 }, "addressLine1": { "type": "string", "maxLength": 200 }, "addressLine2": { "type": "string", "maxLength": 200 }, "city": { "type": "string", "maxLength": 200 }, "state": { "type": "string", "maxLength": 200 }, "postalCode": { "type": "string", "maxLength": 200 }, "currency": { "type": "string", "enum": [ "USD", "CAD", "EUR", "GBP", "MXN" ] }, "paymentTermsDays": { "type": "integer", "minimum": 0, "maximum": 365 }, "remindersEnabled": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false }, "example": { "name": "Acme Co", "email": "ap@acme.example" } } } }, "responses": { "200": { "description": "A customer with this name already exists, so nothing was created.", "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "idempotent-replayed": { "description": "Present and true when this is the replay of an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "created": { "type": "boolean" } }, "required": [ "id", "created" ], "additionalProperties": false } } } }, "201": { "description": "A customer was created.", "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "idempotent-replayed": { "description": "Present and true when this is the replay of an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "created": { "type": "boolean" } }, "required": [ "id", "created" ], "additionalProperties": false }, "example": { "id": "0190a1b2-c3d4-7e5f-9a9b-0c1d2e3f1005", "created": true } } } }, "401": { "description": "The key is missing, malformed, revoked, or expired.", "x-error-codes": [ "invalid_key" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_key" ] } } } } } ] }, "example": { "error": { "code": "invalid_key", "message": "The key is missing, malformed, revoked, or expired.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "403": { "description": "The key does not carry the scope this endpoint needs.", "x-error-codes": [ "insufficient_scope" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "insufficient_scope" ] } } } } } ] }, "example": { "error": { "code": "insufficient_scope", "message": "The key does not carry the scope this endpoint needs.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "409": { "description": "The request clashed with something that has already happened.", "x-error-codes": [ "conflict" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "conflict" ] } } } } } ] }, "example": { "error": { "code": "conflict", "message": "The request clashed with something that has already happened.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "422": { "description": "Something in the path, the query, or the body did not pass the schema.", "x-error-codes": [ "validation_failed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "example": { "error": { "code": "validation_failed", "message": "Something in the path, the query, or the body did not pass the schema.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "429": { "description": "Too many requests for this key. The retry-after header says how long to wait.", "x-error-codes": [ "rate_limited" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "retry-after": { "description": "How many seconds to wait before trying again.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "example": { "error": { "code": "rate_limited", "message": "Too many requests for this key. The retry-after header says how long to wait.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "500": { "description": "Something went wrong on our side.", "x-error-codes": [ "internal_error" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } } } } } ] }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } } } } }, "/vendors": { "get": { "operationId": "vendors.list", "summary": "Lists the vendors in your account, who expenses are paid to.", "description": "A key limited to certain businesses still sees every vendor: vendors belong to your account, not to one business. `search` matches the canonical name, the one this list returns as `name`, and nothing else. A name as it was written on a receipt does not match unless it is the canonical one. In `search`, `%` and `_` are wildcards, because the match runs as a SQL `ilike`. To read the next page, pass the previous response's `nextCursor`. A `null` there means you already have everything.", "tags": [ "vendors" ], "x-required-scope": "vendors:read", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Lists the vendors in your account, who expenses are paid to.", "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "vendors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "is1099Eligible": { "type": "boolean" } }, "required": [ "id", "name", "is1099Eligible" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] } }, "required": [ "vendors", "nextCursor" ], "additionalProperties": false }, "example": { "vendors": [ { "id": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1004", "name": "Office Depot", "is1099Eligible": false } ], "nextCursor": null } } } }, "401": { "description": "The key is missing, malformed, revoked, or expired.", "x-error-codes": [ "invalid_key" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_key" ] } } } } } ] }, "example": { "error": { "code": "invalid_key", "message": "The key is missing, malformed, revoked, or expired.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "403": { "description": "The key does not carry the scope this endpoint needs.", "x-error-codes": [ "insufficient_scope" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "insufficient_scope" ] } } } } } ] }, "example": { "error": { "code": "insufficient_scope", "message": "The key does not carry the scope this endpoint needs.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "422": { "description": "Something in the path, the query, or the body did not pass the schema.", "x-error-codes": [ "validation_failed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "example": { "error": { "code": "validation_failed", "message": "Something in the path, the query, or the body did not pass the schema.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "429": { "description": "Too many requests for this key. The retry-after header says how long to wait.", "x-error-codes": [ "rate_limited" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "retry-after": { "description": "How many seconds to wait before trying again.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "example": { "error": { "code": "rate_limited", "message": "Too many requests for this key. The retry-after header says how long to wait.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "500": { "description": "Something went wrong on our side.", "x-error-codes": [ "internal_error" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } } } } } ] }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } } } } }, "/transactions": { "get": { "operationId": "transactions.list", "summary": "Lists expenses and bank-feed transactions for one business, newest first.", "description": "Leave `entityId` out only when this key can reach exactly one business. When it can reach several, a call that omits it is refused; call `GET /businesses` for the ids. `dateFrom` and `dateTo` match the transaction date and include both ends. `text` matches the vendor's name only, not the memo or the account. `%` and `_` are wildcards in it, because the match runs as a SQL `ilike`. To read the next page, pass the previous response's `nextCursor`. A `null` there means you already have everything.", "tags": [ "transactions" ], "x-required-scope": "transactions:read", "parameters": [ { "name": "entityId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1002" }, { "name": "dateFrom", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "example": "2026-01-01" }, { "name": "dateTo", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "example": "2026-01-31" }, { "name": "vendorId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "text", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "accepted", "edited", "uncategorized" ] } }, { "name": "minCents", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{1,15}$" } }, { "name": "maxCents", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{1,15}$" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "example": "25" } ], "responses": { "200": { "description": "Lists expenses and bank-feed transactions for one business, newest first.", "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "amount": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "vendor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "account": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "accepted", "edited", "uncategorized" ] }, "source": { "type": "string", "enum": [ "manual", "csv", "email", "ios", "reconciliation", "financial_connections" ] } }, "required": [ "id", "date", "amount", "vendor", "account", "status", "source" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] } }, "required": [ "transactions", "nextCursor" ], "additionalProperties": false }, "example": { "transactions": [ { "id": "0190a1b2-c3d4-7e5f-9a9b-0c1d2e3f1006", "date": "2026-01-10", "amount": { "cents": "5000", "formatted": "$50.00", "currency": "USD" }, "vendor": "Office Depot", "account": "Office Expense", "status": "accepted", "source": "email" } ], "nextCursor": null } } } }, "401": { "description": "The key is missing, malformed, revoked, or expired.", "x-error-codes": [ "invalid_key" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_key" ] } } } } } ] }, "example": { "error": { "code": "invalid_key", "message": "The key is missing, malformed, revoked, or expired.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "403": { "description": "The key does not carry the scope this endpoint needs. The key is limited to certain businesses, and this is not one of them.", "x-error-codes": [ "insufficient_scope", "entity_not_allowed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "insufficient_scope", "entity_not_allowed" ] } } } } } ] }, "example": { "error": { "code": "insufficient_scope", "message": "The key does not carry the scope this endpoint needs.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "404": { "description": "There is no such record, or none this key is allowed to reach.", "x-error-codes": [ "not_found" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "example": { "error": { "code": "not_found", "message": "There is no such record, or none this key is allowed to reach.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "422": { "description": "Something in the path, the query, or the body did not pass the schema.", "x-error-codes": [ "validation_failed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "example": { "error": { "code": "validation_failed", "message": "Something in the path, the query, or the body did not pass the schema.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "429": { "description": "Too many requests for this key. The retry-after header says how long to wait.", "x-error-codes": [ "rate_limited" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "retry-after": { "description": "How many seconds to wait before trying again.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "example": { "error": { "code": "rate_limited", "message": "Too many requests for this key. The retry-after header says how long to wait.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "500": { "description": "Something went wrong on our side.", "x-error-codes": [ "internal_error" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } } } } } ] }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } } } } }, "/transactions/{id}": { "get": { "operationId": "transactions.get", "summary": "Returns full detail for one transaction, including how it was recorded in the books.", "tags": [ "transactions" ], "x-required-scope": "transactions:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "0190a1b2-c3d4-7e5f-9a9b-0c1d2e3f1006" } ], "responses": { "200": { "description": "Returns full detail for one transaction, including how it was recorded in the books.", "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "amount": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "vendor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "account": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "accepted", "edited", "uncategorized" ] }, "source": { "type": "string", "enum": [ "manual", "csv", "email", "ios", "reconciliation", "financial_connections" ] }, "rationale": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "account": { "type": "string" }, "debit": { "anyOf": [ { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, { "type": "null" } ] }, "credit": { "anyOf": [ { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "account", "debit", "credit" ], "additionalProperties": false } } }, "required": [ "id", "date", "amount", "description", "vendor", "account", "status", "source", "rationale", "lines" ], "additionalProperties": false }, "example": { "id": "0190a1b2-c3d4-7e5f-9a9b-0c1d2e3f1006", "date": "2026-01-10", "amount": { "cents": "5000", "formatted": "$50.00", "currency": "USD" }, "description": "Office supplies", "vendor": "Office Depot", "account": "Office Expense", "status": "accepted", "source": "email", "rationale": "Matches prior Office Depot purchases categorized as Office Expense.", "lines": [ { "account": "Office Expense", "debit": { "cents": "5000", "formatted": "$50.00", "currency": "USD" }, "credit": null }, { "account": "Accounts Payable", "debit": null, "credit": { "cents": "5000", "formatted": "$50.00", "currency": "USD" } } ] } } } }, "401": { "description": "The key is missing, malformed, revoked, or expired.", "x-error-codes": [ "invalid_key" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_key" ] } } } } } ] }, "example": { "error": { "code": "invalid_key", "message": "The key is missing, malformed, revoked, or expired.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "403": { "description": "The key does not carry the scope this endpoint needs.", "x-error-codes": [ "insufficient_scope" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "insufficient_scope" ] } } } } } ] }, "example": { "error": { "code": "insufficient_scope", "message": "The key does not carry the scope this endpoint needs.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "404": { "description": "There is no such record, or none this key is allowed to reach.", "x-error-codes": [ "not_found" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "example": { "error": { "code": "not_found", "message": "There is no such record, or none this key is allowed to reach.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "422": { "description": "Something in the path, the query, or the body did not pass the schema.", "x-error-codes": [ "validation_failed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "example": { "error": { "code": "validation_failed", "message": "Something in the path, the query, or the body did not pass the schema.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "429": { "description": "Too many requests for this key. The retry-after header says how long to wait.", "x-error-codes": [ "rate_limited" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "retry-after": { "description": "How many seconds to wait before trying again.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "example": { "error": { "code": "rate_limited", "message": "Too many requests for this key. The retry-after header says how long to wait.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "500": { "description": "Something went wrong on our side.", "x-error-codes": [ "internal_error" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } } } } } ] }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } } } } }, "/invoices": { "get": { "operationId": "invoices.list", "summary": "Lists customer invoices for one business, newest first.", "description": "Leave `entityId` out only when this key can reach exactly one business. When it can reach several, a call that omits it is refused; call `GET /businesses` for the ids. `dateFrom` and `dateTo` match the issue date and include both ends. To read the next page, pass the previous response's `nextCursor`. A `null` there means you already have everything. `overdueOnly` is applied to the page you asked for, not to the whole list, so a page can come back with fewer rows than `limit`, or none, while `nextCursor` is still set. An invoice's figures are in the invoice's own currency, which may not be US dollars, and the `currency` beside each figure says which. Every other amount on this surface is US dollars.", "tags": [ "invoices" ], "x-required-scope": "invoices:read", "parameters": [ { "name": "entityId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1002" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "sent", "viewed", "partially_paid", "paid", "overdue", "void" ] }, "example": "sent" }, { "name": "customerId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "dateFrom", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "dateTo", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "overdueOnly", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Lists customer invoices for one business, newest first.", "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "sent", "viewed", "partially_paid", "paid", "overdue", "void" ] }, "customer": { "type": "string" }, "issueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "dueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "total": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "paid": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "balance": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "currency": { "type": "string", "enum": [ "USD", "CAD", "EUR", "GBP", "MXN" ] } }, "required": [ "id", "number", "status", "customer", "issueDate", "dueDate", "total", "paid", "balance", "currency" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] } }, "required": [ "invoices", "nextCursor" ], "additionalProperties": false }, "example": { "invoices": [ { "id": "0190a1b2-c3d4-7e5f-9a9b-0c1d2e3f1007", "number": "ACME-0001", "status": "sent", "customer": "Acme Co", "issueDate": "2026-06-01", "dueDate": "2026-06-15", "total": { "cents": "10000", "formatted": "$100.00", "currency": "USD" }, "paid": { "cents": "0", "formatted": "$0.00", "currency": "USD" }, "balance": { "cents": "10000", "formatted": "$100.00", "currency": "USD" }, "currency": "USD" } ], "nextCursor": null } } } }, "401": { "description": "The key is missing, malformed, revoked, or expired.", "x-error-codes": [ "invalid_key" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_key" ] } } } } } ] }, "example": { "error": { "code": "invalid_key", "message": "The key is missing, malformed, revoked, or expired.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "403": { "description": "The key does not carry the scope this endpoint needs. The key is limited to certain businesses, and this is not one of them.", "x-error-codes": [ "insufficient_scope", "entity_not_allowed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "insufficient_scope", "entity_not_allowed" ] } } } } } ] }, "example": { "error": { "code": "insufficient_scope", "message": "The key does not carry the scope this endpoint needs.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "404": { "description": "There is no such record, or none this key is allowed to reach.", "x-error-codes": [ "not_found" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "example": { "error": { "code": "not_found", "message": "There is no such record, or none this key is allowed to reach.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "422": { "description": "Something in the path, the query, or the body did not pass the schema.", "x-error-codes": [ "validation_failed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "example": { "error": { "code": "validation_failed", "message": "Something in the path, the query, or the body did not pass the schema.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "429": { "description": "Too many requests for this key. The retry-after header says how long to wait.", "x-error-codes": [ "rate_limited" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "retry-after": { "description": "How many seconds to wait before trying again.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "example": { "error": { "code": "rate_limited", "message": "Too many requests for this key. The retry-after header says how long to wait.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "500": { "description": "Something went wrong on our side.", "x-error-codes": [ "internal_error" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } } } } } ] }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } } } }, "post": { "operationId": "invoices.create", "summary": "Creates a draft invoice for a customer. Nothing is sent and nothing is emailed.", "description": "Leave `entityId` out only when this key can reach exactly one business. When it can reach several, a call that omits it is refused; call `GET /businesses` for the ids. `unitPriceCents` is whole cents, and `quantity` allows up to six decimal places. Each line's quantity must be greater than zero. `issueDate` defaults to the current date in UTC. `dueDate` defaults to `issueDate` plus the payment terms, taken from the customer, then the business, then your account. A `dueDate` before `issueDate` is refused. Every line amount, the subtotal, and the total must each stay under ten trillion dollars. `currency` is the invoice's own currency, and defaults to US dollars when you leave it out. It is not taken from the customer, even when the customer is set to another currency, which is how the app's own invoice form behaves too. `unitPriceCents`, and every figure the invoice reads back with, are cents of the invoice's own currency. Your books stay in US dollars: the conversion happens when the invoice is sent. Sending an invoice in another currency needs an exchange rate for its issue date. Until one has been fetched, `POST /invoices/{id}/send` is refused with `validation_failed` and the draft is left as it is.", "tags": [ "invoices" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Send the same key again to replay the original result instead of running the write a second time. Kept for 24 hours.", "schema": { "type": "string", "pattern": "^[\\x20-\\x7E]{1,200}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entityId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "customerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "issueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "paymentTermsDays": { "type": "integer", "minimum": 0, "maximum": 365 }, "dueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "lines": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "quantity": { "type": "string", "pattern": "^\\d{1,9}(?:\\.\\d{1,6})?$" }, "unitPriceCents": { "type": "string", "pattern": "^\\d{1,15}$" }, "accountId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "description", "quantity", "unitPriceCents", "accountId" ], "additionalProperties": false } }, "currency": { "type": "string", "enum": [ "USD", "CAD", "EUR", "GBP", "MXN" ] }, "taxRatePercent": { "type": "string", "pattern": "^(?:100(?:\\.0{1,6})?|\\d{1,2}(?:\\.\\d{1,6})?)$" }, "memo": { "type": "string", "maxLength": 2000 } }, "required": [ "customerId", "lines" ], "additionalProperties": false }, "example": { "entityId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1002", "customerId": "0190a1b2-c3d4-7e5f-9a9b-0c1d2e3f1005", "lines": [ { "description": "Consulting", "quantity": "1", "unitPriceCents": "10000", "accountId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1003" } ] } } } }, "responses": { "201": { "description": "Creates a draft invoice for a customer. Nothing is sent and nothing is emailed.", "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "idempotent-replayed": { "description": "Present and true when this is the replay of an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "invoiceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "invoiceNumber": { "type": "string" }, "webUrl": { "type": "string" } }, "required": [ "invoiceId", "invoiceNumber", "webUrl" ], "additionalProperties": false }, "example": { "invoiceId": "0190a1b2-c3d4-7e5f-9a9b-0c1d2e3f1007", "invoiceNumber": "ACME-0001", "webUrl": "https://www.numm.io/app/invoices/0190a1b2-c3d4-7e5f-9a9b-0c1d2e3f1007" } } } }, "401": { "description": "The key is missing, malformed, revoked, or expired.", "x-error-codes": [ "invalid_key" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_key" ] } } } } } ] }, "example": { "error": { "code": "invalid_key", "message": "The key is missing, malformed, revoked, or expired.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "403": { "description": "The key does not carry the scope this endpoint needs. The key is limited to certain businesses, and this is not one of them.", "x-error-codes": [ "insufficient_scope", "entity_not_allowed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "insufficient_scope", "entity_not_allowed" ] } } } } } ] }, "example": { "error": { "code": "insufficient_scope", "message": "The key does not carry the scope this endpoint needs.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "404": { "description": "There is no such record, or none this key is allowed to reach.", "x-error-codes": [ "not_found" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "example": { "error": { "code": "not_found", "message": "There is no such record, or none this key is allowed to reach.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "409": { "description": "The request clashed with something that has already happened.", "x-error-codes": [ "conflict" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "conflict" ] } } } } } ] }, "example": { "error": { "code": "conflict", "message": "The request clashed with something that has already happened.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "422": { "description": "Something in the path, the query, or the body did not pass the schema.", "x-error-codes": [ "validation_failed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "example": { "error": { "code": "validation_failed", "message": "Something in the path, the query, or the body did not pass the schema.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "429": { "description": "Too many requests for this key. The retry-after header says how long to wait.", "x-error-codes": [ "rate_limited" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "retry-after": { "description": "How many seconds to wait before trying again.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "example": { "error": { "code": "rate_limited", "message": "Too many requests for this key. The retry-after header says how long to wait.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "500": { "description": "Something went wrong on our side.", "x-error-codes": [ "internal_error" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } } } } } ] }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } } } } }, "/invoices/{id}": { "get": { "operationId": "invoices.get", "summary": "Returns full detail for one invoice, including its lines, payments, and pay link.", "description": "An invoice's figures are in the invoice's own currency, which may not be US dollars, and the `currency` beside each figure says which. Every other amount on this surface is US dollars. `payUrl` is the customer's own pay page and needs no sign-in. Anyone with the link can open the invoice and pay it, so treat it like the invoice email itself.", "tags": [ "invoices" ], "x-required-scope": "invoices:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "0190a1b2-c3d4-7e5f-9a9b-0c1d2e3f1007" } ], "responses": { "200": { "description": "Returns full detail for one invoice, including its lines, payments, and pay link.", "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "sent", "viewed", "partially_paid", "paid", "overdue", "void" ] }, "customer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "issueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "dueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "terms": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string", "enum": [ "USD", "CAD", "EUR", "GBP", "MXN" ] }, "subtotal": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "tax": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "total": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "paid": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "balance": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "type": "string" }, "unitPrice": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "amount": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "account": { "type": "string" } }, "required": [ "description", "quantity", "unitPrice", "amount", "account" ], "additionalProperties": false } }, "payments": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "method": { "type": "string", "enum": [ "stripe", "check", "cash", "wire", "other" ] }, "paidAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "amount", "method", "paidAt" ], "additionalProperties": false } }, "payUrl": { "type": "string" } }, "required": [ "id", "number", "status", "customer", "issueDate", "dueDate", "terms", "currency", "subtotal", "tax", "total", "paid", "balance", "memo", "lines", "payments", "payUrl" ], "additionalProperties": false }, "example": { "id": "0190a1b2-c3d4-7e5f-9a9b-0c1d2e3f1007", "number": "ACME-0001", "status": "sent", "customer": { "id": "0190a1b2-c3d4-7e5f-9a9b-0c1d2e3f1005", "name": "Acme Co" }, "issueDate": "2026-06-01", "dueDate": "2026-06-15", "terms": "Net 15", "currency": "USD", "subtotal": { "cents": "10000", "formatted": "$100.00", "currency": "USD" }, "tax": { "cents": "0", "formatted": "$0.00", "currency": "USD" }, "total": { "cents": "10000", "formatted": "$100.00", "currency": "USD" }, "paid": { "cents": "0", "formatted": "$0.00", "currency": "USD" }, "balance": { "cents": "10000", "formatted": "$100.00", "currency": "USD" }, "memo": null, "lines": [ { "description": "Consulting", "quantity": "1", "unitPrice": { "cents": "10000", "formatted": "$100.00", "currency": "USD" }, "amount": { "cents": "10000", "formatted": "$100.00", "currency": "USD" }, "account": "Consulting Revenue" } ], "payments": [], "payUrl": "https://www.numm.io/pay/abc123" } } } }, "401": { "description": "The key is missing, malformed, revoked, or expired.", "x-error-codes": [ "invalid_key" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_key" ] } } } } } ] }, "example": { "error": { "code": "invalid_key", "message": "The key is missing, malformed, revoked, or expired.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "403": { "description": "The key does not carry the scope this endpoint needs.", "x-error-codes": [ "insufficient_scope" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "insufficient_scope" ] } } } } } ] }, "example": { "error": { "code": "insufficient_scope", "message": "The key does not carry the scope this endpoint needs.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "404": { "description": "There is no such record, or none this key is allowed to reach.", "x-error-codes": [ "not_found" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "example": { "error": { "code": "not_found", "message": "There is no such record, or none this key is allowed to reach.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "422": { "description": "Something in the path, the query, or the body did not pass the schema.", "x-error-codes": [ "validation_failed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "example": { "error": { "code": "validation_failed", "message": "Something in the path, the query, or the body did not pass the schema.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "429": { "description": "Too many requests for this key. The retry-after header says how long to wait.", "x-error-codes": [ "rate_limited" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "retry-after": { "description": "How many seconds to wait before trying again.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "example": { "error": { "code": "rate_limited", "message": "Too many requests for this key. The retry-after header says how long to wait.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "500": { "description": "Something went wrong on our side.", "x-error-codes": [ "internal_error" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } } } } } ] }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } } } } }, "/review-queue": { "get": { "operationId": "review.list", "summary": "Returns pending AI-categorized expenses awaiting human review.", "description": "Leave `entityId` out to read the queue across every business in your account at once. A key limited to particular businesses is the exception: unless it is limited to exactly one, it has to name the one it wants. This list is limited rather than paged: `hasMore` says whether more is waiting behind the `limit` you asked for. `limit` counts `highConfidence` and `needsReview` together. `highConfidence` holds the items the AI scored high enough to accept in a batch; everything else is in `needsReview`. Each item carries the `confidence` the split used, which is `null` when the AI never scored it.", "tags": [ "review-queue" ], "x-required-scope": "review:read", "parameters": [ { "name": "entityId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1002" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Returns pending AI-categorized expenses awaiting human review.", "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "highConfidence": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "amount": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "vendor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "proposedAccountId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "proposedAccount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "rationale": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "date", "amount", "vendor", "description", "proposedAccountId", "proposedAccount", "confidence", "rationale" ], "additionalProperties": false } }, "needsReview": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "amount": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "vendor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "proposedAccountId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "proposedAccount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "rationale": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "date", "amount", "vendor", "description", "proposedAccountId", "proposedAccount", "confidence", "rationale" ], "additionalProperties": false } }, "hasMore": { "type": "boolean" } }, "required": [ "highConfidence", "needsReview", "hasMore" ], "additionalProperties": false }, "example": { "hasMore": false, "highConfidence": [], "needsReview": [ { "id": "0190a1b2-c3d4-7e5f-9a9b-0c1d2e3f1008", "date": "2026-02-05", "amount": { "cents": "500", "formatted": "$5.00", "currency": "USD" }, "vendor": "Office Depot", "description": null, "proposedAccountId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1003", "proposedAccount": "Office Expense", "confidence": null, "rationale": null } ] } } } }, "401": { "description": "The key is missing, malformed, revoked, or expired.", "x-error-codes": [ "invalid_key" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_key" ] } } } } } ] }, "example": { "error": { "code": "invalid_key", "message": "The key is missing, malformed, revoked, or expired.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "403": { "description": "The key does not carry the scope this endpoint needs. The key is limited to certain businesses, and this is not one of them.", "x-error-codes": [ "insufficient_scope", "entity_not_allowed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "insufficient_scope", "entity_not_allowed" ] } } } } } ] }, "example": { "error": { "code": "insufficient_scope", "message": "The key does not carry the scope this endpoint needs.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "404": { "description": "There is no such record, or none this key is allowed to reach.", "x-error-codes": [ "not_found" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "example": { "error": { "code": "not_found", "message": "There is no such record, or none this key is allowed to reach.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "422": { "description": "Something in the path, the query, or the body did not pass the schema.", "x-error-codes": [ "validation_failed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "example": { "error": { "code": "validation_failed", "message": "Something in the path, the query, or the body did not pass the schema.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "429": { "description": "Too many requests for this key. The retry-after header says how long to wait.", "x-error-codes": [ "rate_limited" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "retry-after": { "description": "How many seconds to wait before trying again.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "example": { "error": { "code": "rate_limited", "message": "Too many requests for this key. The retry-after header says how long to wait.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "500": { "description": "Something went wrong on our side.", "x-error-codes": [ "internal_error" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } } } } } ] }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } } } } }, "/today": { "get": { "operationId": "today.get", "summary": "Returns the Today homepage for one business: the headline and its ranked signal cards.", "description": "Leave `entityId` out only when this key can reach exactly one business. When it can reach several, a call that omits it is refused; call `GET /businesses` for the ids. Reading Today also updates when each signal was last seen and closes the ones that no longer apply, exactly as opening the Today page does. Nothing in your books changes.", "tags": [ "today" ], "x-required-scope": "today:read", "parameters": [ { "name": "entityId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1002" } ], "responses": { "200": { "description": "Returns the Today homepage for one business: the headline and its ranked signal cards.", "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "headline": { "type": "string" }, "signals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "severity": { "type": "string", "enum": [ "blocking", "urgent", "attention", "informational" ] }, "sentence": { "type": "string" }, "action": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": [ "label" ], "additionalProperties": false } } }, "required": [ "id", "severity", "sentence", "action", "evidence" ], "additionalProperties": false } } }, "required": [ "headline", "signals" ], "additionalProperties": false }, "example": { "headline": "12 items need your review.", "signals": [ { "id": "review_queue_depth", "severity": "attention", "sentence": "12 items are waiting in the review queue.", "action": "Review the queue.", "evidence": [ { "label": "12 pending items", "url": "/app/review-queue" } ] } ] } } } }, "401": { "description": "The key is missing, malformed, revoked, or expired.", "x-error-codes": [ "invalid_key" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_key" ] } } } } } ] }, "example": { "error": { "code": "invalid_key", "message": "The key is missing, malformed, revoked, or expired.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "403": { "description": "The key does not carry the scope this endpoint needs. The key is limited to certain businesses, and this is not one of them.", "x-error-codes": [ "insufficient_scope", "entity_not_allowed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "insufficient_scope", "entity_not_allowed" ] } } } } } ] }, "example": { "error": { "code": "insufficient_scope", "message": "The key does not carry the scope this endpoint needs.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "404": { "description": "There is no such record, or none this key is allowed to reach.", "x-error-codes": [ "not_found" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "example": { "error": { "code": "not_found", "message": "There is no such record, or none this key is allowed to reach.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "422": { "description": "Something in the path, the query, or the body did not pass the schema.", "x-error-codes": [ "validation_failed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "example": { "error": { "code": "validation_failed", "message": "Something in the path, the query, or the body did not pass the schema.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "429": { "description": "Too many requests for this key. The retry-after header says how long to wait.", "x-error-codes": [ "rate_limited" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "retry-after": { "description": "How many seconds to wait before trying again.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "example": { "error": { "code": "rate_limited", "message": "Too many requests for this key. The retry-after header says how long to wait.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "500": { "description": "Something went wrong on our side.", "x-error-codes": [ "internal_error" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } } } } } ] }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } } } } }, "/reports/profit-and-loss": { "get": { "operationId": "reports.profitAndLoss", "summary": "Returns the profit and loss statement for one business over a date range.", "description": "Leave `entityId` out only when this key can reach exactly one business. When it can reach several, a call that omits it is refused; call `GET /businesses` for the ids. `prior` is the calendar month before the month `periodStart` falls in, whatever range you ask for. An account with no activity in either period is left out. Figures follow the business's own accounting basis. `basis` in the response says which one.", "tags": [ "reports" ], "x-required-scope": "reports:read", "parameters": [ { "name": "entityId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1002" }, { "name": "periodStart", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "example": "2026-01-01" }, { "name": "periodEnd", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "example": "2026-01-31" } ], "responses": { "200": { "description": "Returns the profit and loss statement for one business over a date range.", "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string" }, "basis": { "type": "string", "enum": [ "cash", "accrual" ] }, "period": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "start", "end" ], "additionalProperties": false }, "rows": { "type": "array", "items": { "type": "object", "properties": { "account": { "type": "string" }, "type": { "type": "string", "enum": [ "revenue", "expense", "total" ] }, "depth": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "isTotal": { "type": "boolean" }, "amount": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "prior": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false } }, "required": [ "account", "type", "depth", "isTotal", "amount", "prior" ], "additionalProperties": false } }, "totals": { "type": "object", "properties": { "revenue": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "expenses": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "netIncome": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false } }, "required": [ "revenue", "expenses", "netIncome" ], "additionalProperties": false }, "prior": { "type": "object", "properties": { "revenue": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "expenses": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "netIncome": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false } }, "required": [ "revenue", "expenses", "netIncome" ], "additionalProperties": false } }, "required": [ "entity", "basis", "period", "rows", "totals", "prior" ], "additionalProperties": false }, "example": { "entity": "Acme Co", "basis": "accrual", "period": { "start": "2026-01-01", "end": "2026-01-31" }, "rows": [ { "account": "Consulting Revenue", "type": "revenue", "depth": 1, "isTotal": false, "amount": { "cents": "10000", "formatted": "$100.00", "currency": "USD" }, "prior": { "cents": "0", "formatted": "$0.00", "currency": "USD" } }, { "account": "Total revenue", "type": "total", "depth": 0, "isTotal": true, "amount": { "cents": "10000", "formatted": "$100.00", "currency": "USD" }, "prior": { "cents": "0", "formatted": "$0.00", "currency": "USD" } } ], "totals": { "revenue": { "cents": "10000", "formatted": "$100.00", "currency": "USD" }, "expenses": { "cents": "0", "formatted": "$0.00", "currency": "USD" }, "netIncome": { "cents": "10000", "formatted": "$100.00", "currency": "USD" } }, "prior": { "revenue": { "cents": "0", "formatted": "$0.00", "currency": "USD" }, "expenses": { "cents": "0", "formatted": "$0.00", "currency": "USD" }, "netIncome": { "cents": "0", "formatted": "$0.00", "currency": "USD" } } } } } }, "401": { "description": "The key is missing, malformed, revoked, or expired.", "x-error-codes": [ "invalid_key" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_key" ] } } } } } ] }, "example": { "error": { "code": "invalid_key", "message": "The key is missing, malformed, revoked, or expired.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "403": { "description": "The key does not carry the scope this endpoint needs. The key is limited to certain businesses, and this is not one of them.", "x-error-codes": [ "insufficient_scope", "entity_not_allowed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "insufficient_scope", "entity_not_allowed" ] } } } } } ] }, "example": { "error": { "code": "insufficient_scope", "message": "The key does not carry the scope this endpoint needs.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "404": { "description": "There is no such record, or none this key is allowed to reach.", "x-error-codes": [ "not_found" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "example": { "error": { "code": "not_found", "message": "There is no such record, or none this key is allowed to reach.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "422": { "description": "Something in the path, the query, or the body did not pass the schema.", "x-error-codes": [ "validation_failed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "example": { "error": { "code": "validation_failed", "message": "Something in the path, the query, or the body did not pass the schema.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "429": { "description": "Too many requests for this key. The retry-after header says how long to wait.", "x-error-codes": [ "rate_limited" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "retry-after": { "description": "How many seconds to wait before trying again.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "example": { "error": { "code": "rate_limited", "message": "Too many requests for this key. The retry-after header says how long to wait.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "500": { "description": "Something went wrong on our side.", "x-error-codes": [ "internal_error" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } } } } } ] }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } } } } }, "/reports/balance-sheet": { "get": { "operationId": "reports.balanceSheet", "summary": "Returns the balance sheet for one business as of a date.", "description": "Leave `entityId` out only when this key can reach exactly one business. When it can reach several, a call that omits it is refused; call `GET /businesses` for the ids. `asOf` is required. The report is the position as of that date. Figures follow the business's own accounting basis. `basis` in the response says which one.", "tags": [ "reports" ], "x-required-scope": "reports:read", "parameters": [ { "name": "entityId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1002" }, { "name": "asOf", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "example": "2026-01-31" } ], "responses": { "200": { "description": "Returns the balance sheet for one business as of a date.", "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string" }, "basis": { "type": "string", "enum": [ "cash", "accrual" ] }, "asOf": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "account": { "type": "string" }, "type": { "type": "string", "enum": [ "asset", "liability", "equity", "total" ] }, "depth": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "isTotal": { "type": "boolean" }, "amount": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false } }, "required": [ "account", "type", "depth", "isTotal", "amount" ], "additionalProperties": false } }, "totals": { "type": "object", "properties": { "assets": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "liabilities": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "equity": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false } }, "required": [ "assets", "liabilities", "equity" ], "additionalProperties": false } }, "required": [ "entity", "basis", "asOf", "rows", "totals" ], "additionalProperties": false }, "example": { "entity": "Acme Co", "basis": "accrual", "asOf": "2026-01-31", "rows": [ { "account": "Total assets", "type": "total", "depth": 0, "isTotal": true, "amount": { "cents": "0", "formatted": "$0.00", "currency": "USD" } } ], "totals": { "assets": { "cents": "0", "formatted": "$0.00", "currency": "USD" }, "liabilities": { "cents": "0", "formatted": "$0.00", "currency": "USD" }, "equity": { "cents": "0", "formatted": "$0.00", "currency": "USD" } } } } } }, "401": { "description": "The key is missing, malformed, revoked, or expired.", "x-error-codes": [ "invalid_key" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_key" ] } } } } } ] }, "example": { "error": { "code": "invalid_key", "message": "The key is missing, malformed, revoked, or expired.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "403": { "description": "The key does not carry the scope this endpoint needs. The key is limited to certain businesses, and this is not one of them.", "x-error-codes": [ "insufficient_scope", "entity_not_allowed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "insufficient_scope", "entity_not_allowed" ] } } } } } ] }, "example": { "error": { "code": "insufficient_scope", "message": "The key does not carry the scope this endpoint needs.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "404": { "description": "There is no such record, or none this key is allowed to reach.", "x-error-codes": [ "not_found" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "example": { "error": { "code": "not_found", "message": "There is no such record, or none this key is allowed to reach.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "422": { "description": "Something in the path, the query, or the body did not pass the schema.", "x-error-codes": [ "validation_failed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "example": { "error": { "code": "validation_failed", "message": "Something in the path, the query, or the body did not pass the schema.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "429": { "description": "Too many requests for this key. The retry-after header says how long to wait.", "x-error-codes": [ "rate_limited" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "retry-after": { "description": "How many seconds to wait before trying again.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "example": { "error": { "code": "rate_limited", "message": "Too many requests for this key. The retry-after header says how long to wait.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "500": { "description": "Something went wrong on our side.", "x-error-codes": [ "internal_error" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } } } } } ] }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } } } } }, "/reports/trial-balance": { "get": { "operationId": "reports.trialBalance", "summary": "Lists every account's balance as of a date; accountants ask for this.", "description": "Leave `entityId` out only when this key can reach exactly one business. When it can reach several, a call that omits it is refused; call `GET /businesses` for the ids. `asOf` is required. The report is the position as of that date. Figures follow the business's own accounting basis. `basis` in the response says which one.", "tags": [ "reports" ], "x-required-scope": "reports:read", "parameters": [ { "name": "entityId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1002" }, { "name": "asOf", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "example": "2026-01-31" } ], "responses": { "200": { "description": "Lists every account's balance as of a date; accountants ask for this.", "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string" }, "basis": { "type": "string", "enum": [ "cash", "accrual" ] }, "asOf": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "account": { "type": "string" }, "debit": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "credit": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false } }, "required": [ "account", "debit", "credit" ], "additionalProperties": false } }, "totals": { "type": "object", "properties": { "debit": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "credit": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false } }, "required": [ "debit", "credit" ], "additionalProperties": false } }, "required": [ "entity", "basis", "asOf", "rows", "totals" ], "additionalProperties": false }, "example": { "entity": "Acme Co", "basis": "accrual", "asOf": "2026-01-31", "rows": [ { "account": "Office Expense", "debit": { "cents": "5000", "formatted": "$50.00", "currency": "USD" }, "credit": { "cents": "0", "formatted": "$0.00", "currency": "USD" } } ], "totals": { "debit": { "cents": "5000", "formatted": "$50.00", "currency": "USD" }, "credit": { "cents": "5000", "formatted": "$50.00", "currency": "USD" } } } } } }, "401": { "description": "The key is missing, malformed, revoked, or expired.", "x-error-codes": [ "invalid_key" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_key" ] } } } } } ] }, "example": { "error": { "code": "invalid_key", "message": "The key is missing, malformed, revoked, or expired.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "403": { "description": "The key does not carry the scope this endpoint needs. The key is limited to certain businesses, and this is not one of them.", "x-error-codes": [ "insufficient_scope", "entity_not_allowed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "insufficient_scope", "entity_not_allowed" ] } } } } } ] }, "example": { "error": { "code": "insufficient_scope", "message": "The key does not carry the scope this endpoint needs.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "404": { "description": "There is no such record, or none this key is allowed to reach.", "x-error-codes": [ "not_found" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "example": { "error": { "code": "not_found", "message": "There is no such record, or none this key is allowed to reach.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "422": { "description": "Something in the path, the query, or the body did not pass the schema.", "x-error-codes": [ "validation_failed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "example": { "error": { "code": "validation_failed", "message": "Something in the path, the query, or the body did not pass the schema.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "429": { "description": "Too many requests for this key. The retry-after header says how long to wait.", "x-error-codes": [ "rate_limited" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "retry-after": { "description": "How many seconds to wait before trying again.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "example": { "error": { "code": "rate_limited", "message": "Too many requests for this key. The retry-after header says how long to wait.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "500": { "description": "Something went wrong on our side.", "x-error-codes": [ "internal_error" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } } } } } ] }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } } } } }, "/reports/ar-aging": { "get": { "operationId": "reports.arAging", "summary": "Returns unpaid customer invoices bucketed by how overdue they are.", "description": "Leave `entityId` out only when this key can reach exactly one business. When it can reach several, a call that omits it is refused; call `GET /businesses` for the ids. `asOf` defaults to the current date in UTC. `buckets` and `grandTotal` cover every unpaid invoice. `items` lists only the 25 largest by balance. `current` means not yet overdue, and `daysOverdue` is negative for something not yet due. The other buckets are 1 to 30, 31 to 60, 61 to 90, and more than 90 days past due.", "tags": [ "reports" ], "x-required-scope": "reports:read", "parameters": [ { "name": "entityId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1002" }, { "name": "asOf", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "Returns unpaid customer invoices bucketed by how overdue they are.", "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "buckets": { "type": "object", "properties": { "current": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "d1_30": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "d31_60": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "d61_90": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "d90plus": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false } }, "required": [ "current", "d1_30", "d31_60", "d61_90", "d90plus" ], "additionalProperties": false }, "grandTotal": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "customerOrVendor": { "type": "string" }, "dueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "daysOverdue": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "balance": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "number": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "customerOrVendor", "dueDate", "daysOverdue", "balance", "number" ], "additionalProperties": false } } }, "required": [ "buckets", "grandTotal", "items" ], "additionalProperties": false }, "example": { "buckets": { "current": { "cents": "10000", "formatted": "$100.00", "currency": "USD" }, "d1_30": { "cents": "0", "formatted": "$0.00", "currency": "USD" }, "d31_60": { "cents": "0", "formatted": "$0.00", "currency": "USD" }, "d61_90": { "cents": "0", "formatted": "$0.00", "currency": "USD" }, "d90plus": { "cents": "0", "formatted": "$0.00", "currency": "USD" } }, "grandTotal": { "cents": "10000", "formatted": "$100.00", "currency": "USD" }, "items": [ { "id": "0190a1b2-c3d4-7e5f-9a9b-0c1d2e3f1007", "customerOrVendor": "Acme Co", "number": 1, "dueDate": "2026-06-15", "daysOverdue": -10, "balance": { "cents": "10000", "formatted": "$100.00", "currency": "USD" } } ] } } } }, "401": { "description": "The key is missing, malformed, revoked, or expired.", "x-error-codes": [ "invalid_key" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_key" ] } } } } } ] }, "example": { "error": { "code": "invalid_key", "message": "The key is missing, malformed, revoked, or expired.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "403": { "description": "The key does not carry the scope this endpoint needs. The key is limited to certain businesses, and this is not one of them.", "x-error-codes": [ "insufficient_scope", "entity_not_allowed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "insufficient_scope", "entity_not_allowed" ] } } } } } ] }, "example": { "error": { "code": "insufficient_scope", "message": "The key does not carry the scope this endpoint needs.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "404": { "description": "There is no such record, or none this key is allowed to reach.", "x-error-codes": [ "not_found" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "example": { "error": { "code": "not_found", "message": "There is no such record, or none this key is allowed to reach.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "422": { "description": "Something in the path, the query, or the body did not pass the schema.", "x-error-codes": [ "validation_failed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "example": { "error": { "code": "validation_failed", "message": "Something in the path, the query, or the body did not pass the schema.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "429": { "description": "Too many requests for this key. The retry-after header says how long to wait.", "x-error-codes": [ "rate_limited" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "retry-after": { "description": "How many seconds to wait before trying again.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "example": { "error": { "code": "rate_limited", "message": "Too many requests for this key. The retry-after header says how long to wait.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "500": { "description": "Something went wrong on our side.", "x-error-codes": [ "internal_error" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } } } } } ] }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } } } } }, "/reports/ap-aging": { "get": { "operationId": "reports.apAging", "summary": "Returns what one business owes, bucketed by how long it has been outstanding.", "description": "Leave `entityId` out only when this key can reach exactly one business. When it can reach several, a call that omits it is refused; call `GET /businesses` for the ids. This counts reimbursements that have been approved and not yet paid, and accepted expenses that are not reimbursable and did not come from a bank feed. `asOf` defaults to the current date in UTC. `buckets` and `grandTotal` cover everything owed. `items` lists only the 25 largest by balance. `daysOverdue` here counts days since the expense's date or the reimbursement's approval, not days past a due date, and `dueDate` carries that same date. `current` covers anything dated on or after `asOf`. The other buckets are 1 to 30, 31 to 60, 61 to 90, and more than 90 days outstanding.", "tags": [ "reports" ], "x-required-scope": "reports:read", "parameters": [ { "name": "entityId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1002" }, { "name": "asOf", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "Returns what one business owes, bucketed by how long it has been outstanding.", "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "buckets": { "type": "object", "properties": { "current": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "d1_30": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "d31_60": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "d61_90": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "d90plus": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false } }, "required": [ "current", "d1_30", "d31_60", "d61_90", "d90plus" ], "additionalProperties": false }, "grandTotal": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "customerOrVendor": { "type": "string" }, "dueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "daysOverdue": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "balance": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false }, "number": { "type": "null" } }, "required": [ "id", "customerOrVendor", "dueDate", "daysOverdue", "balance", "number" ], "additionalProperties": false } } }, "required": [ "buckets", "grandTotal", "items" ], "additionalProperties": false }, "example": { "buckets": { "current": { "cents": "0", "formatted": "$0.00", "currency": "USD" }, "d1_30": { "cents": "5000", "formatted": "$50.00", "currency": "USD" }, "d31_60": { "cents": "0", "formatted": "$0.00", "currency": "USD" }, "d61_90": { "cents": "0", "formatted": "$0.00", "currency": "USD" }, "d90plus": { "cents": "0", "formatted": "$0.00", "currency": "USD" } }, "grandTotal": { "cents": "5000", "formatted": "$50.00", "currency": "USD" }, "items": [ { "id": "0190a1b2-c3d4-7e5f-9a9b-0c1d2e3f1008", "customerOrVendor": "Office Depot", "number": null, "dueDate": "2026-02-05", "daysOverdue": 5, "balance": { "cents": "5000", "formatted": "$50.00", "currency": "USD" } } ] } } } }, "401": { "description": "The key is missing, malformed, revoked, or expired.", "x-error-codes": [ "invalid_key" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_key" ] } } } } } ] }, "example": { "error": { "code": "invalid_key", "message": "The key is missing, malformed, revoked, or expired.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "403": { "description": "The key does not carry the scope this endpoint needs. The key is limited to certain businesses, and this is not one of them.", "x-error-codes": [ "insufficient_scope", "entity_not_allowed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "insufficient_scope", "entity_not_allowed" ] } } } } } ] }, "example": { "error": { "code": "insufficient_scope", "message": "The key does not carry the scope this endpoint needs.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "404": { "description": "There is no such record, or none this key is allowed to reach.", "x-error-codes": [ "not_found" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "example": { "error": { "code": "not_found", "message": "There is no such record, or none this key is allowed to reach.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "422": { "description": "Something in the path, the query, or the body did not pass the schema.", "x-error-codes": [ "validation_failed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "example": { "error": { "code": "validation_failed", "message": "Something in the path, the query, or the body did not pass the schema.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "429": { "description": "Too many requests for this key. The retry-after header says how long to wait.", "x-error-codes": [ "rate_limited" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "retry-after": { "description": "How many seconds to wait before trying again.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "example": { "error": { "code": "rate_limited", "message": "Too many requests for this key. The retry-after header says how long to wait.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "500": { "description": "Something went wrong on our side.", "x-error-codes": [ "internal_error" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } } } } } ] }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } } } } }, "/expenses": { "post": { "operationId": "expenses.create", "summary": "Records and immediately posts a manual expense.", "description": "Leave `entityId` out only when this key can reach exactly one business. When it can reach several, a call that omits it is refused; call `GET /businesses` for the ids. Send exactly one of `vendorName` or `vendorId`. A `vendorName` that matches no existing vendor exactly creates a new one, so prefer `vendorId` when you have it. The match is case sensitive. `amountCents` must be greater than zero. The account you send is posted as it is. Nothing here is categorized by AI, and nothing lands in the review queue.", "tags": [ "expenses" ], "x-required-scope": "expenses:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Send the same key again to replay the original result instead of running the write a second time. Kept for 24 hours.", "schema": { "type": "string", "pattern": "^[\\x20-\\x7E]{1,200}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entityId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "amountCents": { "type": "string", "pattern": "^\\d{1,15}$" }, "vendorName": { "type": "string", "minLength": 1, "maxLength": 200 }, "vendorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "accountId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "memo": { "type": "string", "maxLength": 2000 } }, "required": [ "date", "amountCents", "accountId" ], "additionalProperties": false }, "example": { "entityId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1002", "date": "2026-02-01", "amountCents": "1500", "vendorId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1004", "accountId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1003" } } } }, "responses": { "201": { "description": "Records and immediately posts a manual expense.", "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "idempotent-replayed": { "description": "Present and true when this is the replay of an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "expenseId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "transactionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] } }, "required": [ "expenseId", "transactionId" ], "additionalProperties": false }, "example": { "expenseId": "0190a1b2-c3d4-7e5f-9a9b-0c1d2e3f100a", "transactionId": "0190a1b2-c3d4-7e5f-9a9b-0c1d2e3f1006" } } } }, "401": { "description": "The key is missing, malformed, revoked, or expired.", "x-error-codes": [ "invalid_key" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_key" ] } } } } } ] }, "example": { "error": { "code": "invalid_key", "message": "The key is missing, malformed, revoked, or expired.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "402": { "description": "The subscription is past due, so the books are read only for now.", "x-error-codes": [ "read_only_billing_state" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "read_only_billing_state" ] } } } } } ] }, "example": { "error": { "code": "read_only_billing_state", "message": "The subscription is past due, so the books are read only for now.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "403": { "description": "The key does not carry the scope this endpoint needs. The key is limited to certain businesses, and this is not one of them.", "x-error-codes": [ "insufficient_scope", "entity_not_allowed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "insufficient_scope", "entity_not_allowed" ] } } } } } ] }, "example": { "error": { "code": "insufficient_scope", "message": "The key does not carry the scope this endpoint needs.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "404": { "description": "There is no such record, or none this key is allowed to reach.", "x-error-codes": [ "not_found" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "example": { "error": { "code": "not_found", "message": "There is no such record, or none this key is allowed to reach.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "409": { "description": "The date falls inside a closed period, so nothing can be posted to it. The request clashed with something that has already happened.", "x-error-codes": [ "period_locked", "conflict" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "period_locked", "conflict" ] } } } } } ] }, "example": { "error": { "code": "period_locked", "message": "The date falls inside a closed period, so nothing can be posted to it.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "422": { "description": "Something in the path, the query, or the body did not pass the schema.", "x-error-codes": [ "validation_failed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "example": { "error": { "code": "validation_failed", "message": "Something in the path, the query, or the body did not pass the schema.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "429": { "description": "Too many requests for this key. The retry-after header says how long to wait.", "x-error-codes": [ "rate_limited" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "retry-after": { "description": "How many seconds to wait before trying again.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "example": { "error": { "code": "rate_limited", "message": "Too many requests for this key. The retry-after header says how long to wait.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "500": { "description": "Something went wrong on our side.", "x-error-codes": [ "internal_error" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } } } } } ] }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } } } } }, "/invoices/{id}/send": { "post": { "operationId": "invoices.send", "summary": "Finalizes a draft invoice and emails it to the customer.", "description": "Finalizing posts the invoice to the books and emails the customer before this call returns. There is no API call that undoes it. An invoice drafted in a currency other than US dollars needs an exchange rate for its issue date. Without one this call is refused with `validation_failed`, and the draft is left as it was. Try again once the day's rate has been fetched.", "tags": [ "invoices" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "0190a1b2-c3d4-7e5f-9a9b-0c1d2e3f1007" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Send the same key again to replay the original result instead of running the write a second time. Kept for 24 hours.", "schema": { "type": "string", "pattern": "^[\\x20-\\x7E]{1,200}$" } } ], "responses": { "200": { "description": "Finalizes a draft invoice and emails it to the customer.", "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "idempotent-replayed": { "description": "Present and true when this is the replay of an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ], "additionalProperties": false }, "example": { "ok": true } } } }, "401": { "description": "The key is missing, malformed, revoked, or expired.", "x-error-codes": [ "invalid_key" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_key" ] } } } } } ] }, "example": { "error": { "code": "invalid_key", "message": "The key is missing, malformed, revoked, or expired.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "402": { "description": "The subscription is past due, so the books are read only for now.", "x-error-codes": [ "read_only_billing_state" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "read_only_billing_state" ] } } } } } ] }, "example": { "error": { "code": "read_only_billing_state", "message": "The subscription is past due, so the books are read only for now.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "403": { "description": "The key does not carry the scope this endpoint needs.", "x-error-codes": [ "insufficient_scope" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "insufficient_scope" ] } } } } } ] }, "example": { "error": { "code": "insufficient_scope", "message": "The key does not carry the scope this endpoint needs.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "404": { "description": "There is no such record, or none this key is allowed to reach.", "x-error-codes": [ "not_found" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "example": { "error": { "code": "not_found", "message": "There is no such record, or none this key is allowed to reach.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "409": { "description": "The date falls inside a closed period, so nothing can be posted to it. The request clashed with something that has already happened.", "x-error-codes": [ "period_locked", "conflict" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "period_locked", "conflict" ] } } } } } ] }, "example": { "error": { "code": "period_locked", "message": "The date falls inside a closed period, so nothing can be posted to it.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "422": { "description": "Something in the path, the query, or the body did not pass the schema.", "x-error-codes": [ "validation_failed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "example": { "error": { "code": "validation_failed", "message": "Something in the path, the query, or the body did not pass the schema.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "429": { "description": "Too many requests for this key. The retry-after header says how long to wait.", "x-error-codes": [ "rate_limited" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "retry-after": { "description": "How many seconds to wait before trying again.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "example": { "error": { "code": "rate_limited", "message": "Too many requests for this key. The retry-after header says how long to wait.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "500": { "description": "Something went wrong on our side.", "x-error-codes": [ "internal_error" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } } } } } ] }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } } } } }, "/invoices/{id}/remind": { "post": { "operationId": "invoices.remind", "summary": "Sends a payment reminder email for one sent (or overdue) invoice.", "description": "The invoice has to be sent, viewed, or overdue, and the customer has to have an email address. A second reminder for the same invoice within 24 hours is refused with `conflict`.", "tags": [ "invoices" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "0190a1b2-c3d4-7e5f-9a9b-0c1d2e3f1007" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Send the same key again to replay the original result instead of running the write a second time. Kept for 24 hours.", "schema": { "type": "string", "pattern": "^[\\x20-\\x7E]{1,200}$" } } ], "responses": { "200": { "description": "Sends a payment reminder email for one sent (or overdue) invoice.", "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "idempotent-replayed": { "description": "Present and true when this is the replay of an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ], "additionalProperties": false }, "example": { "ok": true } } } }, "401": { "description": "The key is missing, malformed, revoked, or expired.", "x-error-codes": [ "invalid_key" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_key" ] } } } } } ] }, "example": { "error": { "code": "invalid_key", "message": "The key is missing, malformed, revoked, or expired.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "403": { "description": "The key does not carry the scope this endpoint needs.", "x-error-codes": [ "insufficient_scope" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "insufficient_scope" ] } } } } } ] }, "example": { "error": { "code": "insufficient_scope", "message": "The key does not carry the scope this endpoint needs.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "404": { "description": "There is no such record, or none this key is allowed to reach.", "x-error-codes": [ "not_found" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "example": { "error": { "code": "not_found", "message": "There is no such record, or none this key is allowed to reach.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "409": { "description": "The request clashed with something that has already happened.", "x-error-codes": [ "conflict" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "conflict" ] } } } } } ] }, "example": { "error": { "code": "conflict", "message": "The request clashed with something that has already happened.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "422": { "description": "Something in the path, the query, or the body did not pass the schema.", "x-error-codes": [ "validation_failed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "example": { "error": { "code": "validation_failed", "message": "Something in the path, the query, or the body did not pass the schema.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "429": { "description": "Too many requests for this key. The retry-after header says how long to wait.", "x-error-codes": [ "rate_limited" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "retry-after": { "description": "How many seconds to wait before trying again.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "example": { "error": { "code": "rate_limited", "message": "Too many requests for this key. The retry-after header says how long to wait.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "500": { "description": "Something went wrong on our side.", "x-error-codes": [ "internal_error" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } } } } } ] }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } } } } }, "/invoices/{id}/payments": { "post": { "operationId": "invoices.recordPayment", "summary": "Records a payment received against a sent invoice: check, cash, wire, or other.", "description": "`amountCents` must be greater than zero, and may not exceed the remaining balance. The invoice has to have been sent already, and must not be fully paid. `method` defaults to `other`, and `paidAt` defaults to the current date in UTC. `method` covers the payments you take yourself. Card payments arrive through Stripe and post on their own. The balance in the response leaves out any payment that was refunded. `amountCents` and the `balance` in the response are in the invoice's own currency, which may not be US dollars. Every other amount on this surface is US dollars.", "tags": [ "invoices" ], "x-required-scope": "invoices:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "0190a1b2-c3d4-7e5f-9a9b-0c1d2e3f1007" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Send the same key again to replay the original result instead of running the write a second time. Kept for 24 hours.", "schema": { "type": "string", "pattern": "^[\\x20-\\x7E]{1,200}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amountCents": { "type": "string", "pattern": "^\\d{1,15}$" }, "paidAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "method": { "type": "string", "enum": [ "check", "cash", "wire", "other" ] }, "memo": { "type": "string", "maxLength": 2000 } }, "required": [ "amountCents" ], "additionalProperties": false }, "example": { "amountCents": "4000", "method": "check" } } } }, "responses": { "200": { "description": "Records a payment received against a sent invoice: check, cash, wire, or other.", "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "idempotent-replayed": { "description": "Present and true when this is the replay of an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "draft", "sent", "viewed", "partially_paid", "paid", "overdue", "void" ] }, "balance": { "type": "object", "properties": { "cents": { "type": "string", "pattern": "^-?\\d+$" }, "formatted": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "cents", "formatted", "currency" ], "additionalProperties": false } }, "required": [ "paymentId", "status", "balance" ], "additionalProperties": false }, "example": { "paymentId": "0190a1b2-c3d4-7e5f-9a9b-0c1d2e3f1009", "status": "partially_paid", "balance": { "cents": "6000", "formatted": "$60.00", "currency": "USD" } } } } }, "401": { "description": "The key is missing, malformed, revoked, or expired.", "x-error-codes": [ "invalid_key" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_key" ] } } } } } ] }, "example": { "error": { "code": "invalid_key", "message": "The key is missing, malformed, revoked, or expired.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "402": { "description": "The subscription is past due, so the books are read only for now.", "x-error-codes": [ "read_only_billing_state" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "read_only_billing_state" ] } } } } } ] }, "example": { "error": { "code": "read_only_billing_state", "message": "The subscription is past due, so the books are read only for now.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "403": { "description": "The key does not carry the scope this endpoint needs.", "x-error-codes": [ "insufficient_scope" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "insufficient_scope" ] } } } } } ] }, "example": { "error": { "code": "insufficient_scope", "message": "The key does not carry the scope this endpoint needs.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "404": { "description": "There is no such record, or none this key is allowed to reach.", "x-error-codes": [ "not_found" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "example": { "error": { "code": "not_found", "message": "There is no such record, or none this key is allowed to reach.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "409": { "description": "The date falls inside a closed period, so nothing can be posted to it. The request clashed with something that has already happened.", "x-error-codes": [ "period_locked", "conflict" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "period_locked", "conflict" ] } } } } } ] }, "example": { "error": { "code": "period_locked", "message": "The date falls inside a closed period, so nothing can be posted to it.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "422": { "description": "Something in the path, the query, or the body did not pass the schema.", "x-error-codes": [ "validation_failed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "example": { "error": { "code": "validation_failed", "message": "Something in the path, the query, or the body did not pass the schema.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "429": { "description": "Too many requests for this key. The retry-after header says how long to wait.", "x-error-codes": [ "rate_limited" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "retry-after": { "description": "How many seconds to wait before trying again.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "example": { "error": { "code": "rate_limited", "message": "Too many requests for this key. The retry-after header says how long to wait.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "500": { "description": "Something went wrong on our side.", "x-error-codes": [ "internal_error" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } } } } } ] }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } } } } }, "/review-queue/{id}/accept": { "post": { "operationId": "review.accept", "summary": "Posts a pending review-queue expense, under the proposed account or one you name.", "description": "With no `accountId`, the category the AI proposed is used. If the item has no proposed category, you have to send one.", "tags": [ "review-queue" ], "x-required-scope": "review:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "0190a1b2-c3d4-7e5f-9a9b-0c1d2e3f1008" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Send the same key again to replay the original result instead of running the write a second time. Kept for 24 hours.", "schema": { "type": "string", "pattern": "^[\\x20-\\x7E]{1,200}$" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Posts a pending review-queue expense, under the proposed account or one you name.", "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "idempotent-replayed": { "description": "Present and true when this is the replay of an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ], "additionalProperties": false }, "example": { "ok": true } } } }, "401": { "description": "The key is missing, malformed, revoked, or expired.", "x-error-codes": [ "invalid_key" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_key" ] } } } } } ] }, "example": { "error": { "code": "invalid_key", "message": "The key is missing, malformed, revoked, or expired.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "402": { "description": "The subscription is past due, so the books are read only for now.", "x-error-codes": [ "read_only_billing_state" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "read_only_billing_state" ] } } } } } ] }, "example": { "error": { "code": "read_only_billing_state", "message": "The subscription is past due, so the books are read only for now.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "403": { "description": "The key does not carry the scope this endpoint needs.", "x-error-codes": [ "insufficient_scope" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "insufficient_scope" ] } } } } } ] }, "example": { "error": { "code": "insufficient_scope", "message": "The key does not carry the scope this endpoint needs.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "404": { "description": "There is no such record, or none this key is allowed to reach.", "x-error-codes": [ "not_found" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "not_found" ] } } } } } ] }, "example": { "error": { "code": "not_found", "message": "There is no such record, or none this key is allowed to reach.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "409": { "description": "The date falls inside a closed period, so nothing can be posted to it. The request clashed with something that has already happened.", "x-error-codes": [ "period_locked", "conflict" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "period_locked", "conflict" ] } } } } } ] }, "example": { "error": { "code": "period_locked", "message": "The date falls inside a closed period, so nothing can be posted to it.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "422": { "description": "Something in the path, the query, or the body did not pass the schema.", "x-error-codes": [ "validation_failed" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "validation_failed" ] } } } } } ] }, "example": { "error": { "code": "validation_failed", "message": "Something in the path, the query, or the body did not pass the schema.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "429": { "description": "Too many requests for this key. The retry-after header says how long to wait.", "x-error-codes": [ "rate_limited" ], "headers": { "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } }, "retry-after": { "description": "How many seconds to wait before trying again.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "example": { "error": { "code": "rate_limited", "message": "Too many requests for this key. The retry-after header says how long to wait.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } }, "500": { "description": "Something went wrong on our side.", "x-error-codes": [ "internal_error" ], "headers": { "ratelimit-limit": { "description": "How many requests this key may make in the current 10-minute window.", "schema": { "type": "string" } }, "ratelimit-remaining": { "description": "How many of those are left.", "schema": { "type": "string" } }, "ratelimit-reset": { "description": "When the window resets, as a Unix time in seconds.", "schema": { "type": "string" } }, "x-request-id": { "description": "This request's id. Quote it when you ask us about a call.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "internal_error" ] } } } } } ] }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "requestId": "api:0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1000:1f0c2d8e" } } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Send your key as a bearer token: Authorization: Bearer nmo_live_REPLACE_WITH_YOUR_KEY" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_key", "insufficient_scope", "entity_not_allowed", "period_locked", "read_only_billing_state", "rate_limited", "validation_failed", "not_found", "conflict", "internal_error" ] }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }