Reminders

Chasing is the part of Syllevo an accountant is most nervous about, because the messages go out in their name, to their clients, without them in the room. These routes are the controls for that: what is scheduled today, who receives it, how often, and how to stop it.

Reminders are sent by the engine on a schedule. There is no route that composes a message, and there is no route that sends arbitrary mail. The only send route here asks for the next scheduled touch to happen now, and it refuses more often than it agrees.

Routes

The vocabulary

Four words, and everything on this page is built from them.

• A sequence is one client's chasing for one calendar month. It has a state, a number of touches it is allowed to spend, and a list of the touches spent so far.
• A touch is one message, scheduled or sent. A sequence with three touches sends at most three messages for that month, no matter how many documents are missing.
• A contact is an address at the client. Everyone marked primary is addressed on the same message, never one message each.
• A period is the calendar month, written as ISO 8601 year-month: "2026-08".

One message per touch, listing everything currently missing. That batching rule is the whole reason the product does not make the inbox worse.

GET /v1/reminders/sending-today

Everything scheduled to leave during the firm's local day, grouped by client. This is the screen an accountant checks before they trust the engine with anything.

Each entry in profiles carries profileId, profileName, touchCount, and touches.

The day is the organization's local day, resolved the same way the daily send cap resolves it, so the preview and the cap can never disagree about which messages belong to today.

The touch shape

touches appears here, on a sequence, and in history. It is always this:

outcome:

cancelReason:

A cancelled touch is usually the good ending. The message content is computed at send time rather than at schedule time, exactly so a reminder for documents that already arrived gets cancelled instead of sent.

WindowClosed explains something that will otherwise look like a bug: two rows can carry the same touchNumber. The abandoned attempt keeps its number and the replacement reuses it. Key on id, not on touchNumber.

recipientEmail and recipientName are filled in on the sending-today preview and nowhere else. Everywhere else a touch identifies its recipient by id only.

GET /v1/profiles/{profileId}/reminders

One client's chasing for one month.

Omitting period does not mean "this month". It means the sequence that is actually running, which is what a firm looking at a client mid-close wants to see.

A null sequence is normal. It means nothing has been chased for that month, usually because nothing was missing.

The sequence shape

state:

pauseReason:

stopReason:

3 exhausted is the state that needs a person. It means the engine spent every touch it was allowed and documents are still missing, which is the whole point of having a maximum: at some point the software stops and a human picks up the phone.

1 paused with reason 1, client replied, is the other one worth surfacing. When a client writes back, chasing stops and the reply is forwarded to the firm. Syllevo does not argue with a client by robot, so nothing resumes until somebody says so.

An ordinary out-of-office does not pause anything. If it states a return date the whole remaining sequence shifts, which is what remainingOutOfOfficeShiftBusinessDays counts down. Pause reason 2 is for the far side of that allowance.

GET /v1/profiles/{profileId}/reminders/history

Every sequence this client has ever had, newest first, one summary each.

A summary carries id, period, state, pauseReason, stopReason, touchesConsumed, closeOutSentAt, createdAt, endedAt, and lastTouch, which is one touch object rather than the whole list. Fetch the month itself when you need the full set.

POST /v1/profiles/{profileId}/reminders/pause

Holds the chasing. SendReminders.

Answers 200 with the sequence. Refused with 409 reminder_sequence_not_active when there is nothing running to hold.

The pause is recorded as the firm's, not the client's. A client asking for quiet is a different reason with a different audit trail, and the engine writes that one itself.

POST /v1/profiles/{profileId}/reminders/resume

Starts it again. SendReminders. No body. Answers 200 with the sequence.

Refused with 409 reminder_sequence_not_paused when there is nothing to pick back up.

POST /v1/profiles/{profileId}/reminders/send-now

Asks for one message outside the schedule. SendReminders. No body.

This is the route that refuses most, and every refusal is the engine protecting the firm's relationship with its client. On success:

Note the name: scheduled, not sent. Even a manual send lands in the next open moment of the recipient's send window. Asking at 22:00 does not write to a client at 22:00.

verdict:

Anything other than 0 comes back as 409 rather than 200, carrying the matching code: reminder_sequence_not_chasing, reminder_nothing_missing, reminder_no_usable_contact, or reminder_touch_already_pending. The last one carries pendingTouchAt alongside the usual error fields, so a screen can say when the scheduled message goes instead of just refusing.

{
  "status": 409,
  "code": "reminder_touch_already_pending",
  "messageKey": "web.errors.reminders.touchAlreadyPending",
  "detail": null,
  "details": null,
  "errors": null,
  "pendingTouchAt": "2026-09-12T09:00:00Z"
}

Settings

The firm sets one schedule. A client can override it. Both use the same body, and the effective values are what the engine reads.

GET and PUT /v1/reminders/settings

The firm's default, inherited by every client without an override. Admin on both, because this changes how every client of the firm is chased.

sendWindowEnd must be later than sendWindowStart and the window must be at least 60 minutes wide. A window cannot wrap past midnight, and a one-minute window would be a send cap of zero in practice.

maxTouches stops at 5 and there is no way to raise it. Five messages about one month is already more than most clients will forgive.

Turning escalation on takes two saves. Escalation writes to somebody the client did not choose to involve, a partner or the client's manager, so the first PUT with escalationEnabled: true is refused with 409 reminder_escalation_confirmation_required. Send it again with confirmEscalation: true and it sticks. After that, escalationConfirmed stays true and ordinary saves do not ask again.

escalationRunnable is the flag that actually decides: enabled and confirmed together. Read that one, not escalationEnabled.

The response adds isDefaulted, true when no row has been saved and the values above are the built-in defaults, plus id, profileId, createdAt, lastUpdatedAt, escalationConfirmedAt, and escalationRunnable.

GET, PUT, and DELETE /v1/profiles/{profileId}/reminders/settings

One client's override. ManageSettings on the client. The PUT body is the same as above.

effective carries the same schedule fields plus organizationSettingsId and profileSettingsId, so you can tell which row each value came from.

Read effective. It is the answer to "what will happen to this client", and it is the only field on this response that does not require you to work out inheritance yourself.

DELETE drops the override and puts the client back on the firm's default. It answers 200 with the settings that now stand, so a screen does not have to ask again.

Contacts

Who at the client gets written to. SendReminders on the client for all three routes.

role:

• 0 primary receives the sequence itself: one message per touch, listing everything currently missing. A client may have several, an owner and an office admin, and they are addressed together on one message rather than one message each.
• 1 escalation is written to only as the sequence's final touch, only where the firm configured one, and only in a separate message the client is never copied on. That message does not list the missing documents. Naming a client's outstanding items to a third party is a disclosure the client never agreed to.

hardBouncedEmail is kept separately from email on purpose. When somebody fixes a typo, the current address changes and the record of what bounced stays, so the same mistake is visible rather than quietly overwritten. canReceiveReminders is the field to branch on: a hard-bounced contact is still listed, still editable, and still receives nothing.

GET /v1/profiles/{profileId}/contacts

Every contact this client has, hard-bounced ones included. Answers a plain array.

POST /v1/profiles/{profileId}/contacts

Answers 201. An unsupported locale is refused with 400 validation.unsupportedLocale rather than quietly falling back to English, because an English reminder to a Romanian client is exactly the failure that makes a firm stop trusting the engine.

POST /v1/profiles/22222222-2222-4222-8222-222222222222/contacts HTTP/1.1
Host: api.syllevo.com
X-Api-Key: syl_live_examplekeynotreal000000000000
Content-Type: application/json

{
  "email": "maria@example.com",
  "role": 0,
  "displayName": "Maria Ionescu",
  "locale": "ro"
}

PATCH /v1/profiles/{profileId}/contacts/{contactId}

email is required even on a patch. Sending clearDisplayName: true together with a displayName is two contradictory instructions and is refused with 400 rather than guessed at.

There is no delete route. A contact that should stop receiving mail is handled by role and by bounce state, and the history of who was written to stays intact.