Contractors

Contractor API

Let contractors log hours, submit timesheets and read their pay from their own tools.

Contractors who work for a company on Oatmilk have their own API at /api/v1/contractor/. It reaches only that contractor's own records: their hours, timesheets, pay, agreements and profile. Company API keys don't work here, and contractor sign-ins can't see the company's books.

HTTP

POST https://app.getoatmilk.com/api/v1/contractor/hours.create
Authorization: Bearer <contractor OAuth token>

Signing in

The contractor API uses OAuth with the contractor:read and contractor:write permissions. A contractor connects an app or AI assistant by signing in with the account they use for the contractor portal. Use https://app.getoatmilk.com/api/mcp?toolset=contractor to give an assistant only the contractor tools.

Choose the company

A contractor can work for several companies. Call organizations.list first: it needs no company. Then send X-Accounting-Organization with the chosen company's ID on every other request.

GET/api/v1/contractor/organizations.list

curl https://app.getoatmilk.com/api/v1/contractor/organizations.list \
  -H "Authorization: Bearer $OATMILK_OAUTH_TOKEN"

const response = await fetch("https://app.getoatmilk.com/api/v1/contractor/organizations.list", {
  headers: {
    Authorization: `Bearer ${process.env.OATMILK_OAUTH_TOKEN}`,
  },
});
const { data, error } = await response.json();
if (!response.ok) throw new Error(`${error.code}: ${error.message}`);
console.log(data);

import os

import requests

response = requests.get(
    "https://app.getoatmilk.com/api/v1/contractor/organizations.list",
    headers={
        "Authorization": f"Bearer {os.environ['OATMILK_OAUTH_TOKEN']}",
    },
    timeout=30,
)
payload = response.json()
if not response.ok:
    raise RuntimeError(f"{payload['error']['code']}: {payload['error']['message']}")
print(payload["data"])

Log and submit hours

POST/api/v1/contractor/hours.create

curl https://app.getoatmilk.com/api/v1/contractor/hours.create \
  -H "Authorization: Bearer $OATMILK_OAUTH_TOKEN" \
  -H "X-Accounting-Organization: $OATMILK_ORGANIZATION_ID" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "date": "2026-09-15",
  "minutes": 90,
  "description": "Design review with the finance team"
}'

const response = await fetch("https://app.getoatmilk.com/api/v1/contractor/hours.create", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OATMILK_OAUTH_TOKEN}`,
    "X-Accounting-Organization": process.env.OATMILK_ORGANIZATION_ID,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "date": "2026-09-15",
    "minutes": 90,
    "description": "Design review with the finance team"
  }),
});
const { data, error } = await response.json();
if (!response.ok) throw new Error(`${error.code}: ${error.message}`);
console.log(data);

import os
import uuid

import requests

response = requests.post(
    "https://app.getoatmilk.com/api/v1/contractor/hours.create",
    headers={
        "Authorization": f"Bearer {os.environ['OATMILK_OAUTH_TOKEN']}",
        "X-Accounting-Organization": os.environ["OATMILK_ORGANIZATION_ID"],
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "date": "2026-09-15",
        "minutes": 90,
        "description": "Design review with the finance team",
    },
    timeout=30,
)
payload = response.json()
if not response.ok:
    raise RuntimeError(f"{payload['error']['code']}: {payload['error']['message']}")
print(payload["data"])

When the pay period is ready, submit every draft entry in it at once:

POST/api/v1/contractor/timesheet.submit

curl https://app.getoatmilk.com/api/v1/contractor/timesheet.submit \
  -H "Authorization: Bearer $OATMILK_OAUTH_TOKEN" \
  -H "X-Accounting-Organization: $OATMILK_ORGANIZATION_ID" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "date": "2026-09-15"
}'

const response = await fetch("https://app.getoatmilk.com/api/v1/contractor/timesheet.submit", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OATMILK_OAUTH_TOKEN}`,
    "X-Accounting-Organization": process.env.OATMILK_ORGANIZATION_ID,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "date": "2026-09-15"
  }),
});
const { data, error } = await response.json();
if (!response.ok) throw new Error(`${error.code}: ${error.message}`);
console.log(data);

import os
import uuid

import requests

response = requests.post(
    "https://app.getoatmilk.com/api/v1/contractor/timesheet.submit",
    headers={
        "Authorization": f"Bearer {os.environ['OATMILK_OAUTH_TOKEN']}",
        "X-Accounting-Organization": os.environ["OATMILK_ORGANIZATION_ID"],
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "date": "2026-09-15",
    },
    timeout=30,
)
payload = response.json()
if not response.ok:
    raise RuntimeError(f"{payload['error']['code']}: {payload['error']['message']}")
print(payload["data"])

What stays in the portal

Bank details, tax numbers, agreeing to receive tax slips by email, and signing agreements only happen in the contractor's own portal session. The API refuses them with INTERACTIVE_PORTAL_REQUIRED or INTERACTIVE_SIGNATURE_REQUIRED and a portalUrl that opens the exact step.

Every contractor action

The contractor reference lists all 43 actions with their fields.