{ "openapi": "3.0.3", "info": { "title": "Puzzle Api", "description": "Puzzle Api", "version": "0" }, "servers": [ { "url": "https://staging.southparkdata.com/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" ] } } } } } } }, "/companies": { "get": { "operationId": "companiesApi", "summary": "Get companies", "description": "Returns a list of companies the calling user has access to.\n\nRequired scope: read:company", "tags": [ "Company" ], "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" } }, "required": [ "id", "name", "connectedAt", "status", "financialYearStartDate", "reportingCurrency" ] } } }, "required": [ "companies" ] } } } } } } }, "/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.\n\nThe 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.\n\nThe type of data that can be added to an account depends on the account type.\n\nRequired 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", "PaymentProcessing", "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.\n\nRequired 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.\n\nNote that Puzzle stores all account balances trending towards positive, regardless of account type. Additional details can be found here.\n\nRequired 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.\n\nIf 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.\n\nNote that Puzzle stores all account balances trending towards positive, regardless of account type. Additional details can be found here.\n\nIf any of the company accounts are currently syncing or processing, this endpoint will return a 409 error.\n\nYou 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.\n\nRequired 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.\n\nBy default, the balances on the account are calculated using cash basis.\n\nRequired 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.\n\nRequired 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.\n\nRequired 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.\n\nRequired 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.\n\nRequired 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.\n\nRequired 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.\n\nRequired 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.\n\nRequired 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" }, "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.\n\nRequired 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" }, "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.\n\nRequired 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" }, "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.\n\nRequired 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" }, "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.\n\nRequired 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.\n\nRequired 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.\n\nRequired 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.\n\nRequired 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.\n\nRequired 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.\n\nRequired 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.\n\nRequired 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.\n\nRequired 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.\n\nRequired 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.\n\nRequired 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.\n\nThis endpoint returns income statement data broken down by the specified time interval (month, quarter, or year). You can filter results by departments and locations.\n\nRequired 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" } } ] } }, { "name": "locations", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, { "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.\n\nThis 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.\n\nRequired 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" } } ] } } ], "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.\n\nThis endpoint returns balance sheet statement data broken down by the specified time interval (month, quarter, or year).\n\nRequired 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.\n\nThis 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.\n\nRequired 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" } } ] } } ], "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.\n\nThis endpoint returns cash activity statement data broken down by the specified time interval (month, quarter, or year). \n\nRequired 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\n\nCurrently only the 'month' interval is supported, but will soon support 'quarter' and 'year'.\n\nThe array of metrics will be returned in ascending order from earliest time interval to latest.\n\nRequired 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.\n\nRequired 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" } }, "required": [ "timePeriod", "dataCompletenessLevel", "percentDollarVolumeCategorized" ] } } }, "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.\n\nCurrently only the 'month' interval is supported, but will soon support 'quarter' and 'year'.\n\nThe array of metrics will be returned in ascending order from earliest time interval to latest.\n\nRequired 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.\n\nCurrently only the 'month' interval is supported, but will soon support 'quarter' and 'year'.\n\nThe array of metrics will be returned in ascending order from earliest time interval to latest.\n\nRequired 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.\n\nRequired 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.\n\nBy default, all accounts are returned and the balances are calculated using cash basis.\n\nRequired 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.\n\nOnly 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.\n\nRequires 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.\n\nRequires 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.\n\nRequires 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.\n\nRequired 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" ] }, "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\n\nJournal 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.\n\nCreate Journal Entries endpoint creates a Journal Entry into our Gateway and not on our Ledger. Once the Gateway receives a Journal Entry, you get an OK response. Ledger Journal Entries are created async and can be retrieved through the Get Journal Entries endpoint.\n\nPuzzle 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}}\".\n\nAll 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" ] }, "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\n\nJournal entries are the entries made in a company's ledger accounts as a way of recording financial impact.\n\nDelete 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": [ "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\n\nJournal 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.\n\nCreate Journal Entries endpoint creates a Journal Entry into our Gateway and not on our Ledger. Once the Gateway receives a Journal Entry, you get an OK response. Ledger Journal Entries are created async and can be retrieved through the Get Journal Entries endpoint.\n\nPuzzle 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}}\".\n\nAll 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": "object", "properties": { "entries": { "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" ] }, "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" ] } } }, "required": [ "entries" ] } } } }, "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.\n\nRequired 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\n\nRequired scope: read:company", "tags": [ "Transactions" ], "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", "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 }, "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", "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.\n\nYou can create up to 500 transactions per request\nTransactions can only be added to accounts with the following types: Depository, Credit, Investment, Loan, or PaymentProcessing\nTransactions 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.\npending = 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.\nduplicate = There is already a transaction with that same nativeId in the system, so this transaction data was ignored.\nThe sign on the amount field depends on the account type.\nAdditional details can be found here.\nThe 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.\n\nRequired 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" } }, "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\n\nRequired scope: read:company", "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" } } ], "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 }, "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", "vendorId", "customerId", "documents", "classifications" ] } } } } } }, "patch": { "operationId": "updateTransaction", "summary": "Update Transaction", "description": "Updates an existing Transaction\n\nRequired 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.\n\nRequired 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.\n\nSupported entity prefixes: bil_ (bills), inv_ (invoices), txn_ (transactions), mje_ (manual journal entries)\n\nRequired 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.\n\nSupported entity prefixes: bil_ (bills), inv_ (invoices), txn_ (transactions), je_ (journal entries), mje_ (manual journal entries)\n\nRequired 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.\n\nRequires 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.\n\nDepartments must have a unique name. A 400 error will be thrown if a department with the same name already exists.\n\nRequires 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.\n\nRequires 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.\n\nLocations must be unique. A 400 error will be thrown if a location with the same city, state, and zip code already exists.\n\nRequires 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.\n\nRequires 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.\n\nRequired 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" ] }, "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.\n\nPayrolls will reference these benefits and provide details on the employee and company contribution amounts.\n\nRequires 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.\n\nRequires 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.\n\nPayrolls can only be added to accounts with the Payroll type.\nAll the amounts on the top-level payroll object are the totals for all the associated compensations\nPayrolls must have at least one employeeCompensation OR contractorCompensation\nThe transactionAmounts field should contain a list of all the amounts for all the non-reimbursement transactions that were used to fund this payroll.\nIf no transactionAmounts are provided, the companyDebit amount will be used instead\nPuzzle uses this information to link this payroll with all the transactions that funded it to ensure everything gets represented in the general ledger correctly.\nPuzzle currently only supports USD currencies\n\nRequired 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\n\nRequired 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:\n\ndateMacro (a predefined date range)\nstartDate and endDate (a custom date range)\n\nIf all three are provided, dateMacro takes precedence.\n\nRequired 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}/monthly-checklists": { "get": { "operationId": "monthlyChecklists", "summary": "Get Monthly Checklist", "description": "This endpoint retrieves the monthly checklist for the given company and month.\n\nRequired 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 }, "order": { "type": "integer", "nullable": true } }, "required": [ "id", "status", "completedAt", "completedBy", "modifiedBy", "removedBy", "key", "month", "description", "supplementalInfo", "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.\n\nRequired 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.\n\nRequires 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.\n\nRequired 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.\n\nRequires 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\n\nRetrieves a list of tasks for the company. Tasks represent work items that need to be completed, such as categorization reviews, documentation requests, or messages.\n\nRequired 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\n\nClick here for more information.\n\nCreate a task for the given company.\n\nRequired 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\n\nClick here for more information.\n\nUpdate a task for the given company.\n\nRequired 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" ] } } } }