{"templateId":"markdown","sharedDataIds":{},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Request options ( _options )"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"request-options--_options-","__idx":0},"children":["Request options (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_options"]},")"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Write endpoints across the API accept an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_options"]}," object in the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["request body"]},","," ","alongside the fields being written. Nothing in it is stored on the record. It"," ","changes ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["how"]}," the write is carried out."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"user_id\": 1234,\n  \"status_id\": 2,\n  \"_options\": {\n    \"dry_run\": true\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_options"]}," is always optional, and it is not itself validated: a key an endpoint"," ","does not implement is ignored, and so is an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_options"]}," that is not an object at"," ","all. Sending one never turns a request that would have succeeded into an error."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["An option an endpoint ignores is not an error, and that cuts both ways."]}," Because"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"dry_run","__idx":1},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dry_run"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dry_run"]}," asks \"would this request be accepted?\" without writing anything."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Type"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Default"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"automations\": [\"<the name of each automation that would run>\"],\n  \"automation_count\": 1\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An empty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["automations"]}," array means the write would trigger nothing configured — not"," ","that the write would fail."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}," naming the fields at fault. It does ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}," ","and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["405"]},", and a dry run returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," for every one of them."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["So a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Three further limits:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The response carries no record and no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},", so a dry run cannot be used to"," ","validate and then create in a single call. It is a separate round trip."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Deletes ignore it."]}," Sending ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dry_run"]}," on a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]}," deletes the record."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," with the record, because the record was really created"," ","or really changed. Each endpoint that honours ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"trigger_automation","__idx":2},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["trigger_automation"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["trigger_automation"]}," controls whether the account's automations run in response to"," ","the write."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Type"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Default"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," to make the change and run none of them:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"status_id\": 3,\n  \"_options\": {\n    \"trigger_automation\": false\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhooks are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," covered by this flag. A write sent with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["trigger_automation"]}," ","set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," still delivers its webhook, so a subscriber still hears about the"," ","change."]}]},"headings":[{"value":"Request options ( _options )","id":"request-options--_options-","depth":1},{"value":"dry_run","id":"dry_run","depth":2},{"value":"trigger_automation","id":"trigger_automation","depth":2}],"frontmatter":{"seo":{"title":"Request options ( _options )"}},"lastModified":"2026-08-18T06:10:52.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/api-docs/guides/request-options","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}