canonical: https://jentic.com/apis/harpoonapp.com/harpoonapp

# Harpoonapp Harpoon API

Harpoon is a financial planning and management platform built for freelancers and small agencies, focused on revenue forecasting, invoicing, and expense tracking. The API exposes 36 endpoints to manage clients, contacts, credits, estimates, invoices, expenses, and expected revenue records. Authentication is HTTP Bearer using a personal access token issued from the Harpoon dashboard. The API focuses on financial records - it does not run payroll or sync directly to external bank feeds.

## For AI agents

Manage Harpoon clients, contacts, estimates, invoices, expenses, and expected revenue with a Bearer token.

## Scope

Does not handle payment capture, payroll, or bank feed reconciliation - use for freelance and agency financial records (clients, estimates, invoices, expenses, revenue forecasts) only.

## Capabilities

- Create, list, fetch, update, and delete clients in a Harpoon workspace
- Manage contacts attached to a client
- Issue and look up client credits
- Generate estimates with auto-incrementing document IDs
- Track expected revenue records for forecasting
- Manage invoices and expenses for billable work

## Use cases

### Freelance Invoicing Automation

Automate invoice creation when a freelancer marks a project complete by calling POST /estimates to draft an estimate and converting it to an invoice via the Invoices endpoints. The Harpoon API auto-allocates document IDs through GET `/estimates/next-document-id` so numbering stays consistent. Most freelancers integrate this with a time-tracker to capture billable hours.

Example prompt: Fetch the next estimate ID from GET `/estimates/next-document-id`, then POST /estimates with the line items for project 'Brand Refresh'.

### Revenue Forecasting Dashboard

Pipe expected revenue records into a forecasting dashboard by calling GET /expected-revenue and listing forecasted amounts by client. The endpoint returns expected revenue items with amounts, dates, and clientIds that a BI tool can roll up into monthly run-rate. Freelancers use this to project cash flow.

Example prompt: List all expected revenue via GET /expected-revenue and group by month and clientId for a 90-day forecast.

### Client and Contact Sync

Keep the freelancer's CRM and accounting workspace in sync by mirroring clients and their contacts via /clients and /contacts. The API supports list, get, create, update, and delete on both resources, enabling two-way reconciliation. Pair this with a CRM webhook to trigger on every contact change.

Example prompt: When a new contact is added in HubSpot, call POST /contacts in Harpoon with the same email, name, and clientId.

### AI Agent Billing Assistant

Wire a billing assistant that responds to 'create an invoice for client X for project Y' by chaining the estimate, invoice, and expense endpoints through Jentic. The Bearer token sits in your Jentic One instance and is injected per call. Harpoon does not include payment capture, so the agent ends at invoice issuance, not collection.

Example prompt: When asked 'invoice Acme for 12 hours of strategy work at $200/hr', create an estimate with the line items, convert to invoice, and return the invoice ID.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/clients` | List clients |
| POST | `/clients` | Create a client |
| POST | `/contacts` | Create a contact |
| GET | `/estimates/next-document-id` | Get the next estimate document ID |
| POST | `/estimates` | Create an estimate |
| GET | `/expected-revenue` | List expected revenue records |
| POST | `/credits` | Issue a client credit |

## Key resources

- **Clients** — Customer organisation records
- **Contacts** — Individual contacts attached to a client
- **Estimates** — Quotes and proposals with auto-numbered document IDs
- **Invoices** — Billable invoices issued to clients
- **Expenses** — Project and overhead expense records
- **Credits** — Client credit balances
- **Expected Revenue** — Forecasted revenue for pipeline reporting

## Why Jentic

- **Setup:** Wiring the Harpoon API by hand means setting its Authorization Bearer token on every call and building each client, estimate, invoice, and revenue request yourself. Through Jentic you install once, import the Harpoon API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** The Harpoon API carries its targets in the request body against collection endpoints like /clients and /estimates, so scope your agent to the operations it needs, such as reading clients or expected revenue. You choose what it may call, so creating clients, estimates, or credits are not included unless you add them.
- **Credential handling:** Your Harpoon personal access token is stored once, encrypted, by your own Jentic One instance and injected as the Authorization Bearer header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a freelance invoice' or 'check expected revenue', and Jentic returns the matching Harpoon operation with its input schema so the agent calls the right endpoint without reading the developer docs.

## Related APIs

- **Xero Accounting** — Full general-ledger accounting for businesses that have outgrown freelance-focused tools.
- **Stripe** — Capture payment for invoices issued in Harpoon by charging cards or processing ACH.
- **Zoho** — Broader CRM and books platform for agencies needing more than freelance financial tracking.

## FAQ

### What authentication does the Harpoon API use?

Harpoon uses HTTP Bearer authentication. Generate a personal access token in the Harpoon dashboard and include it as Authorization: Bearer <token>. Through Jentic the token is stored in the encrypted vault and injected per call so it never enters the agent's prompt context.

### Can I create estimates with auto-incrementing IDs in Harpoon?

Yes. Call GET `/estimates/next-document-id` to retrieve the next document ID, then include it in the POST /estimates body. This keeps estimate numbering consistent without race conditions across multiple integrations.

### What are the rate limits for the Harpoon API?

Harpoon does not publish a public per-second rate limit in the OpenAPI spec; the API is intended for individual freelancer and small agency volumes. Build clients to back off on HTTP 429, and contact Harpoon support if a high-volume integration is planned.

### How do I create an invoice through Jentic?

Search Jentic for 'create a harpoon invoice', load the schema for the invoice creation operation, and execute with clientId and line items. Run pip install jentic and use the async client.search, client.load, and client.execute pattern.

### Does the Harpoon API include payment processing?

No. Harpoon focuses on invoicing, estimates, expenses, and revenue forecasting. Payment capture (credit card or ACH) is handled by external processors; the API records that an invoice is paid but does not charge cards itself.

### Can I limit what my agent is allowed to do with the Harpoon API?

Yes. Because you run Jentic One yourself, your own rules decide which Harpoon operations and credentials the agent may use. The Harpoon API carries its targets in the request body against collection endpoints like /clients and /estimates, so you can scope the agent to only the operations it needs, such as reading clients with GET /clients or listing forecasts with GET /expected-revenue. Write operations like POST /estimates, POST /clients, or POST /credits stay off limits unless you explicitly grant them.