openapi: 3.0.3 info: title: Puzzle Api description: Puzzle Api version: '0' servers: - url: https://app.puzzle.io/rest/v0 paths: /company: post: operationId: createCompanyApi summary: Initiate Creating a Company description: >- 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. tags: - Company requestBody: required: true content: application/json: schema: type: object properties: user: type: object properties: email: type: string minLength: 1 firstName: type: string minLength: 1 lastName: type: string minLength: 1 required: - email - firstName - lastName company: type: object properties: name: type: string minLength: 1 type: type: string enum: - SAAS - ECOMMERCE - MARKETPLACE - ADVERTISING - SERVICES - ENTERPRISE - FINTECH - FINTECH_CRYPTO - VIRTUAL_GOODS - CONSUMER - NOT_SURE - OTHER - AGRICULTURE_AND_FARMING - CONSTRUCTION - HEALTHCARE - HOME_SERVICES - LEGAL - MANUFACTURING - MEDIA_AND_ENTERTAINMENT - PROFESSIONAL_SERVICES - RETAIL - REAL_ESTATE - RESTAURANT - TRANSPORTATION - WHOLESALE_TRADE description: >- The value is normalized before matching, so any casing that maps onto a listed value is accepted. revenueModel: type: string enum: - AnnualSubscription - MonthlySubscription - MultipleRevenueModels - NotSure - PreRevenue - ServiceBased - TransactionBased - UsageBased - Subscription - AddOns - TransactionBasedPhysical - TransactionBasedOther - Contracts - HourlyBilling - Marketplace - Commission timeZone: type: string minLength: 1 currentUserRole: type: string enum: - Founder - CompanyEmployee - OutsourcedAccountantOrCFO coaType: type: string enum: - saas - ecommerce - fondo - every - decimal - custom orgType: type: string enum: - CCorporation - LLC - Partnership - SCorporation - SoleProprietorship hasHistoricalData: type: boolean isFreshStart: type: boolean phoneNumber: type: string website: type: string required: - name - type - revenueModel - timeZone - currentUserRole - orgType integration: type: object properties: nativeCompanyId: type: string minLength: 1 authForwardToken: type: string createPushIntegrationConnection: type: boolean required: - nativeCompanyId required: - user - company responses: '200': description: OK content: application/json: schema: type: object properties: userId: type: string minLength: 1 description: Partner-facing external identifier companyId: type: string minLength: 1 description: Partner-facing external identifier setPasswordUrl: type: string nullable: true required: - userId - companyId - setPasswordUrl /firm/accuracy-checks: get: operationId: firmAccuracyChecks summary: Get firm accuracy checks description: >- Items Puzzle has flagged as potentially incorrect or needing review, across every company the calling connection reaches through its active firm authorizations. Each row carries its own companyId, matching the ids returned by GET /companies. These are deterministic rule checks, not AI output: duplicate transactions, a descriptor with multiple vendors, a vendor with multiple categories, invoices paid with a non-zero balance, uncategorized invoice or bill lines, unbilled recurring revenue, and known issues. `type` is the reason the check fired and `createdAt` is when it first fired. Defaults to open checks (status ACTIVE) so a dashboard sees what still needs attention; pass statuses to widen. Ordered by magnitude so the largest items come first. companyIds narrows to a subset of the firm's companies; naming a company the connection is not authorized for returns 403 rather than an empty result. Required: read:company tags: - Firm parameters: - name: companyIds in: query required: false schema: anyOf: - type: string minLength: 1 description: Partner-facing external identifier - type: array items: type: string minLength: 1 description: Partner-facing external identifier - name: groups in: query required: false schema: anyOf: - type: string enum: - BILL - INVOICE - TRANSACTION - type: array items: type: string enum: - BILL - INVOICE - TRANSACTION - name: types in: query required: false schema: anyOf: - type: string enum: - TRANSACTION_DESCRIPTOR_MULTIPLE_VENDORS - TRANSACTION_VENDOR_MULTIPLE_CATEGORIES - TRANSACTION_DUPLICATE - INVOICE_PAID_WITH_NON_ZERO_BALANCE - INVOICE_UNCATEGORIZED_LINES - UNBILLED_RECURRING_REVENUE - BILL_UNCATEGORIZED_LINES - KNOWN_ISSUE - type: array items: type: string enum: - TRANSACTION_DESCRIPTOR_MULTIPLE_VENDORS - TRANSACTION_VENDOR_MULTIPLE_CATEGORIES - TRANSACTION_DUPLICATE - INVOICE_PAID_WITH_NON_ZERO_BALANCE - INVOICE_UNCATEGORIZED_LINES - UNBILLED_RECURRING_REVENUE - BILL_UNCATEGORIZED_LINES - KNOWN_ISSUE - name: statuses in: query required: false schema: anyOf: - type: string enum: - ACTIVE - COMPLETED - DISMISSED - PROCESSING - type: array items: type: string enum: - ACTIVE - COMPLETED - DISMISSED - PROCESSING - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 - name: cursor in: query required: false schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier companyId: type: string minLength: 1 description: Partner-facing external identifier group: type: string enum: - BILL - INVOICE - TRANSACTION type: type: string enum: - TRANSACTION_DESCRIPTOR_MULTIPLE_VENDORS - TRANSACTION_VENDOR_MULTIPLE_CATEGORIES - TRANSACTION_DUPLICATE - INVOICE_PAID_WITH_NON_ZERO_BALANCE - INVOICE_UNCATEGORIZED_LINES - UNBILLED_RECURRING_REVENUE - BILL_UNCATEGORIZED_LINES - KNOWN_ISSUE status: type: string enum: - ACTIVE - COMPLETED - DISMISSED - PROCESSING createdAt: type: string minLength: 1 description: ISO 8601 timestamp updatedAt: type: string minLength: 1 description: ISO 8601 timestamp uniqueKey: type: string magnitude: type: integer required: - id - companyId - group - type - status - createdAt - updatedAt - uniqueKey - magnitude nextCursor: type: string nullable: true required: - items - nextCursor /firm/ai-close-items: get: operationId: firmAiCloseItems summary: Get firm AI Close items description: >- AI Close checklist items across every company the calling connection reaches through its active firm authorizations, by close month. Distinct from GET /firm/accuracy-checks: this is the AI-assisted close surface, where accuracy checks are deterministic rules. Archived and removed items are excluded — the feed is what is open, not the history. Items carry status, assignee, approver and due date where set. cursor is an insertOrder high-water mark rather than an opaque token. companyIds narrows to a subset of the firm's companies; naming a company the connection is not authorized for returns 403 rather than an empty result. Required: read:company tags: - Firm parameters: - name: companyIds in: query required: false schema: anyOf: - type: string minLength: 1 description: Partner-facing external identifier - type: array items: type: string minLength: 1 description: Partner-facing external identifier - name: months in: query required: false schema: anyOf: - type: string pattern: ^\d{4}-(0[1-9]|1[0-2])$ - type: array items: type: string pattern: ^\d{4}-(0[1-9]|1[0-2])$ - name: statuses in: query required: false schema: anyOf: - type: string enum: - ToDo - InProgress - NeedsAction - WaitingOnClient - ReadyForReview - Done - type: array items: type: string enum: - ToDo - InProgress - NeedsAction - WaitingOnClient - ReadyForReview - Done - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 - name: cursor in: query required: false schema: type: string pattern: ^[1-9]\d*$ responses: '200': description: OK content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier companyId: type: string minLength: 1 description: Partner-facing external identifier month: type: string type: type: string enum: - Manual - AiAssist status: type: string enum: - ToDo - InProgress - NeedsAction - WaitingOnClient - ReadyForReview - Done name: type: string description: type: string nullable: true dueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD nullable: true completedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true createdAt: type: string minLength: 1 description: ISO 8601 timestamp assignee: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier name: type: string nullable: true email: type: string nullable: true required: - id - name - email nullable: true approver: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier name: type: string nullable: true email: type: string nullable: true required: - id - name - email nullable: true required: - id - companyId - month - type - status - name - description - dueDate - completedAt - createdAt - assignee - approver nextCursor: type: string nullable: true required: - items - nextCursor /firm/audit-logs: get: operationId: firmAuditLogs summary: Get firm activity description: >- Timestamped audit log across every company the calling connection reaches through its active firm authorizations. Firm-scoped on purpose: a firm with many clients does not have to make one request per client. Each row carries its own companyId, matching the ids returned by GET /companies. startDate and endDate are interpreted in UTC, unlike the per-company endpoints which use the company's timezone, because the feed can span companies in different zones. companyIds narrows to a subset of the firm's companies; naming a company the connection is not authorized for returns 403 rather than an empty result. Required: read:company tags: - Firm parameters: - name: startDate in: query required: true schema: type: string minLength: 1 description: Calendar date, YYYY-MM-DD - name: endDate in: query required: true schema: type: string minLength: 1 description: Calendar date, YYYY-MM-DD - name: companyIds in: query required: false schema: anyOf: - type: string minLength: 1 description: Partner-facing external identifier - type: array items: type: string minLength: 1 description: Partner-facing external identifier - name: userIds in: query required: false schema: anyOf: - type: string minLength: 1 description: Partner-facing external identifier - type: array items: type: string minLength: 1 description: Partner-facing external identifier - name: itemTypes in: query required: false schema: anyOf: - type: string - type: array items: type: string - name: activityTypes in: query required: false schema: anyOf: - type: string - type: array items: type: string - name: actorTypes in: query required: false schema: anyOf: - type: string - type: array items: type: string - name: limit in: query required: false schema: type: integer - name: cursor in: query required: false schema: type: string - name: sortBy in: query required: false schema: type: string enum: - DATE_ASC - DATE_DESC responses: '200': description: OK content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string companyId: type: string minLength: 1 description: Partner-facing external identifier createdAt: type: string minLength: 1 description: ISO 8601 timestamp itemType: type: string activityType: type: string nullable: true actorType: type: string itemDescription: type: string nullable: true detail: type: string nullable: true user: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier name: type: string nullable: true email: type: string nullable: true required: - id - name - email nullable: true required: - id - companyId - createdAt - itemType - activityType - actorType - itemDescription - detail - user nextCursor: type: string nullable: true required: - items - nextCursor /companies: get: operationId: companiesApi summary: Get companies description: >- Modern client credentials return a paginated list of companies authorized through the API connection's firms. The limit defaults to 100 and is capped at 100. Pass include=integration_health to add a batched health summary for each company's logical integrations. OAuth and upstream-user authentication preserve the existing unpaginated response and ignore limit, cursor, and include. Required for modern client credentials: read:company tags: - Company parameters: - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 description: >- Page size for modern client credentials (default 100, maximum 100); ignored for OAuth and upstream users. - name: cursor in: query required: false schema: type: string minLength: 1 description: >- Pagination cursor for modern client credentials; ignored for OAuth and upstream users. - name: include in: query required: false schema: type: string enum: - integration_health description: >- Adds integrationHealth to each company. Requires puzzle-client-id, Authorization: Bearer , read:company, an active firm authorization and a nonremoved firm-client link. Ignored for OAuth and upstream users. responses: '200': description: OK content: application/json: schema: type: object properties: companies: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier name: type: string connectedAt: type: string minLength: 1 description: ISO 8601 timestamp status: type: string enum: - Ready - Syncing - NoData financialYearStartDate: type: string reportingCurrency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code integrationHealth: type: object properties: overallStatus: type: string enum: - HEALTHY - DEGRADED - ACTION_REQUIRED - NO_INTEGRATIONS counts: type: object properties: healthy: type: integer degraded: type: integer disconnected: type: integer required: - healthy - degraded - disconnected integrations: type: array items: type: object properties: category: type: string enum: - BANKING - CREDIT_CARD - PAYMENT_PROCESSOR - PAYROLL - ACCOUNTING - OTHER description: >- Provider-based categories: BANKING = Plaid, Finicity, Mercury, Meow, Rho, SVB OFX; CREDIT_CARD = Brex, Ramp; PAYMENT_PROCESSOR = Stripe; PAYROLL = Central, Deel, Every, Finch, Gusto, HelloFranklin, Human, Rippling, TriNet; ACCOUNTING = QuickBooks; OTHER = Arlo, BillDotCom, Captable, Carta, DirectIngest, Expensify, SWorks, Salesforce, Slack, Synder, Zaprite. Categories describe the provider, not individual account types (including Plaid accounts). provider: type: string enum: - ARLO - BILL_DOT_COM - BREX - CAPTABLE - CARTA - CENTRAL - DEEL - DIRECT_INGEST - EVERY - EXPENSIFY - FINCH - FINICITY - GUSTO - HELLO_FRANKLIN - HUMAN - MEOW - MERCURY - PLAID - QUICK_BOOKS - RAMP - RHO - RIPPLING - S_WORKS - SALESFORCE - SLACK - STRIPE - SVB_OFX - SYNDER - TRI_NET - ZAPRITE displayName: type: string status: type: string enum: - OK - TEMPORARY_OUTAGE - DISCONNECTED - UNKNOWN description: >- DISCONNECTED requires action: a disconnected connection, an authentication error (LOGIN_REQUIRED, ACCESS_REVOKED, INSUFFICIENT_PERMISSIONS, MFA_NOT_SUPPORTED, INVALID_MFA, ITEM_LOCKED), pending add-on payment, or active import start-date setup. Other connection errors and failed or warning syncs are TEMPORARY_OUTAGE. Without these conditions, no sync history is UNKNOWN; successful or in-progress syncs are OK. There is no freshness cutoff for successful syncs, so OK does not guarantee current data. actionRequired: type: boolean lastSyncAttemptAt: type: string minLength: 1 description: >- Start of the latest recorded sync attempt, not the last successful data ingestion. nullable: true lastSyncStatus: type: string enum: - SUCCEEDED - FAILED - HAS_WARNINGS - IN_PROGRESS nullable: true description: >- Status of the latest recorded sync; in-progress attempts older than three hours report FAILED. errorCode: type: string enum: - LOGIN_REQUIRED - ACCESS_REVOKED - INSUFFICIENT_PERMISSIONS - EXTERNAL_ERROR - INTERNAL_ERROR - TOO_MUCH_DATA - NO_ACCOUNTS - MFA_NOT_SUPPORTED - INVALID_MFA - ITEM_LOCKED - ITEM_NOT_SUPPORTED - INSTITUTION_ERROR - INVALID_INPUT - ADD_ON_PAYMENT_NOT_COMPLETED - USER_EPOCH_REQUIRED - NATIVE_SOURCE_AVAILABLE - AUTO_DISCONNECTED_AFTER_MIGRATION nullable: true description: >- Safe connection or setup reason when available; raw provider messages are not exposed. USER_EPOCH_REQUIRED means the user must choose the import start date during the active setup window. required: - category - provider - displayName - status - actionRequired - lastSyncAttemptAt - lastSyncStatus - errorCode required: - overallStatus - counts - integrations description: >- Health of recorded, nonremoved connections, including disconnected feeds. Replacement rows for the same Plaid item or named provider feed collapse to the newest row; separate Plaid items and unnamed connections remain distinct. Provider mapping coverage does not guarantee sync telemetry: push or manual integrations can have no sync runs and report UNKNOWN with null sync fields. An empty integration list reports NO_INTEGRATIONS. required: - id - name - connectedAt - status - financialYearStartDate - reportingCurrency nextCursor: type: string nullable: true description: >- Pass as cursor on the next request, retaining include=integration_health; null ends pagination. required: - companies - nextCursor /company/{id}: get: operationId: company summary: Get Company tags: - Company parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier name: type: string institutionConnections: type: array items: type: object properties: institution: type: object properties: name: type: string required: - name status: type: string enum: - OK - TemporaryOutage - Disconnected accounts: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier nativeId: type: string nullable: true type: type: string enum: - Investment - Invoice - Credit - Depository - Loan - Other - PaymentProcessing - Payroll - Fintech - Sweep name: type: string mask: type: string nullable: true currentBalance: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency status: type: string enum: - Syncing - Ready ingestStatus: type: string enum: - Syncing - Ready connectionStatus: type: string enum: - OK - TemporaryOutage - Disconnected lastUpdatedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true required: - id - nativeId - type - name - mask - currentBalance - status - ingestStatus - connectionStatus - lastUpdatedAt lastSyncedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true createdAt: type: string minLength: 1 description: ISO 8601 timestamp updatedAt: type: string minLength: 1 description: ISO 8601 timestamp fdicCoverage: type: object properties: status: type: string enum: - AtRisk - Review - Covered depositoryTotal: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency estimatedInsuranceCoverage: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency required: - status - depositoryTotal - estimatedInsuranceCoverage nullable: true required: - institution - status - accounts - lastSyncedAt - createdAt - updatedAt - fdicCoverage status: type: string enum: - Ready - Syncing - NoData financialSummary: type: object properties: status: type: string enum: - InProgress - Failed - Ready metrics: type: object properties: annualAvgFullyLoadedSalaryCostPerEmployee: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency annualAvgSalaryCostPerEmployee: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency lastMonthAvgFullyLoadedSalaryCostPerEmployee: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency lastMonthAvgSalaryCostPerEmployee: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency totalCash: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency runway: type: integer nullable: true fundraiseDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD nullable: true cashOutDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD nullable: true lastMonthOperatingBurn: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency lastMonthTotalBurn: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency lastMonthBankBurn: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency required: - annualAvgFullyLoadedSalaryCostPerEmployee - annualAvgSalaryCostPerEmployee - lastMonthAvgFullyLoadedSalaryCostPerEmployee - lastMonthAvgSalaryCostPerEmployee - totalCash - runway - fundraiseDate - cashOutDate - lastMonthOperatingBurn - lastMonthTotalBurn - lastMonthBankBurn nullable: true updatedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true errors: type: array items: type: object properties: message: type: string required: - message required: - status - metrics - updatedAt - errors nullable: true metadata: type: object properties: dataCompletenessLevel: type: string enum: - Complete - High - Medium - Low categorization: type: object properties: percentDollarVolumeCategorized: type: number required: - percentDollarVolumeCategorized required: - dataCompletenessLevel - categorization nullable: true required: - id - name - institutionConnections - status - financialSummary - metadata /company/{id}/accounts: post: operationId: createFinancialAccount summary: Create Financial Account description: >- 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 tags: - Accounts parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: nativeId: type: string minLength: 1 name: type: string minLength: 1 mask: type: string type: type: string enum: - Investment - Invoice - Credit - Depository - Loan - Other - Payroll - Fintech - Sweep currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code subType: type: string enum: - Annuity - Brokerage - BrokerageForMinors - CD - Checking - CreditCard - EducationSavingsAccount - HSA - Investment - LineOfCredit - Loan - MoneyMarket - Mortgage - Other - PayPal - Prepaid - ProfitSharingPlan - Retirement - Savings - StockPlan - Stripe - TaxAdvantagedInvestment - Trust - Unknown - CashLike required: - nativeId - name - mask - type - currency responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier nativeId: type: string nullable: true name: type: string mask: type: string type: type: string enum: - Investment - Invoice - Credit - Depository - Loan - Other - PaymentProcessing - Payroll - Fintech - Sweep subType: type: string enum: - Annuity - Brokerage - BrokerageForMinors - CD - Checking - CreditCard - EducationSavingsAccount - HSA - Investment - LineOfCredit - Loan - MoneyMarket - Mortgage - Other - PayPal - Prepaid - ProfitSharingPlan - Retirement - Savings - StockPlan - Stripe - TaxAdvantagedInvestment - Trust - Unknown - CashLike nullable: true currentBalance: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency nullable: true status: type: string enum: - Syncing - Ready lastUpdatedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true required: - id - nativeId - name - mask - type - subType - currentBalance - status - lastUpdatedAt get: operationId: financialAccounts summary: Get Financial Accounts description: |- Retrieves a list of all of the company's financial accounts. Required scope: read:company tags: - Accounts parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier responses: '200': description: OK content: application/json: schema: type: object properties: accounts: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier nativeId: type: string nullable: true name: type: string mask: type: string type: type: string enum: - Investment - Invoice - Credit - Depository - Loan - Other - PaymentProcessing - Payroll - Fintech - Sweep subType: type: string enum: - Annuity - Brokerage - BrokerageForMinors - CD - Checking - CreditCard - EducationSavingsAccount - HSA - Investment - LineOfCredit - Loan - MoneyMarket - Mortgage - Other - PayPal - Prepaid - ProfitSharingPlan - Retirement - Savings - StockPlan - Stripe - TaxAdvantagedInvestment - Trust - Unknown - CashLike nullable: true currentBalance: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency nullable: true status: type: string enum: - Syncing - Ready lastUpdatedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true required: - id - nativeId - name - mask - type - subType - currentBalance - status - lastUpdatedAt required: - accounts /company/{id}/accounts/balances: post: operationId: createAccountBalance summary: Create Account Balance description: >- 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 tags: - Accounts parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: accountId: type: string minLength: 1 description: Partner-facing external identifier balance: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency availableBalance: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency timestamp: type: string minLength: 1 description: ISO 8601 timestamp required: - accountId - balance - timestamp responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier accountId: type: string minLength: 1 description: Partner-facing external identifier balance: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency availableBalance: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency timestamp: type: string minLength: 1 description: ISO 8601 timestamp required: - id - accountId - balance - availableBalance - timestamp get: operationId: balances summary: Get Financial Account Balances description: >- 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 tags: - Accounts parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: dates in: query required: true schema: anyOf: - type: string - type: array items: type: string responses: '200': description: OK content: application/json: schema: type: object properties: balancesByDate: type: array items: type: object properties: date: type: string balances: type: array items: type: object properties: balance: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency date: type: string derivedFrom: type: string enum: - OfficialInstitutionBalance - Calculated account: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier nativeId: type: string nullable: true type: type: string enum: - Investment - Invoice - Credit - Depository - Loan - Other - PaymentProcessing - Payroll - Fintech - Sweep name: type: string mask: type: string nullable: true currentBalance: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency status: type: string enum: - Syncing - Ready ingestStatus: type: string enum: - Syncing - Ready connectionStatus: type: string enum: - OK - TemporaryOutage - Disconnected lastUpdatedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true pathToDetails: type: string required: - id - nativeId - type - name - mask - currentBalance - status - ingestStatus - connectionStatus - lastUpdatedAt - pathToDetails nullable: true required: - balance - date - derivedFrom - account totalCash: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency required: - date - balances - totalCash required: - balancesByDate /company/{id}/ledgerAccounts/{ledgerAccountId}: get: operationId: ledgerAccount summary: Get Ledger Account description: |- 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 tags: - Accounts parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: ledgerAccountId in: path required: true description: The ledger account ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: basis in: query required: false schema: type: string enum: - cash - accrual responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier name: type: string coaKeys: type: array items: type: string minLength: 1 description: Chart-of-accounts key restrictedCoaKeys: type: array items: type: string minLength: 1 description: Chart-of-accounts key nominalCode: type: string description: type: string nullable: true keywords: type: array items: type: string type: type: string tags: type: array items: type: string category: type: string subCategory: type: string nullable: true tertiaryCategory: type: string nullable: true parentCode: type: string nullable: true currentBalance: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency currentBalanceWithoutSubAccounts: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency isBankAccount: type: boolean accountId: type: string minLength: 1 description: Partner-facing external identifier nullable: true views: type: array items: type: string currentness: type: string nullable: true required: - id - name - coaKeys - restrictedCoaKeys - nominalCode - keywords - type - tags - category - currentBalance - currentBalanceWithoutSubAccounts - isBankAccount - views /company/{id}/bills: get: operationId: billsApi summary: Get Bills description: |- Retrieves bills. Required scope: read:company tags: - Bills parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: isLinked in: query required: false schema: type: string description: Boolean flag; "true" enables, any other value disables - name: isPaid in: query required: false schema: type: string description: Boolean flag; "true" enables, any other value disables - name: isSubmitted in: query required: false schema: type: string description: Boolean flag; "true" enables, any other value disables - name: isVoided in: query required: false schema: type: string description: Boolean flag; "true" enables, any other value disables - name: minAmount in: query required: false schema: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string - name: maxAmount in: query required: false schema: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string - name: from in: query required: false schema: type: string minLength: 1 description: Calendar date, YYYY-MM-DD - name: to in: query required: false schema: type: string minLength: 1 description: Calendar date, YYYY-MM-DD - name: dueDateFrom in: query required: false schema: type: string minLength: 1 description: Calendar date, YYYY-MM-DD - name: dueDateTo in: query required: false schema: type: string minLength: 1 description: Calendar date, YYYY-MM-DD - name: statuses in: query required: false schema: anyOf: - type: string enum: - Draft - Voided - Paid - Unpaid - Current - Overdue - type: array items: type: string enum: - Draft - Voided - Paid - Unpaid - Current - Overdue - name: vendorIds in: query required: false schema: anyOf: - type: string minLength: 1 description: Partner-facing external identifier - type: array items: type: string minLength: 1 description: Partner-facing external identifier - name: sortBy in: query required: false schema: type: string enum: - AMOUNT_DESC - AMOUNT_ASC - DESCRIPTOR_DESC - DESCRIPTOR_ASC - DUE_DATE_DESC - DUE_DATE_ASC - ISSUE_DATE_DESC - ISSUE_DATE_ASC - VENDOR_DESC - VENDOR_ASC - name: count in: query required: false schema: type: integer - name: after in: query required: false schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier userId: type: string minLength: 1 description: Partner-facing external identifier vendorId: type: string minLength: 1 description: Partner-facing external identifier issueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD dueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD nullable: true externalId: type: string nullable: true description: type: string nullable: true submittedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true voidedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true paidAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true status: type: string enum: - Deleted - Draft - Posted - Voided - Paid currentness: type: string enum: - Current - Overdue nullable: true amount: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency nullable: true provider: type: string nullable: true documents: type: array items: type: object properties: file: type: object properties: id: type: string filename: type: string nullable: true contentType: type: string size: type: integer isDeleted: type: boolean downloadInfo: type: object properties: signedUrl: type: string urlExpiresAt: type: string minLength: 1 description: ISO 8601 timestamp required: - signedUrl - urlExpiresAt parseError: type: string nullable: true parseType: type: string enum: - bill - invoice - receipt - bankStatement - unknown nullable: true required: - id - filename - contentType - size - isDeleted - downloadInfo - parseError - parseType uploadActorType: type: string enum: - SYSTEM_ACTOR - TRAIN_ACTOR - USER_ACTOR - USER_ACTOR_VIA_AI - ADMIN_ACTOR - AI_ACTOR required: - file - uploadActorType lines: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier classifications: type: array items: type: object properties: class: type: string description: type: string nullable: true segments: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier nullable: true segment: type: string description: type: string nullable: true required: - id - segment - description required: - class - description - segments amount: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency coaKey: type: string minLength: 1 description: Chart-of-accounts key nullable: true quantity: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string nullable: true unitPrice: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string nullable: true description: type: string nullable: true required: - id - classifications - amount - coaKey - quantity - unitPrice - description required: - id - userId - issueDate - dueDate - externalId - description - submittedAt - voidedAt - paidAt - status - currentness - amount - provider - documents - lines pageInfo: type: object properties: endCursor: type: string nullable: true hasNextPage: type: boolean total: type: integer nullable: true required: - endCursor - hasNextPage - total total: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency required: - items - pageInfo - total post: operationId: createBillApi summary: Create Bill description: |- Creates a bill for the company. Required scope: write:bill tags: - Bills parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: nativeId: type: string vendorId: type: string minLength: 1 description: Partner-facing external identifier description: type: string issueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD dueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD shouldPost: type: boolean lines: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code coaKey: type: string minLength: 1 description: Chart-of-accounts key quantity: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string unitPrice: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string description: type: string classifications: type: array items: type: object properties: class: type: string minLength: 1 segment: type: string minLength: 1 required: - class - segment prepaid: type: object properties: expenseRecognitionMethod: type: string enum: - automatic - manual startDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD endDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD required: - expenseRecognitionMethod fixedAsset: type: object properties: type: type: string enum: - ComputersAndHardware - Furniture - Other - Software inServiceAt: type: string minLength: 1 description: Calendar date, YYYY-MM-DD capitalizedAt: type: string minLength: 1 description: Calendar date, YYYY-MM-DD depreciationMethod: type: string enum: - StraightLine description: type: string salvageValue: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string usefulLifeMonths: type: integer required: - type - inServiceAt required: - amount - currency - coaKey document: type: object properties: documentType: type: string enum: - Receipt - Bill - Invoice fileName: type: string minLength: 1 contentType: type: string minLength: 1 base64File: type: string minLength: 1 nativeDocumentId: type: string minLength: 1 required: - documentType - fileName - contentType - base64File - nativeDocumentId required: - issueDate - lines responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier userId: type: string minLength: 1 description: Partner-facing external identifier vendorId: type: string minLength: 1 description: Partner-facing external identifier issueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD dueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD nullable: true externalId: type: string nullable: true description: type: string nullable: true submittedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true voidedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true paidAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true status: type: string enum: - Deleted - Draft - Posted - Voided - Paid currentness: type: string enum: - Current - Overdue nullable: true amount: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency nullable: true provider: type: string nullable: true documents: type: array items: type: object properties: file: type: object properties: id: type: string filename: type: string nullable: true contentType: type: string size: type: integer isDeleted: type: boolean downloadInfo: type: object properties: signedUrl: type: string urlExpiresAt: type: string minLength: 1 description: ISO 8601 timestamp required: - signedUrl - urlExpiresAt parseError: type: string nullable: true parseType: type: string enum: - bill - invoice - receipt - bankStatement - unknown nullable: true required: - id - filename - contentType - size - isDeleted - downloadInfo - parseError - parseType uploadActorType: type: string enum: - SYSTEM_ACTOR - TRAIN_ACTOR - USER_ACTOR - USER_ACTOR_VIA_AI - ADMIN_ACTOR - AI_ACTOR required: - file - uploadActorType lines: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier classifications: type: array items: type: object properties: class: type: string description: type: string nullable: true segments: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier nullable: true segment: type: string description: type: string nullable: true required: - id - segment - description required: - class - description - segments amount: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency coaKey: type: string minLength: 1 description: Chart-of-accounts key nullable: true quantity: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string nullable: true unitPrice: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string nullable: true description: type: string nullable: true required: - id - classifications - amount - coaKey - quantity - unitPrice - description createdAt: type: string minLength: 1 description: ISO 8601 timestamp updatedAt: type: string minLength: 1 description: ISO 8601 timestamp removedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true required: - id - userId - issueDate - dueDate - externalId - description - submittedAt - voidedAt - paidAt - status - currentness - amount - provider - documents - lines - createdAt - updatedAt - removedAt /company/{id}/bills/{billId}: get: operationId: billApi summary: Get Bill description: |- Retrieves a bill. Required scope: read:company tags: - Bills parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: billId in: path required: true description: The bill ID schema: type: string minLength: 1 description: Partner-facing external identifier responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier userId: type: string minLength: 1 description: Partner-facing external identifier vendorId: type: string minLength: 1 description: Partner-facing external identifier issueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD dueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD nullable: true externalId: type: string nullable: true description: type: string nullable: true submittedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true voidedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true paidAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true status: type: string enum: - Deleted - Draft - Posted - Voided - Paid currentness: type: string enum: - Current - Overdue nullable: true amount: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency nullable: true provider: type: string nullable: true documents: type: array items: type: object properties: file: type: object properties: id: type: string filename: type: string nullable: true contentType: type: string size: type: integer isDeleted: type: boolean downloadInfo: type: object properties: signedUrl: type: string urlExpiresAt: type: string minLength: 1 description: ISO 8601 timestamp required: - signedUrl - urlExpiresAt parseError: type: string nullable: true parseType: type: string enum: - bill - invoice - receipt - bankStatement - unknown nullable: true required: - id - filename - contentType - size - isDeleted - downloadInfo - parseError - parseType uploadActorType: type: string enum: - SYSTEM_ACTOR - TRAIN_ACTOR - USER_ACTOR - USER_ACTOR_VIA_AI - ADMIN_ACTOR - AI_ACTOR required: - file - uploadActorType lines: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier classifications: type: array items: type: object properties: class: type: string description: type: string nullable: true segments: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier nullable: true segment: type: string description: type: string nullable: true required: - id - segment - description required: - class - description - segments amount: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency coaKey: type: string minLength: 1 description: Chart-of-accounts key nullable: true quantity: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string nullable: true unitPrice: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string nullable: true description: type: string nullable: true required: - id - classifications - amount - coaKey - quantity - unitPrice - description required: - id - userId - issueDate - dueDate - externalId - description - submittedAt - voidedAt - paidAt - status - currentness - amount - provider - documents - lines post: operationId: updateBillApi summary: Update Bill description: |- Updates an existing bill with new values. Required scope: write:bill tags: - Bills parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: billId in: path required: true description: The bill ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: nativeId: type: string vendorId: type: string minLength: 1 description: Partner-facing external identifier description: type: string issueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD dueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD shouldPost: type: boolean lines: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code coaKey: type: string minLength: 1 description: Chart-of-accounts key quantity: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string unitPrice: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string description: type: string classifications: type: array items: type: object properties: class: type: string minLength: 1 segment: type: string minLength: 1 required: - class - segment prepaid: type: object properties: expenseRecognitionMethod: type: string enum: - automatic - manual startDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD endDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD required: - expenseRecognitionMethod fixedAsset: type: object properties: type: type: string enum: - ComputersAndHardware - Furniture - Other - Software inServiceAt: type: string minLength: 1 description: Calendar date, YYYY-MM-DD capitalizedAt: type: string minLength: 1 description: Calendar date, YYYY-MM-DD depreciationMethod: type: string enum: - StraightLine description: type: string salvageValue: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string usefulLifeMonths: type: integer required: - type - inServiceAt required: - amount - currency - coaKey document: type: object properties: documentType: type: string enum: - Receipt - Bill - Invoice fileName: type: string minLength: 1 contentType: type: string minLength: 1 base64File: type: string minLength: 1 nativeDocumentId: type: string minLength: 1 required: - documentType - fileName - contentType - base64File - nativeDocumentId required: - issueDate - lines responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier userId: type: string minLength: 1 description: Partner-facing external identifier vendorId: type: string minLength: 1 description: Partner-facing external identifier issueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD dueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD nullable: true externalId: type: string nullable: true description: type: string nullable: true submittedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true voidedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true paidAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true status: type: string enum: - Deleted - Draft - Posted - Voided - Paid currentness: type: string enum: - Current - Overdue nullable: true amount: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency nullable: true provider: type: string nullable: true documents: type: array items: type: object properties: file: type: object properties: id: type: string filename: type: string nullable: true contentType: type: string size: type: integer isDeleted: type: boolean downloadInfo: type: object properties: signedUrl: type: string urlExpiresAt: type: string minLength: 1 description: ISO 8601 timestamp required: - signedUrl - urlExpiresAt parseError: type: string nullable: true parseType: type: string enum: - bill - invoice - receipt - bankStatement - unknown nullable: true required: - id - filename - contentType - size - isDeleted - downloadInfo - parseError - parseType uploadActorType: type: string enum: - SYSTEM_ACTOR - TRAIN_ACTOR - USER_ACTOR - USER_ACTOR_VIA_AI - ADMIN_ACTOR - AI_ACTOR required: - file - uploadActorType lines: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier classifications: type: array items: type: object properties: class: type: string description: type: string nullable: true segments: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier nullable: true segment: type: string description: type: string nullable: true required: - id - segment - description required: - class - description - segments amount: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency coaKey: type: string minLength: 1 description: Chart-of-accounts key nullable: true quantity: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string nullable: true unitPrice: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string nullable: true description: type: string nullable: true required: - id - classifications - amount - coaKey - quantity - unitPrice - description required: - id - userId - issueDate - dueDate - externalId - description - submittedAt - voidedAt - paidAt - status - currentness - amount - provider - documents - lines /company/{id}/bills/{billId}/status: patch: operationId: updateBillStatusApi summary: Update Bill Status description: |- Updates an existing Bill's sStatus. Required scope: write:bill tags: - Bills parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: billId in: path required: true description: The bill ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: status: type: string enum: - Deleted - Draft - Posted - Voided - Paid required: - status responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier userId: type: string minLength: 1 description: Partner-facing external identifier vendorId: type: string minLength: 1 description: Partner-facing external identifier issueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD dueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD nullable: true externalId: type: string nullable: true description: type: string nullable: true submittedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true voidedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true paidAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true status: type: string enum: - Deleted - Draft - Posted - Voided - Paid currentness: type: string enum: - Current - Overdue nullable: true amount: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency nullable: true provider: type: string nullable: true documents: type: array items: type: object properties: file: type: object properties: id: type: string filename: type: string nullable: true contentType: type: string size: type: integer isDeleted: type: boolean downloadInfo: type: object properties: signedUrl: type: string urlExpiresAt: type: string minLength: 1 description: ISO 8601 timestamp required: - signedUrl - urlExpiresAt parseError: type: string nullable: true parseType: type: string enum: - bill - invoice - receipt - bankStatement - unknown nullable: true required: - id - filename - contentType - size - isDeleted - downloadInfo - parseError - parseType uploadActorType: type: string enum: - SYSTEM_ACTOR - TRAIN_ACTOR - USER_ACTOR - USER_ACTOR_VIA_AI - ADMIN_ACTOR - AI_ACTOR required: - file - uploadActorType lines: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier classifications: type: array items: type: object properties: class: type: string description: type: string nullable: true segments: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier nullable: true segment: type: string description: type: string nullable: true required: - id - segment - description required: - class - description - segments amount: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency coaKey: type: string minLength: 1 description: Chart-of-accounts key nullable: true quantity: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string nullable: true unitPrice: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string nullable: true description: type: string nullable: true required: - id - classifications - amount - coaKey - quantity - unitPrice - description createdAt: type: string minLength: 1 description: ISO 8601 timestamp updatedAt: type: string minLength: 1 description: ISO 8601 timestamp removedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true required: - id - userId - issueDate - dueDate - externalId - description - submittedAt - voidedAt - paidAt - status - currentness - amount - provider - documents - lines - createdAt - updatedAt - removedAt /company/{id}/integrationConnection: post: operationId: createIntegrationConnection summary: Create Integration Connection description: >- Creates an integration connection for the company that you can use to push data into Puzzle. Required scope: write:integration_connection tags: - Company parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier responses: '200': description: OK content: application/json: schema: type: object properties: message: type: string required: - message /company/{id}/invoices: get: operationId: invoicesApi summary: Get Invoices description: >- Retrieves invoices. Pagination accepts `count` and `after`; filter by issue date with both `from` and `to`, and by status with `statuses`. `maxResults`, `startDate`, and `endDate` are not supported. Required scope: read:company tags: - Invoices parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: from in: query required: false schema: type: string minLength: 1 description: Calendar date, YYYY-MM-DD - name: to in: query required: false schema: type: string minLength: 1 description: Calendar date, YYYY-MM-DD - name: customerIds in: query required: false schema: anyOf: - type: string minLength: 1 description: Partner-facing external identifier - type: array items: type: string minLength: 1 description: Partner-facing external identifier - name: statuses in: query required: false schema: anyOf: - type: string enum: - Deleted - Draft - Posted - Voided - Paid - type: array items: type: string enum: - Deleted - Draft - Posted - Voided - Paid - name: coaKeys in: query required: false schema: anyOf: - type: string minLength: 1 description: Chart-of-accounts key - type: array items: type: string minLength: 1 description: Chart-of-accounts key - name: isPaid in: query required: false schema: type: string description: Boolean flag; "true" enables, any other value disables - name: minAmount in: query required: false schema: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string - name: maxAmount in: query required: false schema: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string - name: sortBy in: query required: false schema: type: string enum: - AMOUNT_DESC - AMOUNT_ASC - CUSTOMER_DESC - CUSTOMER_ASC - DESCRIPTOR_DESC - DESCRIPTOR_ASC - DUE_DATE_DESC - DUE_DATE_ASC - ISSUE_DATE_DESC - ISSUE_DATE_ASC - name: count in: query required: false schema: type: integer - name: after in: query required: false schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier customerId: type: string minLength: 1 description: Partner-facing external identifier nullable: true issueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD nullable: true dueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD nullable: true nativeId: type: string nullable: true description: type: string nullable: true amount: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency documents: type: array items: type: object properties: file: type: object properties: id: type: string filename: type: string nullable: true contentType: type: string size: type: integer isDeleted: type: boolean downloadInfo: type: object properties: signedUrl: type: string urlExpiresAt: type: string minLength: 1 description: ISO 8601 timestamp required: - signedUrl - urlExpiresAt parseError: type: string nullable: true parseType: type: string enum: - bill - invoice - receipt - bankStatement - unknown nullable: true required: - id - filename - contentType - size - isDeleted - downloadInfo - parseError - parseType uploadActorType: type: string enum: - SYSTEM_ACTOR - TRAIN_ACTOR - USER_ACTOR - USER_ACTOR_VIA_AI - ADMIN_ACTOR - AI_ACTOR required: - file - uploadActorType lines: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier classifications: type: array items: type: object properties: class: type: string description: type: string nullable: true segments: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier nullable: true segment: type: string description: type: string nullable: true required: - id - segment - description required: - class - description - segments amount: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency coaKey: type: string minLength: 1 description: Chart-of-accounts key quantity: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string nullable: true unitPrice: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string nullable: true productId: type: string minLength: 1 description: Partner-facing external identifier nullable: true description: type: string nullable: true required: - id - classifications - amount - coaKey - quantity - unitPrice - description status: type: string enum: - Deleted - Draft - Posted - Voided - Paid contractId: type: string minLength: 1 description: Partner-facing external identifier nullable: true required: - id - issueDate - dueDate - nativeId - description - amount - documents - lines - status pageInfo: type: object properties: endCursor: type: string nullable: true hasNextPage: type: boolean total: type: integer nullable: true required: - endCursor - hasNextPage - total total: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency required: - items - pageInfo - total post: operationId: createInvoiceApi summary: Create Invoice description: |- Creates an invoice for the company. Required scope: write:invoice tags: - Invoices parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: accountId: type: string minLength: 1 description: Partner-facing external identifier nativeId: type: string customerId: type: string minLength: 1 description: Partner-facing external identifier description: type: string status: type: string enum: - Deleted - Draft - Posted - Voided - Paid issueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD dueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD lines: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string coaKey: type: string minLength: 1 description: Chart-of-accounts key quantity: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string unitPrice: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string description: type: string classifications: type: array items: type: object properties: class: type: string minLength: 1 segment: type: string minLength: 1 required: - class - segment productId: type: string minLength: 1 description: Partner-facing external identifier productName: type: string schedule: type: object properties: dateRange: type: object properties: fromInclusive: type: string minLength: 1 description: Calendar date, YYYY-MM-DD toInclusive: type: string minLength: 1 description: Calendar date, YYYY-MM-DD required: - fromInclusive - toInclusive postingMethod: type: string enum: - automatically - userConfirm required: - dateRange revRecOptions: anyOf: - type: object properties: accountingConfigurationId: type: string minLength: 1 description: Partner-facing external identifier required: - accountingConfigurationId additionalProperties: false - type: object properties: accountingOptions: type: object properties: timing: type: string enum: - OverTime - PointInTime calculation: type: string enum: - Days360 - DaysActual - Manual - PercentageBased - StraightLineByPeriod - StraightLineDaily - StraightLineMonthly category: type: string minLength: 1 description: Chart-of-accounts key firstPeriodAllocation: type: string enum: - DayBased - FullMonth - HalfMonth - Mid - Zero required: - timing required: - accountingOptions additionalProperties: false required: - amount - coaKey document: type: object properties: documentType: type: string enum: - Receipt - Bill - Invoice fileName: type: string minLength: 1 contentType: type: string minLength: 1 base64File: type: string minLength: 1 nativeDocumentId: type: string minLength: 1 required: - documentType - fileName - contentType - base64File - nativeDocumentId required: - customerId - issueDate - lines responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier customerId: type: string minLength: 1 description: Partner-facing external identifier nullable: true issueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD nullable: true dueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD nullable: true nativeId: type: string nullable: true description: type: string nullable: true amount: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency documents: type: array items: type: object properties: file: type: object properties: id: type: string filename: type: string nullable: true contentType: type: string size: type: integer isDeleted: type: boolean downloadInfo: type: object properties: signedUrl: type: string urlExpiresAt: type: string minLength: 1 description: ISO 8601 timestamp required: - signedUrl - urlExpiresAt parseError: type: string nullable: true parseType: type: string enum: - bill - invoice - receipt - bankStatement - unknown nullable: true required: - id - filename - contentType - size - isDeleted - downloadInfo - parseError - parseType uploadActorType: type: string enum: - SYSTEM_ACTOR - TRAIN_ACTOR - USER_ACTOR - USER_ACTOR_VIA_AI - ADMIN_ACTOR - AI_ACTOR required: - file - uploadActorType lines: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier classifications: type: array items: type: object properties: class: type: string description: type: string nullable: true segments: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier nullable: true segment: type: string description: type: string nullable: true required: - id - segment - description required: - class - description - segments amount: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency coaKey: type: string minLength: 1 description: Chart-of-accounts key quantity: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string nullable: true unitPrice: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string nullable: true productId: type: string minLength: 1 description: Partner-facing external identifier nullable: true description: type: string nullable: true createdAt: type: string minLength: 1 description: ISO 8601 timestamp updatedAt: type: string minLength: 1 description: ISO 8601 timestamp removedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true required: - id - classifications - amount - coaKey - quantity - unitPrice - description - createdAt - updatedAt - removedAt status: type: string enum: - Deleted - Draft - Posted - Voided - Paid contractId: type: string minLength: 1 description: Partner-facing external identifier nullable: true createdAt: type: string minLength: 1 description: ISO 8601 timestamp updatedAt: type: string minLength: 1 description: ISO 8601 timestamp removedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true required: - id - issueDate - dueDate - nativeId - description - amount - documents - lines - status - createdAt - updatedAt - removedAt /company/{id}/invoices/{invoiceId}: get: operationId: invoiceApi summary: Get Invoice description: |- Retrieves an invoice. Required scope: read:company tags: - Invoices parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: invoiceId in: path required: true description: The invoice ID schema: type: string minLength: 1 description: Partner-facing external identifier responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier customerId: type: string minLength: 1 description: Partner-facing external identifier nullable: true issueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD nullable: true dueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD nullable: true nativeId: type: string nullable: true description: type: string nullable: true amount: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency documents: type: array items: type: object properties: file: type: object properties: id: type: string filename: type: string nullable: true contentType: type: string size: type: integer isDeleted: type: boolean downloadInfo: type: object properties: signedUrl: type: string urlExpiresAt: type: string minLength: 1 description: ISO 8601 timestamp required: - signedUrl - urlExpiresAt parseError: type: string nullable: true parseType: type: string enum: - bill - invoice - receipt - bankStatement - unknown nullable: true required: - id - filename - contentType - size - isDeleted - downloadInfo - parseError - parseType uploadActorType: type: string enum: - SYSTEM_ACTOR - TRAIN_ACTOR - USER_ACTOR - USER_ACTOR_VIA_AI - ADMIN_ACTOR - AI_ACTOR required: - file - uploadActorType lines: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier classifications: type: array items: type: object properties: class: type: string description: type: string nullable: true segments: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier nullable: true segment: type: string description: type: string nullable: true required: - id - segment - description required: - class - description - segments amount: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency coaKey: type: string minLength: 1 description: Chart-of-accounts key quantity: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string nullable: true unitPrice: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string nullable: true productId: type: string minLength: 1 description: Partner-facing external identifier nullable: true description: type: string nullable: true required: - id - classifications - amount - coaKey - quantity - unitPrice - description status: type: string enum: - Deleted - Draft - Posted - Voided - Paid contractId: type: string minLength: 1 description: Partner-facing external identifier nullable: true required: - id - issueDate - dueDate - nativeId - description - amount - documents - lines - status put: operationId: updateInvoiceApi summary: Update Invoice description: |- Updates an invoice. Required scope: write:invoice tags: - Invoices parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: invoiceId in: path required: true description: The invoice ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: customerId: type: string minLength: 1 description: Partner-facing external identifier description: type: string status: type: string enum: - Deleted - Draft - Posted - Voided - Paid issueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD dueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD nativeId: type: string lines: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier coaKey: type: string minLength: 1 description: Chart-of-accounts key amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string description: type: string quantity: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string unitPrice: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string classifications: type: array items: type: object properties: class: type: string minLength: 1 segment: type: string minLength: 1 required: - class - segment productId: type: string minLength: 1 description: Partner-facing external identifier productName: type: string schedule: type: object properties: dateRange: type: object properties: fromInclusive: type: string minLength: 1 description: Calendar date, YYYY-MM-DD toInclusive: type: string minLength: 1 description: Calendar date, YYYY-MM-DD required: - fromInclusive - toInclusive postingMethod: type: string enum: - automatically - userConfirm required: - dateRange revRecOptions: anyOf: - type: object properties: accountingConfigurationId: type: string minLength: 1 description: Partner-facing external identifier required: - accountingConfigurationId additionalProperties: false - type: object properties: accountingOptions: type: object properties: timing: type: string enum: - OverTime - PointInTime calculation: type: string enum: - Days360 - DaysActual - Manual - PercentageBased - StraightLineByPeriod - StraightLineDaily - StraightLineMonthly category: type: string minLength: 1 description: Chart-of-accounts key firstPeriodAllocation: type: string enum: - DayBased - FullMonth - HalfMonth - Mid - Zero required: - timing required: - accountingOptions additionalProperties: false required: - coaKey - amount document: type: object properties: documentType: type: string enum: - Receipt - Bill - Invoice fileName: type: string minLength: 1 contentType: type: string minLength: 1 base64File: type: string minLength: 1 nativeDocumentId: type: string minLength: 1 required: - documentType - fileName - contentType - base64File - nativeDocumentId required: - status - issueDate responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier customerId: type: string minLength: 1 description: Partner-facing external identifier nullable: true issueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD nullable: true dueDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD nullable: true nativeId: type: string nullable: true description: type: string nullable: true amount: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency documents: type: array items: type: object properties: file: type: object properties: id: type: string filename: type: string nullable: true contentType: type: string size: type: integer isDeleted: type: boolean downloadInfo: type: object properties: signedUrl: type: string urlExpiresAt: type: string minLength: 1 description: ISO 8601 timestamp required: - signedUrl - urlExpiresAt parseError: type: string nullable: true parseType: type: string enum: - bill - invoice - receipt - bankStatement - unknown nullable: true required: - id - filename - contentType - size - isDeleted - downloadInfo - parseError - parseType uploadActorType: type: string enum: - SYSTEM_ACTOR - TRAIN_ACTOR - USER_ACTOR - USER_ACTOR_VIA_AI - ADMIN_ACTOR - AI_ACTOR required: - file - uploadActorType lines: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier classifications: type: array items: type: object properties: class: type: string description: type: string nullable: true segments: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier nullable: true segment: type: string description: type: string nullable: true required: - id - segment - description required: - class - description - segments amount: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency coaKey: type: string minLength: 1 description: Chart-of-accounts key quantity: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string nullable: true unitPrice: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string nullable: true productId: type: string minLength: 1 description: Partner-facing external identifier nullable: true description: type: string nullable: true createdAt: type: string minLength: 1 description: ISO 8601 timestamp updatedAt: type: string minLength: 1 description: ISO 8601 timestamp removedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true required: - id - classifications - amount - coaKey - quantity - unitPrice - description - createdAt - updatedAt - removedAt status: type: string enum: - Deleted - Draft - Posted - Voided - Paid contractId: type: string minLength: 1 description: Partner-facing external identifier nullable: true createdAt: type: string minLength: 1 description: ISO 8601 timestamp updatedAt: type: string minLength: 1 description: ISO 8601 timestamp removedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true required: - id - issueDate - dueDate - nativeId - description - amount - documents - lines - status - createdAt - updatedAt - removedAt /company/{id}/vendors: get: operationId: vendors summary: Get Vendors description: |- Retrieves a list of all of the company's vendors. Required scope: read:company tags: - Vendors parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: type in: query required: false schema: type: string enum: - Individual - Business - Unknown - name: status in: query required: false schema: type: string enum: - Active - Inactive - Unknown - name: permaNames in: query required: false schema: anyOf: - type: string - type: array items: type: string - name: is1099Vendor in: query required: false schema: type: string description: Boolean flag; "true" enables, any other value disables - name: count in: query required: false schema: type: integer - name: after in: query required: false schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier permaName: type: string name: type: string is1099Vendor: type: boolean nullable: true description: type: string nullable: true type: type: string enum: - Individual - Business - Unknown nullable: true status: type: string enum: - Active - Inactive - Unknown nullable: true required: - id - permaName - name - is1099Vendor - description - type - status pageInfo: type: object properties: endCursor: type: string nullable: true hasNextPage: type: boolean total: type: integer nullable: true required: - endCursor - hasNextPage - total required: - items - pageInfo post: operationId: createVendorApi summary: Create Vendor description: |- Creates a new Vendor for the company. Required scope: write:vendor tags: - Vendors parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 is1099Vendor: type: boolean description: type: string type: type: string enum: - Individual - Business - Unknown status: type: string enum: - Active - Inactive - Unknown required: - name responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier permaName: type: string name: type: string is1099Vendor: type: boolean nullable: true description: type: string nullable: true type: type: string enum: - Individual - Business - Unknown nullable: true status: type: string enum: - Active - Inactive - Unknown nullable: true required: - id - permaName - name - is1099Vendor - description - type - status /company/{id}/vendors/{vendorId}: patch: operationId: updateVendorApi summary: Update Vendor description: |- Updates an existing Vendor for the company. Required scope: write:vendor tags: - Vendors parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: vendorId in: path required: true description: The vendor ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: name: type: string is1099Vendor: type: boolean description: type: string type: type: string enum: - Individual - Business - Unknown status: type: string enum: - Active - Inactive - Unknown responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier permaName: type: string name: type: string is1099Vendor: type: boolean nullable: true description: type: string nullable: true type: type: string enum: - Individual - Business - Unknown nullable: true status: type: string enum: - Active - Inactive - Unknown nullable: true required: - id - permaName - name - is1099Vendor - description - type - status /company/{id}/customers: get: operationId: customersApi summary: Get Customers description: |- Retrieves a list of all of the company's customers. Required scope: write:customer tags: - Customers parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: name in: query required: false schema: type: string - name: type in: query required: false schema: type: string enum: - Individual - Business - Unknown - name: status in: query required: false schema: type: string enum: - Active - Inactive - Unknown - name: count in: query required: false schema: type: integer - name: after in: query required: false schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier name: type: string nullable: true email: type: string nullable: true phoneNumber: type: string nullable: true billingAddressJson: type: object properties: zip: type: string city: type: string addressLine1: type: string addressLine2: type: string state: anyOf: - type: string enum: - '' - type: object properties: label: type: string value: type: string required: - label - value country: anyOf: - type: string enum: - '' - type: object properties: label: type: string value: type: string required: - label - value required: - zip - city - addressLine1 - addressLine2 nullable: true companyName: type: string nullable: true contactName: type: string nullable: true description: type: string nullable: true website: type: string nullable: true status: type: string enum: - Active - Inactive - Unknown nullable: true type: type: string enum: - Individual - Business - Unknown nullable: true required: - id - name - email - phoneNumber - billingAddressJson - companyName - contactName - description - website - status - type pageInfo: type: object properties: endCursor: type: string nullable: true hasNextPage: type: boolean total: type: integer nullable: true required: - endCursor - hasNextPage - total required: - items - pageInfo post: operationId: createCustomerApi summary: Create Customer description: |- Creates a new Customer for the company. Required scope: write:customer tags: - Customers parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 email: type: string phoneNumber: type: string billingAddressJson: type: object properties: zip: type: string city: type: string addressLine1: type: string addressLine2: type: string state: anyOf: - type: string enum: - '' - type: object properties: label: type: string value: type: string required: - label - value country: anyOf: - type: string enum: - '' - type: object properties: label: type: string value: type: string required: - label - value required: - zip - city - addressLine1 - addressLine2 nullable: true companyName: type: string contactName: type: string description: type: string website: type: string status: type: string enum: - Active - Inactive - Unknown type: type: string enum: - Individual - Business - Unknown required: - name responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier name: type: string nullable: true email: type: string nullable: true phoneNumber: type: string nullable: true billingAddressJson: type: object properties: zip: type: string city: type: string addressLine1: type: string addressLine2: type: string state: anyOf: - type: string enum: - '' - type: object properties: label: type: string value: type: string required: - label - value country: anyOf: - type: string enum: - '' - type: object properties: label: type: string value: type: string required: - label - value required: - zip - city - addressLine1 - addressLine2 nullable: true companyName: type: string nullable: true contactName: type: string nullable: true description: type: string nullable: true website: type: string nullable: true status: type: string enum: - Active - Inactive - Unknown nullable: true type: type: string enum: - Individual - Business - Unknown nullable: true required: - id - name - email - phoneNumber - billingAddressJson - companyName - contactName - description - website - status - type /company/{id}/customers/{customerId}: patch: operationId: updateCustomerApi summary: Update Customer description: |- Updates a Customer for the company. Required scope: write:customer tags: - Customers parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: customerId in: path required: true description: The customer ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: name: type: string email: type: string phoneNumber: type: string billingAddressJson: type: object properties: zip: type: string city: type: string addressLine1: type: string addressLine2: type: string state: anyOf: - type: string enum: - '' - type: object properties: label: type: string value: type: string required: - label - value country: anyOf: - type: string enum: - '' - type: object properties: label: type: string value: type: string required: - label - value required: - zip - city - addressLine1 - addressLine2 nullable: true companyName: type: string contactName: type: string description: type: string website: type: string status: type: string enum: - Active - Inactive - Unknown type: type: string enum: - Individual - Business - Unknown responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier name: type: string nullable: true email: type: string nullable: true phoneNumber: type: string nullable: true billingAddressJson: type: object properties: zip: type: string city: type: string addressLine1: type: string addressLine2: type: string state: anyOf: - type: string enum: - '' - type: object properties: label: type: string value: type: string required: - label - value country: anyOf: - type: string enum: - '' - type: object properties: label: type: string value: type: string required: - label - value required: - zip - city - addressLine1 - addressLine2 nullable: true companyName: type: string nullable: true contactName: type: string nullable: true description: type: string nullable: true website: type: string nullable: true status: type: string enum: - Active - Inactive - Unknown nullable: true type: type: string enum: - Individual - Business - Unknown nullable: true required: - id - name - email - phoneNumber - billingAddressJson - companyName - contactName - description - website - status - type /company/{id}/requests: get: operationId: requests summary: Get Requests description: |- Retrieve a list of requests in a company. Required scope: read:company tags: - Requests parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: status in: query required: false schema: type: string - name: type in: query required: false schema: type: string - name: transactionIds in: query required: false schema: anyOf: - type: string minLength: 1 description: Partner-facing external identifier - type: array items: type: string minLength: 1 description: Partner-facing external identifier - name: requestedUserIds in: query required: false schema: anyOf: - type: string minLength: 1 description: Partner-facing external identifier - type: array items: type: string minLength: 1 description: Partner-facing external identifier - name: requestedByUserIds in: query required: false schema: anyOf: - type: string minLength: 1 description: Partner-facing external identifier - type: array items: type: string minLength: 1 description: Partner-facing external identifier - name: startDate in: query required: false schema: type: string minLength: 1 description: Calendar date, YYYY-MM-DD - name: endDate in: query required: false schema: type: string minLength: 1 description: Calendar date, YYYY-MM-DD responses: '200': description: OK content: application/json: schema: type: object properties: requests: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier transactionId: type: string minLength: 1 description: Partner-facing external identifier nullable: true status: type: string enum: - Cancelled - Completed - Open type: type: string enum: - CategoryReview - Documentation - Message - Integration requestedByUserId: type: string minLength: 1 description: Partner-facing external identifier nullable: true requestedUserId: type: string minLength: 1 description: Partner-facing external identifier nullable: true requestedUserEmail: type: string nullable: true requestedByUserEmail: type: string nullable: true requestedByUserPosition: type: string enum: - Founder - CompanyEmployee - OutsourcedAccountantOrCFO nullable: true requestedUserPosition: type: string enum: - Founder - CompanyEmployee - OutsourcedAccountantOrCFO nullable: true requestedByUserFirmGroups: type: array items: type: string nullable: true requestedUserFirmGroups: type: array items: type: string nullable: true completedByUserId: type: string minLength: 1 description: Partner-facing external identifier nullable: true completedByUserEmail: type: string nullable: true completedByUserPosition: type: string enum: - Founder - CompanyEmployee - OutsourcedAccountantOrCFO nullable: true completedByUserFirmGroups: type: array items: type: string nullable: true cancelledByUserId: type: string minLength: 1 description: Partner-facing external identifier nullable: true cancelledByUserEmail: type: string nullable: true cancelledByUserPosition: type: string enum: - Founder - CompanyEmployee - OutsourcedAccountantOrCFO nullable: true cancelledByUserFirmGroups: type: array items: type: string nullable: true message: type: string nullable: true required: - id - transactionId - status - type - requestedByUserId - requestedUserId - requestedUserEmail - requestedByUserEmail - requestedByUserPosition - requestedUserPosition - requestedByUserFirmGroups - requestedUserFirmGroups - completedByUserId - completedByUserEmail - completedByUserPosition - completedByUserFirmGroups - cancelledByUserId - cancelledByUserEmail - cancelledByUserPosition - cancelledByUserFirmGroups - message required: - requests post: operationId: createRequests summary: Create Requests description: >- Creates category, documentation, and message requests in a company for a transaction. Required scope: write:request tags: - Requests parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: transactionId: type: string minLength: 1 description: Partner-facing external identifier requests: type: object properties: categoryReview: type: object properties: requestedUserId: type: string minLength: 1 description: Partner-facing external identifier status: type: string enum: - Cancelled - Completed - Open required: - status documentationReview: type: object properties: requestedUserId: type: string minLength: 1 description: Partner-facing external identifier status: type: string enum: - Cancelled - Completed - Open required: - status messages: type: array items: type: object properties: message: type: string minLength: 1 required: - message required: - transactionId responses: '200': description: OK content: application/json: schema: type: object properties: transactionId: type: string minLength: 1 description: Partner-facing external identifier requests: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier transactionId: type: string minLength: 1 description: Partner-facing external identifier nullable: true status: type: string enum: - Cancelled - Completed - Open type: type: string enum: - CategoryReview - Documentation - Message - Integration requestedByUserId: type: string minLength: 1 description: Partner-facing external identifier nullable: true requestedUserId: type: string minLength: 1 description: Partner-facing external identifier nullable: true requestedUserEmail: type: string nullable: true requestedByUserEmail: type: string nullable: true requestedByUserPosition: type: string enum: - Founder - CompanyEmployee - OutsourcedAccountantOrCFO nullable: true requestedUserPosition: type: string enum: - Founder - CompanyEmployee - OutsourcedAccountantOrCFO nullable: true requestedByUserFirmGroups: type: array items: type: string nullable: true requestedUserFirmGroups: type: array items: type: string nullable: true completedByUserId: type: string minLength: 1 description: Partner-facing external identifier nullable: true completedByUserEmail: type: string nullable: true completedByUserPosition: type: string enum: - Founder - CompanyEmployee - OutsourcedAccountantOrCFO nullable: true completedByUserFirmGroups: type: array items: type: string nullable: true cancelledByUserId: type: string minLength: 1 description: Partner-facing external identifier nullable: true cancelledByUserEmail: type: string nullable: true cancelledByUserPosition: type: string enum: - Founder - CompanyEmployee - OutsourcedAccountantOrCFO nullable: true cancelledByUserFirmGroups: type: array items: type: string nullable: true message: type: string nullable: true createdAt: type: string minLength: 1 description: ISO 8601 timestamp updatedAt: type: string minLength: 1 description: ISO 8601 timestamp required: - id - transactionId - status - type - requestedByUserId - requestedUserId - requestedUserEmail - requestedByUserEmail - requestedByUserPosition - requestedUserPosition - requestedByUserFirmGroups - requestedUserFirmGroups - completedByUserId - completedByUserEmail - completedByUserPosition - completedByUserFirmGroups - cancelledByUserId - cancelledByUserEmail - cancelledByUserPosition - cancelledByUserFirmGroups - message - createdAt - updatedAt required: - transactionId - requests /company/{id}/vendor-spending-report: get: operationId: vendorSpendingReportApi summary: Get Vendor Spending Report description: |- Retrieves a report of the company's vendor spending. Required scope: read:company tags: - Reports parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: startDate in: query required: true schema: type: string pattern: ^\d{4}-\d{2}$ description: Calendar month, YYYY-MM - name: endDate in: query required: true schema: type: string pattern: ^\d{4}-\d{2}$ description: Calendar month, YYYY-MM responses: '200': description: OK content: application/json: schema: type: object properties: title: type: string columns: type: array items: type: string rows: type: array items: type: array items: type: string required: - title - columns - rows /company/{id}/financialStatements: post: operationId: financialStatements summary: Get Financial Statements description: >- Retrieve the financial statements of a company. Currently supports the Cash Activity Report, Income Statement, and Balance Sheet. Required scope: read:company tags: - Reports parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: basis: type: string enum: - cash - accrual key: type: string enum: - income_statement - cash_activity_report - trial_balance - balance_sheet intervals: type: array items: type: object properties: key: type: string periods: type: array items: type: string required: - key - periods required: - key - intervals responses: '200': description: OK content: application/json: schema: type: object properties: lines: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier parentId: type: string nullable: true childIds: type: array items: type: string depth: type: integer nullable: true name: type: string type: type: string enum: - account - rollup - parent_account_group - counterparty - accrualRevenueSource - department - event - revenueSource amountType: type: string enum: - credit - debit nullable: true accountNumber: type: string nullable: true accountId: type: string minLength: 1 description: Partner-facing external identifier nullable: true intervals: type: array items: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string required: - amount required: - id - parentId - childIds - depth - name - type - amountType - accountNumber - accountId - intervals properties: type: object properties: basis: type: string enum: - cash - accrual currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code key: type: string enum: - income_statement - cash_activity_report - trial_balance - balance_sheet name: type: string intervals: type: array items: type: object properties: key: type: string periods: type: array items: type: string required: - key - periods required: - basis - currency - key - name - intervals required: - lines - properties /company/{id}/statements/profitLoss: get: operationId: incomeStatementApi summary: Get Income Statement description: >- 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 tags: - Reports parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: basis in: query required: false schema: type: string enum: - cash - accrual description: >- The value is normalized before matching, so any casing that maps onto a listed value is accepted. - name: viewBy in: query required: false schema: type: string enum: - month - quarter - year - totals - departments description: >- The value is normalized before matching, so any casing that maps onto a listed value is accepted. - name: startPeriod in: query required: false schema: type: string minLength: 1 - name: endPeriod in: query required: false schema: type: string minLength: 1 - name: dateMacro in: query required: false schema: type: string enum: - CurrentMonth - LastFullMonth - LastThreeMonths - LastThreeFullMonths - CurrentYear - LastYear - QuarterToDate - YearToDate - name: departments in: query required: false schema: anyOf: - type: string - type: array items: type: string description: >- One or more cls_ classification segment IDs returned by GET /company/{id}/classifications, or the case-insensitive literal "none". Values may be repeated or comma-separated. - name: locations in: query required: false schema: anyOf: - type: string - type: array items: type: string description: >- One or more cls_ classification segment IDs returned by GET /company/{id}/classifications, or the case-insensitive literal "none". Values may be repeated or comma-separated. - name: expandCounterparties in: query required: false schema: type: string description: Boolean flag; "true" enables, any other value disables - name: expandRevenueSources in: query required: false schema: type: string description: Boolean flag; "true" enables, any other value disables responses: '200': description: OK content: application/json: schema: type: object properties: columns: type: array items: type: object properties: key: type: string label: type: string dateRange: type: object properties: start: type: string minLength: 1 description: Calendar date, YYYY-MM-DD end: type: string minLength: 1 description: Calendar date, YYYY-MM-DD required: - start - end nullable: true required: - key - label lines: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier title: type: string values: type: array items: type: object properties: balance: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string columnKey: type: string required: - balance - columnKey accountId: type: string minLength: 1 description: Partner-facing external identifier nullable: true accountNumber: type: string nullable: true parentId: type: string minLength: 1 description: Partner-facing external identifier nullable: true childIds: type: array items: type: string minLength: 1 description: Partner-facing external identifier lineType: type: string enum: - account - rollup - parent_account_group - counterparty - accrualRevenueSource - department - event - revenueSource metadata: type: object properties: counterpartyName: type: string nullable: true counterpartyType: type: string enum: - customer - vendor - employee - contractor nullable: true revenueSourceType: type: string enum: - transaction - invoice - schedule - mje - other - subledger nullable: true required: - counterpartyName - counterpartyType - revenueSourceType nullable: true required: - id - title - values - childIds - lineType required: - columns - lines /company/{id}/statements/profitLoss/interop: get: operationId: incomeStatementInteropFormatApi summary: Get Income Statement (Interop Format) description: >- 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 tags: - Reports parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: startPeriod in: query required: true schema: type: string minLength: 1 - name: endPeriod in: query required: true schema: type: string minLength: 1 - name: basis in: query required: false schema: type: string enum: - cash - accrual - name: departments in: query required: false schema: anyOf: - type: string - type: array items: type: string description: >- One or more cls_ classification segment IDs returned by GET /company/{id}/classifications, or the case-insensitive literal "none". Values may be repeated or comma-separated. responses: '200': description: OK content: application/json: schema: type: object properties: Header: type: object properties: Time: type: string ReportName: type: string StartPeriod: type: string EndPeriod: type: string Currency: type: string ReportBasis: type: string required: - Time - ReportName - StartPeriod - EndPeriod - Currency - ReportBasis Columns: type: array items: type: object properties: ColTitle: type: string ColType: type: string required: - ColTitle - ColType Rows: type: object properties: Row: type: array items: $ref: '#/components/schemas/InteropReportRow' required: - Row required: - Header - Columns - Rows /company/{id}/statements/balanceSheet: get: operationId: balanceSheetStatementApi summary: Get Balance Sheet Statement description: >- 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 tags: - Reports parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: basis in: query required: false schema: type: string enum: - cash - accrual description: >- The value is normalized before matching, so any casing that maps onto a listed value is accepted. - name: viewBy in: query required: false schema: type: string enum: - month - quarter - year - totals - departments description: >- The value is normalized before matching, so any casing that maps onto a listed value is accepted. - name: startPeriod in: query required: false schema: type: string minLength: 1 - name: endPeriod in: query required: false schema: type: string minLength: 1 - name: dateMacro in: query required: false schema: type: string enum: - CurrentMonth - LastFullMonth - LastThreeMonths - LastThreeFullMonths - CurrentYear - LastYear - QuarterToDate - YearToDate responses: '200': description: OK content: application/json: schema: type: object properties: columns: type: array items: type: object properties: key: type: string label: type: string dateRange: type: object properties: start: type: string minLength: 1 description: Calendar date, YYYY-MM-DD end: type: string minLength: 1 description: Calendar date, YYYY-MM-DD required: - start - end nullable: true required: - key - label lines: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier title: type: string values: type: array items: type: object properties: balance: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string columnKey: type: string required: - balance - columnKey accountId: type: string minLength: 1 description: Partner-facing external identifier nullable: true accountNumber: type: string nullable: true parentId: type: string minLength: 1 description: Partner-facing external identifier nullable: true childIds: type: array items: type: string minLength: 1 description: Partner-facing external identifier lineType: type: string enum: - account - rollup - parent_account_group - counterparty - accrualRevenueSource - department - event - revenueSource metadata: type: object properties: counterpartyName: type: string nullable: true counterpartyType: type: string enum: - customer - vendor - employee - contractor nullable: true revenueSourceType: type: string enum: - transaction - invoice - schedule - mje - other - subledger nullable: true required: - counterpartyName - counterpartyType - revenueSourceType nullable: true required: - id - title - values - childIds - lineType required: - columns - lines /company/{id}/statements/balanceSheet/interop: get: operationId: balanceSheetInteropFormatApi summary: Get Balance Sheet (Interop Format) description: >- 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 tags: - Reports parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: startPeriod in: query required: true schema: type: string minLength: 1 - name: endPeriod in: query required: true schema: type: string minLength: 1 - name: basis in: query required: false schema: type: string enum: - cash - accrual - name: departments in: query required: false schema: anyOf: - type: string - type: array items: type: string description: >- One or more cls_ classification segment IDs returned by GET /company/{id}/classifications, or the case-insensitive literal "none". Values may be repeated or comma-separated. responses: '200': description: OK content: application/json: schema: type: object properties: Header: type: object properties: Time: type: string ReportName: type: string StartPeriod: type: string EndPeriod: type: string Currency: type: string ReportBasis: type: string required: - Time - ReportName - StartPeriod - EndPeriod - Currency - ReportBasis Columns: type: array items: type: object properties: ColTitle: type: string ColType: type: string required: - ColTitle - ColType Rows: type: object properties: Row: type: array items: $ref: '#/components/schemas/InteropReportRow' required: - Row required: - Header - Columns - Rows /company/{id}/statements/cashActivity: get: operationId: cashActivityStatementApi summary: Get Cash Activity Statement description: >- 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 tags: - Reports parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: viewBy in: query required: false schema: type: string enum: - month - quarter - year - totals - departments description: >- The value is normalized before matching, so any casing that maps onto a listed value is accepted. - name: startPeriod in: query required: false schema: type: string minLength: 1 - name: endPeriod in: query required: false schema: type: string minLength: 1 - name: dateMacro in: query required: false schema: type: string enum: - CurrentMonth - LastFullMonth - LastThreeMonths - LastThreeFullMonths - CurrentYear - LastYear - QuarterToDate - YearToDate responses: '200': description: OK content: application/json: schema: type: object properties: columns: type: array items: type: object properties: key: type: string label: type: string dateRange: type: object properties: start: type: string minLength: 1 description: Calendar date, YYYY-MM-DD end: type: string minLength: 1 description: Calendar date, YYYY-MM-DD required: - start - end nullable: true required: - key - label lines: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier title: type: string values: type: array items: type: object properties: balance: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string columnKey: type: string required: - balance - columnKey accountId: type: string minLength: 1 description: Partner-facing external identifier nullable: true accountNumber: type: string nullable: true parentId: type: string minLength: 1 description: Partner-facing external identifier nullable: true childIds: type: array items: type: string minLength: 1 description: Partner-facing external identifier lineType: type: string enum: - account - rollup - parent_account_group - counterparty - accrualRevenueSource - department - event - revenueSource metadata: type: object properties: counterpartyName: type: string nullable: true counterpartyType: type: string enum: - customer - vendor - employee - contractor nullable: true revenueSourceType: type: string enum: - transaction - invoice - schedule - mje - other - subledger nullable: true required: - counterpartyName - counterpartyType - revenueSourceType nullable: true required: - id - title - values - childIds - lineType required: - columns - lines /company/{id}/metrics/expenses: get: operationId: expenseMetrics summary: Get Expense Metrics description: >- 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 tags: - Metrics parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 - name: startDate in: query required: true schema: type: string minLength: 1 description: Calendar date, YYYY-MM-DD - name: endDateExclusive in: query required: false schema: type: string minLength: 1 description: Calendar date, YYYY-MM-DD - name: interval in: query required: false schema: type: string enum: - month description: >- The value is normalized before matching, so any casing that maps onto a listed value is accepted. responses: '200': description: OK content: application/json: schema: type: object properties: metrics: type: array items: type: object properties: totalExpenses: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency totalOperatingExpenses: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency timePeriod: type: object properties: startDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD endDateExclusive: type: string minLength: 1 description: Calendar date, YYYY-MM-DD required: - startDate - endDateExclusive required: - totalExpenses - totalOperatingExpenses - timePeriod required: - metrics /company/{id}/metrics/categorization: get: operationId: categorizationMetrics summary: Get Categorization Metrics description: |- Retrieves categorization metrics for the company. Required scope: read:company tags: - Metrics parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 - name: startDate in: query required: true schema: type: string minLength: 1 description: Calendar date, YYYY-MM-DD - name: endDateExclusive in: query required: false schema: type: string minLength: 1 description: Calendar date, YYYY-MM-DD - name: interval in: query required: false schema: type: string enum: - month description: >- The value is normalized before matching, so any casing that maps onto a listed value is accepted. responses: '200': description: OK content: application/json: schema: type: object properties: metrics: type: array items: type: object properties: timePeriod: type: object properties: startDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD endDateExclusive: type: string minLength: 1 description: Calendar date, YYYY-MM-DD required: - startDate - endDateExclusive dataCompletenessLevel: type: string enum: - Complete - High - Medium - Low percentDollarVolumeCategorized: type: number percentDollarVolumeConfirmed: type: number required: - timePeriod - dataCompletenessLevel - percentDollarVolumeCategorized - percentDollarVolumeConfirmed required: - metrics /company/{id}/metrics/revenue: get: operationId: revenueMetrics summary: Get Revenue Metrics description: >- 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 tags: - Metrics parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 - name: startDate in: query required: true schema: type: string minLength: 1 description: Calendar date, YYYY-MM-DD - name: endDateExclusive in: query required: false schema: type: string minLength: 1 description: Calendar date, YYYY-MM-DD - name: interval in: query required: false schema: type: string enum: - month description: >- The value is normalized before matching, so any casing that maps onto a listed value is accepted. responses: '200': description: OK content: application/json: schema: type: object properties: metrics: type: array items: type: object properties: timePeriod: type: object properties: startDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD endDateExclusive: type: string minLength: 1 description: Calendar date, YYYY-MM-DD required: - startDate - endDateExclusive annualizedRevenue: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency totalRevenue: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency totalCostOfRevenue: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency totalGrossProfit: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency required: - timePeriod - annualizedRevenue - totalRevenue - totalCostOfRevenue - totalGrossProfit required: - metrics /company/{id}/metrics/employee: get: operationId: employeeMetrics summary: Get Employee Metrics description: >- 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 tags: - Metrics parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 - name: startDate in: query required: true schema: type: string minLength: 1 description: Calendar date, YYYY-MM-DD - name: endDateExclusive in: query required: false schema: type: string minLength: 1 description: Calendar date, YYYY-MM-DD - name: interval in: query required: false schema: type: string enum: - month description: >- The value is normalized before matching, so any casing that maps onto a listed value is accepted. responses: '200': description: OK content: application/json: schema: type: object properties: metrics: type: array items: type: object properties: averageFullyLoadedSalaryCostPerEmployee: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency averageSalaryCostPerEmployee: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency totalSalaryExpense: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency totalFullyLoadedSalaryExpense: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency timePeriod: type: object properties: startDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD endDateExclusive: type: string minLength: 1 description: Calendar date, YYYY-MM-DD required: - startDate - endDateExclusive required: - averageFullyLoadedSalaryCostPerEmployee - averageSalaryCostPerEmployee - totalSalaryExpense - totalFullyLoadedSalaryExpense - timePeriod required: - metrics /company/{id}/metrics/spending: get: operationId: spendingMetrics summary: Get Spending Metrics description: >- Retrieves payroll and non-payroll spending metrics for the given period range. Provide startPeriod and endPeriod in YYYY-MM format. Required scope: read:company tags: - Metrics parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 - name: startDate in: query required: true schema: type: string minLength: 1 description: Calendar date, YYYY-MM-DD - name: endDateExclusive in: query required: false schema: type: string minLength: 1 description: Calendar date, YYYY-MM-DD - name: interval in: query required: false schema: type: string enum: - month description: >- The value is normalized before matching, so any casing that maps onto a listed value is accepted. responses: '200': description: OK content: application/json: schema: type: object properties: startPeriod: type: string endPeriod: type: string payrollMetrics: type: array items: type: object properties: period: type: string payrollSpending: type: object properties: departments: type: array items: type: object properties: name: type: string amount: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency headCount: type: integer required: - name - amount - headCount numericSummary: type: object properties: netPay: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency employerTaxes: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency employeeTaxes: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency benefits: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency employeeBenefitsDeductions: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency contractorNetPay: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency required: - netPay - employerTaxes - employeeTaxes - benefits - employeeBenefitsDeductions - contractorNetPay nullable: true required: - departments - numericSummary required: - period - payrollSpending nonPayrollMetrics: type: array items: type: object properties: period: type: string nonPayrollSpending: type: object properties: topVendors: type: array items: type: object properties: vendor: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier name: type: string is1099Vendor: type: string enum: - 'Yes' - 'No' - Unknown required: - id - name - is1099Vendor nullable: true amount: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency count: type: integer required: - vendor - amount - count topCategories: type: array items: type: object properties: ledgerCoaKey: type: string amount: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency count: type: integer required: - ledgerCoaKey - amount - count allOtherVendors: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency allOtherCategories: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency required: - topVendors - topCategories - allOtherVendors - allOtherCategories required: - period - nonPayrollSpending required: - startPeriod - endPeriod - payrollMetrics - nonPayrollMetrics /company/{id}/disconnect: post: operationId: disconnect summary: Disconnect Company tags: - Company parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier responses: '200': description: OK content: application/json: schema: type: object properties: disconnect: type: boolean required: - disconnect /linkToken: post: operationId: createTemporaryLinkToken summary: Fetch a Link Token description: "This authentication method has been deprecated. Please use the Authentication endpoints instead. Additional details can be found here.\n\nCreates a link token that can be used to authenticate a user when directing them to the connection flow. The token expires after 30 minutes.\n\nAfter obtaining your link token, create a link to Puzzle so the user can connect their Puzzle account.\n\n\n Connect your Puzzle account\n\n\nThey will see your welcome page and an opportunity to log in or sign up with Puzzle." tags: - User requestBody: required: true content: application/json: schema: type: object properties: userName: type: string userEmail: type: string companyId: type: string minLength: 1 companyName: type: string required: - userName - userEmail - companyId - companyName responses: '200': description: OK content: application/json: schema: type: object properties: linkToken: type: string companyId: type: string minLength: 1 description: Partner-facing external identifier required: - linkToken - companyId /me: get: operationId: me summary: Get Current User description: >- Gets information about the current user. Only valid for OAuth connections. tags: - User responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier companies: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier name: type: string connectedAt: type: string minLength: 1 description: ISO 8601 timestamp status: type: string enum: - Ready - Syncing - NoData financialYearStartDate: type: string reportingCurrency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - id - name - connectedAt - status - financialYearStartDate - reportingCurrency required: - id - companies /company/{id}/chartOfAccounts: get: operationId: chartOfAccounts summary: Get Chart of Accounts description: >- 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 tags: - Company parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: basis in: query required: false schema: type: string enum: - cash - accrual - name: startDate in: query required: false schema: type: string minLength: 1 - name: effectiveDate in: query required: false schema: type: string minLength: 1 description: Calendar date, YYYY-MM-DD - name: nominalCode in: query required: false schema: type: string - name: getRestricted in: query required: false schema: type: string description: Boolean flag; "true" enables, any other value disables responses: '200': description: OK content: application/json: schema: type: object properties: accounts: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier name: type: string coaKeys: type: array items: type: string minLength: 1 description: Chart-of-accounts key restrictedCoaKeys: type: array items: type: string minLength: 1 description: Chart-of-accounts key nominalCode: type: string description: type: string nullable: true keywords: type: array items: type: string type: type: string tags: type: array items: type: string category: type: string subCategory: type: string nullable: true tertiaryCategory: type: string nullable: true parentCode: type: string nullable: true currentBalance: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency currentBalanceWithoutSubAccounts: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency isBankAccount: type: boolean accountId: type: string minLength: 1 description: Partner-facing external identifier nullable: true views: type: array items: type: string currentness: type: string nullable: true required: - id - name - coaKeys - restrictedCoaKeys - nominalCode - keywords - type - tags - category - currentBalance - currentBalanceWithoutSubAccounts - isBankAccount - views required: - accounts /categories: get: operationId: puzzleCategories summary: Get Puzzle Categories description: >- Retrieves all of the valid Puzzle categories that can be used to categorize transactions. Only valid for OAuth connections. tags: - User responses: '200': description: OK content: application/json: schema: type: object properties: categories: type: array items: type: string enum: - accounts_receivable - accrued_revenue - accumulated_depreciation_fixed_assets - cash_adjustments - deposits - fixed_assets - other_current_assets - other_noncurrent_assets - security_deposits - accounts_payable - debt_payable_current - debt_payable_noncurrent - deferred_revenue - notes_payable - other_current_liabilities - accrued_salaries_and_benefits - accrued_expenses - advertising - bad_debt - bank_fees - benefits_adjustments - benefits_payment_medical - benefits_payment_other_payable - benefits_payment_other_prepaid - benefits_payment_retirement - bonuses - bonuses_adjustments - branded_gifts_and_swag - business_development_and_conferences - commissions - commissions_adjustments - computers_and_hardware - consultants - cost_of_sales - credit_card_payment - depreciation_fixed_assets - design - dues_and_subscriptions - employee_gifts - entertainment - facilities - furniture - gain_loss_fixed_asset_disposal - general_and_administrative - independent_contractors - interest_expense - interest_and_dividend_income - insurance - legal - marketing - meals_and_entertainment - meals_with_clients - miscellaneous_expenses - office_meals - other_expenses - other_meals - other_employee_costs - other_payroll - payroll_fees - payroll_taxes - payment_processor_fees - partnership_revenue - penalties_and_settlements - personnel_expense - professional_services - prepaid_benefits - prepaid_expenses - recruiting - recruiters - rent - repairs_and_maintenance - retirement_expense - salaries_adjustments - salaries_and_benefits - sales_and_marketing - shipping - software - software_subscriptions_and_tools - supplies - tax - tax_and_accounting - training_and_development - travel - travel_airfare - travel_ground_transportation - travel_lodging - travel_meals - utilities - uncategorized_expenses - hosting - bill_pay_clearing - employee_reimbursement_clearing - income - consulting_income - consulting_income_refund - subscription_income - subscription_income_refund - transaction_income - transaction_income_refund - usage_income - usage_income_refund - miscellaneous_income - miscellaneous_income_refund - credit_card_rewards_redeemed - other_revenue - equity - common_stock - debt_convertible_note - other_investments - preferred_stock - venture_safe_note - retained_earnings - transfer_account - processor_transfers - realized_gains_and_losses - unrealized_gains_and_losses - no_category required: - categories /company/{id}/classifications: get: operationId: classifications summary: Get Classifications description: >- Retrieves a list of all classifications available for the calling company. Requires scope: read:company tags: - Company parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier responses: '200': description: OK content: application/json: schema: type: object properties: classifications: type: array items: type: object properties: class: type: string description: type: string nullable: true segments: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier nullable: true segment: type: string description: type: string nullable: true required: - id - segment - description required: - class - description - segments required: - classifications post: operationId: createClassification summary: Create Classifications description: |- Creates a classification. Requires scope: write:classification tags: - Company parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: class: type: object properties: name: type: string minLength: 1 description: type: string required: - name segment: type: object properties: name: type: string minLength: 1 description: type: string required: - name required: - class - segment responses: '200': description: OK content: application/json: schema: type: object properties: classification: type: object properties: class: type: string description: type: string nullable: true segments: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier nullable: true segment: type: string required: - id - segment required: - class - description - segments required: - classification /company/{id}/classifications/{classificationId}: get: operationId: classification summary: Get Classification description: |- Retrieves a classification available for the calling company. Requires scope: read:company tags: - Company parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: classificationId in: path required: true description: The classification ID schema: type: string minLength: 1 description: Partner-facing external identifier responses: '200': description: OK content: application/json: schema: type: object properties: classification: type: object properties: class: type: string description: type: string nullable: true segments: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier nullable: true segment: type: string description: type: string nullable: true required: - id - segment - description required: - class - description - segments required: - classification /company/{id}/workers: get: operationId: workersList summary: Get Workers description: >- Retrieves a list of all of the company's workers, both employees and contractors. Required scope: read:worker tags: - Payroll parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: subset in: query required: false schema: type: string enum: - Active - Terminated - Contractor - name: search in: query required: false schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: workers: type: array items: anyOf: - type: object properties: annualCosts: type: object properties: salaryCost: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency burdenCost: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency fullyLoadedCost: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency required: - salaryCost - burdenCost - fullyLoadedCost nullable: true id: type: string minLength: 1 description: Partner-facing external identifier firstName: type: string nullable: true lastName: type: string nullable: true employmentType: type: string enum: - FullTime - PartTime - Contractor jobTitle: type: string department: type: string nullable: true startDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD employeeTerminations: type: array items: type: object properties: terminationDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD required: - terminationDate flsaStatus: type: string enum: - Exempt - SalariedNonexempt - Nonexempt - Owner nullable: true officeLocation: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier city: type: string state: type: string zipCode: type: string required: - id - city - state - zipCode payFrequency: type: string enum: - Hour - Day - Week - Month - Year - Paycheck - Unknown payRate: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string terminated: type: boolean required: - annualCosts - id - firstName - lastName - employmentType - jobTitle - department - startDate - employeeTerminations - flsaStatus - officeLocation - payFrequency - payRate - terminated - type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier firstName: type: string nullable: true lastName: type: string nullable: true businessName: type: string nullable: true startDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD department: type: string nullable: true hourlyRate: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string nullable: true isActive: type: boolean type: type: string enum: - Individual - Business nullable: true wageType: type: string enum: - Fixed - Hourly - Daily - Weekly - Monthly - Biweekly - Semimonthly - Annually - Custom payRate: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string required: - id - firstName - lastName - businessName - startDate - department - hourlyRate - isActive - type - wageType - payRate required: - workers /company/{id}/journalEntry: post: operationId: upsertJournalEntry summary: Create Journal Entry description: >- 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. By default, entries are submitted for posting asynchronously and can then be retrieved through the Get Journal Entries endpoint. Set posted to false on a Journal entry to save a draft for review and posting in Puzzle. The posted option is per entry for both single and bulk creation and defaults to true. Drafts do not emit ledger events and are excluded from Get Journal Entries until posted. Transaction entries do not support posted: false. Reusing document.nativeDocumentId returns the existing entry without updating or posting it. Posted 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. tags: - JournalEntry parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: basis: type: array items: type: string memo: type: string postingDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD type: type: string enum: - Journal - Transaction posted: type: boolean description: >- Defaults to true. Set false with type Journal to save a draft for review and posting in Puzzle. Drafts are excluded from the public journal list until posted. Reusing document.nativeDocumentId returns the existing entry without changing its posting status. Transaction entries do not support drafts. nativeTransactionId: type: string createdFor: type: string lines: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string coaKey: type: string minLength: 1 description: Chart-of-accounts key description: type: string manualJournalEntryId: type: string minLength: 1 description: Partner-facing external identifier classifications: type: array items: type: object properties: class: type: string minLength: 1 segment: type: string minLength: 1 required: - class - segment userDefinedMetadata: type: object additionalProperties: {} nullable: true vendorId: type: string minLength: 1 description: Partner-facing external identifier vendorName: type: string customerId: type: string minLength: 1 description: Partner-facing external identifier customerName: type: string required: - amount - coaKey - description document: type: object properties: documentType: type: string enum: - Receipt - Bill - Invoice fileName: type: string minLength: 1 contentType: type: string minLength: 1 base64File: type: string minLength: 1 nativeDocumentId: type: string minLength: 1 required: - documentType - fileName - contentType - base64File - nativeDocumentId required: - basis - memo - postingDate - lines responses: '200': description: OK content: application/json: schema: type: object properties: summary: type: object properties: requested: type: integer success: type: integer error: type: integer required: - requested - success - error results: type: array items: type: object properties: index: type: integer status: type: string enum: - success - error id: type: string minLength: 1 description: Partner-facing external identifier nativeId: type: string error: type: object properties: message: type: string code: type: string required: - message - code required: - index - status required: - summary - results /company/{id}/journalEntry/{journalEntryId}: delete: operationId: deleteJournalEntry summary: Delete Journal Entry description: >- 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. tags: - JournalEntry parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: journalEntryId in: path required: true description: The journal entry ID schema: type: string minLength: 1 description: Partner-facing external identifier responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean error: type: string required: - success /company/{id}/journalEntries: get: operationId: journalEntries summary: Get Journal Entries description: 'Required scope: read:company' tags: - JournalEntries parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: limit in: query required: false schema: type: integer - name: cursor in: query required: false schema: type: string - name: basis in: query required: false schema: type: string enum: - cash - accrual - name: createdAfter in: query required: false schema: type: string minLength: 1 description: ISO 8601 timestamp responses: '200': description: OK content: application/json: schema: type: object properties: journalEntries: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier manualJournalEntryId: type: string minLength: 1 description: Partner-facing external identifier nullable: true description: type: string nullable: true memo: type: string nullable: true postingDate: type: string effectiveAt: type: string minLength: 1 description: ISO 8601 timestamp basis: type: string enum: - cash - accrual nullable: true type: type: string enum: - MANUAL - PARTNER lines: type: array items: type: object properties: description: type: string nullable: true amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code accountId: type: string minLength: 1 description: Partner-facing external identifier required: - description - amount - currency - accountId required: - id - manualJournalEntryId - description - memo - postingDate - effectiveAt - basis - type - lines pageInfo: type: object properties: nextCursor: type: string minLength: 1 description: Partner-facing external identifier nullable: true required: - nextCursor required: - journalEntries - pageInfo post: operationId: upsertJournalEntries summary: Create Journal Entry description: >- 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. By default, entries are submitted for posting asynchronously and can then be retrieved through the Get Journal Entries endpoint. Set posted to false on a Journal entry to save a draft for review and posting in Puzzle. The posted option is per entry for both single and bulk creation and defaults to true. Drafts do not emit ledger events and are excluded from Get Journal Entries until posted. Transaction entries do not support posted: false. Reusing document.nativeDocumentId returns the existing entry without updating or posting it. Posted 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. tags: - JournalEntries parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: array items: type: object properties: basis: type: array items: type: string memo: type: string postingDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD type: type: string enum: - Journal - Transaction posted: type: boolean description: >- Defaults to true. Set false with type Journal to save a draft for review and posting in Puzzle. Drafts are excluded from the public journal list until posted. Reusing document.nativeDocumentId returns the existing entry without changing its posting status. Transaction entries do not support drafts. nativeTransactionId: type: string createdFor: type: string lines: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string coaKey: type: string minLength: 1 description: Chart-of-accounts key description: type: string manualJournalEntryId: type: string minLength: 1 description: Partner-facing external identifier classifications: type: array items: type: object properties: class: type: string minLength: 1 segment: type: string minLength: 1 required: - class - segment userDefinedMetadata: type: object additionalProperties: {} nullable: true vendorId: type: string minLength: 1 description: Partner-facing external identifier vendorName: type: string customerId: type: string minLength: 1 description: Partner-facing external identifier customerName: type: string required: - amount - coaKey - description document: type: object properties: documentType: type: string enum: - Receipt - Bill - Invoice fileName: type: string minLength: 1 contentType: type: string minLength: 1 base64File: type: string minLength: 1 nativeDocumentId: type: string minLength: 1 required: - documentType - fileName - contentType - base64File - nativeDocumentId required: - basis - memo - postingDate - lines responses: '200': description: OK content: application/json: schema: type: object properties: summary: type: object properties: requested: type: integer success: type: integer error: type: integer required: - requested - success - error results: type: array items: type: object properties: index: type: integer status: type: string enum: - success - error id: type: string minLength: 1 description: Partner-facing external identifier nativeId: type: string error: type: object properties: message: type: string code: type: string required: - message - code required: - index - status required: - summary - results /company/{id}/journalEntries/{journalEntryId}/document: post: operationId: createJournalEntryDocument summary: Create Document description: |- Create a document for a given journal entry. Required scope: write:journal tags: - JournalEntries parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: journalEntryId in: path required: true description: The journal entry ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: documentType: type: string enum: - Receipt - Bill - Invoice fileName: type: string minLength: 1 contentType: type: string minLength: 1 base64File: type: string minLength: 1 nativeDocumentId: type: string minLength: 1 required: - documentType - fileName - contentType - base64File - nativeDocumentId responses: '200': description: OK content: application/json: schema: type: object properties: transactionId: type: string minLength: 1 description: Partner-facing external identifier nullable: true manualJournalEntryId: type: string minLength: 1 description: Partner-facing external identifier nullable: true journalEntryId: type: string minLength: 1 description: Partner-facing external identifier nullable: true billId: type: string minLength: 1 description: Partner-facing external identifier nullable: true invoiceId: type: string minLength: 1 description: Partner-facing external identifier nullable: true document: type: object properties: id: type: string documentType: type: string enum: - Receipt - Bill - Invoice contentType: type: string downloadInfo: type: object properties: signedUrl: type: string urlExpiresAt: type: string minLength: 1 description: ISO 8601 timestamp required: - signedUrl - urlExpiresAt required: - id - documentType - contentType - downloadInfo required: - transactionId - manualJournalEntryId - journalEntryId - billId - invoiceId - document /company/{id}/transactions: get: operationId: getTransactions summary: Get Transactions description: >- Get transactions by filter. Categorization attribution is omitted by default; pass includeCategorization=true to include it. NotCategorized includes null and company-specific uncategorized categories on both linked and unlinked transactions. Required scope: read:company tags: - Transactions parameters: - name: includeCategorization in: query required: false schema: type: string description: >- Include categorization attribution and history only when "true"; omitted by default - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: startDate in: query required: true schema: type: string minLength: 1 description: Calendar date, YYYY-MM-DD - name: endDate in: query required: true schema: type: string minLength: 1 description: Calendar date, YYYY-MM-DD - name: accountIds in: query required: false schema: anyOf: - type: string minLength: 1 description: Partner-facing external identifier - type: array items: type: string minLength: 1 description: Partner-facing external identifier - name: vendorIds in: query required: false schema: anyOf: - type: string minLength: 1 description: Partner-facing external identifier - type: array items: type: string minLength: 1 description: Partner-facing external identifier - name: coaKeys in: query required: false schema: anyOf: - type: string - type: array items: type: string - name: status in: query required: false schema: type: string enum: - Finalized - NotFinalized - NotCategorized - name: sortBy in: query required: false schema: type: string enum: - ABS_AMOUNT_ASC - ABS_AMOUNT_DESC - AMOUNT_ASC - AMOUNT_DESC - DATE_ASC - DATE_DESC - DESCRIPTION_ASC - DESCRIPTION_DESC - NAME_ASC - UNCATEGORIZED_AMOUNT_DESC - VENDOR_ASC - VENDOR_DESC - name: after in: query required: false schema: type: string - name: count in: query required: false schema: type: integer responses: '200': description: OK content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier amount: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency descriptor: type: string timestamp: type: string minLength: 1 description: ISO 8601 timestamp memo: type: string nullable: true nativeId: type: string nullable: true category: type: string nullable: true coaKey: type: string nullable: true accountId: type: string minLength: 1 description: Partner-facing external identifier nullable: true status: type: string enum: - Finalized - NotFinalized - NotCategorized nullable: true actorType: type: string enum: - SYSTEM_ACTOR - TRAIN_ACTOR - USER_ACTOR - USER_ACTOR_VIA_AI - ADMIN_ACTOR - AI_ACTOR nullable: true categorization: type: object properties: status: type: string enum: - CATEGORIZED - UNCATEGORIZED - PARTIALLY_CATEGORIZED confirmationStatus: type: string enum: - CONFIRMED - UNCONFIRMED - PARTIALLY_CONFIRMED confirmedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true lastHumanConfirmation: type: object properties: source: type: string enum: - AI - MANUAL - USER_DIRECTED_AI - AUTOMATION - UNKNOWN actorType: type: string enum: - SYSTEM_ACTOR - TRAIN_ACTOR - USER_ACTOR - USER_ACTOR_VIA_AI - ADMIN_ACTOR - AI_ACTOR nullable: true userId: type: string minLength: 1 description: Partner-facing external identifier nullable: true at: type: string minLength: 1 description: ISO 8601 timestamp nullable: true required: - source - actorType - userId - at nullable: true detailsConfirmationStatus: type: string enum: - CONFIRMED - UNCONFIRMED - PARTIALLY_CONFIRMED details: type: array items: type: object properties: detailId: type: string coaKey: type: string nullable: true status: type: string enum: - CATEGORIZED - UNCATEGORIZED - PARTIALLY_CATEGORIZED confirmationStatus: type: string enum: - CONFIRMED - UNCONFIRMED - PARTIALLY_CONFIRMED confirmedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true attributionStatus: type: string enum: - COMPLETE - PARTIAL - UNKNOWN current: type: object properties: source: type: string enum: - AI - MANUAL - USER_DIRECTED_AI - AUTOMATION - UNKNOWN actorType: type: string enum: - SYSTEM_ACTOR - TRAIN_ACTOR - USER_ACTOR - USER_ACTOR_VIA_AI - ADMIN_ACTOR - AI_ACTOR nullable: true userId: type: string minLength: 1 description: Partner-facing external identifier nullable: true at: type: string minLength: 1 description: ISO 8601 timestamp nullable: true coaKey: type: string nullable: true required: - source - actorType - userId - at - coaKey original: type: object properties: source: type: string enum: - AI - MANUAL - USER_DIRECTED_AI - AUTOMATION - UNKNOWN actorType: type: string enum: - SYSTEM_ACTOR - TRAIN_ACTOR - USER_ACTOR - USER_ACTOR_VIA_AI - ADMIN_ACTOR - AI_ACTOR nullable: true userId: type: string minLength: 1 description: Partner-facing external identifier nullable: true at: type: string minLength: 1 description: ISO 8601 timestamp nullable: true coaKey: type: string nullable: true required: - source - actorType - userId - at - coaKey nullable: true lastHumanConfirmation: type: object properties: source: type: string enum: - AI - MANUAL - USER_DIRECTED_AI - AUTOMATION - UNKNOWN actorType: type: string enum: - SYSTEM_ACTOR - TRAIN_ACTOR - USER_ACTOR - USER_ACTOR_VIA_AI - ADMIN_ACTOR - AI_ACTOR nullable: true userId: type: string minLength: 1 description: Partner-facing external identifier nullable: true at: type: string minLength: 1 description: ISO 8601 timestamp nullable: true required: - source - actorType - userId - at nullable: true categoryChanges: type: array items: type: object properties: source: type: string enum: - AI - MANUAL - USER_DIRECTED_AI - AUTOMATION - UNKNOWN actorType: type: string enum: - SYSTEM_ACTOR - TRAIN_ACTOR - USER_ACTOR - USER_ACTOR_VIA_AI - ADMIN_ACTOR - AI_ACTOR nullable: true userId: type: string minLength: 1 description: Partner-facing external identifier nullable: true at: type: string minLength: 1 description: ISO 8601 timestamp nullable: true coaKey: type: string nullable: true previousCoaKey: type: string nullable: true required: - source - actorType - userId - at - coaKey - previousCoaKey required: - detailId - coaKey - status - confirmationStatus - confirmedAt - attributionStatus - current - original - lastHumanConfirmation - categoryChanges required: - status - confirmationStatus - confirmedAt - lastHumanConfirmation - detailsConfirmationStatus - details vendorId: type: string minLength: 1 description: Partner-facing external identifier nullable: true customerId: type: string minLength: 1 description: Partner-facing external identifier nullable: true documents: type: array items: type: object properties: id: type: string documentType: type: string enum: - Receipt - Bill - Invoice contentType: type: string downloadInfo: type: object properties: signedUrl: type: string urlExpiresAt: type: string minLength: 1 description: ISO 8601 timestamp required: - signedUrl - urlExpiresAt required: - id - documentType - contentType - downloadInfo nullable: true classifications: type: array items: type: object properties: class: type: string description: type: string nullable: true segments: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier nullable: true segment: type: string description: type: string nullable: true required: - id - segment - description required: - class - description - segments nullable: true required: - id - amount - descriptor - timestamp - memo - nativeId - category - coaKey - accountId - status - actorType - vendorId - customerId - documents - classifications pageInfo: type: object properties: endCursor: type: string nullable: true hasNextPage: type: boolean total: type: integer nullable: true required: - endCursor - hasNextPage - total required: - items - pageInfo post: operationId: createTransactions summary: Create Transactions description: >- 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, or Loan 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. classifications and customerId, on the transaction and on its splits, are validated synchronously: an invalid value rejects the whole request with a 400. Required scope: write:transaction tags: - Transactions parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: accountId: type: string minLength: 1 description: Partner-facing external identifier transactions: type: array items: type: object properties: nativeId: type: string timestamp: type: string minLength: 1 description: ISO 8601 timestamp amount: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency description: type: string category: type: string coaKey: type: string memo: type: string customerId: type: string minLength: 1 description: Partner-facing external identifier vendorId: type: string minLength: 1 description: Partner-facing external identifier merchantName: type: string counterpartyName: type: string balance: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency splits: type: array items: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string descriptor: type: string ledgerCoaKey: type: string minLength: 1 description: Chart-of-accounts key accrualDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD capitalizable: type: boolean customerId: type: string minLength: 1 description: Partner-facing external identifier isBillPayment: type: boolean isInvoicePayment: type: boolean updateOfSplitId: type: string minLength: 1 description: Partner-facing external identifier vendorPermaName: type: string classifications: type: array items: type: object properties: class: type: string minLength: 1 segment: type: string minLength: 1 required: - class - segment required: - amount - descriptor - ledgerCoaKey classifications: type: array items: type: object properties: class: type: string minLength: 1 segment: type: string minLength: 1 required: - class - segment document: type: object properties: documentType: type: string enum: - Receipt - Bill - Invoice fileName: type: string minLength: 1 contentType: type: string minLength: 1 base64File: type: string minLength: 1 nativeDocumentId: type: string minLength: 1 required: - documentType - fileName - contentType - base64File - nativeDocumentId required: - nativeId - timestamp - amount - description omitAccountSideOfEntry: type: boolean required: - accountId - transactions responses: '200': description: OK content: application/json: schema: type: object properties: transactions: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier nativeId: type: string status: type: string enum: - pending - duplicate required: - id - nativeId - status required: - transactions /company/{id}/transactions/{transactionId}: get: operationId: getTransaction summary: Get Transaction description: >- Get a single transaction by ID. Categorization attribution is omitted by default; pass includeCategorization=true to include it. Required scope: read:company tags: - Transactions parameters: - name: includeCategorization in: query required: false schema: type: string description: >- Include categorization attribution and history only when "true"; omitted by default - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: transactionId in: path required: true description: The transaction ID schema: type: string minLength: 1 description: Partner-facing external identifier responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier amount: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency descriptor: type: string timestamp: type: string minLength: 1 description: ISO 8601 timestamp memo: type: string nullable: true nativeId: type: string nullable: true category: type: string nullable: true coaKey: type: string nullable: true accountId: type: string minLength: 1 description: Partner-facing external identifier nullable: true status: type: string enum: - Finalized - NotFinalized - NotCategorized nullable: true actorType: type: string enum: - SYSTEM_ACTOR - TRAIN_ACTOR - USER_ACTOR - USER_ACTOR_VIA_AI - ADMIN_ACTOR - AI_ACTOR nullable: true categorization: type: object properties: status: type: string enum: - CATEGORIZED - UNCATEGORIZED - PARTIALLY_CATEGORIZED confirmationStatus: type: string enum: - CONFIRMED - UNCONFIRMED - PARTIALLY_CONFIRMED confirmedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true lastHumanConfirmation: type: object properties: source: type: string enum: - AI - MANUAL - USER_DIRECTED_AI - AUTOMATION - UNKNOWN actorType: type: string enum: - SYSTEM_ACTOR - TRAIN_ACTOR - USER_ACTOR - USER_ACTOR_VIA_AI - ADMIN_ACTOR - AI_ACTOR nullable: true userId: type: string minLength: 1 description: Partner-facing external identifier nullable: true at: type: string minLength: 1 description: ISO 8601 timestamp nullable: true required: - source - actorType - userId - at nullable: true detailsConfirmationStatus: type: string enum: - CONFIRMED - UNCONFIRMED - PARTIALLY_CONFIRMED details: type: array items: type: object properties: detailId: type: string coaKey: type: string nullable: true status: type: string enum: - CATEGORIZED - UNCATEGORIZED - PARTIALLY_CATEGORIZED confirmationStatus: type: string enum: - CONFIRMED - UNCONFIRMED - PARTIALLY_CONFIRMED confirmedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true attributionStatus: type: string enum: - COMPLETE - PARTIAL - UNKNOWN current: type: object properties: source: type: string enum: - AI - MANUAL - USER_DIRECTED_AI - AUTOMATION - UNKNOWN actorType: type: string enum: - SYSTEM_ACTOR - TRAIN_ACTOR - USER_ACTOR - USER_ACTOR_VIA_AI - ADMIN_ACTOR - AI_ACTOR nullable: true userId: type: string minLength: 1 description: Partner-facing external identifier nullable: true at: type: string minLength: 1 description: ISO 8601 timestamp nullable: true coaKey: type: string nullable: true required: - source - actorType - userId - at - coaKey original: type: object properties: source: type: string enum: - AI - MANUAL - USER_DIRECTED_AI - AUTOMATION - UNKNOWN actorType: type: string enum: - SYSTEM_ACTOR - TRAIN_ACTOR - USER_ACTOR - USER_ACTOR_VIA_AI - ADMIN_ACTOR - AI_ACTOR nullable: true userId: type: string minLength: 1 description: Partner-facing external identifier nullable: true at: type: string minLength: 1 description: ISO 8601 timestamp nullable: true coaKey: type: string nullable: true required: - source - actorType - userId - at - coaKey nullable: true lastHumanConfirmation: type: object properties: source: type: string enum: - AI - MANUAL - USER_DIRECTED_AI - AUTOMATION - UNKNOWN actorType: type: string enum: - SYSTEM_ACTOR - TRAIN_ACTOR - USER_ACTOR - USER_ACTOR_VIA_AI - ADMIN_ACTOR - AI_ACTOR nullable: true userId: type: string minLength: 1 description: Partner-facing external identifier nullable: true at: type: string minLength: 1 description: ISO 8601 timestamp nullable: true required: - source - actorType - userId - at nullable: true categoryChanges: type: array items: type: object properties: source: type: string enum: - AI - MANUAL - USER_DIRECTED_AI - AUTOMATION - UNKNOWN actorType: type: string enum: - SYSTEM_ACTOR - TRAIN_ACTOR - USER_ACTOR - USER_ACTOR_VIA_AI - ADMIN_ACTOR - AI_ACTOR nullable: true userId: type: string minLength: 1 description: Partner-facing external identifier nullable: true at: type: string minLength: 1 description: ISO 8601 timestamp nullable: true coaKey: type: string nullable: true previousCoaKey: type: string nullable: true required: - source - actorType - userId - at - coaKey - previousCoaKey required: - detailId - coaKey - status - confirmationStatus - confirmedAt - attributionStatus - current - original - lastHumanConfirmation - categoryChanges required: - status - confirmationStatus - confirmedAt - lastHumanConfirmation - detailsConfirmationStatus - details vendorId: type: string minLength: 1 description: Partner-facing external identifier nullable: true customerId: type: string minLength: 1 description: Partner-facing external identifier nullable: true documents: type: array items: type: object properties: id: type: string documentType: type: string enum: - Receipt - Bill - Invoice contentType: type: string downloadInfo: type: object properties: signedUrl: type: string urlExpiresAt: type: string minLength: 1 description: ISO 8601 timestamp required: - signedUrl - urlExpiresAt required: - id - documentType - contentType - downloadInfo nullable: true classifications: type: array items: type: object properties: class: type: string description: type: string nullable: true segments: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier nullable: true segment: type: string description: type: string nullable: true required: - id - segment - description required: - class - description - segments nullable: true required: - id - amount - descriptor - timestamp - memo - nativeId - category - coaKey - accountId - status - actorType - vendorId - customerId - documents - classifications patch: operationId: updateTransaction summary: Update Transaction description: |- Updates an existing Transaction Required scope: write:transaction tags: - Transactions parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: transactionId in: path required: true description: The transaction ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: category: type: string coaKey: type: string minLength: 1 description: Chart-of-accounts key customerId: type: string minLength: 1 description: Partner-facing external identifier finalize: type: boolean vendorId: type: string minLength: 1 description: Partner-facing external identifier document: type: object properties: documentType: type: string enum: - Receipt - Bill - Invoice fileName: type: string minLength: 1 contentType: type: string minLength: 1 base64File: type: string minLength: 1 nativeDocumentId: type: string minLength: 1 required: - documentType - fileName - contentType - base64File - nativeDocumentId responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier required: - id /company/{id}/transactions/{transactionId}/document: post: operationId: createTransactionDocument summary: Create Document description: |- Create a document for a given transaction. Required scope: write:transaction tags: - Transactions parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: transactionId in: path required: true description: The transaction ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: documentType: type: string enum: - Receipt - Bill - Invoice fileName: type: string minLength: 1 contentType: type: string minLength: 1 base64File: type: string minLength: 1 nativeDocumentId: type: string minLength: 1 required: - documentType - fileName - contentType - base64File - nativeDocumentId responses: '200': description: OK content: application/json: schema: type: object properties: transactionId: type: string minLength: 1 description: Partner-facing external identifier nullable: true manualJournalEntryId: type: string minLength: 1 description: Partner-facing external identifier nullable: true journalEntryId: type: string minLength: 1 description: Partner-facing external identifier nullable: true billId: type: string minLength: 1 description: Partner-facing external identifier nullable: true invoiceId: type: string minLength: 1 description: Partner-facing external identifier nullable: true document: type: object properties: id: type: string documentType: type: string enum: - Receipt - Bill - Invoice contentType: type: string downloadInfo: type: object properties: signedUrl: type: string urlExpiresAt: type: string minLength: 1 description: ISO 8601 timestamp required: - signedUrl - urlExpiresAt required: - id - documentType - contentType - downloadInfo required: - transactionId - manualJournalEntryId - journalEntryId - billId - invoiceId - document /company/{id}/documents/{entityId}: get: operationId: documentApi summary: Get Documents for Entity description: >- 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 tags: - Documents parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: entityId in: path required: true description: >- The entity ID (e.g., bil_xxx for bills, txn_xxx for transactions, inv_xxx for invoices, mje_xxx for manual journal entries) schema: type: string minLength: 1 description: Partner-facing external identifier responses: '200': description: OK content: application/json: schema: type: object properties: documents: type: array items: type: object properties: id: type: string documentType: type: string enum: - Receipt - Bill - Invoice contentType: type: string downloadInfo: type: object properties: signedUrl: type: string urlExpiresAt: type: string minLength: 1 description: ISO 8601 timestamp required: - signedUrl - urlExpiresAt required: - id - documentType - contentType - downloadInfo required: - documents post: operationId: createDocument summary: Create Attachment for Entity description: >- 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 tags: - Attachments parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: entityId in: path required: true description: >- The entity ID (e.g., bil_xxx for bills, txn_xxx for transactions, inv_xxx for invoices, je_xxx for journal entries, mje_xxx for manual journal entries) schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: documentType: type: string enum: - Receipt - Bill - Invoice fileName: type: string minLength: 1 contentType: type: string minLength: 1 base64File: type: string minLength: 1 nativeDocumentId: type: string minLength: 1 required: - documentType - fileName - contentType - base64File - nativeDocumentId responses: '200': description: OK content: application/json: schema: type: object properties: transactionId: type: string minLength: 1 description: Partner-facing external identifier nullable: true manualJournalEntryId: type: string minLength: 1 description: Partner-facing external identifier nullable: true journalEntryId: type: string minLength: 1 description: Partner-facing external identifier nullable: true billId: type: string minLength: 1 description: Partner-facing external identifier nullable: true invoiceId: type: string minLength: 1 description: Partner-facing external identifier nullable: true document: type: object properties: id: type: string documentType: type: string enum: - Receipt - Bill - Invoice contentType: type: string downloadInfo: type: object properties: signedUrl: type: string urlExpiresAt: type: string minLength: 1 description: ISO 8601 timestamp required: - signedUrl - urlExpiresAt required: - id - documentType - contentType - downloadInfo required: - transactionId - manualJournalEntryId - journalEntryId - billId - invoiceId - document /company/{id}/departments: get: operationId: departments summary: Get Departments description: |- Retrieves a list of all departments for the given company. Requires scope: read:company tags: - Departments parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier responses: '200': description: OK content: application/json: schema: type: object properties: departments: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier name: type: string required: - id - name required: - departments post: operationId: createDepartment summary: Create Department description: >- 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 tags: - Departments parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 required: - name responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier name: type: string required: - id - name /company/{id}/locations: get: operationId: locations summary: Get Locations description: |- Retrieves a list of all locations for the given company. Requires scope: read:company tags: - Locations parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier responses: '200': description: OK content: application/json: schema: type: object properties: locations: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier city: type: string state: type: string zipCode: type: string required: - id - city - state - zipCode required: - locations post: operationId: createLocation summary: Create Location description: >- 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 tags: - Locations parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: city: type: string minLength: 1 state: type: string minLength: 1 zipCode: type: string minLength: 1 required: - city - state - zipCode responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier city: type: string state: type: string zipCode: type: string required: - id - city - state - zipCode /company/{id}/contractors: post: operationId: createContractor summary: Create Contractor description: |- Create a contractor for the given company. Requires scope: write:worker tags: - Payroll parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: firstName: type: string lastName: type: string businessName: type: string nullable: true startDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD type: type: string enum: - Individual - Business payRate: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency wageType: type: string enum: - Fixed - Hourly - Daily - Weekly - Monthly - Biweekly - Semimonthly - Annually - Custom isActive: type: boolean departmentId: type: string minLength: 1 description: Partner-facing external identifier nativeId: type: string required: - firstName - lastName - startDate - type - payRate - wageType - isActive - nativeId responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier firstName: type: string nullable: true lastName: type: string nullable: true businessName: type: string nullable: true startDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD department: type: string nullable: true hourlyRate: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string nullable: true isActive: type: boolean type: type: string enum: - Individual - Business nullable: true wageType: type: string enum: - Fixed - Hourly - Daily - Weekly - Monthly - Biweekly - Semimonthly - Annually - Custom payRate: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string required: - id - firstName - lastName - businessName - startDate - department - hourlyRate - isActive - type - wageType - payRate /company/{id}/employees: post: operationId: createEmployee summary: Create Employee description: |- Create an employee for the given company. Required scope: write:worker tags: - Payroll parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: firstName: type: string lastName: type: string employmentType: type: string enum: - FullTime - PartTime - Contractor jobTitle: type: string startDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD officeLocationId: type: string minLength: 1 description: Partner-facing external identifier payRate: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency payFrequency: type: string enum: - Hour - Day - Week - Month - Year - Paycheck nativeId: type: string terminationDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD flsaStatus: type: string enum: - Exempt - SalariedNonexempt - Nonexempt - Owner departmentId: type: string minLength: 1 description: Partner-facing external identifier required: - firstName - lastName - employmentType - jobTitle - startDate - officeLocationId - payRate - payFrequency - nativeId responses: '200': description: OK content: application/json: schema: type: object properties: annualCosts: type: object properties: salaryCost: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency burdenCost: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency fullyLoadedCost: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency required: - salaryCost - burdenCost - fullyLoadedCost nullable: true id: type: string minLength: 1 description: Partner-facing external identifier firstName: type: string nullable: true lastName: type: string nullable: true employmentType: type: string enum: - FullTime - PartTime - Contractor jobTitle: type: string department: type: string nullable: true startDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD employeeTerminations: type: array items: type: object properties: terminationDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD required: - terminationDate flsaStatus: type: string enum: - Exempt - SalariedNonexempt - Nonexempt - Owner nullable: true officeLocation: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier city: type: string state: type: string zipCode: type: string required: - id - city - state - zipCode payFrequency: type: string enum: - Hour - Day - Week - Month - Year - Paycheck - Unknown payRate: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string terminated: type: boolean required: - annualCosts - id - firstName - lastName - employmentType - jobTitle - department - startDate - employeeTerminations - flsaStatus - officeLocation - payFrequency - payRate - terminated /company/{id}/benefits: get: operationId: benefits summary: Get Benefits description: >- 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 tags: - Payroll parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier responses: '200': description: OK content: application/json: schema: type: object properties: benefits: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier nativeId: type: string nullable: true name: type: string description: type: string type: type: string enum: - medical - dental - vision - retirement - commuter - disability - life_insurance - other_non_taxable - other_taxable - unknown_benefit - student_loan isPreTax: type: boolean dataSource: type: string required: - id - nativeId - name - description - type - isPreTax - dataSource required: - benefits post: operationId: createBenefit summary: Create Benefit description: |- Create a benefit for the given company. Requires scope: write:benefit tags: - Payroll parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: nativeId: type: string name: type: string description: type: string type: type: string enum: - medical - dental - vision - retirement - commuter - disability - life_insurance - other_non_taxable - other_taxable - unknown_benefit - student_loan description: >- The value is normalized before matching, so any casing that maps onto a listed value is accepted. isPreTax: type: boolean required: - nativeId - name - description - type - isPreTax responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier nativeId: type: string nullable: true name: type: string description: type: string type: type: string enum: - medical - dental - vision - retirement - commuter - disability - life_insurance - other_non_taxable - other_taxable - unknown_benefit - student_loan isPreTax: type: boolean dataSource: type: string required: - id - nativeId - name - description - type - isPreTax - dataSource /company/{id}/payrolls: post: operationId: createDetailedPayroll summary: Create Payroll description: >- 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 tags: - Payroll parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: accountId: type: string minLength: 1 description: Partner-facing external identifier nativeId: type: string withdrawalDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD checkDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD companyDebit: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency transactionAmounts: type: array items: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency netPay: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency reimbursements: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency employerTaxes: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency employeeTaxes: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency employerBenefits: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency employeeBenefitsDeductions: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency isOffCycle: type: boolean employeeCompensations: type: array items: type: object properties: employeeId: type: string minLength: 1 description: Partner-facing external identifier grossPay: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency netPay: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency reimbursements: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency employeeTaxes: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency employerTaxes: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency deductions: type: array items: type: object properties: name: type: string amount: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency isPreTax: type: boolean required: - name - amount - isPreTax benefits: type: array items: type: object properties: benefitId: type: string minLength: 1 description: Partner-facing external identifier employeeDeduction: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency companyContribution: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency isImputed: type: boolean required: - benefitId - employeeDeduction - companyContribution - isImputed paymentMethod: type: string enum: - Check - DirectDeposit - HistoricalPayment - Correction required: - employeeId - grossPay - netPay - reimbursements - employeeTaxes - employerTaxes - deductions - benefits - paymentMethod contractorCompensations: type: array items: type: object properties: contractorId: type: string minLength: 1 description: Partner-facing external identifier totalAmount: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency bonus: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency reimbursements: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency paymentMethod: type: string enum: - Check - DirectDeposit - HistoricalPayment - Correction required: - contractorId - totalAmount - bonus - reimbursements payPeriod: type: object properties: fromInclusive: type: string minLength: 1 description: Calendar date, YYYY-MM-DD toInclusive: type: string minLength: 1 description: Calendar date, YYYY-MM-DD required: - fromInclusive - toInclusive deferredPayrollTaxes: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency payrollFees: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency required: - accountId - nativeId - withdrawalDate - checkDate - companyDebit - transactionAmounts - netPay - reimbursements - employerTaxes - employeeTaxes - employerBenefits - employeeBenefitsDeductions - isOffCycle - employeeCompensations - contractorCompensations responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier accountId: type: string minLength: 1 description: Partner-facing external identifier nativeId: type: string nullable: true payPeriod: type: object properties: fromInclusive: type: string minLength: 1 description: Calendar date, YYYY-MM-DD toInclusive: type: string minLength: 1 description: Calendar date, YYYY-MM-DD required: - fromInclusive - toInclusive nullable: true withdrawalDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD checkDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD companyDebit: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency transactionAmounts: type: array items: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency nullable: true netPay: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency reimbursements: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency employerTaxes: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency employeeTaxes: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency employerBenefits: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency employeeBenefitsDeductions: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency deferredPayrollTaxes: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency payrollFees: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency isOffCycle: type: boolean employeeCompensations: type: array items: type: object properties: employeeId: type: string minLength: 1 description: Partner-facing external identifier grossPay: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency netPay: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency reimbursements: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency employeeTaxes: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency employerTaxes: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency deductions: type: array items: type: object properties: name: type: string amount: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency isPreTax: type: boolean required: - name - amount - isPreTax benefits: type: array items: type: object properties: benefitId: type: string minLength: 1 description: Partner-facing external identifier employeeDeduction: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency companyContribution: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency isImputed: type: boolean required: - benefitId - employeeDeduction - companyContribution - isImputed paymentMethod: type: string enum: - Check - DirectDeposit - HistoricalPayment - Correction required: - employeeId - grossPay - netPay - reimbursements - employeeTaxes - employerTaxes - deductions - benefits - paymentMethod contractorCompensations: type: array items: type: object properties: contractorId: type: string minLength: 1 description: Partner-facing external identifier totalAmount: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency bonus: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency reimbursements: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency paymentMethod: type: string enum: - Check - DirectDeposit - HistoricalPayment - Correction nullable: true required: - contractorId - totalAmount - bonus - reimbursements - paymentMethod required: - id - accountId - nativeId - payPeriod - withdrawalDate - checkDate - companyDebit - transactionAmounts - netPay - reimbursements - employerTaxes - employeeTaxes - employerBenefits - employeeBenefitsDeductions - deferredPayrollTaxes - payrollFees - isOffCycle - employeeCompensations - contractorCompensations /company/{id}/payrolls/{payrollId}: get: operationId: getPayroll summary: Get Payroll description: |- Get a single payroll by ID Required scope: read:company tags: - Payroll parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: payrollId in: path required: true description: The payroll ID schema: type: string minLength: 1 description: Partner-facing external identifier responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier accountId: type: string minLength: 1 description: Partner-facing external identifier nativeId: type: string nullable: true payPeriod: type: object properties: fromInclusive: type: string minLength: 1 description: Calendar date, YYYY-MM-DD toInclusive: type: string minLength: 1 description: Calendar date, YYYY-MM-DD required: - fromInclusive - toInclusive nullable: true withdrawalDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD checkDate: type: string minLength: 1 description: Calendar date, YYYY-MM-DD companyDebit: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency transactionAmounts: type: array items: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency nullable: true netPay: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency reimbursements: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency employerTaxes: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency employeeTaxes: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency employerBenefits: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency employeeBenefitsDeductions: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency deferredPayrollTaxes: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency payrollFees: type: object properties: amount: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency isOffCycle: type: boolean employeeCompensations: type: array items: type: object properties: employeeId: type: string minLength: 1 description: Partner-facing external identifier grossPay: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency netPay: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency reimbursements: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency employeeTaxes: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency employerTaxes: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency deductions: type: array items: type: object properties: name: type: string amount: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency isPreTax: type: boolean required: - name - amount - isPreTax benefits: type: array items: type: object properties: benefitId: type: string minLength: 1 description: Partner-facing external identifier employeeDeduction: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency companyContribution: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency isImputed: type: boolean required: - benefitId - employeeDeduction - companyContribution - isImputed paymentMethod: type: string enum: - Check - DirectDeposit - HistoricalPayment - Correction required: - employeeId - grossPay - netPay - reimbursements - employeeTaxes - employerTaxes - deductions - benefits - paymentMethod contractorCompensations: type: array items: type: object properties: contractorId: type: string minLength: 1 description: Partner-facing external identifier totalAmount: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency bonus: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency reimbursements: type: object properties: amount: type: string minLength: 1 description: >- Arbitrary-precision decimal, serialized as a string currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code required: - amount - currency description: A monetary amount with its currency paymentMethod: type: string enum: - Check - DirectDeposit - HistoricalPayment - Correction nullable: true required: - contractorId - totalAmount - bonus - reimbursements - paymentMethod required: - id - accountId - nativeId - payPeriod - withdrawalDate - checkDate - companyDebit - transactionAmounts - netPay - reimbursements - employerTaxes - employeeTaxes - employerBenefits - employeeBenefitsDeductions - deferredPayrollTaxes - payrollFees - isOffCycle - employeeCompensations - contractorCompensations /company/{id}/trial-balance: get: operationId: ledgerReportDownload summary: Get Trial Balance Report description: >- 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 tags: - Company parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: type in: query required: false schema: type: string enum: - TrialBalance - FsTrialBalance - name: viewBy in: query required: false schema: type: string enum: - Total - Year - Quarter - Month - Departments - name: startPeriod in: query required: false schema: type: string minLength: 1 - name: endPeriod in: query required: false schema: type: string minLength: 1 - name: dateMacro in: query required: false schema: type: string enum: - CurrentMonth - LastFullMonth - LastThreeMonths - LastThreeFullMonths - CurrentYear - LastYear - QuarterToDate - YearToDate - name: level in: query required: false schema: type: string enum: - Compact - Summary - Detailed - name: basis in: query required: false schema: type: string enum: - cash - accrual - name: highWatermarkToken in: query required: false schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: title: type: string columns: type: array items: type: string rows: type: array items: type: array items: type: string required: - title - columns - rows /onboarding: post: operationId: initiatePrefilledOnboarding summary: Initiate Prefilled Onboarding description: >- 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. tags: - Onboarding requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 type: type: string enum: - SAAS - ECOMMERCE - MARKETPLACE - ADVERTISING - SERVICES - ENTERPRISE - FINTECH - FINTECH_CRYPTO - VIRTUAL_GOODS - CONSUMER - NOT_SURE - OTHER - AGRICULTURE_AND_FARMING - CONSTRUCTION - HEALTHCARE - HOME_SERVICES - LEGAL - MANUFACTURING - MEDIA_AND_ENTERTAINMENT - PROFESSIONAL_SERVICES - RETAIL - REAL_ESTATE - RESTAURANT - TRANSPORTATION - WHOLESALE_TRADE description: >- The value is normalized before matching, so any casing that maps onto a listed value is accepted. timeZone: type: string minLength: 1 currentUserRole: type: string enum: - Founder - CompanyEmployee - OutsourcedAccountantOrCFO orgType: type: string enum: - CCorporation - LLC - Partnership - SCorporation - SoleProprietorship revenueModel: type: string enum: - AnnualSubscription - MonthlySubscription - MultipleRevenueModels - NotSure - PreRevenue - ServiceBased - TransactionBased - UsageBased - Subscription - AddOns - TransactionBasedPhysical - TransactionBasedOther - Contracts - HourlyBilling - Marketplace - Commission hasHistoricalData: type: boolean phoneNumber: type: string connectionInfo: type: object properties: nativeCompanyId: type: string minLength: 1 authForwardToken: type: string createPushIntegrationConnection: type: boolean required: - nativeCompanyId required: - name - type - timeZone - currentUserRole - orgType responses: '200': description: OK content: application/json: schema: type: object properties: url: type: string required: - url /company/{id}/close-progress: get: operationId: closeProgress summary: Get Close Progress description: >- Returns monthly and AI close checklist progress separately for the given company, month, and accounting basis. Includes account references, assigned preparer and approver, and completion attribution where recorded. Period lock status is independent of checklist completion. Sources overlap and their counts must not be summed. Required scope: read:company tags: - Company parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: month in: query required: true schema: type: string pattern: ^\d{4}-(0[1-9]|1[0-2])$ - name: basis in: query required: true schema: type: string enum: - cash - accrual responses: '200': description: OK content: application/json: schema: type: object properties: companyId: type: string minLength: 1 description: Partner-facing external identifier month: type: string pattern: ^\d{4}-(0[1-9]|1[0-2])$ basis: type: string enum: - cash - accrual availability: type: string enum: - Available - Empty - Unavailable sources: type: array items: type: object properties: source: type: string enum: - Monthly - AiClose availability: type: string enum: - Available - Empty - Unavailable progress: type: object properties: total: type: integer minimum: 0 completed: type: integer minimum: 0 outstanding: type: integer minimum: 0 required: - total - completed - outstanding nullable: true reconciliations: type: object properties: total: type: integer minimum: 0 completed: type: integer minimum: 0 outstanding: type: integer minimum: 0 required: - total - completed - outstanding nullable: true items: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier source: type: string enum: - Monthly - AiClose parentId: type: string minLength: 1 description: Partner-facing external identifier nullable: true key: type: string nullable: true description: type: string nullable: true status: type: string enum: - Complete - Incomplete - SystemComplete - ToDo - InProgress - NeedsAction - WaitingOnClient - ReadyForReview - Done account: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier name: type: string nullable: true mask: type: string nullable: true required: - id - name - mask nullable: true preparer: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier name: type: string nullable: true email: type: string nullable: true required: - id - name - email nullable: true approver: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier name: type: string nullable: true email: type: string nullable: true required: - id - name - email nullable: true completedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true completedBy: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier name: type: string nullable: true email: type: string nullable: true required: - id - name - email nullable: true required: - id - source - parentId - key - description - status - account - preparer - approver - completedAt - completedBy nullable: true required: - source - availability - progress - reconciliations - items periodLock: type: object properties: status: type: string enum: - Locked - Unlocked - Pending - Unavailable lockedThrough: type: string pattern: ^\d{4}-(0[1-9]|1[0-2])$ nullable: true required: - status - lockedThrough required: - companyId - month - basis - availability - sources - periodLock /company/{id}/monthly-checklists: get: operationId: monthlyChecklists summary: Get Monthly Checklist description: >- This endpoint retrieves the monthly checklist for the given company and month. Required scope: read:company tags: - Company parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: month in: query required: true schema: type: string minLength: 1 responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string items: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier status: type: string enum: - Complete - Incomplete - SystemComplete completedAt: type: string minLength: 1 description: ISO 8601 timestamp nullable: true completedBy: type: string minLength: 1 description: Partner-facing external identifier nullable: true modifiedBy: type: string minLength: 1 description: Partner-facing external identifier nullable: true removedBy: type: string minLength: 1 description: Partner-facing external identifier nullable: true key: type: string enum: - account - review_new_vendors - review_locked_period - progress_transactions_finalized - progress_transactions_categorized - statement_balance_sheet - statement_profit_and_loss - bank_transfer_balance - credit_card_payment_balance - payroll_clearing_balance - investment_amounts - loan_amounts - uncategorized_expense_amounts - uncategorized_revenue_amounts - uncategorized_reimbursement_amounts - fixed_asset_amounts - custom month: type: string description: type: string nullable: true supplementalInfo: type: string nullable: true progress: type: integer nullable: true order: type: integer nullable: true required: - id - status - completedAt - completedBy - modifiedBy - removedBy - key - month - description - supplementalInfo - progress - order month: type: string required: - id - items - month /company/{id}/products: get: operationId: productsApi summary: Get Products description: |- Retrieves a list of all of the company's products. Required scope: read:company tags: - Products parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: name in: query required: false schema: type: string - name: serviceType in: query required: false schema: type: string enum: - Inventory - NonInventory - Service - name: status in: query required: false schema: type: string enum: - Active - Inactive - name: sortBy in: query required: false schema: type: string enum: - INSERT_ORDER_DESC - INSERT_ORDER_ASC - NAME_ASC - NAME_DESC - name: count in: query required: false schema: type: integer - name: after in: query required: false schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier name: type: string nullable: true serviceType: type: string enum: - Inventory - NonInventory - Service nullable: true status: type: string enum: - Active - Inactive nullable: true sku: type: string nullable: true description: type: string nullable: true priceRate: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string nullable: true required: - id - name - serviceType - status - sku - description - priceRate pageInfo: type: object properties: endCursor: type: string nullable: true hasNextPage: type: boolean total: type: integer nullable: true required: - endCursor - hasNextPage - total required: - items - pageInfo post: operationId: createProductApi summary: Create Product description: |- Create a product for the given company. Requires scope: write:product tags: - Products parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: name: type: string serviceType: type: string enum: - Inventory - NonInventory - Service status: type: string enum: - Active - Inactive sku: type: string description: type: string priceRate: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string required: - name responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier name: type: string nullable: true serviceType: type: string enum: - Inventory - NonInventory - Service nullable: true status: type: string enum: - Active - Inactive nullable: true sku: type: string nullable: true description: type: string nullable: true priceRate: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string nullable: true required: - id - name - serviceType - status - sku - description - priceRate /company/{id}/products/{productId}: get: operationId: productApi summary: Get Product description: |- Get a single product by ID for the company. Required scope: read:company tags: - Products parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: productId in: path required: true description: The product ID schema: type: string minLength: 1 description: Partner-facing external identifier responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier name: type: string nullable: true serviceType: type: string enum: - Inventory - NonInventory - Service nullable: true status: type: string enum: - Active - Inactive nullable: true sku: type: string nullable: true description: type: string nullable: true priceRate: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string nullable: true required: - id - name - serviceType - status - sku - description - priceRate patch: operationId: updateProductApi summary: Update Product description: |- Update a product for the given company. Requires scope: write:product tags: - Products parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: productId in: path required: true description: The product ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: name: type: string serviceType: type: string enum: - Inventory - NonInventory - Service status: type: string enum: - Active - Inactive sku: type: string description: type: string priceRate: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier name: type: string nullable: true serviceType: type: string enum: - Inventory - NonInventory - Service nullable: true status: type: string enum: - Active - Inactive nullable: true sku: type: string nullable: true description: type: string nullable: true priceRate: type: string minLength: 1 description: Arbitrary-precision decimal, serialized as a string nullable: true required: - id - name - serviceType - status - sku - description - priceRate /company/{id}/tasks: get: operationId: tasks summary: Get Tasks description: >- 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 tags: - Tasks parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: status in: query required: false schema: anyOf: - type: string - type: array items: type: string - name: type in: query required: false schema: anyOf: - type: string - type: array items: type: string - name: assigneeIds in: query required: false schema: anyOf: - type: string minLength: 1 description: Partner-facing external identifier - type: array items: type: string minLength: 1 description: Partner-facing external identifier - name: transactionIds in: query required: false schema: anyOf: - type: string minLength: 1 description: Partner-facing external identifier - type: array items: type: string minLength: 1 description: Partner-facing external identifier - name: createdBy in: query required: false schema: type: string minLength: 1 description: Partner-facing external identifier - name: createdAfter in: query required: false schema: type: string minLength: 1 description: ISO 8601 timestamp - name: count in: query required: false schema: type: integer - name: after in: query required: false schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier companyId: type: string minLength: 1 description: Partner-facing external identifier type: type: string enum: - CategoryReview - Documentation - Message status: type: string enum: - Open - Completed - Cancelled transactionId: type: string minLength: 1 description: Partner-facing external identifier nullable: true createdBy: type: string minLength: 1 description: Partner-facing external identifier nullable: true modifiedBy: type: string minLength: 1 description: Partner-facing external identifier nullable: true assignees: type: array items: type: string minLength: 1 description: Partner-facing external identifier nullable: true text: type: string nullable: true required: - id - companyId - type - status - transactionId - createdBy - modifiedBy - assignees - text pageInfo: type: object properties: endCursor: type: string nullable: true hasNextPage: type: boolean total: type: integer nullable: true required: - endCursor - hasNextPage - total required: - items - pageInfo post: operationId: createTask summary: Create Task description: |- 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 tags: - Tasks parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: type: type: string enum: - CategoryReview - Documentation - Message transactionId: type: string minLength: 1 description: Partner-facing external identifier assignees: type: array items: type: string minLength: 1 description: Partner-facing external identifier text: type: string required: - type - transactionId responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier companyId: type: string minLength: 1 description: Partner-facing external identifier type: type: string enum: - CategoryReview - Documentation - Message status: type: string enum: - Open - Completed - Cancelled transactionId: type: string minLength: 1 description: Partner-facing external identifier nullable: true createdBy: type: string minLength: 1 description: Partner-facing external identifier nullable: true modifiedBy: type: string minLength: 1 description: Partner-facing external identifier nullable: true assignees: type: array items: type: string minLength: 1 description: Partner-facing external identifier nullable: true text: type: string nullable: true createdAt: type: string minLength: 1 description: ISO 8601 timestamp updatedAt: type: string minLength: 1 description: ISO 8601 timestamp required: - id - companyId - type - status - transactionId - createdBy - modifiedBy - assignees - text - createdAt - updatedAt /company/{id}/tasks/{taskId}: patch: operationId: updateTask summary: Update Task description: |- 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 tags: - Tasks parameters: - name: id in: path required: true description: The company ID schema: type: string minLength: 1 description: Partner-facing external identifier - name: taskId in: path required: true description: The task ID schema: type: string minLength: 1 description: Partner-facing external identifier requestBody: required: true content: application/json: schema: type: object properties: status: type: string enum: - Open - Completed - Cancelled assignees: type: array items: type: string minLength: 1 description: Partner-facing external identifier text: type: string responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Partner-facing external identifier companyId: type: string minLength: 1 description: Partner-facing external identifier type: type: string enum: - CategoryReview - Documentation - Message status: type: string enum: - Open - Completed - Cancelled transactionId: type: string minLength: 1 description: Partner-facing external identifier nullable: true createdBy: type: string minLength: 1 description: Partner-facing external identifier nullable: true modifiedBy: type: string minLength: 1 description: Partner-facing external identifier nullable: true assignees: type: array items: type: string minLength: 1 description: Partner-facing external identifier nullable: true text: type: string nullable: true required: - id - companyId - type - status - transactionId - createdBy - modifiedBy - assignees - text /oauth/authorize: get: tags: - OAuth summary: Authorize (OAuth 2.0 + PKCE) description: >- 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. operationId: oauthAuthorize parameters: - name: response_type in: query required: true description: Must be `code` for the Authorization Code flow. schema: type: string enum: - code - name: client_id in: query required: true description: The client identifier issued to the app. schema: type: string - name: redirect_uri in: query required: false description: >- One of the app's registered redirect URIs. REQUIRED if it was included during the initial authorization request registration. schema: type: string format: uri - name: scope in: query required: false description: Space-delimited scopes being requested. schema: type: string example: read:company write:company - name: state in: query required: false description: >- Opaque value to maintain state between the request and callback. Returned unchanged to the `redirect_uri`. schema: type: string - name: code_challenge in: query required: false description: >- PKCE code challenge derived from the `code_verifier`. REQUIRED for public clients and recommended for all clients. schema: type: string - name: code_challenge_method in: query required: false description: The method used to derive `code_challenge` (recommended `S256`). schema: type: string enum: - S256 - plain default: S256 responses: '302': description: >- Redirect to the client's `redirect_uri`. On success includes `code` (and `state` if provided) as query parameters. headers: Location: description: Redirect URI with authorization response params. schema: type: string format: uri example: https://app.example.com/callback?code=abc123&state=xyz '400': description: Invalid request (e.g., missing/invalid parameters). '401': description: Client is unauthorized for this request. '500': description: Server error /oauth/token: post: tags: - OAuth summary: Get Token (OAuth 2.0) description: >- 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. operationId: oauthGetToken requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object oneOf: - required: - grant_type - code - redirect_uri properties: grant_type: type: string enum: - authorization_code code: type: string description: Authorization code from /authorize. redirect_uri: type: string format: uri description: Must exactly match the redirect URI used at /authorize. code_verifier: type: string description: >- Required if a code_challenge was used at /authorize (PKCE). - required: - grant_type - refresh_token properties: grant_type: type: string enum: - refresh_token refresh_token: type: string description: Refresh token previously issued by this endpoint. properties: client_id: type: string description: >- Client identifier (required for public clients or when not using HTTP Basic). client_secret: type: string description: >- Client secret (confidential clients; omit when using HTTP Basic or for public clients). examples: authCode: summary: Exchange authorization code value: grant_type: authorization_code code: abc123 redirect_uri: https://app.example.com/callback code_verifier: rAnd0mlyGen3ratedString refresh: summary: Use refresh token value: grant_type: refresh_token refresh_token: r1fR3shTok3n responses: '200': description: Successful token response content: application/json: schema: type: object required: - access_token - token_type properties: access_token: type: string description: OAuth 2.0 access token. token_type: type: string description: Typically "Bearer". example: Bearer expires_in: type: integer description: Lifetime of the access token in seconds. refresh_token: type: string description: May be returned to obtain new access tokens. scope: type: string description: Space-delimited scopes granted. examples: success: summary: Example success value: access_token: eyJhbGciOi... token_type: Bearer expires_in: 3600 refresh_token: r1fR3shTok3n scope: read:company write:company '400': description: >- Invalid request/parameters (e.g., missing grant_type, bad code, or PKCE failure) content: application/json: schema: type: object required: - error properties: error: type: string description: >- One of: invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type, invalid_scope. error_description: type: string error_uri: type: string format: uri '401': description: Client authentication failed (confidential client) '500': description: Server error components: schemas: InteropReportRow: type: object properties: type: type: string nullable: true group: type: string nullable: true Header: type: object properties: ColData: type: array items: type: object properties: value: type: string id: type: string nullable: true required: - value - id required: - ColData nullable: true Summary: type: object properties: ColData: type: array items: type: object properties: value: type: string id: type: string nullable: true required: - value - id required: - ColData nullable: true ColData: type: array items: type: object properties: value: type: string id: type: string nullable: true required: - value - id nullable: true Rows: type: object properties: Row: type: array items: $ref: '#/components/schemas/InteropReportRow' required: - Row nullable: true required: - type - group - Header - Summary - ColData