`contractorOps.taxInfo.update`

Add or replace a contractor's tax number (taxNumber: kind sin, bn, itn or foreign, the value, and country for a foreign number) or remove one (removeTaxNumber: the kind), with expectedRevision once that kind was saved before; and/or set the mailing address their slips go to (mailingAddress: line1 street, line2 unit, city, region province or state, postalCode, country) with expectedProfileRevision. A SIN must pass the check-digit test, a business number has 9 digits and an optional program account like RT0001, and a Canadian postal code looks like K1A 0B6. Numbers are stored encrypted and only ever returned masked; the audit log records that one changed, never the value. Finance can change a contractor's tax numbers at most 5 times an hour, and 50 times an hour across the organization (429 with Retry-After); a contractor's own portal saves have a separate budget, so neither can use up the other's. Nothing is returned about other contractors' numbers, except that an administrator in the dashboard saving a SIN or ITN is told who else has the same one (sameNumberAs).

POST/api/v1/accounting/contractorOps.taxInfo.update

Permissions

accounting:readaccounting:write

Who can call it

admin, finance

Retries

Idempotency key required, with expectedRevision

MCP

Not offered over MCP: The warning that another contractor already has the same SIN or ITN would let a client test numbers against everyone else's.

Fields

contractorIdstring (ID)Required
The ID of a contractor, from contractors.list.
taxNumberobject
No other fields
removeTaxNumberenum
sinbnitnforeign
expectedRevisioninteger
The record's current revision, from the last time you read it. If someone changed the record since, the request is refused with a conflict so you can reload and check before trying again.
at most 9007199254740991 · greater than 0
mailingAddressobject
No other fields
usTaxFormenum or null
w9w8benw8beneunsure
usTaxClassificationenum or null
individualc_corporations_corporationpartnershiptrust_estatellc_cllc_sllc_pother
expectedProfileRevisioninteger
The related record's current revision, from the last time you read it.
at most 9007199254740991 · greater than 0
idempotencyKeystringRequired
Any unique text you generate once per intended change, so a retried request only happens once. Send it as the Idempotency-Key header instead if you prefer; if you send both they must match.
8–200 characters

curl https://app.getoatmilk.com/api/v1/accounting/contractorOps.taxInfo.update \
  -H "Authorization: Bearer $OATMILK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "contractorId": "4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
  "taxNumber": {
    "kind": "sin",
    "value": "example"
  }
}'

const response = await fetch("https://app.getoatmilk.com/api/v1/accounting/contractorOps.taxInfo.update", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OATMILK_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "contractorId": "4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
    "taxNumber": {
      "kind": "sin",
      "value": "example"
    }
  }),
});
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/accounting/contractorOps.taxInfo.update",
    headers={
        "Authorization": f"Bearer {os.environ['OATMILK_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "contractorId": "4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
        "taxNumber": {
            "kind": "sin",
            "value": "example",
        },
    },
    timeout=30,
)
payload = response.json()
if not response.ok:
    raise RuntimeError(f"{payload['error']['code']}: {payload['error']['message']}")
print(payload["data"])

Response

{
  "data": { … }
}

Try it

Checks your input with this action’s real schema and answers like the API, with synthetic data. No key needed, and nothing changes.

Input

POST/api/v1/accounting/contractorOps.taxInfo.update

curl https://app.getoatmilk.com/api/v1/accounting/contractorOps.taxInfo.update \
  -H "Authorization: Bearer $OATMILK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "contractorId": "4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
  "taxNumber": {
    "kind": "sin",
    "value": "example"
  }
}'

const response = await fetch("https://app.getoatmilk.com/api/v1/accounting/contractorOps.taxInfo.update", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OATMILK_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "contractorId": "4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
    "taxNumber": {
      "kind": "sin",
      "value": "example"
    }
  }),
});
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/accounting/contractorOps.taxInfo.update",
    headers={
        "Authorization": f"Bearer {os.environ['OATMILK_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "contractorId": "4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
        "taxNumber": {
            "kind": "sin",
            "value": "example",
        },
    },
    timeout=30,
)
payload = response.json()
if not response.ok:
    raise RuntimeError(f"{payload['error']['code']}: {payload['error']['message']}")
print(payload["data"])

Fields

Fields inside taxNumber

Fields inside mailingAddress

Example

Try it