Pinpal Jobs API and MCP reference

Pinpal Jobs keeps a person's clients and everything they send them: quotes, contracts and invoices, each with its status. If they connected you, you draft the documents, send them when asked, follow up and write in the document's thread what you did. Pinpal keeps the numbering, the status and the record.

MCP server: https://jobs.mypinpal.com/mcp. For Claude, ChatGPT and every other MCP client. Nothing to install.
REST API: https://jobs.mypinpal.com/api/v1, below. Same token.

Base URL: https://jobs.mypinpal.com/api/v1. Auth: Authorization: Bearer TOKEN. A short copy of this page lives at /llms.txt.

MCP server and tools

Server URL: https://jobs.mypinpal.com/mcp (Streamable HTTP). Any MCP client that supports OAuth connects on its own: a call without a token answers 401 and points at /.well-known/oauth-protected-resource, the client registers itself and sends the person to sign in with Apple or Google. Every tool is one call into the REST API below, so the rules are the same whichever door is used.

get_account: clients, document types with their statuses, labels, counts.
get_settings / update_settings: company details, free fields (tax ID, VAT number, whatever the person needs), payment details, currency, tax lines, footer, days, numbering.
list_clients / read_client / create_client / update_client: a client by id or exact name; archived: true archives.
list_documents: filter by client, type, status, filter (waiting, unpaid, drafts, open, closed) or label.
read_document: by id or number.
create_document: a new draft.
update_document: the content of a draft; labels any time; note goes to the thread.
set_status: sent (numbers and locks), accepted, signed, declined, paid.
new_version: a new version of a quote or a contract, same number.
send_document: mails the link and the PDF; the first send numbers and locks.
send_reminder: to the address it went to.
mark_paid: date, today by default.
share_document / unshare_document: the client's page URL (.json for the client's AI); unsharing stops the link.
get_template / update_template: the look of a type: options, never markup; reset: true.
list_comments / add_comment: the document's thread.
attach_file / read_file: base64 or text in; image or text out.
list_labels: use the person's labels, never make them.

How to behave

Draft is the only status whose content changes. The first send takes the next number and locks the document; a locked document answers 409 to a content change.
Quotes and contracts get versions; an invoice is final once sent. A correction is a new invoice.
Overdue is never stored: a sent invoice past its due date shows as overdue.
Nothing is sent unless the person asks. Say in the thread what you did.
Pinpal Jobs writes no legal text. Use the person's own words, fields and terms.
You cannot delete a client, a document, a comment or a file, or change a label (403).

REST API

Method and path	What
`GET /me`	the account, types, labels, counts
`DELETE /me`	revoke this token
`GET/PATCH /settings`	company details and defaults
`GET/POST /clients`	the clients; a new client
`GET/PATCH /clients/:id`	one client
`GET/POST /documents`	the documents, with the filters above; a new draft
`GET/PATCH /documents/:id`	one document; `status` moves it
`POST /documents/:id/versions`	a new version
`POST /documents/:id/send`	send by email with the PDF
`POST /documents/:id/remind`	a reminder
`POST /documents/:id/paid`	mark paid
`POST/DELETE /documents/:id/share`	share or stop sharing
`GET/POST /documents/:id/comments`	the thread
`GET/POST /documents/:id/files`	files
`GET/PATCH /templates/:type`	the look of a type
`GET /labels`	the labels

Shapes

Document (list): id, clientId, clientName, type, typeName, number, version, title, status, statusName, currency, total, issueDate, dueDate, sentTo, sentAt, paidDate, locked, shared, labels, commentCount, fileCount, updatedAt, createdAt. In full, also lines, taxLines, subtotal, tax, taxes, body, footer, remindedAt, approvedBy, approvedAt, shareUrl, previewUrl, pdfUrl, versions, comments, files.

Line: { description, quantity, unitPrice } (decimal strings; numbers accepted on input). Tax line: { label, rate }.

Client: id, name, contact, email, phone, address, notes, color, imageUrl, archived, documents, open, waiting, unpaid, drafts, lastActivityAt.

Errors

401 missing or bad token
402 the free plan is full: a new one past the 20 free documents ({"error":"free_limit_reached","limit":20,"message":"..."}); relay the message, do not retry
403 only the person may do this (delete, change labels)
404 no such thing
409 the document is locked or the change does not fit its state

OAuth 2.0

An app can obtain a token without a paste. The person signs in on jobs.mypinpal.com; your server swaps the code for the same kind of personal API token. Discovery: /.well-known/oauth-authorization-server.

GET https://jobs.mypinpal.com/oauth/authorize
  ?client_id=…
  &redirect_uri=…
  &response_type=code
  &state=…
  &code_challenge=…
  &code_challenge_method=S256

POST https://jobs.mypinpal.com/oauth/token
  grant_type=authorization_code
  code=…
  redirect_uri=…
  client_id=…
  code_verifier=…

→ { "access_token": "…", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "…", "scope": "jobs" }

Dynamic client registration and PKCE are supported, so an MCP client needs no setup.

Pinpal Jobs API and MCP.