OatmilkDevelopers

Contractors

contractorOps.import.agreements

Bring agreements and NDAs in from a contracts table such as the Notion Contractor Contracts database, or the NDAs from a documents table such as Contractors Documents (source notion with databaseId, the database's link or ID, or csv with rows). mapping names the column for any fields whose column names don't match; the rest are matched by name. Fields: contractor (or email), title, kind (a type column: NDA, Contract…), signed (a signed column), role, rate (hourly), currency, startDate, endDate, file (a Notion files column with the signed copy), fileUrl (a link to a copy kept elsewhere) and nda (an NDA link or file on a contract row). A signed agreement with a start date becomes a version of the contractor's terms from that date, unless terms starting that day are already on file; one without dates is recorded as signed with the dates not stated and never becomes terms, so it can't replace dated ones; an unsigned, draft or stale row is kept as an unsigned draft. The signed copy is kept: a file attached to a Notion row is brought in with the Notion file import and filed as the agreement's signed document (linked to its terms), and a copy that's only a link is recorded as signed elsewhere. NDAs are kept apart from the contractor agreement. The role is linked to a job role by title and, for a title with several levels, the level whose pay band holds the rate; otherwise jobRoleSuggestion says what to do, and a contractor with no job role gets the one their current agreement matches. A table without start dates only brings in its NDAs. Every row is kept by the row it came from, so importing again fills in what's missing (a signed copy, a job role) instead of adding it twice. Rows for someone not in Oatmilk are left out with the reason; a rate of $1 or less is read as none. Nothing is sent to sign and nobody is emailed. A column whose name says it holds payment or tax details is never read, and problems says so when mapping names one. With preview true nothing is saved, and each row says whether it's already on file (onFile) and where the table disagrees with the terms on file (conflict).

POST/api/v1/accounting/contractorOps.import.agreements

Permissions

accounting:readaccounting:write

Who can call it

admin, finance

Retries

Idempotency key required

MCP

accounting_contractor_ops_import_agreements

Fields

  • sourceenumRequired

    notion reads a Notion database on the server; csv takes the rows of a parsed CSV file.

    csvnotion
  • rowsarray of maps

    For csv: each row as column name to value, at most 500.

    1–500 items

  • databaseIdstring

    For notion: the database's link or ID. The database must be shared with the Oatmilk connection.

    1–2000 characters

  • mappingobject

    The column for any fields whose column names don't match (null for none). Fields left out, or every field when it's omitted, are matched by column name; the result returns the mapping it used, so a preview shows the suggested one.

  • previewboolean

    true checks every row and saves nothing.

  • 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

Example

curl https://app.getoatmilk.com/api/v1/accounting/contractorOps.import.agreements \
  -H "Authorization: Bearer $OATMILK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "source": "csv",
  "rows": [
    {}
  ]
}'
Response
{
  "data": { … }
}

Try it

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.

POST/api/v1/accounting/contractorOps.import.agreements
curl https://app.getoatmilk.com/api/v1/accounting/contractorOps.import.agreements \
  -H "Authorization: Bearer $OATMILK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "source": "csv",
  "rows": [
    {}
  ]
}'

More in Contractors.