Connect your own system

• Your system sends records. It calls one address with a key made for the connection.
• sōtem reads your API. You give the address, the sign-in and, per record type, where the list is and how its pages work. A setting is saved only after a live test that shows three records as they will land.
• Agents ask to act there. An admin defines actions such as "update a deal stage". An agent files an approval card with the exact request; approving sends it once.
• Webhooks both ways. Your system can push records or ask for a read, signed. sōtem tells your system when an agent finished, an approval was decided or a record changed.

Set it up in Connections (sōtem) or Settings › Integrations (Mondaily): Connect your own system. Only an owner or admin can.

Up to 100 records a call. The same id again updates the same record, so a retry is safe.

POST https://api.mondaily.com/api/v1/connect/records
Authorization: Bearer md_live_…          (scope records:write)
Idempotency-Key: nightly-2026-11-02      (optional)

{ "records": [
  { "object_type": "people", "id": "C-1042",
    "fields": { "first_name": "Ada", "last_name": "Lovelace", "email": "ada@example.com" } },
  { "object_type": "deals", "id": "D-77", "fields": { "name": "Engine order", "deal_value": 2500 } }
] }

• object_type is people, companies, deals or one of your workspace's own record types.
• People, companies and deals are first matched to records you already have (email, web domain, name). One match is linked and only its empty fields are filled; two or more mean a new record that Data health shows as a possible duplicate.
• If someone changed a field in sōtem since your last send, their change stays and both values are kept for review.
• "deleted": true marks a record as deleted in your system. sōtem keeps it and says so.
• Read them back with GET /api/v1/connect/records (scope records:read).

Pages by page number, offset, cursor or a Link header. With a changed-since parameter, every read after the first asks only for what changed (with five minutes of overlap); without one, sōtem reads the list again and nothing that is unchanged is written twice. Reads run every 30 minutes and on Read now. If your system fails, sōtem waits 30 minutes, then longer each time up to 12 hours, and the card says why.

Only https addresses on the public internet are called. Private, local and cloud metadata addresses are refused, also when a name resolves to one later, and redirects are not followed. Each answer is limited to 15 seconds and 2 MB. Your key or password is stored encrypted and never shown again.

An action is a method (POST, PUT, PATCH or DELETE), a path under your API's address with {id} for the record's id in your system, and a JSON body with {{field}} placeholders. Each request is filed as an approval card showing exactly what will be sent. It runs once, with an Idempotency-Key header, and only its HTTP status is logged. An admin may let a low or medium risk action run within the workspace's autonomy level; a high risk action, and anything a scheduled agent proposes while nobody is watching, always waits for a person.

Both directions use the same signature: X-Mondaily-Signature: t=<unix>,v1=<hex>, the HMAC-SHA256 of <t>.<raw body> with the secret shown when you made it.

POST https://api.mondaily.com/api/v1/connect/hooks/<connection id>
X-Mondaily-Signature: t=1793606400,v1=…

{ "type": "records.upsert", "records": [ … ] }
{ "type": "sync.requested", "object_type": "deals" }

A signature older than five minutes is refused, and each signed delivery is accepted once. Outgoing events are agent.finished, approval.decided and record.changed; they carry ids and types, never record contents. A failed delivery is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours. After 10 failures in a row the webhook turns itself off and the card says so.

• Keys made on the connection carry records:write, records:read, agents:run or approvals:read. The secret is shown once.
• POST /api/v1/connect/agents/<id>/run starts one of your custom agents (a key made by an owner or admin). Anything it would change waits for approval.
• GET /api/v1/connect/approvals lists what is waiting, without the details.
• The full description: openapi.json (OpenAPI 3.1). The TypeScript client @sotem/sdk has connect.records, signWebhook and verifyWebhook.

Disconnecting revokes the connection's keys and deletes its secrets, actions and webhooks. The records stay as ordinary records, unless you also choose to delete the ones this connection added that nobody edited since. Records you had before are never deleted.