`zapier-platform-schema` Generated Documentation

This is automatically generated by the npm run docs command in zapier-platform-schema version 15.19.0.

Index

/AppFlagsSchema
/AppSchema
/AuthenticationBasicConfigSchema
/AuthenticationCustomConfigSchema
/AuthenticationDigestConfigSchema
/AuthenticationOAuth1ConfigSchema
/AuthenticationOAuth2ConfigSchema
/AuthenticationSchema
/AuthenticationSessionConfigSchema
/BasicActionOperationSchema
/BasicCreateActionOperationSchema
/BasicDisplaySchema
/BasicHookOperationSchema
/BasicOperationSchema
/BasicPollingOperationSchema
/BufferConfigSchema
/BulkReadSchema
/BulkReadsSchema
/CreateSchema
/CreatesSchema
/DynamicFieldsSchema
/FieldChoiceWithLabelSchema
/FieldChoicesSchema
/FieldMetaSchema
/FieldOrFunctionSchema
/FieldSchema
/FieldsSchema
/FlatObjectSchema
/FunctionRequireSchema
/FunctionSchema
/FunctionSourceSchema
/HydratorsSchema
/KeySchema
/LockObjectSchema
/MiddlewaresSchema
/RedirectRequestSchema
/RefResourceSchema
/RequestSchema
/ResourceMethodCreateSchema
/ResourceMethodGetSchema
/ResourceMethodHookSchema
/ResourceMethodListSchema
/ResourceMethodSearchSchema
/ResourceSchema
/ResourcesSchema
/ResultsSchema
/SearchAndCreatesSchema
/SearchOrCreateSchema
/SearchOrCreatesSchema
/SearchSchema
/SearchesSchema
/ThrottleObjectSchema
/ThrottleOverrideObjectSchema
/TriggerSchema
/TriggersSchema
/VersionSchema

/AppFlagsSchema

Codifies high-level options for your integration.

Details

Type - object
Source Code

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 always call `throwForStatus()`. `z.request()` calls can also ignore this flag if they set `skipThrowForStatus` directly

Examples

{ skipHttpPatch: true, skipThrowForStatus: false }
{ skipHttpPatch: false, skipThrowForStatus: true }
{}

Anti-Examples

{ foo: true } - Invalid key.
{ skipHttpPatch: 'yes' } - Invalid value.
{ skipThrowForStatus: 'no' } - Invalid value.

/AppSchema

Represents a full app.

Details

Type - object
Source Code

Properties

Key	Required	Type	Description
`version`	yes	/VersionSchema	A version identifier for your code.
`platformVersion`	yes	/VersionSchema	A version identifier for the Zapier execution environment.
`beforeApp`	no	/MiddlewaresSchema	EXPERIMENTAL: Before the perform method is called on your app, you can modify the execution context.
`afterApp`	no	/MiddlewaresSchema	EXPERIMENTAL: After the perform method is called on your app, you can modify the response.
`authentication`	no	/AuthenticationSchema	Choose what scheme your API uses for authentication.
`requestTemplate`	no	/RequestSchema	Define a request mixin, great for setting custom headers, content-types, etc.
`beforeRequest`	no	/MiddlewaresSchema	Before an HTTP request is sent via our `z.request()` client, you can modify it.
`afterResponse`	no	/MiddlewaresSchema	After an HTTP response is recieved via our `z.request()` client, you can modify it.
`hydrators`	no	/HydratorsSchema	An optional bank of named functions that you can use in `z.hydrate('someName')` to lazily load data.
`resources`	no	/ResourcesSchema	All the resources for your app. Zapier will take these and generate the relevent triggers/searches/creates automatically.
`triggers`	no	/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	All of the read bulks (GETs) your app exposes to retrieve resources in batches.
`searches`	no	/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	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	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	An alias for "searchOrCreates".
`flags`	no	/AppFlagsSchema	Top-level app options
`throttle`	no	/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.

/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

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

Properties

Key	Required	Type	Description
`sendCode`	no	oneOf(/RequestSchema, /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

Examples

{}

Anti-Examples

{ foo: true } - Invalid key.

/AuthenticationOAuth1ConfigSchema

Config for OAuth1 authentication.

Details

Type - object
Source Code

Properties

Key	Required	Type	Description
`getRequestToken`	yes	oneOf(/RequestSchema, /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, /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, /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

Properties

Key	Required	Type	Description
`authorizeUrl`	yes	oneOf(/RedirectRequestSchema, /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, /FunctionSchema)	Define how Zapier fetches an access token from the API
`refreshAccessToken`	no	oneOf(/RequestSchema, /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

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, /FunctionSchema)	A function or request that confirms the authentication is working.
`fields`	no	/FieldsSchema	Fields you can request from the user before they connect your app to Zapier.
`connectionLabel`	no	anyOf(/RequestSchema, /FunctionSchema, `string`)	A string with variables, function, or request that returns the connection label for the authenticated user.
`basicConfig`	no	/AuthenticationBasicConfigSchema	No description given.
`customConfig`	no	/AuthenticationCustomConfigSchema	No description given.
`digestConfig`	no	/AuthenticationDigestConfigSchema	No description given.
`oauth1Config`	no	/AuthenticationOAuth1ConfigSchema	No description given.
`oauth2Config`	no	/AuthenticationOAuth2ConfigSchema	No description given.
`sessionConfig`	no	/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

Properties

Key	Required	Type	Description
`perform`	yes	oneOf(/RequestSchema, /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

Properties

Key	Required	Type	Description
`resource`	no	/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, /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	A function that parses data from a perform (which uses z.generateCallbackUrl()) and callback request to resume this action.
`performGet`	no	oneOf(/RequestSchema, /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	/DynamicFieldsSchema	What should the form a user sees and configures look like?
`outputFields`	no	/DynamicFieldsSchema	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	INTERNAL USE ONLY. Zapier uses this configuration for internal operation locking.
`throttle`	no	/ThrottleObjectSchema	Zapier uses this configuration to apply throttling when the limit for the window is exceeded.

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.

/BasicCreateActionOperationSchema

Represents the fundamental mechanics of a create.

Details

Type - object
Source Code

Properties

Key	Required	Type	Description
`resource`	no	/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, /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	A function that parses data from a perform (which uses z.generateCallbackUrl()) and callback request to resume this action.
`performGet`	no	oneOf(/RequestSchema, /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	/DynamicFieldsSchema	What should the form a user sees and configures look like?
`outputFields`	no	/DynamicFieldsSchema	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	INTERNAL USE ONLY. Zapier uses this configuration for internal operation locking.
`throttle`	no	/ThrottleObjectSchema	Zapier uses this configuration to apply throttling when the limit for the window is exceeded.
`shouldLock`	no	`boolean`	Should this action be performed one at a time (avoid concurrency)?
`buffer`	no (with exceptions, see description)	/BufferConfigSchema	Currently an internal-only feature. Zapier uses this configuration for creating objects in bulk with `performBuffer`.
`performBuffer`	no (with exceptions, see description)	/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

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

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	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	A function that processes the inbound webhook request.
`performList`	yes (with exceptions, see description)	oneOf(/RequestSchema, /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 push`.
`canPaginate`	no	`boolean`	Does this endpoint support pagination via temporary cursor storage?
`performSubscribe`	yes (with exceptions, see description)	oneOf(/RequestSchema, /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 push`.
`performUnsubscribe`	yes (with exceptions, see description)	oneOf(/RequestSchema, /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 push`.
`inputFields`	no	/DynamicFieldsSchema	What should the form a user sees and configures look like?
`outputFields`	no	/DynamicFieldsSchema	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

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

Properties

Key	Required	Type	Description
`resource`	no	/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, /FunctionSchema)	How will Zapier get the data? This can be a function like `(z) => [{id: 123}]` or a request like `{url: 'http...'}`.
`inputFields`	no	/DynamicFieldsSchema	What should the form a user sees and configures look like?
`outputFields`	no	/DynamicFieldsSchema	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	INTERNAL USE ONLY. Zapier uses this configuration for internal operation locking.
`throttle`	no	/ThrottleObjectSchema	Zapier uses this configuration to apply throttling when the limit for the window is exceeded.

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

Properties

Key	Required	Type	Description
`type`	no	`string` in (`'polling'`)	Clarify how this operation works (polling == pull or hook == push).
`resource`	no	/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, /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	/DynamicFieldsSchema	What should the form a user sees and configures look like?
`outputFields`	no	/DynamicFieldsSchema	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	Zapier uses this configuration to apply throttling when the limit for the window is exceeded.

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

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. 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

Properties

Key	Required	Type	Description
`key`	yes	/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	Configures the UI for this read bulk.
`operation`	yes	/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

Properties

Key	Required	Type	Description
`^[a-zA-Z]+[a-zA-Z0-9_]*$`	no	/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

Properties

Key	Required	Type	Description
`key`	yes	/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	Configures the UI for this create.
`operation`	yes	/BasicCreateActionOperationSchema	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.' },
  operation: { perform: '$func$2$f$', sample: { id: 1 }, shouldLock: true }
}

{
  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$', shouldLock: 'yes' }
}

Invalid value for key on operation: shouldLock

{
  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

Properties

Key	Required	Type	Description
`^[a-zA-Z]+[a-zA-Z0-9_]*$`	no	/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

/DynamicFieldsSchema

Like /FieldsSchema but you can provide functions to create dynamic or custom fields.

Details

Type - /FieldOrFunctionSchema
Source Code

Examples

[]
[ { key: 'abc' } ]
[ { key: 'abc' }, '$func$2$f$' ]
[ '$func$2$f$', '$func$2$f$' ]

Anti-Examples

[ {} ] - FieldSchema missing required key: key
[ { key: 'abc', choices: {} } ] - Invalid value for key in FieldSchema: choices (cannot be empty)
'$func$2$f$' - Must be an array

/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).

Details

Type - object
Source Code

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

Details

Type - oneOf(object, array[oneOf(string, /FieldChoiceWithLabelSchema)])
Source Code

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

/FieldMetaSchema

Allows for additional metadata to be stored on the field.

Details

Type - object
Source Code

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

/FieldOrFunctionSchema

Represents an array of fields or functions.

Details

Type - array[oneOf(/FieldSchema, /FunctionSchema)]
Source Code

Examples

[]
[ { key: 'abc' } ]
[ { key: 'abc' }, '$func$2$f$' ]
[ '$func$2$f$', '$func$2$f$' ]

Anti-Examples

[ {} ] - Array item not a valid FieldSchema or FunctionSchema
[ { key: 'abc', choices: {} } ] - Array item not a valid FieldSchema
'$func$2$f$' - Must be an array

/FieldSchema

Defines a field an app either needs as input, or gives as output. 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

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").
`helpText`	no	`string`	A human readable description of this value (IE: "The first part of a full name."). You can use Markdown.
`type`	no	`string` in (`'string'`, `'text'`, `'integer'`, `'number'`, `'boolean'`, `'datetime'`, `'file'`, `'password'`, `'copy'`, `'code'`)	The type of this value. Use `string` for basic text input, `text` for a large, `<textarea>` 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.
`placeholder`	no	`string`	An example value that is not saved.
`default`	no	`string`	A default value that is saved the first time a Zap is created.
`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 will be ignored if set in `inputFields`. It only works in static `outputFields`; will not work in custom/dynamic `outputFields`. For more information, see How deduplication works in Zapier.
`dynamic`	no	/RefResourceSchema	A reference to a trigger that will power a dynamic dropdown.
`search`	no	/RefResourceSchema	A reference to a search that will guide the user to add a search step to populate this field when creating a Zap.
`choices`	no	/FieldChoicesSchema	An object of machine keys and human values to populate a static dropdown.
`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`[/FieldSchema]	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?
`computed`	no	`boolean`	Is this field automatically populated (and hidden from the user)? Note: Only OAuth and Session Auth support fields with this key.
`altersDynamicFields`	no	`boolean`	Does the value of this field affect the definitions of other fields in the set?
`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.
`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	Allows for additional metadata to be stored on the field. Supports simple key-values only (no sub-objects or arrays).

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', children: [ { key: 'abc' } ] }
{ key: 'abc', type: 'integer', helpText: 'neat' }

{
  key: 'abc',
  type: 'integer',
  meta: { internalType: 'numeric', should_call_api: true, display_order: 1 }
}

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 FieldSchema)

/FieldsSchema

An array or collection of fields.

Details

Type - array[/FieldSchema]
Source Code

Examples

[ { key: 'abc' } ]

Anti-Examples

{} - Must be an array

/FlatObjectSchema

An object whose values can only be primitives

Details

Type - object
Source Code

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

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, /FunctionSourceSchema)
Source Code

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

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

Properties

Key	Required	Type	Description
`^[a-zA-Z]+[a-zA-Z0-9]*$`	no	/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)

/KeySchema

A unique identifier for this item.

Details

Type - string
Pattern - ^[a-zA-Z]+[a-zA-Z0-9_]*$
Source Code

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

INTERNAL USE ONLY. Zapier uses this configuration for internal operation locking.

Details

Type - object
Source Code

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)
Source Code

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

/RedirectRequestSchema

A representation of a HTTP redirect - you can use the {{syntax}} to inject authentication, field or global variables.

Details

Type - object
Source Code

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	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

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

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	A mapping of the querystring - will get merged with any query params in the URL. Keys and values will be encoded.
`headers`	no	/FlatObjectSchema	The HTTP headers for the request.
`auth`	no	oneOf(`array`[`string`], /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	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

Properties

Key	Required	Type	Description
`display`	yes	/BasicDisplaySchema	Define how this create method will be exposed in the UI.
`operation`	yes	/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

Properties

Key	Required	Type	Description
`display`	yes	/BasicDisplaySchema	Define how this get method will be exposed in the UI.
`operation`	yes	/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

Properties

Key	Required	Type	Description
`display`	yes	/BasicDisplaySchema	Define how this hook/trigger method will be exposed in the UI.
`operation`	yes	/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

Properties

Key	Required	Type	Description
`display`	yes	/BasicDisplaySchema	Define how this list/trigger method will be exposed in the UI.
`operation`	yes	/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

Properties

Key	Required	Type	Description
`display`	yes	/BasicDisplaySchema	Define how this search method will be exposed in the UI.
`operation`	yes	/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

Properties

Key	Required	Type	Description
`key`	yes	/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	How will we get a single object given a unique identifier/id?
`hook`	no	/ResourceMethodHookSchema	How will we get notified of new objects? Will be turned into a trigger automatically.
`list`	no	/ResourceMethodListSchema	How will we get a list of new objects? Will be turned into a trigger automatically.
`search`	no	/ResourceMethodSearchSchema	How will we find a specific object given filters or search terms? Will be turned into a search automatically.
`create`	no	/ResourceMethodCreateSchema	How will we find create a specific object given inputs? Will be turned into a create automatically.
`outputFields`	no	/DynamicFieldsSchema	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

Properties

Key	Required	Type	Description
`^[a-zA-Z]+[a-zA-Z0-9_]*$`	no	/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

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

Properties

Key	Required	Type	Description
`^[a-zA-Z]+[a-zA-Z0-9_]*$`	no	/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

Properties

Key	Required	Type	Description
`key`	yes	/KeySchema	A key to uniquely identify this search-or-create. Must match the search key.
`display`	yes	/BasicDisplaySchema	Configures the UI for this search-or-create.
`search`	yes	/KeySchema	The key of the search that powers this search-or-create
`create`	yes	/KeySchema	The key of the create that powers this search-or-create
`update`	no	/KeySchema	EXPERIMENTAL: The key of the update action (in `creates`) that will be used if a search succeeds.
`updateInputFromSearchOutput`	no	/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

Properties

Key	Required	Type	Description
`^[a-zA-Z]+[a-zA-Z0-9_]*$`	no	/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

Properties

Key	Required	Type	Description
`key`	yes	/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	Configures the UI for this search.
`operation`	yes	/BasicActionOperationSchema	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

Properties

Key	Required	Type	Description
`^[a-zA-Z]+[a-zA-Z0-9_]*$`	no	/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

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]	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

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

Properties

Key	Required	Type	Description
`key`	yes	/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	Configures the UI for this trigger.
`operation`	yes	anyOf(/BasicPollingOperationSchema, /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

Properties

Key	Required	Type	Description
`^[a-zA-Z]+[a-zA-Z0-9_]*$`	no	/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.

Details

Type - string
Pattern - ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$
Source Code

Examples

'1.0.0'
'2.11.3'
'999.999.999'

Anti-Examples

'1.0.0.0' - Must have only 2 periods
'1000.0.0' - Each number can be a maximum of 3 digits
'v1.0.0' - No letters allowed
'1.0.0-beta' - undefined

Files

schema.md

Latest commit

History

schema.md

File metadata and controls

zapier-platform-schema Generated Documentation

Index

/AppFlagsSchema

Details

Properties

Examples

Anti-Examples

/AppSchema

Details

Properties

Examples

Anti-Examples

/AuthenticationBasicConfigSchema

Details

Examples

Anti-Examples

/AuthenticationCustomConfigSchema

Details

Properties

Examples

Anti-Examples

/AuthenticationDigestConfigSchema

Details

Examples

Anti-Examples

/AuthenticationOAuth1ConfigSchema

Details

Properties

Examples

Anti-Examples

/AuthenticationOAuth2ConfigSchema

Details

Properties

Examples

Anti-Examples

/AuthenticationSchema

Details

Properties

Examples

Anti-Examples

/AuthenticationSessionConfigSchema

Details

Properties

Examples

Anti-Examples

/BasicActionOperationSchema

Details

Properties

Examples

Anti-Examples

/BasicCreateActionOperationSchema

Details

Properties

Examples

Anti-Examples

/BasicDisplaySchema

Details

Properties

Examples

Anti-Examples

/BasicHookOperationSchema

Details

Properties

Examples

Anti-Examples

/BasicOperationSchema

Details

Properties

Examples

Anti-Examples

/BasicPollingOperationSchema

Details

Properties

Examples

`zapier-platform-schema` Generated Documentation