PayPolka

API and AI

You can connect AI assistants like Claude, ChatGPT, and Cursor, or your own scripts and automations, directly to your PayPolka account. Every connection acts as the person who made it and follows the same role and financial visibility rules as the web app.

Assistants like Claude connect by signing in to PayPolka in your browser. Scripts and tools that take a key use a personal access token. By default, both run in draft-safe mode. An assistant can log hours, record expenses, check unbilled work, and prepare draft estimates or invoices for you to review, without emailing a client or issuing a Stripe refund.

Create a personal access token

  1. Open your avatar menu in the top right and choose Profile.
  2. Scroll to API & AI access.
  3. Enter a Token name, such as Claude Desktop or Billing script, so you remember where it is used.
  4. If you are an owner or admin and want this token to be able to email estimates and invoices to clients or issue Stripe refunds, check Allow sending client emails & Stripe refunds. Leave it unchecked to keep the token in draft-safe mode.
  5. Enter your Current password. A token keeps working after you sign out, so PayPolka asks for your password before it creates one.
  6. Select Create API token.

Copy the pp_... token right away and store it in your password manager or tool configuration. PayPolka stores only a hashed copy of the token, so the full value is shown only once.

How permissions and guardrails work

A token acts as the person who created it and never grants extra access beyond their role:

  • Members can log and edit their own unlocked time and expenses, submit their week for approval, read and post project messages, and list active projects along with the labor and expense categories needed to log work. Hourly rates, budgets, client totals, estimates, invoices, and financial reports are omitted from every response.
  • Managers have the same access as members, plus the ability to view, approve, and send back submitted timesheets for the people assigned to them.
  • Accountants have read-only access to clients, projects, estimates, invoices, payments, and financial reports. Their tokens cannot create, edit, or delete records.
  • Owners and admins can read and manage clients, projects, time entries, expenses, estimates, invoices, payments, and reports across the account.

Even for an owner or admin, a token cannot send an estimate, send an invoice, or refund a Stripe payment unless Allow sending client emails & Stripe refunds was checked when the token was created. Without that setting, your assistant prepares the draft and you send it when you are ready. With it, keep in mind that sending a recurring invoice for a client on autopay also charges their saved card or bank account, the same as sending it yourself.

Limits that protect your account

An assistant can misread a request, so a few limits keep one bad instruction from doing much damage.

What an assistant can delete. No token can delete a client, a project, a teammate, or the account. An assistant can delete time entries and expenses that aren’t locked and that you could delete yourself, and draft invoices. Anything that has been invoiced, approved, sent, or paid stays put.

Ten deletes an hour. All of your tokens and connected apps share a limit of 10 deletes an hour. Once it’s reached, PayPolka refuses the next delete, keeps the record, and tells the assistant what time the next delete is allowed. Deleting in the web app has no limit, so if you’re cleaning up a large batch on purpose, do it there.

Every delete is on record. Each delete an assistant makes appears in Settings, Activity with who made it, what was deleted, and which token or app made the request. For example: Sam Lee, 2026-10-20, 1.5h on Kitchen Remodel (via Claude).

Fields it doesn’t recognize are refused. If an assistant sends a field PayPolka doesn’t take, such as a typo in a line item’s price, the request fails, nothing is saved, and the error names the field. A request that changed nothing can’t come back looking like a success.

Requests are rate limited. Each token can make 120 requests a minute across MCP and the REST API. Past that, PayPolka asks the assistant to wait until the minute is up.

PayPolka also marks each tool as read-only or as one that changes or deletes data. AI apps that use those marks can group the tools and ask you before running a destructive one. In claude.ai, check the tool permissions on the connector and keep deletes, write-offs, and payments set to ask first.

Connect an AI assistant with MCP

PayPolka includes a built-in Remote MCP (Model Context Protocol) server at:

https://app.paypolka.com/mcp

MCP lets your AI assistant see PayPolka’s tools and use them for you. Most assistants connect by sending you to PayPolka to sign in and approve the connection, so you never copy a token.

Connect Claude

  1. In claude.ai, open Settings, then Connectors, and choose Add custom connector.
  2. Enter a name, such as PayPolka, and the URL https://app.paypolka.com/mcp. Claude detects that PayPolka asks you to sign in and lets Claude register itself, so leave Sign in now and Register automatically selected. Select Add.
  3. Select Connect. Claude opens PayPolka in your browser. Sign in if you aren’t already.
  4. PayPolka shows a Connect page that names the app, your account, and the role it will act as. Enter your password and select Connect.
  5. Back in Claude, review the connector’s tool permissions. Reading is safe to allow. Keep deletes, write-offs, and payments set to ask you first.

If you’re an owner or admin, the Connect page also has Let it email clients and issue Stripe refunds. Leave it off and Claude drafts invoices and estimates while you click Send yourself.

Other assistants that add an MCP server by URL and send you to sign in work the same way: add the URL, sign in, and select Connect on PayPolka’s page.

A connected app keeps working as long as it’s used. If it sits unused for 60 days, connect it again. Changing or resetting your password, or signing out your other devices, disconnects every app and revokes every token.

Connect with a token

Some tools, like Cursor or your own scripts, take a server URL and an Authorization header instead. Create a personal access token, then enter https://app.paypolka.com/mcp and Bearer pp_YOUR_TOKEN.

If your MCP client uses a JSON configuration file with npx mcp-remote or native HTTP transport, add PayPolka under mcpServers:

{
  "mcpServers": {
    "paypolka": {
      "url": "https://app.paypolka.com/mcp",
      "headers": {
        "Authorization": "Bearer pp_YOUR_TOKEN"
      }
    }
  }
}

Once connected, the assistant starts by reading your workspace context so it knows your active clients, projects, labor categories, expense categories, and catalog items. You can refer to projects, clients, and documents by their names or codes (CL-01, EST-01, INV-01) instead of copying database IDs.

Common tasks to run with an assistant

  • Log time from rough notes: Ask your assistant to log 1h 30m or 2.5 hours to a project and labor category with a note explaining what you completed. Entries follow the same lock rules and 24-hour daily cap as the weekly grid. See Time tracking.
  • Record expenses and receipts: Log a project expense by category, date, and amount, or enter a unit quantity (such as mileage) and let PayPolka calculate the total from the category rate. You can also attach a base64-encoded receipt file. See Expenses.
  • Review unbilled work and prepare a draft invoice: Ask which projects have unbilled hours or expenses, then tell the assistant to create a draft invoice from the unbilled work for a project and date range. If you don’t give dates, the assistant bills all unbilled work on the project up to today. The draft links the underlying time and expense entries so they won’t be billed twice. Open the draft in PayPolka to check the lines before sending. See Invoices.
  • Draft an estimate or progress bill: Build a draft estimate using your saved labor categories and catalog items, or create a draft invoice for a percentage (such as 25%) or dollar amount of an accepted estimate. See Estimates and Estimate to invoice.
  • Check project budgets and reports: Ask for a project’s budget vs actual status, the Uninvoiced report, or the Profitability report for a date range. See Reports.

Use the JSON REST API

If you are building custom scripts, webhooks, or internal tools, use the JSON REST API at:

https://app.paypolka.com/api/v1

Authenticate every request with your personal access token in the Authorization header:

curl -H "Authorization: Bearer pp_YOUR_TOKEN" \
  https://app.paypolka.com/api/v1/context

GET /api/v1/context returns your account settings, your current user role and permissions, active clients and projects, labor categories, expense categories, and catalog items in a single call.

Main resource endpoints include:

  • GET /api/v1/context and GET /api/v1/dashboard
  • GET /api/v1/reports/:report (time_summary, billable_split, budget_vs_actual, uninvoiced, profitability)
  • GET, POST, PATCH, DELETE /api/v1/time_entries
  • GET /api/v1/timesheets, POST /api/v1/timesheets/submit, and POST /api/v1/timesheets/:id/approve, /reject, and /reopen
  • GET, POST, PATCH, DELETE /api/v1/expenses
  • GET, POST, PATCH /api/v1/clients and /api/v1/projects (plus POST /api/v1/projects/:id/fixed_fee_invoice)
  • GET, POST /api/v1/projects/:project_id/messages and POST /api/v1/projects/:project_id/messages/:message_id/comments
  • GET, POST, PATCH /api/v1/estimates (plus POST /api/v1/estimates/:id/accept, /decline, /reopen, /send_estimate, and /create_invoice)
  • GET, POST, PATCH, DELETE /api/v1/invoices (plus POST /api/v1/invoices/from_work and POST /api/v1/invoices/:id/send_invoice, /write_off, and /reopen)
  • POST /api/v1/invoices/:invoice_id/payments and POST /api/v1/invoices/:invoice_id/payments/:id/refund

The full OpenAPI 3.1 specification is available at https://app.paypolka.com/openapi.json. You can import that URL into API clients, workflow builders, or code generators.

Review and revoke tokens

Your tokens and connected apps are listed on Profile under API & AI access. Connected apps are labeled Connected app. Select Revoke next to any of them, and the assistant or script using it stops working right away.

Owners and admins can also see and revoke tokens across the whole account. Open Settings, Team, and scroll to API & AI tokens. The table lists each token’s name and prefix, the teammate it belongs to and their role, whether it is in draft-safe mode or can send and refund, and when it was last used.

When a teammate is deactivated or removed from the account, all of their tokens are deleted right away. If you change an owner or admin to another role, their tokens and connected apps drop back to draft-safe mode. Creating or revoking a token and connecting an app are recorded in Settings, Activity. See Account settings.