{ "openapi": "3.0.3", "info": { "title": "Synced API", "version": "1", "description": "Synced operations, called for an organisation your access token was approved for. A token for one organisation needs nothing more. A token a user approved for several must name one on every call in the Synced-Organisation header; GET /v1/organisations lists them." }, "servers": [ { "url": "https://api.syncedhq.com" } ], "paths": { "/v1/operations/accounts.list": { "get": { "operationId": "accounts_list", "summary": "List accounts", "description": "The organisation's chart of accounts, from QuickBooks, Xero or, with no accounting system, Synced's own: each account's name, full name (parent:child in QuickBooks), number or code, type and whether it is active. Use search to narrow it (matches name, full name or number). Use it to find the exact account before asking for an account's transactions.", "security": [ { "oauth2": [ "synced.read" ] } ], "x-synced-readonly": true, "x-synced-roles": "Super admin, Admin, Submitter, Custom", "parameters": [ { "$ref": "#/components/parameters/Organisation" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "title": "Search", "description": "Words from the account's name or full name, or its number." } }, { "name": "includeInactive", "in": "query", "required": false, "schema": { "type": "boolean", "title": "Include inactive", "default": false } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "fullName": { "type": "string" }, "number": { "type": "string" }, "type": { "type": "string" }, "classification": { "type": "string" }, "active": { "type": "boolean" }, "parentId": { "type": "string" } } } } } } } } }, "401": { "description": "Missing or invalid access token" }, "403": { "description": "The token lacks the scope, or no longer has access to the organisation" }, "404": { "description": "No such operation" }, "429": { "description": "Rate limited" } } } }, "/v1/operations/banking.accounts": { "get": { "operationId": "banking_accounts", "summary": "List bank accounts", "description": "The organisation's bank and card accounts, as the Transactions screen in Synced lists them: each account's id, name, number, bank, currency, how many transactions it has and how many are still to reconcile, and its balance as Synced derives it from the imported transactions. Use search to narrow it (matches name, number or bank). Use it to find the account before asking for its transactions.", "security": [ { "oauth2": [ "synced.read" ] } ], "x-synced-readonly": true, "x-synced-roles": "Super admin, Admin", "parameters": [ { "$ref": "#/components/parameters/Organisation" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "title": "Search", "description": "Words from the account's name, number or bank." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "number": { "type": "string" }, "type": { "type": "string" }, "bank": { "type": "string" }, "currency": { "type": "string" }, "isDefault": { "type": "boolean" }, "toReconcile": { "type": "integer" }, "transactions": { "type": "integer" }, "lastTransactionDate": { "type": "string" }, "balance": { "type": "number" } } } } } } } } }, "401": { "description": "Missing or invalid access token" }, "403": { "description": "The token lacks the scope, or no longer has access to the organisation" }, "404": { "description": "No such operation" }, "429": { "description": "Rate limited" } } } }, "/v1/operations/banking.transactions": { "get": { "operationId": "banking_transactions", "summary": "Bank transactions", "description": "The bank and card transactions on the Transactions screen in Synced, newest first. account names one account (name, number or id; banking.accounts lists them); leave it out for every account. status is to_reconcile, reconciled or all (the default). Set the period with period (this_month, last_month, this_quarter, last_quarter, ytd, last_year) or from and to (yyyy-MM-dd); the default is the last three months. search matches the bank narration or the matched supplier; amountMin and amountMax bound the size of the amount, money in or out alike. Each transaction has its date, narration, amount (negative for money spent), account, status and reconciledIn: synced (matched to a document in Synced), accounting_system (reconciled in Xero or QuickBooks) or outside_synced (marked reconciled outside Synced). A transaction matched in Synced carries linked: the document's id, number, type, supplier, total, what it is coded to and a link to open it (documents.get takes the id for its lines). totals cover the whole period and account(s), whatever status or search. It is paged: limit (default 100, at most 500) and page; hasMore says there is another page.", "security": [ { "oauth2": [ "synced.read" ] } ], "x-synced-readonly": true, "x-synced-roles": "Super admin, Admin", "parameters": [ { "$ref": "#/components/parameters/Organisation" }, { "name": "account", "in": "query", "required": false, "schema": { "type": "string", "title": "Account", "description": "One bank or card account's name, number or id. Leave out for every account." } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "title": "Status", "default": "all", "enum": [ "all", "to_reconcile", "reconciled" ], "description": "to_reconcile, reconciled, or all (both)." } }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "title": "Period", "enum": [ "this_month", "last_month", "this_quarter", "last_quarter", "ytd", "last_year", "custom" ], "description": "A preset period, or custom with from and to. Default: the last three months." } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "title": "From", "description": "The first day, yyyy-MM-dd." } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "title": "To", "description": "The last day, yyyy-MM-dd." } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "title": "Search", "description": "Contained in the bank narration or the matched supplier." } }, { "name": "amountMin", "in": "query", "required": false, "schema": { "type": "number", "title": "Amount at least", "minimum": 0, "description": "The size of the amount, money in or out alike." } }, { "name": "amountMax", "in": "query", "required": false, "schema": { "type": "number", "title": "Amount at most", "minimum": 0, "description": "The size of the amount, money in or out alike." } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "title": "Order", "enum": [ "newest", "oldest" ], "default": "newest" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "title": "Limit", "minimum": 1, "maximum": 500, "default": 100, "description": "Transactions per page." } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "title": "Page", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "object" }, "period": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } } }, "status": { "type": "string" }, "totals": { "type": "object", "properties": { "openingBalance": { "type": "number" }, "moneyIn": { "type": "number" }, "moneyOut": { "type": "number" }, "closingBalance": { "type": "number" }, "transactions": { "type": "integer" }, "toReconcile": { "type": "integer" }, "reconciled": { "type": "integer" } } }, "count": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "hasMore": { "type": "boolean" }, "transactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "type": "string" }, "description": { "type": "string" }, "amount": { "type": "number" }, "direction": { "type": "string" }, "currency": { "type": "string" }, "account": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "status": { "type": "string", "enum": [ "to_reconcile", "reconciled" ] }, "reconciledIn": { "type": "string", "description": "synced, accounting_system or outside_synced; null while to reconcile." }, "suggestedMatch": { "type": "boolean" }, "report": { "type": "string" }, "runningBalance": { "type": "number" }, "linked": { "type": "object", "properties": { "documentId": { "type": "string" }, "number": { "type": "string" }, "type": { "type": "string" }, "supplier": { "type": "string" }, "date": { "type": "string" }, "total": { "type": "number" }, "currency": { "type": "string" }, "codedTo": { "type": "string" }, "tax": { "type": "string" }, "details": { "type": "string" }, "accountingId": { "type": "string" }, "link": { "type": "string" } } } } } } } } } } }, "401": { "description": "Missing or invalid access token" }, "403": { "description": "The token lacks the scope, or no longer has access to the organisation" }, "404": { "description": "No such operation" }, "429": { "description": "Rate limited" } } } }, "/v1/operations/bills.list_saved_filters": { "get": { "operationId": "bills_list_saved_filters", "summary": "List Bills To Pay Filters", "description": "Lists the organisation's saved Bills to Pay filters: name, description, and how many outstanding bills each matches with their total amount due. Pass a name to bills_list_to_pay as its filter.", "security": [ { "oauth2": [ "synced.read" ] } ], "x-synced-readonly": true, "x-synced-roles": "Super admin, Admin, Submitter, Custom", "parameters": [ { "$ref": "#/components/parameters/Organisation" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "baseCurrency": { "type": "string", "title": "Base currency" }, "filters": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "title": "Filter id" }, "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "count": { "type": "integer", "title": "Number of bills" }, "total": { "type": "number", "title": "Total amount due" } } } } } } } } }, "401": { "description": "Missing or invalid access token" }, "403": { "description": "The token lacks the scope, or no longer has access to the organisation" }, "404": { "description": "No such operation" }, "429": { "description": "Rate limited" } } } }, "/v1/operations/bills.list_to_pay": { "get": { "operationId": "bills_list_to_pay", "summary": "List Bills To Pay", "description": "Lists the organisation's outstanding bills and expense claims (Bills to Pay): supplier, invoice number, type, date, due date, scheduled date, tags, currency, original amount, amount due in the base currency and latest note, with the count and total. Leave filter empty for every outstanding bill. To narrow to one of the organisation's saved Bills to Pay filters, pass its name, or words from its name or description; call bills_list_saved_filters to see them. An unknown or ambiguous filter is answered with the list of filters to choose from.", "security": [ { "oauth2": [ "synced.read" ] } ], "x-synced-readonly": true, "x-synced-roles": "Super admin, Admin, Submitter, Custom", "parameters": [ { "$ref": "#/components/parameters/Organisation" }, { "name": "filter", "in": "query", "required": false, "schema": { "type": "string", "title": "Saved filter", "description": "A saved Bills to Pay filter, by name or words from its description. Leave empty for all bills." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "title": "Bills to pay", "properties": { "filter": { "type": "object", "title": "Filter applied", "description": "Null when every outstanding bill is listed.", "properties": { "id": { "type": "string", "title": "Filter id" }, "name": { "type": "string", "title": "Filter name" }, "description": { "type": "string", "title": "Filter description" } } }, "count": { "type": "integer", "title": "Number of bills" }, "total": { "type": "number", "title": "Total amount due", "description": "In the base currency." }, "baseCurrency": { "type": "string", "title": "Base currency" }, "bills": { "type": "array", "title": "Bills", "items": { "type": "object", "properties": { "supplier": { "type": "string", "title": "Supplier", "description": "For an expense claim, the employee and the claim." }, "invoiceNumber": { "type": "string", "title": "Invoice number" }, "type": { "type": "string", "title": "Type", "enum": [ "Bill", "Expense claim" ] }, "date": { "type": "string", "title": "Date", "format": "date" }, "dueDate": { "type": "string", "title": "Due date", "format": "date" }, "scheduledDate": { "type": "string", "title": "Scheduled date", "format": "date" }, "tags": { "type": "string", "title": "Tags", "description": "Comma-separated." }, "currency": { "type": "string", "title": "Currency", "description": "The bill's own currency." }, "originalAmount": { "type": "number", "title": "Original amount", "description": "In the bill's currency, when it is not the base currency." }, "amountDue": { "type": "number", "title": "Amount due", "description": "In the base currency." }, "latestNote": { "type": "string", "title": "Latest note" } } } } } } } } }, "401": { "description": "Missing or invalid access token" }, "403": { "description": "The token lacks the scope, or no longer has access to the organisation" }, "404": { "description": "No such operation" }, "429": { "description": "Rate limited" } } } }, "/v1/operations/documents.file": { "get": { "operationId": "documents_file", "summary": "Get a document's file", "description": "One Synced document's original file (the PDF or image of the bill or receipt as it arrived), base64, up to 10 MB. Synced's account-transactions view calls this to show the document; to read a document's supplier, totals and lines, use documents.get instead. The id is a document id from ledger.account_transactions or documents.get. An id that is not one of this organisation's documents, or a document with no file, is not found.", "security": [ { "oauth2": [ "synced.read" ] } ], "x-synced-readonly": true, "x-synced-roles": "Super admin, Admin", "parameters": [ { "$ref": "#/components/parameters/Organisation" }, { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "title": "Document id", "description": "One Synced document id." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "contentType": { "type": "string", "enum": [ "application/pdf", "image/png", "image/jpeg", "image/gif", "image/webp" ] }, "size": { "type": "integer", "description": "Bytes, before base64." }, "data": { "type": "string", "contentEncoding": "base64" } } } } } }, "401": { "description": "Missing or invalid access token" }, "403": { "description": "The token lacks the scope, or no longer has access to the organisation" }, "404": { "description": "No such operation" }, "429": { "description": "Rate limited" } } } }, "/v1/operations/documents.get": { "get": { "operationId": "documents_get", "summary": "Get documents", "description": "Synced documents by id: one, or several separated by commas (up to 50). Each comes with its supplier, number, dates, currency and totals; its coded lines (the account, tax, class and customer each line was published with); and its invoice line items (what the supplier's invoice itself listed: product code, quantity, unit, unit price, tax and amount). The ids are the document ids ledger.account_transactions returns. An id that is not one of this organisation's documents is listed under notFound.", "security": [ { "oauth2": [ "synced.read" ] } ], "x-synced-readonly": true, "x-synced-roles": "Super admin, Admin", "parameters": [ { "$ref": "#/components/parameters/Organisation" }, { "name": "ids", "in": "query", "required": true, "schema": { "type": "string", "title": "Document ids", "description": "One or more Synced document ids, comma separated (up to 50)." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "type": { "type": "string" }, "supplier": { "type": "string" }, "date": { "type": "string" }, "dueDate": { "type": "string" }, "currency": { "type": "string" }, "subtotal": { "type": "number" }, "tax": { "type": "number" }, "total": { "type": "number" }, "accountingId": { "type": "string" }, "publishedAt": { "type": "string" }, "link": { "type": "string" }, "codedLines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "number" }, "subtotal": { "type": "number" }, "tax": { "type": "number" }, "total": { "type": "number" }, "account": { "type": "string" }, "accountId": { "type": "string" }, "taxCodeId": { "type": "string" }, "class": { "type": "string" }, "customer": { "type": "string" } } } }, "invoiceLines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "productCode": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "unitPrice": { "type": "number" }, "tax": { "type": "number" }, "amount": { "type": "number" } } } } } } }, "notFound": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "description": "Missing or invalid access token" }, "403": { "description": "The token lacks the scope, or no longer has access to the organisation" }, "404": { "description": "No such operation" }, "429": { "description": "Rate limited" } } } }, "/v1/operations/ledger.account_transactions": { "get": { "operationId": "ledger_account_transactions", "summary": "Account transactions", "description": "Everything coded to one account (and its sub-accounts) in a period, one row per line, in home currency. It reads Synced's copy of the organisation's books: from QuickBooks, bills, expenses, cheques, card charges and refunds, supplier credits, deposits, sales invoices, sales receipts and customer credit notes; from Xero, approved and paid bills, sales invoices, credit notes, and spend and receive money; with no accounting system, the documents booked in Synced. system says which. Name the account with account (a name, full name, number or code; accounts.list lists them). Set the period with period (this_month, last_month, this_quarter, last_quarter, ytd, last_year) or from and to (yyyy-MM-dd); the default is the last three months. groupBy supplier totals the lines per supplier, largest first, and groupBy month per month; with detailForTop N the transactions of the N largest groups come nested under them, which answers \"a breakdown by supplier, with the line items of the top 5\" in one call. supplier narrows to one or several suppliers (comma separated). Totals are exact even when the list is cut at limit. A transaction published from Synced carries its document (documents.get takes its id). reconcile true also fetches the accounting system's own total for the account and period and reports what Synced does not hold (QuickBooks: mostly journal entries; Xero: manual journals, for income and expense accounts).", "security": [ { "oauth2": [ "synced.read" ] } ], "x-synced-readonly": true, "x-synced-roles": "Super admin, Admin", "parameters": [ { "$ref": "#/components/parameters/Organisation" }, { "name": "account", "in": "query", "required": true, "schema": { "type": "string", "title": "Account", "description": "The account's name, full name (Parent:Child), number or id." } }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "title": "Period", "enum": [ "this_month", "last_month", "this_quarter", "last_quarter", "ytd", "last_year", "custom" ], "description": "A preset period, or custom with from and to. Default: the last three months." } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "title": "From", "description": "The first day, yyyy-MM-dd." } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "title": "To", "description": "The last day, yyyy-MM-dd." } }, { "name": "groupBy", "in": "query", "required": false, "schema": { "type": "string", "title": "Group by", "enum": [ "none", "supplier", "month" ], "default": "none", "description": "none: the transactions. supplier: totals per supplier, largest first. month: totals per month, in date order." } }, { "name": "supplier", "in": "query", "required": false, "schema": { "type": "string", "title": "Supplier", "description": "Only these suppliers: names or ids, comma separated." } }, { "name": "detailForTop", "in": "query", "required": false, "schema": { "type": "integer", "title": "Detail for top", "minimum": 0, "maximum": 50, "default": 0, "description": "With groupBy: nest the transactions of the top N groups." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "title": "Limit", "minimum": 1, "maximum": 1000, "default": 200, "description": "The most transactions (or groups) to return. Totals always cover everything." } }, { "name": "reconcile", "in": "query", "required": false, "schema": { "type": "boolean", "title": "Check against QuickBooks", "default": false, "description": "Also fetch QuickBooks' total for the account and period (slower)." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "fullName": { "type": "string" }, "type": { "type": "string" }, "subAccounts": { "type": "array", "items": { "type": "string" } } } }, "period": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "label": { "type": "string" } } }, "system": { "type": "string", "description": "QuickBooks, Xero or Synced (no accounting system)." }, "currency": { "type": "string" }, "total": { "type": "number" }, "count": { "type": "integer" }, "groupBy": { "type": "string" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "total": { "type": "number" }, "count": { "type": "integer" }, "share": { "type": "number" }, "transactions": { "type": "array", "items": { "type": "object" } } } } }, "transactions": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "type": { "type": "string" }, "number": { "type": "string" }, "supplier": { "type": "string" }, "description": { "type": "string" }, "account": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "amountInCurrency": { "type": "number" }, "transactionId": { "type": "string" }, "link": { "type": "string" }, "document": { "type": "object" } } } }, "truncated": { "type": "boolean" }, "reconciliation": { "type": "object" }, "notes": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "description": "Missing or invalid access token" }, "403": { "description": "The token lacks the scope, or no longer has access to the organisation" }, "404": { "description": "No such operation" }, "429": { "description": "Rate limited" } } } }, "/v1/operations/reports.balance_sheet": { "get": { "operationId": "reports_balance_sheet", "summary": "Balance Sheet", "description": "The organisation's Balance Sheet, read live from Xero or QuickBooks (for an organisation with no accounting system, built by Synced from the documents booked in it, which does not see bank or opening balances: basis and notes say so): assets, liabilities and equity at a date. Give the date with asAt (yyyy-MM-dd), or a period preset (this_month, last_month, this_quarter, last_quarter, ytd, last_year) for its last day. To compare, set comparePeriods (1 to 12) and compareBy (month or year). The response lists the dates once (current first) and every section, group and account with one amount per date, in that order, plus Total Assets and Total Liabilities and Equity.", "security": [ { "oauth2": [ "synced.read" ] } ], "x-synced-readonly": true, "x-synced-roles": "Super admin, Admin", "parameters": [ { "$ref": "#/components/parameters/Organisation" }, { "name": "asAt", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "title": "As at", "description": "The date the balances are at, yyyy-MM-dd. Overrides period." } }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "title": "Period", "default": "this_month", "enum": [ "this_month", "last_month", "this_quarter", "last_quarter", "ytd", "last_year" ], "description": "Balances at the last day of this period, when asAt is not given." } }, { "name": "comparePeriods", "in": "query", "required": false, "schema": { "type": "integer", "title": "Comparison periods", "minimum": 0, "maximum": 12, "default": 0, "description": "How many earlier dates to compare with." } }, { "name": "compareBy", "in": "query", "required": false, "schema": { "type": "string", "title": "Compare by", "enum": [ "month", "year" ], "default": "month", "description": "month: each comparison is the month end before. year: the same date a year earlier." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "title": "Financial statement", "properties": { "report": { "type": "string", "title": "Report" }, "organisation": { "type": "string", "title": "Organisation" }, "currency": { "type": "string", "title": "Currency" }, "period": { "type": "string", "title": "Period preset" }, "compareBy": { "type": "string", "title": "Compared by" }, "comparePeriods": { "type": "integer", "title": "Comparison periods" }, "periods": { "type": "array", "title": "Periods (current first)", "items": { "type": "object", "properties": { "label": { "type": "string" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } } }, "sections": { "type": "array", "title": "Sections", "items": { "type": "object", "properties": { "title": { "type": "string" }, "total": { "type": "array", "items": { "type": "number" } }, "groups": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "total": { "type": "array", "items": { "type": "number" } }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "amounts": { "type": "array", "items": { "type": "number" } } } } } } } } } } }, "summary": { "type": "array", "title": "Summary lines", "items": { "type": "object", "properties": { "label": { "type": "string" }, "amounts": { "type": "array", "items": { "type": "number" } } } } } } } } } }, "401": { "description": "Missing or invalid access token" }, "403": { "description": "The token lacks the scope, or no longer has access to the organisation" }, "404": { "description": "No such operation" }, "429": { "description": "Rate limited" } } } }, "/v1/operations/reports.profit_and_loss": { "get": { "operationId": "reports_profit_and_loss", "summary": "Profit and Loss", "description": "The organisation's Profit and Loss (income statement), read live from Xero or QuickBooks; for an organisation with no accounting system, Synced builds it from the documents booked in it (basis and notes say so). Choose the period with period (this_month, last_month, this_quarter, last_quarter, ytd, last_year), or set period to custom with from and to. To compare, set comparePeriods (1 to 12) and compareBy (month or year): comparePeriods 2 with compareBy year gives this period and the same period in each of the two years before. The response lists the periods once (current first) and every section, group and account with one amount per period, in that order, plus Gross Profit and Net Profit.", "security": [ { "oauth2": [ "synced.read" ] } ], "x-synced-readonly": true, "x-synced-roles": "Super admin, Admin", "parameters": [ { "$ref": "#/components/parameters/Organisation" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "title": "Period", "default": "this_month", "enum": [ "this_month", "last_month", "this_quarter", "last_quarter", "ytd", "last_year", "custom" ], "description": "A preset period, or custom with from and to." } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "title": "From", "description": "With period custom: the first day, yyyy-MM-dd." } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "title": "To", "description": "With period custom: the last day, yyyy-MM-dd." } }, { "name": "comparePeriods", "in": "query", "required": false, "schema": { "type": "integer", "title": "Comparison periods", "minimum": 0, "maximum": 12, "default": 0, "description": "How many earlier periods to compare with." } }, { "name": "compareBy", "in": "query", "required": false, "schema": { "type": "string", "title": "Compare by", "enum": [ "month", "year" ], "default": "month", "description": "month: each comparison is the month before. year: the same period a year earlier." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "title": "Financial statement", "properties": { "report": { "type": "string", "title": "Report" }, "organisation": { "type": "string", "title": "Organisation" }, "currency": { "type": "string", "title": "Currency" }, "period": { "type": "string", "title": "Period preset" }, "compareBy": { "type": "string", "title": "Compared by" }, "comparePeriods": { "type": "integer", "title": "Comparison periods" }, "periods": { "type": "array", "title": "Periods (current first)", "items": { "type": "object", "properties": { "label": { "type": "string" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } } }, "sections": { "type": "array", "title": "Sections", "items": { "type": "object", "properties": { "title": { "type": "string" }, "total": { "type": "array", "items": { "type": "number" } }, "groups": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "total": { "type": "array", "items": { "type": "number" } }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "amounts": { "type": "array", "items": { "type": "number" } } } } } } } } } } }, "summary": { "type": "array", "title": "Summary lines", "items": { "type": "object", "properties": { "label": { "type": "string" }, "amounts": { "type": "array", "items": { "type": "number" } } } } } } } } } }, "401": { "description": "Missing or invalid access token" }, "403": { "description": "The token lacks the scope, or no longer has access to the organisation" }, "404": { "description": "No such operation" }, "429": { "description": "Rate limited" } } } } }, "components": { "parameters": { "Organisation": { "name": "Synced-Organisation", "in": "header", "required": false, "description": "The id of the organisation this call is for. Required when the token was approved for several organisations, and must be one of them (GET /v1/organisations).", "schema": { "type": "string", "format": "uuid" } } }, "securitySchemes": { "oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://api.syncedhq.com/oauth/authorize", "tokenUrl": "https://api.syncedhq.com/oauth/token", "refreshUrl": "https://api.syncedhq.com/oauth/token", "scopes": { "synced.read": "Read your organisation's data", "synced.write": "Create and change records in your organisation" } }, "clientCredentials": { "tokenUrl": "https://api.syncedhq.com/oauth/token", "scopes": { "synced.read": "Read your organisation's data", "synced.write": "Create and change records in your organisation" } } } } } } }