Request options (_options)

Write endpoints across the API accept an _options object in the request body, alongside the fields being written. Nothing in it is stored on the record. It changes how the write is carried out.

{
  "user_id": 1234,
  "status_id": 2,
  "_options": {
    "dry_run": true
  }
}

_options is always optional, and it is not itself validated: a key an endpoint does not implement is ignored, and so is an _options that is not an object at all. Sending one never turns a request that would have succeeded into an error.

Support is per endpoint. This page describes the two options that mean the same thing wherever they are honoured, and each endpoint's own reference says whether it honours them. Some endpoints take further options specific to what they do; those are documented on the endpoint.

An option an endpoint ignores is not an error, and that cuts both ways. Because _options is not validated, a request the endpoint does not act on comes back looking exactly like one it did — so read the endpoint's own reference before relying on either option, rather than assuming it applies everywhere.

dry_run asks "would this request be accepted?" without writing anything.

Nothing is stored, and no email, notification, automation or webhook is sent. The response replaces the usual body: instead of the record, you get the automations the write would have set off.

{
  "automations": ["<the name of each automation that would run>"],
  "automation_count": 1
}

An empty automations array means the write would trigger nothing configured — not that the write would fail.

A dry run checks the request, not the outcome. This is the part worth reading twice. It runs the same field validation as a real write, so bad input still comes back as a 422 naming the fields at fault. It does not run the rules that only apply at the moment of writing — a capacity limit, a duplicate, a state change the account does not permit. Those are the errors documented on the endpoint as 403 and 405, and a dry run returns 200 for every one of them.

So a 200 from a dry run means "the shape of this request is right", not "this request will succeed". Treat it as a way to preview which automations a change would set off, and to catch malformed input early — not as a pre-flight check that the write will land.

Three further limits:

• The response carries no record and no id, so a dry run cannot be used to validate and then create in a single call. It is a separate round trip.
• Deletes ignore it. Sending dry_run on a DELETE deletes the record.
• On some endpoints it also depends on the caller's access, and where it is not honoured the write goes ahead. This is the one to be careful with: the request is not refused and nothing in the response says the option was ignored — you get the normal 201 or 200 with the record, because the record was really created or really changed. Each endpoint that honours dry_run conditionally says so. Before wiring a dry run into anything that runs unattended, send one against a record you are willing to lose and check whether it came back as a preview or as the write.

trigger_automation controls whether the account's automations run in response to the write.

Left alone, a write behaves the way the same change made in the admin console would: the automations configured against it run, sending whatever emails, messages or follow-on changes the account has set up.

Send false to make the change and run none of them:

{
  "status_id": 3,
  "_options": {
    "trigger_automation": false
  }
}

That is what you want for a backfill or a migration, where the records need to exist but the people they belong to should not be emailed about changes that happened months ago. Use it deliberately: for ordinary integration traffic, suppressing automations means the account's configured follow-ups quietly do not happen, which is usually a bug rather than an optimisation.

Webhooks are not covered by this flag. A write sent with trigger_automation set to false still delivers its webhook, so a subscriber still hears about the change.