# `zapier-platform-schema` Generated Documentation This is automatically generated by the `npm run docs` command in `zapier-platform-schema` version `19.1.0`. To see the docs for a different version, switch to the corresponding version tag in the GitHub repository. For example, to view docs for version 17.7.0, switch to the tag 'zapier-platform-schema@17.7.0'. Alternatively, modify the URL directly: https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@17.7.0/packages/schema/docs/build/schema.md, replacing 17.7.0 with your desired version. ----- ## Index * [/AppFlagsSchema](#appflagsschema) * [/AppSchema](#appschema) * [/AuthFieldSchema](#authfieldschema) * [/AuthFieldsSchema](#authfieldsschema) * [/AuthenticationBasicConfigSchema](#authenticationbasicconfigschema) * [/AuthenticationCustomConfigSchema](#authenticationcustomconfigschema) * [/AuthenticationDigestConfigSchema](#authenticationdigestconfigschema) * [/AuthenticationOAuth1ConfigSchema](#authenticationoauth1configschema) * [/AuthenticationOAuth2ConfigSchema](#authenticationoauth2configschema) * [/AuthenticationSchema](#authenticationschema) * [/AuthenticationSessionConfigSchema](#authenticationsessionconfigschema) * [/BasicActionOperationSchema](#basicactionoperationschema) * [/BasicCreateOperationSchema](#basiccreateoperationschema) * [/BasicDisplaySchema](#basicdisplayschema) * [/BasicHookOperationSchema](#basichookoperationschema) * [/BasicOperationSchema](#basicoperationschema) * [/BasicPollingOperationSchema](#basicpollingoperationschema) * [/BasicSearchOperationSchema](#basicsearchoperationschema) * [/BufferConfigSchema](#bufferconfigschema) * [/BulkReadSchema](#bulkreadschema) * [/BulkReadsSchema](#bulkreadsschema) * [/CreateSchema](#createschema) * [/CreatesSchema](#createsschema) * [/FieldChoiceWithLabelSchema](#fieldchoicewithlabelschema) * [/FieldChoicesSchema](#fieldchoicesschema) * [/FieldDynamicChoicesSchema](#fielddynamicchoicesschema) * [/FieldMetaSchema](#fieldmetaschema) * [/FlatObjectSchema](#flatobjectschema) * [/FunctionRequireSchema](#functionrequireschema) * [/FunctionSchema](#functionschema) * [/FunctionSourceSchema](#functionsourceschema) * [/HydratorsSchema](#hydratorsschema) * [/InputFieldGroupSchema](#inputfieldgroupschema) * [/InputFieldGroupsSchema](#inputfieldgroupsschema) * [/InputFieldsSchema](#inputfieldsschema) * [/JsonSchemaSchema](#jsonschemaschema) * [/KeySchema](#keyschema) * [/LockObjectSchema](#lockobjectschema) * [/MiddlewaresSchema](#middlewaresschema) * [/OutputFieldsSchema](#outputfieldsschema) * [/PlainInputFieldSchema](#plaininputfieldschema) * [/PlainOutputFieldSchema](#plainoutputfieldschema) * [/RedirectRequestSchema](#redirectrequestschema) * [/RefResourceSchema](#refresourceschema) * [/RequestSchema](#requestschema) * [/ResourceMethodCreateSchema](#resourcemethodcreateschema) * [/ResourceMethodGetSchema](#resourcemethodgetschema) * [/ResourceMethodHookSchema](#resourcemethodhookschema) * [/ResourceMethodListSchema](#resourcemethodlistschema) * [/ResourceMethodSearchSchema](#resourcemethodsearchschema) * [/ResourceSchema](#resourceschema) * [/ResourcesSchema](#resourcesschema) * [/ResultsSchema](#resultsschema) * [/SearchAndCreatesSchema](#searchandcreatesschema) * [/SearchOrCreateSchema](#searchorcreateschema) * [/SearchOrCreatesSchema](#searchorcreatesschema) * [/SearchSchema](#searchschema) * [/SearchesSchema](#searchesschema) * [/ThrottleObjectSchema](#throttleobjectschema) * [/ThrottleOverrideObjectSchema](#throttleoverrideobjectschema) * [/TriggerSchema](#triggerschema) * [/TriggersSchema](#triggersschema) * [/VersionSchema](#versionschema) ----- ## /AppFlagsSchema Codifies high-level options for your integration. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/AppFlagsSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `skipHttpPatch` | no | `boolean` | By default, Zapier patches the core `http` module so that all requests (including those from 3rd-party SDKs) can be logged. Set this to true if you're seeing issues using an SDK (such as AWS). `skipThrowForStatus` | no | `boolean` | Starting in `core` version `10.0.0`, `response.throwForStatus()` was called by default. We introduced a per-request way to opt-out of this behavior. This flag takes that a step further and controls that behavior integration-wide **for requests made using `z.request()`**. Unless they specify otherwise (per-request, or via middleware), [Shorthand requests](https://github.com/zapier/zapier-platform/blob/main/packages/cli/README.md#shorthand-http-requests) _always_ call `throwForStatus()`. `z.request()` calls can also ignore this flag if they set `skipThrowForStatus` directly. It is important to note that for oauth2 or session auths with `authRefresh:true`, `401` status codes will throw a `RefreshAuthError` regardless of `skipThrowForStatus`, and will need to be handled manually if intervention is required. `throwForThrottlingEarly` | no | `boolean` | Starting in `core` version `18.0.0`, 429 (throttling) responses throw a `ThrottledError` before `afterResponse` middleware runs by default. Set this flag to `true` to preserve the old behavior where `afterResponse` middleware can see and handle 429 responses. This flag can be overridden per-request by setting `throwForThrottlingEarly` directly on the request options. `cleanInputData` | no | `boolean` | If true, Zapier removes empty strings, `null`, `undefined`, and empty Arrays or objects from `bundle.inputData` recursively before passing it to your `perform*` function. If you want to handle empty values yourself in your code, explicitly set this to false. This is a global flag that affects all the triggers and actions in your integration. The `cleanInputData` flag in `operation` takes precedence over this one. #### Examples * `{ skipHttpPatch: true, skipThrowForStatus: false, throwForThrottlingEarly: true }` * `{ skipHttpPatch: false, skipThrowForStatus: true, throwForThrottlingEarly: false }` * `{ throwForThrottlingEarly: true }` * `{}` #### Anti-Examples * `{ foo: true }` - _Invalid key._ * `{ skipHttpPatch: 'yes' }` - _Invalid value._ * `{ skipThrowForStatus: 'no' }` - _Invalid value._ * `{ throwForThrottlingEarly: 'yes' }` - _Invalid value._ ----- ## /AppSchema Represents a full app. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/AppSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `version` | **yes** | [/VersionSchema](#versionschema) | A version identifier for your code. `platformVersion` | **yes** | [/VersionSchema](#versionschema) | A version identifier for the Zapier execution environment. `beforeApp` | no | [/MiddlewaresSchema](#middlewaresschema) | EXPERIMENTAL: Before the perform method is called on your app, you can modify the execution context. `afterApp` | no | [/MiddlewaresSchema](#middlewaresschema) | EXPERIMENTAL: After the perform method is called on your app, you can modify the response. `authentication` | no | [/AuthenticationSchema](#authenticationschema) | Choose what scheme your API uses for authentication. `requestTemplate` | no | [/RequestSchema](#requestschema) | Define a request mixin, great for setting custom headers, content-types, etc. `beforeRequest` | no | [/MiddlewaresSchema](#middlewaresschema) | Before an HTTP request is sent via our `z.request()` client, you can modify it. `afterResponse` | no | [/MiddlewaresSchema](#middlewaresschema) | After an HTTP response is recieved via our `z.request()` client, you can modify it. `hydrators` | no | [/HydratorsSchema](#hydratorsschema) | An optional bank of named functions that you can use in `z.hydrate('someName')` to lazily load data. `resources` | no | [/ResourcesSchema](#resourcesschema) | All the resources for your app. Zapier will take these and generate the relevent triggers/searches/creates automatically. `triggers` | no | [/TriggersSchema](#triggersschema) | All the triggers for your app. You can add your own here, or Zapier will automatically register any from the list/hook methods on your resources. `bulkReads` | no | [/BulkReadsSchema](#bulkreadsschema) | All of the read bulks (GETs) your app exposes to retrieve resources in batches. `searches` | no | [/SearchesSchema](#searchesschema) | All the searches for your app. You can add your own here, or Zapier will automatically register any from the search method on your resources. `creates` | no | [/CreatesSchema](#createsschema) | All the creates for your app. You can add your own here, or Zapier will automatically register any from the create method on your resources. `searchOrCreates` | no | [/SearchOrCreatesSchema](#searchorcreatesschema) | All the search-or-create combos for your app. You can create your own here, or Zapier will automatically register any from resources that define a search, a create, and a get (or define a searchOrCreate directly). Register non-resource search-or-creates here as well. `searchAndCreates` | no | [/SearchAndCreatesSchema](#searchandcreatesschema) | An alias for "searchOrCreates". `flags` | no | [/AppFlagsSchema](#appflagsschema) | Top-level app options `throttle` | no | [/ThrottleObjectSchema](#throttleobjectschema) | Zapier uses this configuration to apply throttling when the limit for the window is exceeded. When set here, it is the default throttle configuration used on each action of the integration. And when set in an action's operation object, it gets overwritten for that action only. #### Examples * `{ version: '1.0.0', platformVersion: '10.1.2' }` #### Anti-Examples * `{ version: 'v1.0.0', platformVersion: '10.1.2' }` - _Invalid value for version._ * `{ version: '1.0.0', platformVersion: 'v10.1.2' }` - _Invalid value for platformVersion._ ----- ## /AuthFieldSchema Field schema specialized for authentication fields. In addition to the requirements below, the following keys are mutually exclusive: * `children` & `list` * `children` & `dict` * `children` & `type` * `children` & `placeholder` * `children` & `helpText` * `children` & `default` * `dict` & `list` * `dynamic` & `dict` * `dynamic` & `choices` #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/AuthFieldSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `key` | **yes** | `string` | A unique machine readable key for this value (IE: "fname"). `label` | no | `string` | A human readable label for this value (IE: "First Name"). `type` | no | `string` in (`'string'`, `'number'`, `'boolean'`, `'datetime'`, `'copy'`, `'password'`, `'integer'`, `'text'`) | The type of this value used to be. `required` | no | `boolean` | If this value is required or not. This defaults to `true`. `default` | no | `string` | A default value that is saved the first time a Zap is created. `list` | no | `boolean` | Acts differently when used in inputFields vs. when used in outputFields. In inputFields: Can a user provide multiples of this field? In outputFields: Does this field return an array of items of type `type`? `children` | no | `array`[[/AuthFieldSchema](#authfieldschema)] | An array of child fields that define the structure of a sub-object for this field. Usually used for line items. `dict` | no | `boolean` | Is this field a key/value input? `helpText` | no | `string` | A human readable description of this value (IE: "The first part of a full name."). You can use Markdown. `placeholder` | no | `string` | An example value that is not saved. `choices` | no | [/FieldChoicesSchema](#fieldchoicesschema) | An object of machine keys and human values to populate a static dropdown. `computed` | no | `boolean` | Is this field automatically populated (and hidden from the user)? Note: Only OAuth and Session Auth support fields with this key. `inputFormat` | no | `string` | Useful when you expect the input to be part of a longer string. Put "{{input}}" in place of the user's input (IE: "https://{{input}}.yourdomain.com"). `isNoSecret` | no | `boolean` | Indicates if this authentication field is safe to e.g. be stored without encryption or displayed (not a secret). #### Examples * `{ key: 'email', type: 'string', isNoSecret: true, required: true }` * `{ key: 'password', type: 'password', isNoSecret: false, required: true }` * `{ key: 'api_key', type: 'string', isNoSecret: false, required: true }` #### Anti-Examples * `{ key: 'password', type: 'password', isNoSecret: true, required: true }` - _"password" is a sensitive field and cannot have isNoSecret set as true._ * `{ key: 'api_key', isNoSecret: true }` - _"api_key" is a sensitive field and cannot have isNoSecret set as true._ * `{ type: 'string', isNoSecret: false }` - _Missing required key: key_ ----- ## /AuthFieldsSchema An array or collection of authentication fields. #### Details * **Type** - `array`[oneOf([/AuthFieldSchema](#authfieldschema))] * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/AuthFieldsSchema.js) #### Examples * ``` [ { key: 'username', type: 'string', isNoSecret: true, required: true }, { key: 'password', type: 'password', isNoSecret: false, required: true } ] ``` * `[ { key: 'api_key', type: 'string', isNoSecret: false, required: true } ]` * ``` [ { key: 'email', type: 'string', isNoSecret: true }, { key: 'password', type: 'password', required: true }, { key: 'mfa_token', type: 'string', isNoSecret: false } ] ``` #### Anti-Examples * `{}` - _Must be an array (currently an object)._ * `[ { key: 'password', isNoSecret: true } ]` - _"password" is a sensitive field and cannot have isNoSecret set as true._ * `[ { key: 'api_key', isNoSecret: true } ]` - _"api_key" is a sensitive field and cannot have isNoSecret set as true._ * `[ { isNoSecret: false } ]` - _Missing required "key" property._ * `[ { key: 'username', type: 'string', isNoSecret: true }, 12345 ]` - _Array item 12345 is not an object (must match AuthFieldSchema)._ ----- ## /AuthenticationBasicConfigSchema Config for Basic Authentication. No extra properties are required to setup Basic Auth, so you can leave this empty if your app uses Basic Auth. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/AuthenticationBasicConfigSchema.js) #### Examples * `{}` #### Anti-Examples * `{ foo: true }` - _Invalid key._ ----- ## /AuthenticationCustomConfigSchema Config for custom authentication (like API keys). No extra properties are required to setup this auth type, so you can leave this empty if your app uses a custom auth method. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/AuthenticationCustomConfigSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `sendCode` | no | oneOf([/RequestSchema](#requestschema), [/FunctionSchema](#functionschema)) | EXPERIMENTAL: Define the call Zapier should make to send the OTP code. #### Examples * `{}` * ``` { sendCode: { url: 'https://example.com/api/send', headers: { Authorization: 'Bearer {{process.env.API_KEY}}' }, body: { to_phone_number: '{{bundle.inputData.phone_number}}', code: '{{bundle.inputData.code}}' } } } ``` #### Anti-Examples * `{ foo: true }` - _Invalid key._ ----- ## /AuthenticationDigestConfigSchema Config for Digest Authentication. No extra properties are required to setup Digest Auth, so you can leave this empty if your app uses Digets Auth. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/AuthenticationDigestConfigSchema.js) #### Examples * `{}` #### Anti-Examples * `{ foo: true }` - _Invalid key._ ----- ## /AuthenticationOAuth1ConfigSchema Config for OAuth1 authentication. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/AuthenticationOAuth1ConfigSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `getRequestToken` | **yes** | oneOf([/RequestSchema](#requestschema), [/FunctionSchema](#functionschema)) | Define where Zapier will acquire a request token which is used for the rest of the three legged authentication process. `authorizeUrl` | **yes** | oneOf([/RedirectRequestSchema](#redirectrequestschema), [/FunctionSchema](#functionschema)) | Define where Zapier will redirect the user to authorize our app. Typically, you should append an `oauth_token` querystring parameter to the request. `getAccessToken` | **yes** | oneOf([/RequestSchema](#requestschema), [/FunctionSchema](#functionschema)) | Define how Zapier fetches an access token from the API #### Examples * ``` { getRequestToken: { require: 'some/path/to/file.js' }, authorizeUrl: { require: 'some/path/to/file2.js' }, getAccessToken: { require: 'some/path/to/file3.js' } } ``` #### Anti-Examples * ``` { getRequestToken: { require: 'some/path/to/file.js' }, authorizeUrl: { require: 'some/path/to/file2.js' } } ``` _Missing required key._ ----- ## /AuthenticationOAuth2ConfigSchema Config for OAuth2 authentication. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/AuthenticationOAuth2ConfigSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `authorizeUrl` | **yes** | oneOf([/RedirectRequestSchema](#redirectrequestschema), [/FunctionSchema](#functionschema)) | Define where Zapier will redirect the user to authorize our app. Note: we append the redirect URL and state parameters to return value of this function. `getAccessToken` | **yes** | oneOf([/RequestSchema](#requestschema), [/FunctionSchema](#functionschema)) | Define how Zapier fetches an access token from the API `refreshAccessToken` | no | oneOf([/RequestSchema](#requestschema), [/FunctionSchema](#functionschema)) | Define how Zapier will refresh the access token from the API `codeParam` | no | `string` | Define a non-standard code param Zapier should scrape instead. `scope` | no | `string` | What scope should Zapier request? `autoRefresh` | no | `boolean` | Should Zapier invoke `refreshAccessToken` when we receive an error for a 401 response? `enablePkce` | no | `boolean` | Should Zapier use PKCE for OAuth2? #### Examples * ``` { authorizeUrl: { require: 'some/path/to/file.js' }, getAccessToken: { require: 'some/path/to/file2.js' } } ``` * ``` { authorizeUrl: { require: 'some/path/to/file.js' }, getAccessToken: { require: 'some/path/to/file2.js' }, refreshAccessToken: { require: 'some/path/to/file3.js' }, codeParam: 'unique_code', scope: 'read/write', autoRefresh: true, enablePkce: true } ``` #### Anti-Examples * `{ authorizeUrl: { require: 'some/path/to/file.js' } }` - _Missing required key getAccessToken._ ----- ## /AuthenticationSchema Represents authentication schemes. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/AuthenticationSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `type` | **yes** | `string` in (`'basic'`, `'custom'`, `'digest'`, `'oauth1'`, `'oauth2'`, `'session'`) | Choose which scheme you want to use. `test` | **yes** | oneOf([/RequestSchema](#requestschema), [/FunctionSchema](#functionschema)) | A function or request that confirms the authentication is working. `fields` | no | [/AuthFieldsSchema](#authfieldsschema) | Fields you can request from the user before they connect your app to Zapier. `connectionLabel` | no | anyOf([/RequestSchema](#requestschema), [/FunctionSchema](#functionschema), `string`) | A string with variables, function, or request that returns the connection label for the authenticated user. `basicConfig` | no | [/AuthenticationBasicConfigSchema](#authenticationbasicconfigschema) | _No description given._ `customConfig` | no | [/AuthenticationCustomConfigSchema](#authenticationcustomconfigschema) | _No description given._ `digestConfig` | no | [/AuthenticationDigestConfigSchema](#authenticationdigestconfigschema) | _No description given._ `oauth1Config` | no | [/AuthenticationOAuth1ConfigSchema](#authenticationoauth1configschema) | _No description given._ `oauth2Config` | no | [/AuthenticationOAuth2ConfigSchema](#authenticationoauth2configschema) | _No description given._ `sessionConfig` | no | [/AuthenticationSessionConfigSchema](#authenticationsessionconfigschema) | _No description given._ #### Examples * `{ type: 'basic', test: '$func$2$f$' }` * `{ type: 'custom', test: '$func$2$f$', fields: [ { key: 'abc' } ] }` * `{ type: 'custom', test: '$func$2$f$', connectionLabel: '{{bundle.inputData.abc}}' }` * `{ type: 'custom', test: '$func$2$f$', connectionLabel: '$func$2$f$' }` * `{ type: 'custom', test: '$func$2$f$', connectionLabel: { url: 'abc' } }` #### Anti-Examples * `{}` - _Missing required keys: type and test_ * `'$func$2$f$'` - _Must be object_ * `{ type: 'unknown', test: '$func$2$f$' }` - _Invalid value for key: type_ * `{ type: 'custom', test: '$func$2$f$', fields: '$func$2$f$' }` - _Invalid value for key: fields_ ----- ## /AuthenticationSessionConfigSchema Config for session authentication. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/AuthenticationSessionConfigSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `perform` | **yes** | oneOf([/RequestSchema](#requestschema), [/FunctionSchema](#functionschema)) | Define how Zapier fetches the additional authData needed to make API calls. #### Examples * `{ perform: { require: 'some/path/to/file.js' } }` #### Anti-Examples * `{}` - _Missing required key: perform_ ----- ## /BasicActionOperationSchema Represents the fundamental mechanics of a search/create. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/BasicActionOperationSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `resource` | no | [/KeySchema](#keyschema) | Optionally reference and extends a resource. Allows Zapier to automatically tie together samples, lists and hooks, greatly improving the UX. EG: if you had another trigger reusing a resource but filtering the results. `perform` | **yes** | oneOf([/RequestSchema](#requestschema), [/FunctionSchema](#functionschema)) | How will Zapier get the data? This can be a function like `(z) => [{id: 123}]` or a request like `{url: 'http...'}`. `performResume` | no | [/FunctionSchema](#functionschema) | A function that parses data from a perform (which uses z.generateCallbackUrl()) and callback request to resume this action. `performGet` | no | oneOf([/RequestSchema](#requestschema), [/FunctionSchema](#functionschema)) | How will Zapier get a single record? If you find yourself reaching for this - consider resources and their built-in get methods. `inputFields` | no | [/InputFieldsSchema](#inputfieldsschema) | What should the form a user sees and configures look like? `inputFieldGroups` | no | [/InputFieldGroupsSchema](#inputfieldgroupsschema) | Defines groups for organizing input fields in the UI. Each group can have a key, label, and emphasis styling. `outputFields` | no | [/OutputFieldsSchema](#outputfieldsschema) | What fields of data will this return? Will use resource outputFields if missing, will also use sample if available. `sample` | **yes** (with exceptions, see description) | `object` | What does a sample of data look like? Will use resource sample if missing. Requirement waived if `display.hidden` is true or if this belongs to a resource that has a top-level sample `lock` | no | [/LockObjectSchema](#lockobjectschema) | Zapier uses this configuration to ensure this action is performed one at a time per scope (avoid concurrency). `throttle` | no | [/ThrottleObjectSchema](#throttleobjectschema) | Zapier uses this configuration to apply throttling when the limit for the window is exceeded. `cleanInputData` | no | `boolean` | If true, Zapier removes empty strings, `null`, `undefined`, and empty Arrays or objects from `bundle.inputData` recursively before passing it to your `perform*` function. If you want to handle empty values yourself in your code, explicitly set this to false. There is also a global flag with the same name in `App.flags`. This one takes precedence over the global one. #### Examples * `{ perform: { require: 'some/path/to/file.js' }, sample: { id: 42, name: 'Hooli' } }` #### Anti-Examples * `{ perform: { require: 'some/path/to/file.js' } }` - _Missing required key: sample. Note - This is only invalid if `display` is not explicitly set to true and if it does not belong to a resource that has a sample._ ----- ## /BasicCreateOperationSchema Represents the fundamental mechanics of a create. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/BasicCreateOperationSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `resource` | no | [/KeySchema](#keyschema) | Optionally reference and extends a resource. Allows Zapier to automatically tie together samples, lists and hooks, greatly improving the UX. EG: if you had another trigger reusing a resource but filtering the results. `perform` | no (with exceptions, see description) | oneOf([/RequestSchema](#requestschema), [/FunctionSchema](#functionschema)) | How will Zapier get the data? This can be a function like `(z) => [{id: 123}]` or a request like `{url: 'http...'}`. Exactly one of `perform` or `performBuffer` must be defined. If you choose to define `buffer` and `performBuffer`, you must omit `perform`. `performResume` | no | [/FunctionSchema](#functionschema) | A function that parses data from a perform (which uses z.generateCallbackUrl()) and callback request to resume this action. `performGet` | no | oneOf([/RequestSchema](#requestschema), [/FunctionSchema](#functionschema)) | How will Zapier get a single record? If you find yourself reaching for this - consider resources and their built-in get methods. `inputFields` | no | [/InputFieldsSchema](#inputfieldsschema) | What should the form a user sees and configures look like? `inputFieldGroups` | no | [/InputFieldGroupsSchema](#inputfieldgroupsschema) | Defines groups for organizing input fields in the UI. Each group can have a key, label, and emphasis styling. `outputFields` | no | [/OutputFieldsSchema](#outputfieldsschema) | What fields of data will this return? Will use resource outputFields if missing, will also use sample if available. `sample` | **yes** (with exceptions, see description) | `object` | What does a sample of data look like? Will use resource sample if missing. Requirement waived if `display.hidden` is true or if this belongs to a resource that has a top-level sample `lock` | no | [/LockObjectSchema](#lockobjectschema) | Zapier uses this configuration to ensure this action is performed one at a time per scope (avoid concurrency). `throttle` | no | [/ThrottleObjectSchema](#throttleobjectschema) | Zapier uses this configuration to apply throttling when the limit for the window is exceeded. `cleanInputData` | no | `boolean` | If true, Zapier removes empty strings, `null`, `undefined`, and empty Arrays or objects from `bundle.inputData` recursively before passing it to your `perform*` function. If you want to handle empty values yourself in your code, explicitly set this to false. There is also a global flag with the same name in `App.flags`. This one takes precedence over the global one. `buffer` | no (with exceptions, see description) | [/BufferConfigSchema](#bufferconfigschema) | Currently an **internal-only** feature. Zapier uses this configuration for creating objects in bulk with `performBuffer`. `performBuffer` | no (with exceptions, see description) | [/FunctionSchema](#functionschema) | Currently an **internal-only** feature. A function to create objects in bulk with. `buffer` and `performBuffer` must either both be defined or neither. Additionally, only one of `perform` or `performBuffer` can be defined. If you choose to define `perform`, you must omit `buffer` and `performBuffer`. #### Examples * `{ perform: { require: 'some/path/to/file.js' }, sample: { id: 42, name: 'Hooli' } }` #### Anti-Examples * `{ perform: { require: 'some/path/to/file.js' } }` - _Missing required key: sample. Note - This is only invalid if `display` is not explicitly set to true and if it does not belong to a resource that has a sample._ ----- ## /BasicDisplaySchema Represents user information for a trigger, search, or create. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/BasicDisplaySchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `label` | **yes** (with exceptions, see description) | `string` | A short label like "New Record" or "Create Record in Project". Optional if `hidden` is true. `description` | **yes** (with exceptions, see description) | `string` | A description of what this trigger, search, or create does. Optional if `hidden` is true. `directions` | no | `string` | A short blurb that can explain how to get this working. EG: how and where to copy-paste a static hook URL into your application. Only evaluated for static webhooks. `hidden` | no | `boolean` | Should this operation be unselectable by users? #### Examples * `{ hidden: true }` * `{ label: 'New Thing', description: 'Gets a new thing for you.' }` * ``` { label: 'New Thing', description: 'Gets a new thing for you.', directions: 'This is how you use the thing.', hidden: false } ``` #### Anti-Examples * `{ label: 'New Thing', hidden: false }` - _Missing required key: description_ * `{ description: 'Gets a new thing for you.', hidden: false }` - _Missing required key: label_ ----- ## /BasicHookOperationSchema Represents the inbound mechanics of hooks with optional subscribe/unsubscribe. Defers to list for fields. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/BasicHookOperationSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `type` | **yes** (with exceptions, see description) | `string` in (`'hook'`) | Must be explicitly set to `"hook"` unless this hook is defined as part of a resource, in which case it's optional. `resource` | no | [/KeySchema](#keyschema) | Optionally reference and extends a resource. Allows Zapier to automatically tie together samples, lists and hooks, greatly improving the UX. EG: if you had another trigger reusing a resource but filtering the results. `perform` | **yes** | [/FunctionSchema](#functionschema) | A function that processes the inbound webhook request. `performList` | **yes** (with exceptions, see description) | oneOf([/RequestSchema](#requestschema), [/FunctionSchema](#functionschema)) | Fetch a list of items on demand during testing instead of waiting for a hook. You can also consider resources and their built-in hook/list methods. Note: this is required for public apps to ensure the best UX for the end-user. For private apps, this is strongly recommended for testing REST Hooks. Otherwise, you can ignore warnings about this property with the `--without-style` flag during `zapier-platform push`. `canPaginate` | no | `boolean` | Does this endpoint support pagination via temporary cursor storage? `performSubscribe` | **yes** (with exceptions, see description) | oneOf([/RequestSchema](#requestschema), [/FunctionSchema](#functionschema)) | Takes a URL and any necessary data from the user and subscribes. Note: this is required for public apps to ensure the best UX for the end-user. For private apps, this is strongly recommended for testing REST Hooks. Otherwise, you can ignore warnings about this property with the `--without-style` flag during `zapier-platform push`. `performUnsubscribe` | **yes** (with exceptions, see description) | oneOf([/RequestSchema](#requestschema), [/FunctionSchema](#functionschema)) | Takes a URL and data from a previous subscribe call and unsubscribes. Note: this is required for public apps to ensure the best UX for the end-user. For private apps, this is strongly recommended for testing REST Hooks. Otherwise, you can ignore warnings about this property with the `--without-style` flag during `zapier-platform push`. `inputFields` | no | [/InputFieldsSchema](#inputfieldsschema) | What should the form a user sees and configures look like? `inputFieldGroups` | no | [/InputFieldGroupsSchema](#inputfieldgroupsschema) | Defines groups for organizing input fields in the UI. Each group can have a key, label, and emphasis styling. `outputFields` | no | [/OutputFieldsSchema](#outputfieldsschema) | What fields of data will this return? Will use resource outputFields if missing, will also use sample if available. `sample` | **yes** (with exceptions, see description) | `object` | What does a sample of data look like? Will use resource sample if missing. Requirement waived if `display.hidden` is true or if this belongs to a resource that has a top-level sample `cleanInputData` | no | `boolean` | If true, Zapier removes empty strings, `null`, `undefined`, and empty Arrays or objects from `bundle.inputData` recursively before passing it to your `perform*` function. If you want to handle empty values yourself in your code, explicitly set this to false. There is also a global flag with the same name in `App.flags`. This one takes precedence over the global one. #### Examples * ``` { type: 'hook', perform: { require: 'some/path/to/file.js' }, performList: { require: 'some/path/to/file2.js' }, performSubscribe: { require: 'some/path/to/file3.js' }, performUnsubscribe: { require: 'some/path/to/file4.js' }, sample: { id: 42, name: 'Hooli' } } ``` #### Anti-Examples * ``` { type: 'hook', perform: { require: 'some/path/to/file.js' }, performList: { require: 'some/path/to/file2.js' }, performSubscribe: { require: 'some/path/to/file3.js' }, performUnsubscribe: { require: 'some/path/to/file4.js' } } ``` _Missing required key: sample. Note - This is only invalid if `display` is not explicitly set to true and if it does not belong to a resource that has a sample._ ----- ## /BasicOperationSchema Represents the fundamental mechanics of triggers, searches, or creates. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/BasicOperationSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `resource` | no | [/KeySchema](#keyschema) | Optionally reference and extends a resource. Allows Zapier to automatically tie together samples, lists and hooks, greatly improving the UX. EG: if you had another trigger reusing a resource but filtering the results. `perform` | **yes** | oneOf([/RequestSchema](#requestschema), [/FunctionSchema](#functionschema)) | How will Zapier get the data? This can be a function like `(z) => [{id: 123}]` or a request like `{url: 'http...'}`. `inputFields` | no | [/InputFieldsSchema](#inputfieldsschema) | What should the form a user sees and configures look like? `inputFieldGroups` | no | [/InputFieldGroupsSchema](#inputfieldgroupsschema) | Defines groups for organizing input fields in the UI. Each group can have a key, label, and emphasis styling. `outputFields` | no | [/OutputFieldsSchema](#outputfieldsschema) | What fields of data will this return? Will use resource outputFields if missing, will also use sample if available. `sample` | **yes** (with exceptions, see description) | `object` | What does a sample of data look like? Will use resource sample if missing. Requirement waived if `display.hidden` is true or if this belongs to a resource that has a top-level sample `lock` | no | [/LockObjectSchema](#lockobjectschema) | Zapier uses this configuration to ensure this action is performed one at a time per scope (avoid concurrency). `throttle` | no | [/ThrottleObjectSchema](#throttleobjectschema) | Zapier uses this configuration to apply throttling when the limit for the window is exceeded. `cleanInputData` | no | `boolean` | If true, Zapier removes empty strings, `null`, `undefined`, and empty Arrays or objects from `bundle.inputData` recursively before passing it to your `perform*` function. If you want to handle empty values yourself in your code, explicitly set this to false. There is also a global flag with the same name in `App.flags`. This one takes precedence over the global one. #### Examples * `{ perform: { require: 'some/path/to/file.js' }, sample: { id: 42, name: 'Hooli' } }` #### Anti-Examples * `{ perform: { require: 'some/path/to/file.js' } }` - _Missing required key: sample. Note - This is only invalid if `display` is not explicitly set to true and if it does not belong to a resource that has a sample._ ----- ## /BasicPollingOperationSchema Represents the fundamental mechanics of a trigger. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/BasicPollingOperationSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `type` | no | `string` in (`'polling'`) | Clarify how this operation works (polling == pull or hook == push). `resource` | no | [/KeySchema](#keyschema) | Optionally reference and extends a resource. Allows Zapier to automatically tie together samples, lists and hooks, greatly improving the UX. EG: if you had another trigger reusing a resource but filtering the results. `perform` | **yes** | oneOf([/RequestSchema](#requestschema), [/FunctionSchema](#functionschema)) | How will Zapier get the data? This can be a function like `(z) => [{id: 123}]` or a request like `{url: 'http...'}`. `canPaginate` | no | `boolean` | Does this endpoint support pagination via temporary cursor storage? `inputFields` | no | [/InputFieldsSchema](#inputfieldsschema) | What should the form a user sees and configures look like? `inputFieldGroups` | no | [/InputFieldGroupsSchema](#inputfieldgroupsschema) | Defines groups for organizing input fields in the UI. Each group can have a key, label, and emphasis styling. `outputFields` | no | [/OutputFieldsSchema](#outputfieldsschema) | What fields of data will this return? Will use resource outputFields if missing, will also use sample if available. `sample` | **yes** (with exceptions, see description) | `object` | What does a sample of data look like? Will use resource sample if missing. Requirement waived if `display.hidden` is true or if this belongs to a resource that has a top-level sample `throttle` | no | [/ThrottleObjectSchema](#throttleobjectschema) | Zapier uses this configuration to apply throttling when the limit for the window is exceeded. `cleanInputData` | no | `boolean` | If true, Zapier removes empty strings, `null`, `undefined`, and empty Arrays or objects from `bundle.inputData` recursively before passing it to your `perform*` function. If you want to handle empty values yourself in your code, explicitly set this to false. There is also a global flag with the same name in `App.flags`. This one takes precedence over the global one. #### Examples * `{ perform: { require: 'some/path/to/file.js' }, sample: { id: 42, name: 'Hooli' } }` #### Anti-Examples * `{ perform: { require: 'some/path/to/file.js' } }` - _Missing required key: sample. Note - This is only invalid if `display` is not explicitly set to true and if it does not belong to a resource that has a sample._ ----- ## /BasicSearchOperationSchema Represents the fundamental mechanics of a search. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/BasicSearchOperationSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `resource` | no | [/KeySchema](#keyschema) | Optionally reference and extends a resource. Allows Zapier to automatically tie together samples, lists and hooks, greatly improving the UX. EG: if you had another trigger reusing a resource but filtering the results. `perform` | **yes** | oneOf([/RequestSchema](#requestschema), [/FunctionSchema](#functionschema)) | How will Zapier get the data? This can be a function like `(z) => [{id: 123}]` or a request like `{url: 'http...'}`. `performResume` | no | [/FunctionSchema](#functionschema) | A function that parses data from a perform (which uses z.generateCallbackUrl()) and callback request to resume this action. `performGet` | no | oneOf([/RequestSchema](#requestschema), [/FunctionSchema](#functionschema)) | How will Zapier get a single record? If you find yourself reaching for this - consider resources and their built-in get methods. `canPaginate` | no | `boolean` | Does this search support pagination? `inputFields` | no | [/InputFieldsSchema](#inputfieldsschema) | What should the form a user sees and configures look like? `inputFieldGroups` | no | [/InputFieldGroupsSchema](#inputfieldgroupsschema) | Defines groups for organizing input fields in the UI. Each group can have a key, label, and emphasis styling. `outputFields` | no | [/OutputFieldsSchema](#outputfieldsschema) | What fields of data will this return? Will use resource outputFields if missing, will also use sample if available. `sample` | **yes** (with exceptions, see description) | `object` | What does a sample of data look like? Will use resource sample if missing. Requirement waived if `display.hidden` is true or if this belongs to a resource that has a top-level sample `lock` | no | [/LockObjectSchema](#lockobjectschema) | Zapier uses this configuration to ensure this action is performed one at a time per scope (avoid concurrency). `throttle` | no | [/ThrottleObjectSchema](#throttleobjectschema) | Zapier uses this configuration to apply throttling when the limit for the window is exceeded. `cleanInputData` | no | `boolean` | If true, Zapier removes empty strings, `null`, `undefined`, and empty Arrays or objects from `bundle.inputData` recursively before passing it to your `perform*` function. If you want to handle empty values yourself in your code, explicitly set this to false. There is also a global flag with the same name in `App.flags`. This one takes precedence over the global one. #### Examples * `{ perform: { require: 'some/path/to/file.js' }, sample: { id: 42, name: 'Hooli' } }` #### Anti-Examples * `{ perform: { require: 'some/path/to/file.js' } }` - _Missing required key: sample. Note - This is only invalid if `display` is not explicitly set to true and if it does not belong to a resource that has a sample._ ----- ## /BufferConfigSchema Currently an **internal-only** feature. Zapier uses this configuration for creating objects in bulk. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/BufferConfigSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `groupedBy` | **yes** | `array` | The list of keys of input fields to group bulk-create with. The actual user data provided for the fields will be used during execution. Note that a required input field should be referenced to get user data always. `limit` | **yes** | `integer` | The maximum number of items to call `performBuffer` with. **Note** that it is capped by the platform to prevent exceeding the [AWS Lambda's request/response payload size quota of 6 MB](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html#function-configuration-deployment-and-execution). Also, the execution is time-bound; we recommend reducing it upon consistent timeout. #### Examples * `{ groupedBy: [ 'workspace', 'sheet' ], limit: 100 }` #### Anti-Examples * `{ groupedBy: [], limit: 100 }` - _Empty groupedBy list provided: `[]`._ * `{ groupedBy: [ 'workspace' ] }` - _Missing required key: `limit`._ * `{ limit: 1 }` - _Missing required key: `groupedBy`._ ----- ## /BulkReadSchema How will Zapier fetch resources from your application? #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/BulkReadSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `key` | **yes** | [/KeySchema](#keyschema) | A key to uniquely identify a record. `noun` | **yes** | `string` | A noun for this read that completes the sentence "reads all of the XXX". `display` | **yes** | [/BasicDisplaySchema](#basicdisplayschema) | Configures the UI for this read bulk. `operation` | **yes** | [/BasicActionOperationSchema](#basicactionoperationschema) | Powers the functionality for this read bulk. #### Examples * ``` { key: 'recipes', noun: 'Recipes', display: { label: 'Recipes', description: 'A Read that lets Zapier fetch all recipes.' }, operation: { perform: '$func$0$f$', sample: { id: 1, firstName: 'Walter', lastName: 'Sobchak', occupation: 'Bowler' } } } ``` #### Anti-Examples * ``` { display: { label: 'Get User', description: 'Retrieve a user.' }, operation: { description: 'Define how this search method will work.' } } ``` _Missing required keys: key and noun_ ----- ## /BulkReadsSchema Enumerates the bulk reads your app exposes. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/BulkReadsSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `^[a-zA-Z]+[a-zA-Z0-9_]*$` | no | [/BulkReadSchema](#bulkreadschema) | Any unique key can be used and its values will be validated against the BulkReadSchema. #### Examples * ``` { recipes: { key: 'recipes', noun: 'Recipes', display: { label: 'Recipes', description: 'A Read that lets Zapier fetch all recipes.' }, operation: { perform: '$func$0$f$', sample: { id: 1, firstName: 'Walter', lastName: 'Sobchak', occupation: 'Bowler' } } } } ``` #### Anti-Examples * ``` { readRecipes: { key: 'recipes', noun: 'Recipes', display: { label: 'Recipes', description: 'A Read that lets Zapier fetch all recipes.' }, operation: { perform: '$func$0$f$', sample: { id: 1, firstName: 'Walter', lastName: 'Sobchak', occupation: 'Bowler' } } } } ``` _Key must match the key of the associated BulkReadSchema_ ----- ## /CreateSchema How will Zapier create a new object? #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/CreateSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `key` | **yes** | [/KeySchema](#keyschema) | A key to uniquely identify this create. `noun` | **yes** | `string` | A noun for this create that completes the sentence "creates a new XXX". `display` | **yes** | [/BasicDisplaySchema](#basicdisplayschema) | Configures the UI for this create. `operation` | **yes** | [/BasicCreateOperationSchema](#basiccreateoperationschema) | Powers the functionality for this create. #### Examples * ``` { key: 'recipe', noun: 'Recipe', display: { label: 'Create Recipe', description: 'Creates a new recipe.' }, operation: { perform: '$func$2$f$', sample: { id: 1 } } } ``` * ``` { key: 'recipe', noun: 'Recipe', display: { label: 'Create Recipe', description: 'Creates a new recipe.', hidden: true }, operation: { perform: '$func$2$f$' } } ``` #### Anti-Examples * `'abc'` - _Must be an object_ * ``` { key: 'recipe', noun: 'Recipe', display: { label: 'Create Recipe', description: 'Creates a new recipe.' }, operation: { perform: '$func$2$f$' } } ``` _Missing required key on operation: sample. Note - this is valid if the resource has defined a sample._ ----- ## /CreatesSchema Enumerates the creates your app has available for users. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/CreatesSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `^[a-zA-Z]+[a-zA-Z0-9_]*$` | no | [/CreateSchema](#createschema) | Any unique key can be used and its values will be validated against the CreateSchema. #### Examples * ``` { createRecipe: { key: 'createRecipe', noun: 'Recipe', display: { label: 'Create Recipe', description: 'Creates a new recipe.' }, operation: { perform: '$func$2$f$', sample: { id: 1 } } } } ``` * ``` { Create_Recipe_01: { key: 'Create_Recipe_01', noun: 'Recipe', display: { label: 'Create Recipe', description: 'Creates a new recipe.' }, operation: { perform: '$func$2$f$', sample: { id: 1 } } } } ``` #### Anti-Examples * ``` { '01_Create_Recipe': { key: '01_Create_Recipe', noun: 'Recipe', display: { label: 'Create Recipe', description: 'Creates a new recipe.' }, operation: { perform: '$func$2$f$', sample: { id: 1 } } } } ``` _Key must start with a letter_ * ``` { Create_Recipe: { key: 'createRecipe', noun: 'Recipe', display: { label: 'Create Recipe', description: 'Creates a new recipe.' }, operation: { perform: '$func$2$f$', sample: { id: 1 } } } } ``` _Key must match the key field in CreateSchema_ ----- ## /FieldChoiceWithLabelSchema An object describing a labeled choice in a static dropdown. Useful if the value a user picks isn't exactly what the zap uses. For instance, when they click on a nickname, but the zap uses the user's full name ([image](https://cdn.zapier.com/storage/photos/8ed01ac5df3a511ce93ed2dc43c7fbbc.png)). #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/FieldChoiceWithLabelSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `value` | **yes** | `string` | The actual value that is sent into the Zap. This is displayed as light grey text in the editor. Should match sample exactly. `sample` | **yes** | `string` | A legacy field that is no longer used by the editor, but it is still required for now and should match the value. `label` | **yes** | `string` | A human readable label for this value. #### Examples * `{ label: 'Red', sample: '#f00', value: '#f00' }` #### Anti-Examples * `{ label: 'Red', value: '#f00' }` - _Missing required key: sample_ ----- ## /FieldChoicesSchema A static dropdown of options. Which you use depends on your order and label requirements: Need a Label? | Does Order Matter? | Type to Use ---|---|--- Yes | No | Object of value -> label No | Yes | Array of Strings Yes | Yes | Array of [FieldChoiceWithLabel](#fieldchoicewithlabelschema) #### Details * **Type** - oneOf(`object`, `array`[oneOf(`string`, [/FieldChoiceWithLabelSchema](#fieldchoicewithlabelschema))]) * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/FieldChoicesSchema.js) #### Examples * `{ a: '1', b: '2', c: '3' }` * `[ 'first', 'second', 'third' ]` #### Anti-Examples * `[ 1, 2, 3 ]` - _If an array, must be of either type string or FieldChoiceWithLabelSchema_ * `[ { a: '1', b: '2', c: '3' } ]` - _If an array, must be of either type string or FieldChoiceWithLabelSchema_ ----- ## /FieldDynamicChoicesSchema Describes dynamic dropdowns powered by a perform function or request. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/FieldDynamicChoicesSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `perform` | **yes** | oneOf([/FunctionSchema](#functionschema), [/RequestSchema](#requestschema)) | A function or request that returns choices for this dynamic dropdown. #### Examples * `{ perform: '$func$0$f$' }` * `{ perform: { source: 'return []' } }` * `{ perform: { method: 'GET', url: 'https://api.example.com/choices' } }` #### Anti-Examples * `{}` - _Missing required key: perform_ * `{ someKey: 'value' }` - _Missing required key: perform_ * `{ perform: 'invalid' }` - _Invalid value for key: perform (must be a function or request)_ * `{ perform: '$func$0$f$', unknownKey: 'value' }` - _Invalid extra property: unknownKey_ ----- ## /FieldMetaSchema Allows for additional metadata to be stored on the field. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/FieldMetaSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `[^\s]+` | no | anyOf(`string`, `integer`, `boolean`) | Only string, integer or boolean values are allowed. #### Examples * `{ shouldCapitalize: true }` * `{ shouldCapitalize: true, internalType: 'datetime' }` #### Anti-Examples * `{ databank: { primaryContact: 'abc' } }` - _No complex values allowed_ * `{ needsProcessing: null }` - _No null values allowed_ ----- ## /FlatObjectSchema An object whose values can only be primitives #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/FlatObjectSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `[^\s]+` | no | anyOf(`null`, `string`, `integer`, `number`, `boolean`) | Any key may exist in this flat object as long as its values are simple. #### Examples * `{ a: 1, b: 2, c: 3 }` * `{ a: 1.2, b: 2.2, c: 3.3 }` * `{ a: 'a', b: 'b', c: 'c' }` * `{ a: true, b: true, c: false }` * `{ a: 'a', b: 2, c: 3.1, d: true, e: false }` * `{ '123': 'hello' }` #### Anti-Examples * `{ a: {}, b: 2 }` - _Invalid value for key: a (objects are not allowed)_ * `{ a: [], b: 2 }` - _Invalid value for key: a (arrays are not allowed)_ * `{ '': 1 }` - _Key cannot be empty_ ----- ## /FunctionRequireSchema A path to a file that might have content like `module.exports = (z, bundle) => [{id: 123}];`. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/FunctionRequireSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `require` | **yes** | `string` | _No description given._ #### Examples * `{ require: 'some/path/to/file.js' }` #### Anti-Examples * `{}` - _Missing required key: require_ * `{ required: 2 }` - _Invalid value for key: required (must be of type string)_ ----- ## /FunctionSchema Internal pointer to a function from the original source or the source code itself. Encodes arity and if `arguments` is used in the body. Note - just write normal functions and the system will encode the pointers for you. Or, provide {source: "return 1 + 2"} and the system will wrap in a function for you. #### Details * **Type** - oneOf(`string`, [/FunctionRequireSchema](#functionrequireschema), [/FunctionSourceSchema](#functionsourceschema)) * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/FunctionSchema.js) #### Examples * `'$func$0$f$'` * `'$func$2$t$'` * `{ source: 'return 1 + 2' }` * `{ require: 'some/path/to/file.js' }` #### Anti-Examples * `'funcy'` - _Invalid function reference_ * `{ source: '1 + 2' }` - _Invalid value for key: source (must end with a `return` statement)_ * `{ source: '1 + 2', require: 'some/path/to/file.js' }` - _Must be either /FunctionRequireSchema _or_ /FunctionSourceSchema_ ----- ## /FunctionSourceSchema Source code like `{source: "return 1 + 2"}` which the system will wrap in a function for you. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/FunctionSourceSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `source` | **yes** | `string` | JavaScript code for the function body. This must end with a `return` statement. `args` | no | `array`[`string`] | Function signature. Defaults to `['z', 'bundle']` if not specified. #### Examples * `{ source: 'return 1 + 2' }` * `{ args: [ 'x', 'y' ], source: 'return x + y;' }` #### Anti-Examples * `{ source: '1 + 2' }` - _Invalid value for key: source (must end with a `return` statement)_ ----- ## /HydratorsSchema A bank of named functions that you can use in `z.hydrate('someName')` to lazily load data. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/HydratorsSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `^[a-zA-Z]+[a-zA-Z0-9]*$` | no | [/FunctionSchema](#functionschema) | Any unique key can be used in `z.hydrate('uniqueKeyHere')`. #### Examples * `{ hydrateFile: { require: 'some/path/to/file.js' } }` #### Anti-Examples * `{ '12th': { require: 'some/path/to/file.js' } }` - _Invalid key (must start with a letter)_ ----- ## /InputFieldGroupSchema Object for visual grouping of input fields. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/InputFieldGroupSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `key` | **yes** | [/KeySchema](#keyschema) | The unique identifier for this group. `label` | no | `string` | The human-readable name for the group. `emphasize` | no | `boolean` | Whether this group should be visually emphasized in the UI. #### Examples * `{ key: 'testGroup' }` * `{ key: 'testGroup', label: 'Test Group', emphasize: true }` #### Anti-Examples * `{ label: 'test label' }` - _key is required_ ----- ## /InputFieldGroupsSchema An array or collection of input field groups. #### Details * **Type** - `array`[[/InputFieldGroupSchema](#inputfieldgroupschema)] * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/InputFieldGroupsSchema.js) #### Examples * `[ { key: 'abc' } ]` #### Anti-Examples * `{}` - _Must be an array_ * `[ { label: 'test label' } ]` - _key is required_ ----- ## /InputFieldsSchema An array or collection of input fields. #### Details * **Type** - `array`[oneOf([/PlainInputFieldSchema](#plaininputfieldschema), [/FunctionSchema](#functionschema))] * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/InputFieldsSchema.js) #### Examples * `[ { key: 'abc' } ]` #### Anti-Examples * `{}` - _Must be an array_ ----- ## /JsonSchemaSchema A JSON Schema object that describes the expected structure of a JSON value. Validated against JSON Schema Draft 4, 6, or 7 meta-schema (based on the `$schema` field, defaulting to Draft 7) via the validateJsonFieldSchema functional constraint. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/JsonSchemaSchema.js) #### Examples * `{ type: 'object', properties: { name: { type: 'string' } } }` * `{ type: 'array', items: { type: 'string' } }` * `{}` * ``` { allOf: [ { type: 'object' }, { properties: { name: { type: 'string' } } } ], not: { type: 'array' } } ``` * ``` { type: 'object', properties: { name: { type: 'string' }, age: { type: 'integer' } }, required: [ 'name' ], additionalProperties: false } ``` * ``` { '$schema': 'http://json-schema.org/draft-07/schema#', type: 'object', properties: { name: { type: 'string' } } } ``` #### Anti-Examples * `[ 'not', 'an', 'object' ]` - _JSON Schema must be an object, not an array_ * `{ type: 'string' }` - _JSON Schema type should be an object or an array. If a primitive is needed, use `type: 'string'` on the input field directly_ ----- ## /KeySchema A unique identifier for this item. #### Details * **Type** - `string` * **Pattern** - `^[a-zA-Z]+[a-zA-Z0-9_]*$` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/KeySchema.js) #### Examples * `'vk'` * `'validKey'` * `'ValidKey'` * `'Valid_Key_2'` #### Anti-Examples * `''` - _Cannot be empty_ * `'A'` - _Minimum of two characters_ * `'1_Key'` - _Must start with a letter_ * `'a-Key'` - _Must not use dashes_ ----- ## /LockObjectSchema Zapier uses this configuration to ensure this action is performed one at a time per scope (avoid concurrency). #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/LockObjectSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `key` | **yes** | `string` | The key to use for locking. This should be unique to the operation. While actions of different integrations with the same key and scope will never lock each other out, actions of the same integration with the same key and scope will do. User data provided for the input fields can be used in the key with the use of the curly braces referencing. For example, to access the user data provided for the input field "test_field", use `{{bundle.inputData.test_field}}`. Note that a required input field should be referenced to get user data always. `scope` | no | `array`[`string` in (`'user'`, `'auth'`, `'account'`)] | By default, locks are scoped to the app. That is, all users of the app will share the same locks. If you want to restrict serial access to a specific user, auth, or account, you can set the scope to one or more of the following: 'user' - Locks based on user ids. 'auth' - Locks based on unique auth ids. 'account' - Locks for all users under a single account. You may also combine scopes. Note that "app" is included, always, in the scope provided. For example, a scope of ['account', 'auth'] would result to ['app', 'account', 'auth']. `timeout` | no | `integer` | The number of seconds to hold the lock before releasing it to become accessible to other task invokes that need it. If not provided, the default set by the app will be used. It cannot be more than 180. #### Examples * `{ key: 'random_key', scope: [ 'account', 'user' ], timeout: 30 }` * `{ key: '{{bundle.inputData.test_field}}' }` #### Anti-Examples * `{ key: 'random_key', scope: [ 'zap' ] }` - _Invalid scope provided: `zap`._ * `{}` - _Missing required key: `key`._ ----- ## /MiddlewaresSchema List of before or after middlewares. Can be an array of functions or a single function #### Details * **Type** - oneOf(`array`[[/FunctionSchema](#functionschema)], [/FunctionSchema](#functionschema)) * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/MiddlewaresSchema.js) #### Examples * `{ require: 'some/path/to/file.js' }` * `[ { require: 'some/path/to/file.js' } ]` #### Anti-Examples * `{}` - _Does not match either /FunctionSchema or an array of such_ ----- ## /OutputFieldsSchema An array or collection of output fields. #### Details * **Type** - `array`[oneOf([/PlainOutputFieldSchema](#plainoutputfieldschema), [/FunctionSchema](#functionschema))] * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/OutputFieldsSchema.js) #### Examples * `[ { key: 'abc' } ]` #### Anti-Examples * `{}` - _Must be an array_ ----- ## /PlainInputFieldSchema Field schema specialized for input fields. In addition to the requirements below, the following keys are mutually exclusive: * `children` & `list` * `children` & `dict` * `children` & `type` * `children` & `placeholder` * `children` & `helpText` * `children` & `default` * `dict` & `list` * `dynamic` & `dict` * `dynamic` & `choices` #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/PlainInputFieldSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `key` | **yes** | `string` | A unique machine readable key for this value (IE: "fname"). `label` | no | `string` | A human readable label for this value (IE: "First Name"). `type` | no | `string` in (`'string'`, `'text'`, `'integer'`, `'number'`, `'boolean'`, `'datetime'`, `'file'`, `'password'`, `'copy'`, `'code'`, `'json'`) | The type of this value. Use `string` for basic text input, `text` for a large, `` style box, and `code` for a `<textarea>` with a fixed-width font. Field type of `file` will accept either a file object or a string. If a URL is provided in the string, Zapier will automatically make a GET for that file. Otherwise, a .txt file will be generated. `required` | no | `boolean` | If this value is required or not. `default` | no | `string` | A default value that is saved the first time a Zap is created. `list` | no | `boolean` | Acts differently when used in inputFields vs. when used in outputFields. In inputFields: Can a user provide multiples of this field? In outputFields: Does this field return an array of items of type `type`? `children` | no | `array`[[/PlainInputFieldSchema](#plaininputfieldschema)] | An array of child fields that define the structure of a sub-object for this field. Usually used for line items. `dict` | no | `boolean` | Is this field a key/value input? `helpText` | no | `string` | A human readable description of this value (IE: "The first part of a full name."). You can use Markdown. `search` | no | [/RefResourceSchema](#refresourceschema) | A reference to a search that will guide the user to add a search step to populate this field when creating a Zap. `dynamic` | no | [/RefResourceSchema](#refresourceschema) | A reference to a trigger that will power a dynamic dropdown. `dependsOn` | no | `array`[`string`] | Specifies which other input fields this field depends on. These must be filled before this one becomes enabled, and when their values change, this field's value should be cleared. `resource` | no | `string` | Explicitly links this input field to a resource. Use the resource key (e.g., "spreadsheet") or dot notation for resource fields (e.g., "spreadsheet.url"). If not set for dynamic dropdowns, the resource is derived implicitly from the `dynamic` property. `choices` | no | oneOf([/FieldChoicesSchema](#fieldchoicesschema), [/FieldDynamicChoicesSchema](#fielddynamicchoicesschema)) | Describes how to populate this dropdown. Can be a static list or a dynamic object with pagination and search support. `placeholder` | no | `string` | An example value that is not saved. `altersDynamicFields` | no | `boolean` | Does the value of this field affect the definitions of other fields in the set? `computed` | no | `boolean` | Is this field automatically populated (and hidden from the user)? Note: Only OAuth, Session Auth, and certain internal use cases support fields with this key. `inputFormat` | no | `string` | Useful when you expect the input to be part of a longer string. Put "{{input}}" in place of the user's input (IE: "https://{{input}}.yourdomain.com"). `meta` | no | [/FieldMetaSchema](#fieldmetaschema) | Allows for additional metadata to be stored on the field. Supports simple key-values only (no sub-objects or arrays). `group` | no | [/KeySchema](#keyschema) | References a group key from the operation's inputFieldGroups to organize this field with others. `schema` | no | [/JsonSchemaSchema](#jsonschemaschema) | A JSON Schema object that describes the expected structure of the JSON value. Only valid when `type` is `json`. #### Examples * `{ key: 'abc' }` * `{ key: 'abc', choices: { mobile: 'Mobile Phone' } }` * `{ key: 'abc', choices: [ 'first', 'second', 'third' ] }` * `{ key: 'abc', choices: [ { label: 'Red', sample: '#f00', value: '#f00' } ] }` * `{ key: 'abc', choices: { perform: '$func$0$f$' } }` * `{ key: 'abc', children: [ { key: 'abc' } ] }` * `{ key: 'abc', type: 'integer' }` * ``` { key: 'abc', type: 'integer', meta: { internalType: 'numeric', should_call_api: true, display_order: 1 } } ``` * `{ key: 'name', group: 'contact' }` * `{ key: 'email', group: 'contact' }` * ``` { key: 'payload', type: 'json', schema: { type: 'object', properties: { name: { type: 'string' } } } } ``` * `{ key: 'spreadsheet', dependsOn: [ 'folder' ] }` * `{ key: 'worksheet', dependsOn: [ 'folder', 'spreadsheet' ] }` * `{ key: 'spreadsheet_id', resource: 'spreadsheet', choices: { perform: '$func$0$f$' } }` #### Anti-Examples * `{}` - _Missing required key: key_ * `{ key: 'abc', type: 'loltype' }` - _Invalid value for key: type_ * `{ key: 'abc', choices: {} }` - _Invalid value for key: choices (cannot be empty)_ * `{ key: 'abc', choices: [] }` - _Invalid value for key: choices (cannot be empty)_ * `{ key: 'abc', choices: [ 3 ] }` - _Invalid value for key: choices (if an array, must be of either string or FieldChoiceWithLabelSchema)_ * `{ key: 'abc', choices: [ { label: 'Red', value: '#f00' } ] }` - _Invalid value for key: choices (if an array of FieldChoiceWithLabelSchema, must provide key `sample`)_ * `{ key: 'abc', choices: 'mobile' }` - _Invalid value for key: choices (must be either object or array)_ * `{ key: 'abc', type: 'string', schema: { type: 'object' } }` - _schema is only valid when type is json_ * `{ key: 'abc', type: 'json', schema: { type: 'foobar' } }` - _schema must contain a valid JSON Schema (invalid type)_ * `{ key: 'abc', children: [ '$func$2$f$' ] }` - _Invalid value for key: children (must be array of PlainInputFieldSchema)_ ----- ## /PlainOutputFieldSchema Field schema specialized for output fields. In addition to the requirements below, the following keys are mutually exclusive: * `children` & `list` * `children` & `dict` * `children` & `type` * `children` & `placeholder` * `children` & `helpText` * `children` & `default` * `dict` & `list` * `dynamic` & `dict` * `dynamic` & `choices` #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/PlainOutputFieldSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `key` | **yes** | `string` | A unique machine readable key for this value (IE: "fname"). `label` | no | `string` | A human readable label for this value (IE: "First Name"). `type` | no | `string` in (`'string'`, `'number'`, `'boolean'`, `'datetime'`, `'file'`, `'password'`, `'integer'`) | The type of this value. Field type of `file` will accept either a file object or a string. If a URL is provided in the string, Zapier will automatically make a GET for that file. Otherwise, a .txt file will be generated. `required` | no | `boolean` | If this value is required or not. `default` | no | `string` | A default value that is saved the first time a Zap is created. `list` | no | `boolean` | Acts differently when used in inputFields vs. when used in outputFields. In inputFields: Can a user provide multiples of this field? In outputFields: Does this field return an array of items of type `type`? `children` | no | `array`[[/PlainOutputFieldSchema](#plainoutputfieldschema)] | An array of child fields that define the structure of a sub-object for this field. Usually used for line items. `dict` | no | `boolean` | Is this field a key/value input? `primary` | no | `boolean` | Use this field as part of the primary key for deduplication. You can set multiple fields as "primary", provided they are unique together. If no fields are set, Zapier will default to using the `id` field. `primary` only makes sense for `outputFields`. It only works in static `outputFields`; will not work in custom/dynamic `outputFields`. For more information, see [How deduplication works in Zapier](https://platform.zapier.com/build/deduplication). `steadyState` | no | `boolean` | Prevents triggering on new output until all values for fields with this property remain unchanged for 2 polls. It can be used to, e.g., not trigger on a new contact until the contact has completed typing their name. NOTE that this only applies to the `outputFields` of polling triggers. `sample` | no | oneOf(`string`, `number`, `boolean`, `object`, `array`, `null`) | An example value for this field. Can be any type (string, number, boolean, object, array, null) to match the expected field output. Values provided here will be combined with values in the operation level `sample` field, with this field taking precedence. This is most useful when using a function to generate dynamic `outputFields`. #### Examples * `{ key: 'abc' }` * `{ key: 'abc', children: [ { key: 'abc' } ] }` * `{ key: 'abc', type: 'number', label: 'neat' }` * `{ key: 'abc', type: 'number' }` * `{ key: 'name', type: 'string', sample: 'John Doe' }` * `{ key: 'price', type: 'number', sample: 29.99 }` * `{ key: 'is_active', type: 'boolean', sample: true }` * `{ key: 'tags', list: true, sample: [ 'work', 'urgent' ] }` * `{ key: 'metadata', sample: { created_at: '2025-01-15', author: 'system' } }` * ``` { key: 'address', sample: { street: '123 Main St', city: 'London' }, children: [ { key: 'street', sample: '123 Main St' }, { key: 'city', sample: 'London' } ] } ``` #### Anti-Examples * `{}` - _Missing required key: key_ * `{ key: 'abc', type: 'loltype' }` - _Invalid value for key: type_ * `{ key: 'abc', choices: {} }` - _Invalid value for key: choices (cannot be empty)_ * `{ key: 'abc', choices: [] }` - _Invalid value for key: choices (cannot be empty)_ * `{ key: 'abc', choices: [ 3 ] }` - _Invalid value for key: choices (if an array, must be of either string or FieldChoiceWithLabelSchema)_ * `{ key: 'abc', choices: [ { label: 'Red', value: '#f00' } ] }` - _Invalid value for key: choices (if an array of FieldChoiceWithLabelSchema, must provide key `sample`)_ * `{ key: 'abc', choices: 'mobile' }` - _Invalid value for key: choices (must be either object or array)_ * `{ key: 'abc', children: [ '$func$2$f$' ] }` - _Invalid value for key: children (must be array of PlainOutputFieldSchema)_ ----- ## /RedirectRequestSchema A representation of a HTTP redirect - you can use the `{{syntax}}` to inject authentication, field or global variables. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/RedirectRequestSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `method` | no | `string` in (`'GET'`) | The HTTP method for the request. `url` | no | `string` | A URL for the request (we will parse the querystring and merge with params). Keys and values will not be re-encoded. `params` | no | [/FlatObjectSchema](#flatobjectschema) | A mapping of the querystring - will get merged with any query params in the URL. Keys and values will be encoded. #### Examples * `{ method: 'GET', url: 'https://google.com' }` #### Anti-Examples * `{ method: 'POST', url: 'https://google.com' }` - _Invalid value for key: method_ ----- ## /RefResourceSchema Reference a resource by key and the data it returns. In the format of: `{resource_key}.{foreign_key}(.{human_label_key})`. #### Details * **Type** - `string` * **Pattern** - `^[a-zA-Z0-9_]+\.[a-zA-Z0-9_\s\[\]]+(\.[a-zA-Z0-9_\s\[\]]+(,[a-zA-Z0-9_\s\[\]]+)*)?$` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/RefResourceSchema.js) #### Examples * `'contact.id'` * `'contact.id.name'` * `'contact.id.firstName,lastName'` * `'contact.id.first_name,last_name,email'` * `'contact.Contact Id.Full Name'` * `'contact.data[]id.data[]First Name,data[]Last Name'` #### Anti-Examples * `'Contact List'` - _Does not match resource_key pattern_ * `'Contact.list,find.id'` - _Does not match foreign_key pattern_ * `'Contact.list.id.full_name'` - _Does not match human_label_key pattern_ ----- ## /RequestSchema A representation of a HTTP request - you can use the `{{syntax}}` to inject authentication, field or global variables. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/RequestSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `method` | no | `string` in (`'GET'`, `'PUT'`, `'POST'`, `'PATCH'`, `'DELETE'`, `'HEAD'`) | The HTTP method for the request. `url` | no | `string` | A URL for the request (we will parse the querystring and merge with params). Keys and values will not be re-encoded. `body` | no | oneOf(`null`, `string`, `object`, `array`) | Can be nothing, a raw string or JSON (object or array). `params` | no | [/FlatObjectSchema](#flatobjectschema) | A mapping of the querystring - will get merged with any query params in the URL. Keys and values will be encoded. `headers` | no | [/FlatObjectSchema](#flatobjectschema) | The HTTP headers for the request. `auth` | no | oneOf(`array`[`string`], [/FlatObjectSchema](#flatobjectschema)) | An object holding the auth parameters for OAuth1 request signing, like `{oauth_token: 'abcd', oauth_token_secret: '1234'}`. Or an array reserved (i.e. not implemented yet) to hold the username and password for Basic Auth. Like `['AzureDiamond', 'hunter2']`. `removeMissingValuesFrom` | no | `object` | Should missing values be sent? (empty strings, `null`, and `undefined` only — `[]`, `{}`, and `false` will still be sent). Allowed fields are `params` and `body`. The default is `false`, ex: ```removeMissingValuesFrom: { params: false, body: false }``` `serializeValueForCurlies` | no | [/FunctionSchema](#functionschema) | A function to customize how to serialize a value for curlies `{{var}}` in the request object. By default, when this is unspecified, the request client only replaces curlies where variables are strings, and would throw an error for non-strings. The function should accepts a single argument as the value to be serialized and return the string representation of the argument. `skipThrowForStatus` | no | `boolean` | If `true`, don't throw an exception for response 400 <= status < 600 automatically before resolving with the response. Defaults to `false`. `skipEncodingChars` | no | `string` | Contains the characters that you want left unencoded in the query params (`req.params`). If unspecified, `z.request()` will percent-encode non-ascii characters and these reserved characters: ``:$/?#[]@$&+,;=^@`\``. #### Examples * `{ method: 'GET', url: 'https://zapier.com' }` #### Anti-Examples * `{ method: 'SUPERCHARGE', url: 'https://zapier.com' }` - _Invalid value for key: method_ ----- ## /ResourceMethodCreateSchema How will we find create a specific object given inputs? Will be turned into a create automatically. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/ResourceMethodCreateSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `display` | **yes** | [/BasicDisplaySchema](#basicdisplayschema) | Define how this create method will be exposed in the UI. `operation` | **yes** | [/BasicActionOperationSchema](#basicactionoperationschema) | Define how this create method will work. #### Examples * ``` { display: { label: 'Create Tag', description: 'Create a new Tag in your account.' }, operation: { perform: '$func$2$f$', sample: { id: 1 } } } ``` * ``` { display: { label: 'Create Tag', description: 'Create a new Tag in your account.', hidden: true }, operation: { perform: '$func$2$f$' } } ``` #### Anti-Examples * ``` { display: { label: 'Create Tag', description: 'Create a new Tag in your account.' }, operation: { perform: '$func$2$f$' } } ``` _Missing key from operation: sample. Note – this is valid if the resource has defined a sample._ ----- ## /ResourceMethodGetSchema How will we get a single object given a unique identifier/id? #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/ResourceMethodGetSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `display` | **yes** | [/BasicDisplaySchema](#basicdisplayschema) | Define how this get method will be exposed in the UI. `operation` | **yes** | [/BasicOperationSchema](#basicoperationschema) | Define how this get method will work. #### Examples * ``` { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' }, operation: { perform: { url: '$func$0$f$' }, sample: { id: 385, name: 'proactive enable ROI' } } } ``` * ``` { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.', hidden: true }, operation: { perform: { url: '$func$0$f$' } } } ``` #### Anti-Examples * ``` { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' }, operation: { perform: { url: '$func$0$f$' } } } ``` _Missing key from operation: sample. Note – this is valid if the resource has defined a sample._ ----- ## /ResourceMethodHookSchema How will we get notified of new objects? Will be turned into a trigger automatically. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/ResourceMethodHookSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `display` | **yes** | [/BasicDisplaySchema](#basicdisplayschema) | Define how this hook/trigger method will be exposed in the UI. `operation` | **yes** | [/BasicHookOperationSchema](#basichookoperationschema) | Define how this hook/trigger method will work. #### Examples * ``` { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' }, operation: { type: 'hook', perform: '$func$0$f$', sample: { id: 385, name: 'proactive enable ROI' } } } ``` * ``` { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.', hidden: true }, operation: { type: 'hook', perform: '$func$0$f$' } } ``` #### Anti-Examples * ``` { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' }, operation: { type: 'hook', perform: '$func$0$f$' } } ``` _Missing key from operation: sample. Note – this is valid if the resource has defined a sample._ ----- ## /ResourceMethodListSchema How will we get a list of new objects? Will be turned into a trigger automatically. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/ResourceMethodListSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `display` | **yes** | [/BasicDisplaySchema](#basicdisplayschema) | Define how this list/trigger method will be exposed in the UI. `operation` | **yes** | [/BasicPollingOperationSchema](#basicpollingoperationschema) | Define how this list/trigger method will work. #### Examples * ``` { display: { label: 'New User', description: 'Trigger when a new User is created in your account.' }, operation: { perform: { url: 'https://fake-crm.getsandbox.com/users' }, sample: { id: 49, name: 'Veronica Kuhn', email: 'veronica.kuhn@company.com' } } } ``` * ``` { display: { label: 'New User', description: 'Trigger when a new User is created in your account.', hidden: true }, operation: { perform: { url: 'https://fake-crm.getsandbox.com/users' } } } ``` #### Anti-Examples * ``` { display: { label: 'New User', description: 'Trigger when a new User is created in your account.' }, operation: { perform: { url: 'https://fake-crm.getsandbox.com/users' } } } ``` _Missing key from operation: sample. Note – this is valid if the resource has defined a sample._ ----- ## /ResourceMethodSearchSchema How will we find a specific object given filters or search terms? Will be turned into a search automatically. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/ResourceMethodSearchSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `display` | **yes** | [/BasicDisplaySchema](#basicdisplayschema) | Define how this search method will be exposed in the UI. `operation` | **yes** | [/BasicActionOperationSchema](#basicactionoperationschema) | Define how this search method will work. #### Examples * ``` { display: { label: 'Find a Recipe', description: 'Search for recipe by cuisine style.' }, operation: { perform: '$func$2$f$', sample: { id: 1 } } } ``` * ``` { display: { label: 'Find a Recipe', description: 'Search for recipe by cuisine style.', hidden: true }, operation: { perform: '$func$2$f$' } } ``` #### Anti-Examples * ``` { key: 'recipe', noun: 'Recipe', display: { label: 'Find a Recipe', description: 'Search for recipe by cuisine style.' }, operation: { perform: '$func$2$f$' } } ``` _Missing key from operation: sample. Note – this is valid if the resource has defined a sample._ ----- ## /ResourceSchema Represents a resource, which will in turn power triggers, searches, or creates. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/ResourceSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `key` | **yes** | [/KeySchema](#keyschema) | A key to uniquely identify this resource. `noun` | **yes** | `string` | A noun for this resource that completes the sentence "create a new XXX". `get` | no | [/ResourceMethodGetSchema](#resourcemethodgetschema) | How will we get a single object given a unique identifier/id? `hook` | no | [/ResourceMethodHookSchema](#resourcemethodhookschema) | How will we get notified of new objects? Will be turned into a trigger automatically. `list` | no | [/ResourceMethodListSchema](#resourcemethodlistschema) | How will we get a list of new objects? Will be turned into a trigger automatically. `search` | no | [/ResourceMethodSearchSchema](#resourcemethodsearchschema) | How will we find a specific object given filters or search terms? Will be turned into a search automatically. `create` | no | [/ResourceMethodCreateSchema](#resourcemethodcreateschema) | How will we find create a specific object given inputs? Will be turned into a create automatically. `outputFields` | no | [/OutputFieldsSchema](#outputfieldsschema) | What fields of data will this return? `sample` | no | `object` | What does a sample of data look like? #### Examples * ``` { key: 'tag', noun: 'Tag', get: { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' }, operation: { perform: { url: 'https://fake-crm.getsandbox.com/tags/{{inputData.id}}' }, sample: { id: 385, name: 'proactive enable ROI' } } } } ``` * ``` { key: 'tag', noun: 'Tag', sample: { id: 385, name: 'proactive enable ROI' }, get: { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' }, operation: { perform: { url: 'https://fake-crm.getsandbox.com/tags/{{inputData.id}}' } } } } ``` * ``` { key: 'tag', noun: 'Tag', get: { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.', hidden: true }, operation: { perform: { url: 'https://fake-crm.getsandbox.com/tags/{{inputData.id}}' } } }, list: { display: { label: 'New Tag', description: 'Trigger when a new Tag is created in your account.' }, operation: { perform: { url: 'https://fake-crm.getsandbox.com/tags' }, sample: { id: 385, name: 'proactive enable ROI' } } } } ``` #### Anti-Examples * ``` { key: 'tag', noun: 'Tag', get: { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' }, operation: { perform: { url: 'https://fake-crm.getsandbox.com/tags/{{inputData.id}}' } } } } ``` _Missing key from operation: sample. Note – this is valid if the resource has defined a sample._ ----- ## /ResourcesSchema All the resources that underlie common CRUD methods powering automatically handled triggers, creates, and searches for your app. Zapier will break these apart for you. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/ResourcesSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `^[a-zA-Z]+[a-zA-Z0-9_]*$` | no | [/ResourceSchema](#resourceschema) | Any unique key can be used and its values will be validated against the ResourceSchema. #### Examples * ``` { tag: { key: 'tag', noun: 'Tag', get: { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' }, operation: { perform: { url: 'https://fake-crm.getsandbox.com/tags/{{inputData.id}}' }, sample: { id: 385, name: 'proactive enable ROI' } } } } } ``` #### Anti-Examples * ``` { getTag: { key: 'tag', noun: 'Tag', get: { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' }, operation: { perform: { url: 'https://fake-crm.getsandbox.com/tags/{{inputData.id}}' }, sample: { id: 385, name: 'proactive enable ROI' } } } } } ``` _Key does not match key for associated /ResourceSchema_ * ``` { tag: { key: 'tag', noun: 'Tag', get: { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' }, operation: { perform: { url: 'https://fake-crm.getsandbox.com/tags/{{inputData.id}}' } } } } } ``` _Missing key from operation: sample. Note – this is valid if the resource has defined a sample._ ----- ## /ResultsSchema An array of objects suitable for returning in perform calls. #### Details * **Type** - `array`[`object`] * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/ResultsSchema.js) #### Examples * `[ { name: 'Alex Trebek' } ]` #### Anti-Examples * `1` - _Invalid type (must be array)_ * `[ 1 ]` - _Invalid type (must be array of objects)_ ----- ## /SearchAndCreatesSchema Alias for /SearchOrCreatesSchema #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/SearchAndCreatesSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `^[a-zA-Z]+[a-zA-Z0-9_]*$` | no | [/SearchOrCreateSchema](#searchorcreateschema) | Any unique key can be used and its values will be validated against the SearchOrCreateSchema. #### Examples * ``` { searchOrCreateWidgets: { key: 'searchOrCreateWidgets', display: { label: 'Search or Create Widgets', description: 'Searches for a widget matching the provided query, or creates one if it does not exist.', hidden: false }, search: 'searchWidgets', create: 'createWidget' } } ``` * ``` { searchAndCreateWidgets: { key: 'searchAndCreateWidgets', display: { label: 'Search and Create Widgets', description: 'Searches for a widget matching the provided query, creates one if it does not exist or updates existing one if found.', hidden: false }, search: 'searchWidgets', create: 'createWidget', update: 'updateWidget' } } ``` #### Anti-Examples * ``` { searchOrCreateWidgets: { key: 'socWidgets', display: { label: 'Search or Create Widgets', description: 'Searches for a widget matching the provided query, or creates one if it does not exist.', hidden: false }, search: 'searchWidgets', create: 'createWidget' } } ``` _Key must match the key of the associated /SearchOrCreateSchema_ ----- ## /SearchOrCreateSchema Pair an existing search and a create to enable "Find or Create" functionality in your app #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/SearchOrCreateSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `key` | **yes** | [/KeySchema](#keyschema) | A key to uniquely identify this search-or-create. Must match the search key. `display` | **yes** | [/BasicDisplaySchema](#basicdisplayschema) | Configures the UI for this search-or-create. `search` | **yes** | [/KeySchema](#keyschema) | The key of the search that powers this search-or-create `create` | **yes** | [/KeySchema](#keyschema) | The key of the create that powers this search-or-create `update` | no | [/KeySchema](#keyschema) | EXPERIMENTAL: The key of the update action (in `creates`) that will be used if a search succeeds. `updateInputFromSearchOutput` | no | [/FlatObjectSchema](#flatobjectschema) | EXPERIMENTAL: A mapping where the key represents the input field for the update action, and the value represents the field from the search action's output that should be mapped to the update action's input field. `searchUniqueInputToOutputConstraint` | no | `object` | EXPERIMENTAL: A mapping where the key represents an input field for the search action, and the value represents how that field's value will be used to filter down the search output for an exact match. #### Examples * ``` { key: 'searchOrCreateWidgets', display: { label: 'Search or Create Widgets', description: 'Searches for a widget matching the provided query, or creates one if it does not exist.', hidden: false }, search: 'searchWidgets', create: 'createWidget' } ``` * ``` { key: 'upsertWidgets', display: { label: 'Upsert Widgets', description: 'Searches for a widget matching the provided query and updates it if found, or creates one if it does not exist.', hidden: false }, search: 'searchWidgets', create: 'createWidget', update: 'updateExistingWidget', updateInputFromSearchOutput: { widget_id: 'id' }, searchUniqueInputToOutputConstraint: { widget_name: 'name' } } ``` #### Anti-Examples * ``` { key: '01_Search_or_Create_Widgets', display: { label: 'Search or Create Widgets', description: 'Searches for a widget matching the provided query, or creates one if it does not exist.', hidden: false }, search: 'searchWidgets', create: 'createWidget' } ``` _Invalid value for key: key (must start with a letter)_ * ``` { key: 'searchOrCreateWidgets', display: { label: 'Search or Create Widgets', description: 'Searches for a widget matching the provided query, or creates one if it does not exist.', hidden: false }, search: { require: 'path/to/some/file.js' }, create: { require: 'path/to/some/file.js' } } ``` _Invalid values for keys: search and create (must be a string that matches the key of a registered search or create)_ * ``` { key: 'upsertWidgets', display: { label: 'Upsert Widgets', description: 'Searches for a widget matching the provided query and updates it if found, or creates one if it does not exist.', hidden: false }, search: 'searchWidgets', create: 'createWidget', updateInputFromSearchOutput: { widget_id: 'id' }, searchUniqueInputToOutputConstraint: { widget_name: 'name' } } ``` _If either the updateInputFromSearchOutput or searchUniqueInputToOutputConstraint keys are present, then the update key must be present as well._ ----- ## /SearchOrCreatesSchema Enumerates the search-or-creates your app has available for users. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/SearchOrCreatesSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `^[a-zA-Z]+[a-zA-Z0-9_]*$` | no | [/SearchOrCreateSchema](#searchorcreateschema) | Any unique key can be used and its values will be validated against the SearchOrCreateSchema. #### Examples * ``` { searchOrCreateWidgets: { key: 'searchOrCreateWidgets', display: { label: 'Search or Create Widgets', description: 'Searches for a widget matching the provided query, or creates one if it does not exist.', hidden: false }, search: 'searchWidgets', create: 'createWidget' } } ``` * ``` { searchAndCreateWidgets: { key: 'searchAndCreateWidgets', display: { label: 'Search and Create Widgets', description: 'Searches for a widget matching the provided query, creates one if it does not exist or updates existing one if found.', hidden: false }, search: 'searchWidgets', create: 'createWidget', update: 'updateWidget' } } ``` #### Anti-Examples * ``` { searchOrCreateWidgets: { key: 'socWidgets', display: { label: 'Search or Create Widgets', description: 'Searches for a widget matching the provided query, or creates one if it does not exist.', hidden: false }, search: 'searchWidgets', create: 'createWidget' } } ``` _Key must match the key of the associated /SearchOrCreateSchema_ ----- ## /SearchSchema How will Zapier search for existing objects? #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/SearchSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `key` | **yes** | [/KeySchema](#keyschema) | A key to uniquely identify this search. `noun` | **yes** | `string` | A noun for this search that completes the sentence "finds a specific XXX". `display` | **yes** | [/BasicDisplaySchema](#basicdisplayschema) | Configures the UI for this search. `operation` | **yes** | [/BasicSearchOperationSchema](#basicsearchoperationschema) | Powers the functionality for this search. #### Examples * ``` { key: 'recipe', noun: 'Recipe', display: { label: 'Find a Recipe', description: 'Search for recipe by cuisine style.' }, operation: { perform: '$func$2$f$', sample: { id: 1 } } } ``` * ``` { key: 'recipe', noun: 'Recipe', display: { label: 'Find a Recipe', description: 'Search for recipe by cuisine style.', hidden: true }, operation: { perform: '$func$2$f$' } } ``` #### Anti-Examples * `'abc'` - _Must be an object_ * ``` { key: 'recipe', noun: 'Recipe', display: { label: 'Find a Recipe', description: 'Search for recipe by cuisine style.' }, operation: { perform: '$func$2$f$' } } ``` _Missing required key in operation: sample. Note - this is valid if the associated resource has defined a sample._ ----- ## /SearchesSchema Enumerates the searches your app has available for users. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/SearchesSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `^[a-zA-Z]+[a-zA-Z0-9_]*$` | no | [/SearchSchema](#searchschema) | Any unique key can be used and its values will be validated against the SearchSchema. #### Examples * ``` { recipe: { key: 'recipe', noun: 'Recipe', display: { label: 'Find a Recipe', description: 'Search for recipe by cuisine style.', hidden: true }, operation: { perform: '$func$2$f$' } } } ``` #### Anti-Examples * ``` { searchRecipe: { key: 'recipe', noun: 'Recipe', display: { label: 'Find a Recipe', description: 'Search for recipe by cuisine style.', hidden: true }, operation: { perform: '$func$2$f$' } } } ``` _Key must match the key of the associated /SearchSchema_ ----- ## /ThrottleObjectSchema Zapier uses this configuration to apply throttling when the limit for the window is exceeded. **NOTE:** The final key used for the throttling is formed as a combination of all the configurations; key, window, limit, and scope. To share a limit across multiple actions in an integration, each should have the same configuration set without "action" in the scope. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/ThrottleObjectSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `window` | **yes** | `integer` | The timeframe, in seconds, within which the system tracks the number of invocations for an action. The number of invocations begins at zero at the start of each window. `limit` | **yes** | `integer` | The maximum number of invocations for an action, allowed within the timeframe window. `key` | no | `string` | The key to throttle with in combination with the scope. User data provided for the input fields can be used in the key with the use of the curly braces referencing. For example, to access the user data provided for the input field "test_field", use `{{bundle.inputData.test_field}}`. Note that a required input field should be referenced to get user data always. `scope` | no | `array`[`string` in (`'user'`, `'auth'`, `'account'`, `'action'`)] | The granularity to throttle by. You can set the scope to one or more of the following: 'user' - Throttles based on user ids. 'auth' - Throttles based on auth ids. 'account' - Throttles based on account ids for all users under a single account. 'action' - Throttles the action it is set on separately from other actions. By default, throttling is scoped to the action and account. `retry` | no | `boolean` | The effect of throttling on the tasks of the action. `true` means throttled tasks are automatically retried after some delay, while `false` means tasks are held without retry. It defaults to `true`. NOTE that it has no effect on polling triggers and should not be set. `filter` | no | `string` in (`'free'`, `'trial'`, `'paid'`) | EXPERIMENTAL: Account-based attribute to override the throttle by. You can set to one of the following: "free", "trial", "paid". Therefore, the throttle scope would be automatically set to "account" and ONLY the accounts based on the specified filter will have their requests throttled based on the throttle overrides while the rest are throttled based on the original configuration. `overrides` | no | `array`[[/ThrottleOverrideObjectSchema](#throttleoverrideobjectschema)] | EXPERIMENTAL: Overrides the original throttle configuration based on a Zapier account attribute. #### Examples * `{ window: 60, limit: 100 }` * `{ window: 600, limit: 100, scope: [ 'account', 'user' ] }` * `{ window: 3600, limit: 10, scope: [ 'auth' ] }` * `{ window: 3600, limit: 10, key: 'random_key', scope: [] }` * ``` { window: 3600, limit: 10, key: 'random_key-{{bundle.inputData.test_field}}', scope: [ 'action', 'auth' ], retry: false } ``` * ``` { window: 3600, limit: 10, scope: [ 'auth' ], retry: false, overrides: [ { window: 3600, limit: 2, filter: 'free', retry: false } ] } ``` #### Anti-Examples * `{ window: 60, limit: 100, scope: [ 'zap' ] }` - _Invalid scope provided: `zap`._ * `{ limit: 10 }` - _Missing required key: `window`._ * `{ window: 600 }` - _Missing required key: `limit`._ * `{ window: 600, limit: 100, overrides: [] }` - _The overrides needs at least one item._ * `{}` - _Missing required keys: `window` and `limit`._ ----- ## /ThrottleOverrideObjectSchema EXPERIMENTAL: Overrides the original throttle configuration based on a Zapier account attribute. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/ThrottleOverrideObjectSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `window` | **yes** | `integer` | The timeframe, in seconds, within which the system tracks the number of invocations for an action. The number of invocations begins at zero at the start of each window. `limit` | **yes** | `integer` | The maximum number of invocations for an action, allowed within the timeframe window. `filter` | **yes** | `string` in (`'free'`, `'trial'`, `'paid'`) | Account-based attribute to override the throttle by. You can set to one of the following: "free", "trial", "paid". Therefore, the throttle scope would be automatically set to "account" and ONLY the accounts based on the specified filter will have their requests throttled based on the throttle overrides while the rest are throttled based on the original configuration. `retry` | no | `boolean` | The effect of throttling on the tasks of the action. `true` means throttled tasks are automatically retried after some delay, while `false` means tasks are held without retry. It defaults to `true`. NOTE that it has no effect on polling triggers and should not be set. #### Examples * `{ window: 60, limit: 100, filter: 'free' }` * `{ window: 60, limit: 100, filter: 'paid', retry: false }` * `{ window: 60, limit: 100, filter: 'trial', retry: true }` #### Anti-Examples * `{ limit: 10 }` - _Missing required key: `window` and `filter`._ * `{ window: 600 }` - _Missing required key: `limit` and `filter`._ * `{ filter: 'trial' }` - _Missing required key: `window` and `limit`._ * `{}` - _Missing required keys: `window`, `limit`, and `filter`._ ----- ## /TriggerSchema How will Zapier get notified of new objects? #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/TriggerSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `key` | **yes** | [/KeySchema](#keyschema) | A key to uniquely identify this trigger. `noun` | **yes** | `string` | A noun for this trigger that completes the sentence "triggers on a new XXX". `display` | **yes** | [/BasicDisplaySchema](#basicdisplayschema) | Configures the UI for this trigger. `operation` | **yes** | anyOf([/BasicPollingOperationSchema](#basicpollingoperationschema), [/BasicHookOperationSchema](#basichookoperationschema)) | Powers the functionality for this trigger. #### Examples * ``` { key: 'new_recipe', noun: 'Recipe', display: { label: 'New Recipe', description: 'Triggers when a new recipe is added.' }, operation: { type: 'polling', perform: '$func$0$f$', sample: { id: 1 } } } ``` * ``` { key: 'new_recipe', noun: 'Recipe', display: { label: 'New Recipe', description: 'Triggers when a new recipe is added.', hidden: true }, operation: { type: 'polling', perform: '$func$0$f$' } } ``` #### Anti-Examples * ``` { key: 'new_recipe', noun: 'Recipe', display: { label: 'New Recipe', description: 'Triggers when a new recipe is added.' }, operation: { perform: '$func$0$f$' } } ``` _Missing required key from operation: sample. Note - this is valid if the Recipe resource has defined a sample._ ----- ## /TriggersSchema Enumerates the triggers your app has available for users. #### Details * **Type** - `object` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/TriggersSchema.js) #### Properties Key | Required | Type | Description --- | -------- | ---- | ----------- `^[a-zA-Z]+[a-zA-Z0-9_]*$` | no | [/TriggerSchema](#triggerschema) | Any unique key can be used and its values will be validated against the TriggerSchema. #### Examples * ``` { newRecipe: { key: 'newRecipe', noun: 'Recipe', display: { label: 'New Recipe', description: 'Triggers when a new recipe is added.' }, operation: { type: 'polling', perform: '$func$0$f$', sample: { id: 1 } } } } ``` #### Anti-Examples * ``` { newRecipe: { key: 'new_recipe', noun: 'Recipe', display: { label: 'New Recipe', description: 'Triggers when a new recipe is added.' }, operation: { type: 'polling', perform: '$func$0$f$', sample: { id: 1 } } } } ``` _Key must match the key on the associated /TriggerSchema_ ----- ## /VersionSchema Represents a simplified semver string, from `0.0.0` to `999.999.999` with optional simplified label. They need to be case-insensitive unique. #### Details * **Type** - `string` * **Pattern** - `^(?:0|[1-9]\d{0,2})\.(?:0|[1-9]\d{0,2})\.(?:0|[1-9]\d{0,2})(?:-(?=.{1,12}$)[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*)?$` * [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@19.1.0/packages/schema/lib/schemas/VersionSchema.js) #### Examples * `'1.0.0'` * `'2.11.3'` * `'999.999.999'` * `'1.2.0-beta'` * `'0.0.0-ISSUE-123'` #### Anti-Examples * `'1.0.0.0'` - _Must have 2 periods_ * `'1000.0.0'` - _Each number can be a maximum of 3 digits_ * `'v1.0.0'` - _No letter prefix allowed_ * `'1.0.0-rc.1'` - _No periods allowed in label_ * `'1.0.0--'` - _No repeated dashes allowed_ * `'1.0.0-foo--bar'` - _No repeated dashes allowed in label_ * `'1.0.0-'` - _No empty label allowed_ * `'1.0.0-foo-'` - _No trailing dash allowed in label_ <!-- {% endraw %} -->