# Puzzle API Documentation > Documentation for Puzzle API ## Guides - [Welcome](https://puzzle-api.readme.io/docs/welcome.md) - [What is Puzzle?](https://puzzle-api.readme.io/docs/what-is-puzzle.md) - [Embedding Puzzle](https://puzzle-api.readme.io/docs/embedding-puzzle.md) - [Use Cases](https://puzzle-api.readme.io/docs/use-cases.md) - [Scopes](https://puzzle-api.readme.io/docs/scopes.md) - [Getting Started](https://puzzle-api.readme.io/docs/getting-started.md) - [Errors](https://puzzle-api.readme.io/docs/errors.md) - [One-Click Onboarding](https://puzzle-api.readme.io/docs/one-click-onboarding.md) - [One-Click Onboarding w/ Journal Entry Synch](https://puzzle-api.readme.io/docs/copy-of-one-click-onboarding-w-journal-entry-synch.md) - [Bookkeeping](https://puzzle-api.readme.io/docs/bookkeeping.md) - [Accounts Payable](https://puzzle-api.readme.io/docs/accounts-payable.md) - [Accounts Receivable](https://puzzle-api.readme.io/docs/accounts-receivable.md) - [Payroll](https://puzzle-api.readme.io/docs/payroll.md) - [Transactions](https://puzzle-api.readme.io/docs/transactions.md) - [Account Balances](https://puzzle-api.readme.io/docs/account-balances-in-puzzle.md) ## API Reference - [Create Classifications](https://puzzle-api.readme.io/reference/createclassification.md): Creates a classification. Requires scope: write:classification - [Get Company](https://puzzle-api.readme.io/reference/company-1.md) - [Disconnect Company](https://puzzle-api.readme.io/reference/disconnect.md) - [Initiate Creating a Company](https://puzzle-api.readme.io/reference/createcompanyapi.md): Call this endpoint to pass some company information that is usually asked for during Puzzle's onboarding flow. A URL will be returned. When you redirect your user to this URL, the company information that was passed the original request will be prefilled for them in Puzzle's UI, allowing them to skip a few steps and create their Puzzle account more quickly. - [Get companies](https://puzzle-api.readme.io/reference/companiesapi.md): Returns a list of companies the calling user has access to. Required scope: read:company - [Create Integration Connection](https://puzzle-api.readme.io/reference/createintegrationconnection.md): Creates an integration connection for the company that you can use to push data into Puzzle. Required scope: write:integration_connection - [Get Chart of Accounts](https://puzzle-api.readme.io/reference/chartofaccounts.md): Retrieves the company's chart of accounts (COA), which defines the financial statement categories used for accounting purposes. By default, all accounts are returned and the balances are calculated using cash basis. Required scope: read:company - [Get Classifications](https://puzzle-api.readme.io/reference/classifications.md): Retrieves a list of all classifications available for the calling company. Requires scope: read:company - [Get Classification](https://puzzle-api.readme.io/reference/classification.md): Retrieves a classification available for the calling company. Requires scope: read:company - [Get Trial Balance Report](https://puzzle-api.readme.io/reference/ledgerreportdownload.md): This endpoint generates a trial balance report. You can specify the time period for the report using either: dateMacro (a predefined date range) startDate and endDate (a custom date range) If all three are provided, dateMacro takes precedence. Required scope: read:company - [Initiate Prefilled Onboarding](https://puzzle-api.readme.io/reference/initiateprefilledonboarding.md): Call this endpoint to pass some company information that is usually asked for during Puzzle's onboarding flow. A URL will be returned. When you redirect your user to this URL, the company information that was passed the original request will be prefilled for them in Puzzle's UI, allowing them to skip a few steps and create their Puzzle account more quickly. - [Get Monthly Checklist](https://puzzle-api.readme.io/reference/monthlychecklists.md): This endpoint retrieves the monthly checklist for the given company and month. Required scope: read:company - [Create Financial Account](https://puzzle-api.readme.io/reference/createfinancialaccount.md): Creates a financial account for the specified Puzzle company. The created account will have a status of Syncing until data is added to it, then it will be Ready. Please allow a couple of minutes for this status to update after the data has been added to the account. The type of data that can be added to an account depends on the account type. Required scope: write:account - [Get Financial Accounts](https://puzzle-api.readme.io/reference/financialaccounts.md): Retrieves a list of all of the company's financial accounts. Required scope: read:company - [Create Account Balance](https://puzzle-api.readme.io/reference/createaccountbalance.md): Creates a balance for a financial account. Note that Puzzle stores all account balances trending towards positive, regardless of account type. Additional details can be found here. Required scope: write:account_balance - [Get Financial Account Balances](https://puzzle-api.readme.io/reference/balances.md): Returns the balances on a company's financial accounts on the provided dates. A balance is the balance on the account at the start of the day provided. If we have an official institution account balance for that date, we will use the institution's provided account balance. If the institution has not provided an account balance for the requested date, we will calculate the balance by summing transactions in the account that have occurred between the target data and the closest balance we have available. Note that Puzzle stores all account balances trending towards positive, regardless of account type. Additional details can be found here. If any of the company accounts are currently syncing or processing, this endpoint will return a 409 error. You can check the status of an account in the company object on the FinancialInstitutionAccount object. If the status is UpToDate then these balances can be retrieved without error. Required scope: read:company - [Get Ledger Account](https://puzzle-api.readme.io/reference/ledgeraccount.md): Retrieves a specific account in the company's chart of accounts. By default, the balances on the account are calculated using cash basis. Required scope: read:company - [Get Bills](https://puzzle-api.readme.io/reference/billsapi.md): Retrieves bills. Required scope: read:company - [Create Bill](https://puzzle-api.readme.io/reference/createbillapi.md): Creates a bill for the company. Required scope: write:bill - [Get Bill](https://puzzle-api.readme.io/reference/billapi.md): Retrieves a bill. Required scope: read:company - [Update Bill](https://puzzle-api.readme.io/reference/updatebillapi.md): Updates an existing bill with new values. Required scope: write:bill - [Update Bill Status](https://puzzle-api.readme.io/reference/updatebillstatusapi.md): Updates an existing Bill's sStatus. Required scope: write:bill - [Get Invoices](https://puzzle-api.readme.io/reference/invoicesapi.md): Retrieves invoices. Required scope: read:company - [Create Invoice](https://puzzle-api.readme.io/reference/createinvoiceapi.md): Creates an invoice for the company. Required scope: write:invoice - [Get Invoice](https://puzzle-api.readme.io/reference/invoiceapi.md): Retrieves an invoice. Required scope: read:company - [Update Invoice](https://puzzle-api.readme.io/reference/updateinvoiceapi.md): Updates an invoice. Required scope: write:invoice - [Get Vendors](https://puzzle-api.readme.io/reference/vendors-1.md): Retrieves a list of all of the company's vendors. Required scope: read:company - [Create Vendor](https://puzzle-api.readme.io/reference/createvendorapi.md): Creates a new Vendor for the company. Required scope: write:vendor - [Update Vendor](https://puzzle-api.readme.io/reference/updatevendorapi.md): Updates an existing Vendor for the company. Required scope: write:vendor - [Get Customers](https://puzzle-api.readme.io/reference/customersapi.md): Retrieves a list of all of the company's customers. Required scope: write:customer - [Create Customer](https://puzzle-api.readme.io/reference/createcustomerapi.md): Creates a new Customer for the company. Required scope: write:customer - [Update Customer](https://puzzle-api.readme.io/reference/updatecustomerapi.md): Updates a Customer for the company. Required scope: write:customer - [Create Requests](https://puzzle-api.readme.io/reference/createrequests.md): Creates category, documentation, and message requests in a company for a transaction. Required scope: write:request - [Create Task](https://puzzle-api.readme.io/reference/createtask.md): This endpoint is experimental and is subject to change Click here for more information. Create a task for the given company. Required scope: write:task - [Update Task](https://puzzle-api.readme.io/reference/updatetask.md): This endpoint is experimental and is subject to change Click here for more information. Update a task for the given company. Required scope: write:task - [Get Requests](https://puzzle-api.readme.io/reference/requests.md): Retrieve a list of requests in a company. Required scope: read:company - [Get Tasks](https://puzzle-api.readme.io/reference/tasks.md): This endpoint is experimental and is subject to change Retrieves a list of tasks for the company. Tasks represent work items that need to be completed, such as categorization reviews, documentation requests, or messages. Required scope: read:company - [Get Vendor Spending Report](https://puzzle-api.readme.io/reference/vendorspendingreportapi.md): Retrieves a report of the company's vendor spending. Required scope: read:company - [Get Income Statement](https://puzzle-api.readme.io/reference/incomestatementapi.md): Retrieves the income statement for a company with flexible filtering options. This endpoint returns income statement data broken down by the specified time interval (month, quarter, or year). You can filter results by departments and locations. Required scope: read:company - [Get Balance Sheet Statement](https://puzzle-api.readme.io/reference/balancesheetstatementapi.md): Retrieves the balance sheet statement for a company with flexible filtering options. This endpoint returns balance sheet statement data broken down by the specified time interval (month, quarter, or year). Required scope: read:company - [Get Cash Activity Statement](https://puzzle-api.readme.io/reference/cashactivitystatementapi.md): Retrieves the cash activity statement for a company with flexible filtering options. This endpoint returns cash activity statement data broken down by the specified time interval (month, quarter, or year). Required scope: read:company - [Get Income Statement (Interop Format)](https://puzzle-api.readme.io/reference/incomestatementinteropformatapi.md): Retrieves the income statement in QuickBooks-compatible format with hierarchical row structure. This endpoint returns income statement data in the same format as QuickBooks Online API, with nested sections and summary rows. Supports filtering by accounting method, and department. Required scope: read:company - [Get Balance Sheet (Interop Format)](https://puzzle-api.readme.io/reference/balancesheetinteropformatapi.md): Retrieves the balance sheet in QuickBooks-compatible format with hierarchical row structure. This endpoint returns balance sheet data in the same format as QuickBooks Online API, with nested sections and summary rows. Supports filtering by accounting method, and department. Required scope: read:company - [Get Financial Statements](https://puzzle-api.readme.io/reference/financialstatements.md): Retrieve the financial statements of a company. Currently supports the Cash Activity Report, Income Statement, and Balance Sheet. Required scope: read:company - [Get Expense Metrics](https://puzzle-api.readme.io/reference/expensemetrics.md): Retrieves a summary of a company's expenses for a given time span, broken into chunks as specified in the 'interval' param Currently only the 'month' interval is supported, but will soon support 'quarter' and 'year'. The array of metrics will be returned in ascending order from earliest time interval to latest. Required scope: read:company - [Get Categorization Metrics](https://puzzle-api.readme.io/reference/categorizationmetrics.md): Retrieves categorization metrics for the company. Required scope: read:company - [Get Revenue Metrics](https://puzzle-api.readme.io/reference/revenuemetrics.md): Retrieves a summary of a company's revenue for a given time span, broken into chunks as specified in the 'interval' param. We will soon support additional revenue metrics such as ARR and accrual-based ARR. Currently only the 'month' interval is supported, but will soon support 'quarter' and 'year'. The array of metrics will be returned in ascending order from earliest time interval to latest. Required scope: read:company - [Get Employee Metrics](https://puzzle-api.readme.io/reference/employeemetrics.md): Retrieves a summary of a company's employees for a given time span, broken into chunks as specified in the 'interval' param. The metrics are currently across all departments. We will support filtering by department in the near future. Currently only the 'month' interval is supported, but will soon support 'quarter' and 'year'. The array of metrics will be returned in ascending order from earliest time interval to latest. Required scope: read:company - [Get Spending Metrics](https://puzzle-api.readme.io/reference/spendingmetrics.md): Retrieves payroll and non-payroll spending metrics for the given period range. Provide startPeriod and endPeriod in YYYY-MM format. Required scope: read:company - [Get Current User](https://puzzle-api.readme.io/reference/me.md): Gets information about the current user. Only valid for OAuth connections. - [Fetch a Link Token](https://puzzle-api.readme.io/reference/createtemporarylinktoken.md): This authentication method has been deprecated. Please use the Authentication endpoints instead. Additional details can be found here. Creates a link token that can be used to authenticate a user when directing them to the connection flow. The token expires after 30 minutes. After obtaining your link token, create a link to Puzzle so the user can connect their Puzzle account. Connect your Puzzle account They will see your welcome page and an opportunity to log in or sign up with Puzzle. - [Get Workers](https://puzzle-api.readme.io/reference/workerslist.md): Retrieves a list of all of the company's workers, both employees and contractors. Required scope: read:worker - [Create Contractor](https://puzzle-api.readme.io/reference/createcontractor.md): Create a contractor for the given company. Requires scope: write:worker - [Create Employee](https://puzzle-api.readme.io/reference/createemployee.md): Create an employee for the given company. Required scope: write:worker - [Get Benefits](https://puzzle-api.readme.io/reference/benefits.md): Retrieves a list of all benefits for the given company. These benefits represent company-level benefits that can have both an employee contribution and a company contribution. Payrolls will reference these benefits and provide details on the employee and company contribution amounts. Requires scope: read:company - [Create Benefit](https://puzzle-api.readme.io/reference/createbenefit.md): Create a benefit for the given company. Requires scope: write:benefit - [Create Payroll](https://puzzle-api.readme.io/reference/createdetailedpayroll.md): Create a single payroll. Payrolls can only be added to accounts with the Payroll type. All the amounts on the top-level payroll object are the totals for all the associated compensations Payrolls must have at least one employeeCompensation OR contractorCompensation The transactionAmounts field should contain a list of all the amounts for all the non-reimbursement transactions that were used to fund this payroll. If no transactionAmounts are provided, the companyDebit amount will be used instead Puzzle uses this information to link this payroll with all the transactions that funded it to ensure everything gets represented in the general ledger correctly. Puzzle currently only supports USD currencies Required scope: write:payroll - [Get Payroll](https://puzzle-api.readme.io/reference/getpayroll.md): Get a single payroll by ID Required scope: read:company - [Create Journal Entry](https://puzzle-api.readme.io/reference/upsertjournalentry.md): Required scope: write:journal Journal entries are the entries made in a company's ledger accounts as a way of recording financial impact. The line items for each journal entry should balance to 0. Create Journal Entries endpoint creates a Journal Entry into our Gateway and not on our Ledger. Once the Gateway receives a Journal Entry, you get an OK response. Ledger Journal Entries are created async and can be retrieved through the Get Journal Entries endpoint. Puzzle journal entries are immutable. This means that when an update is made, 2 additional journal entries get created - one to reverse the original journal entry and another to reflect the updates. Reversal journal entries can be identified by their description field - they will have descriptions matching "Reversal of {{journal entry id}}". All Puzzle companies have both cash and accrual journal entries; they are distinct populations. - [Delete Journal Entry](https://puzzle-api.readme.io/reference/deletejournalentry.md): Required scope: write:journal Journal entries are the entries made in a company's ledger accounts as a way of recording financial impact. Delete Journal Entry endpoint will delete a draft journal entry and void a posted one. - [Get Journal Entries](https://puzzle-api.readme.io/reference/journalentries-1.md): Required scope: read:company - [Create Journal Entry](https://puzzle-api.readme.io/reference/upsertjournalentries.md): Required scope: write:journal Journal entries are the entries made in a company's ledger accounts as a way of recording financial impact. The line items for each journal entry should balance to 0. Create Journal Entries endpoint creates a Journal Entry into our Gateway and not on our Ledger. Once the Gateway receives a Journal Entry, you get an OK response. Ledger Journal Entries are created async and can be retrieved through the Get Journal Entries endpoint. Puzzle journal entries are immutable. This means that when an update is made, 2 additional journal entries get created - one to reverse the original journal entry and another to reflect the updates. Reversal journal entries can be identified by their description field - they will have descriptions matching "Reversal of {{journal entry id}}". All Puzzle companies have both cash and accrual journal entries; they are distinct populations. - [Create Document](https://puzzle-api.readme.io/reference/createjournalentrydocument.md): Create a document for a given journal entry. Required scope: write:journal - [Get Puzzle Categories](https://puzzle-api.readme.io/reference/puzzlecategories.md): Retrieves all of the valid Puzzle categories that can be used to categorize transactions. Only valid for OAuth connections. - [Get Transactions](https://puzzle-api.readme.io/reference/gettransactions.md): Get transactions by filter Required scope: read:company - [Create Transactions](https://puzzle-api.readme.io/reference/createtransactions.md): Create multiple transactions for a single financial account. You can create up to 500 transactions per request Transactions can only be added to accounts with the following types: Depository, Credit, Investment, Loan, or PaymentProcessing Transactions are created asynchronously, so the response only includes a mapping of the Puzzle ID to the native ID and the status of the transaction, which will either be pending or duplicate. pending = The data for that transaction has been saved and is currently being processed. Please allow a couple of minutes for this transaction to show up in the system. duplicate = There is already a transaction with that same nativeId in the system, so this transaction data was ignored. The sign on the amount field depends on the account type. Additional details can be found here. The category field may or may not directly correspond to an account in the Chart of Accounts. It is used to help Puzzle automatically categorize this transaction. It does not guarantee a specific COA assignment. Required scope: write:transaction - [Get Transaction](https://puzzle-api.readme.io/reference/gettransaction.md): Get a single transaction by ID Required scope: read:company - [Update Transaction](https://puzzle-api.readme.io/reference/updatetransaction.md): Updates an existing Transaction Required scope: write:transaction - [Create Document](https://puzzle-api.readme.io/reference/createtransactiondocument.md): Create a document for a given transaction. Required scope: write:transaction - [Get Documents for Entity](https://puzzle-api.readme.io/reference/documentapi.md): Retrieves all documents for a given entity (bill, invoice, transaction, or manual journal entry). Pass the entity ID (e.g., bil_xxx, inv_xxx, txn_xxx, mje_xxx) to get all associated documents with signed download URLs. Supported entity prefixes: bil_ (bills), inv_ (invoices), txn_ (transactions), mje_ (manual journal entries) Required scope: read:company - [Create Attachment for Entity](https://puzzle-api.readme.io/reference/createdocument.md): Creates an attachment for a given entity (bill, invoice, transaction, journal entry, or manual journal entry). Pass the entity ID in the URL and the file data in the request body. Supported entity prefixes: bil_ (bills), inv_ (invoices), txn_ (transactions), je_ (journal entries), mje_ (manual journal entries) Required scope: Depends on entity type - write:bill, write:invoice, write:transaction, or write:journal - [Get Departments](https://puzzle-api.readme.io/reference/departments-1.md): Retrieves a list of all departments for the given company. Requires scope: read:company - [Create Department](https://puzzle-api.readme.io/reference/createdepartment.md): Create a department for the given company. Departments must have a unique name. A 400 error will be thrown if a department with the same name already exists. Requires scope: write:department - [Get Locations](https://puzzle-api.readme.io/reference/locations-1.md): Retrieves a list of all locations for the given company. Requires scope: read:company - [Create Location](https://puzzle-api.readme.io/reference/createlocation.md): Create a location for the given company. Locations must be unique. A 400 error will be thrown if a location with the same city, state, and zip code already exists. Requires scope: write:location - [Get Products](https://puzzle-api.readme.io/reference/productsapi.md): Retrieves a list of all of the company's products. Required scope: read:company - [Create Product](https://puzzle-api.readme.io/reference/createproductapi.md): Create a product for the given company. Requires scope: write:product - [Get Product](https://puzzle-api.readme.io/reference/productapi.md): Get a single product by ID for the company. Required scope: read:company - [Update Product](https://puzzle-api.readme.io/reference/updateproductapi.md): Update a product for the given company. Requires scope: write:product - [Authorize (OAuth 2.0 + PKCE)](https://puzzle-api.readme.io/reference/oauthauthorize.md): Starts the OAuth 2.0 Authorization Code flow. Redirects the user's browser to the login/consent UI and, if approved, back to the client's `redirect_uri` with an authorization code. Supports PKCE. - [Get Token (OAuth 2.0)](https://puzzle-api.readme.io/reference/oauthgettoken.md): Exchanges an authorization code for tokens, or refreshes an access token. Uses application/x-www-form-urlencoded as required by OAuth 2.0. Clients may authenticate via HTTP Basic (recommended for confidential clients) or by including `client_id` (and, if applicable, `client_secret`) in the body.