zapier-platform-schema

zapier-platform-schema Generated Documentation

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


Index


/AppFlagsSchema

Codifies high-level options for your app.

Details

Examples

Anti-Examples

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

/AppSchema

Represents a full app.

Details

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.
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.
flags no /AppFlagsSchema Top-level app options

/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


/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


/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


/AuthenticationOAuth1ConfigSchema

Config for OAuth1 authentication.

Details

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

/AuthenticationOAuth2ConfigSchema

Config for OAuth2 authentication.

Details

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
scope no string What scope should Zapier request?
autoRefresh no boolean Should Zapier include a pre-built afterResponse middleware that invokes refreshAccessToken when we receive a 401 response?

/AuthenticationSchema

Represents authentication schemes.

Details

Examples

Anti-Examples

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.

/AuthenticationSessionConfigSchema

Config for session authentication.

Details

Properties

Key Required Type Description
perform yes oneOf(/RequestSchema, /FunctionSchema) Define how Zapier fetches the additional authData needed to make API calls.

/BasicActionOperationSchema

Represents the fundamental mechanics of a search/create.

Details

Properties

Key Required Type Description
resource no /RefResourceSchema 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 + callback to resume this action. For use with callback semantics
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

/BasicCreateActionOperationSchema

Represents the fundamental mechanics of a create.

Details

Properties

Key Required Type Description
resource no /RefResourceSchema 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 + callback to resume this action. For use with callback semantics
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
shouldLock no boolean Should this action be performed one at a time (avoid concurrency)?

/BasicDisplaySchema

Represents user information for a trigger, search, or create.

Details

Examples

Anti-Examples

Properties

Key Required Type Description
label yes string A short label like “New Record” or “Create Record in Project”.
description yes string A description of what this trigger, search, or create does.
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.
important no boolean Affects how prominently this operation is displayed in the UI. Only mark a few of the most popular operations important.
hidden no boolean Should this operation be unselectable by users?

/BasicHookOperationSchema

Represents the inbound mechanics of hooks with optional subscribe/unsubscribe. Defers to list for fields.

Details

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 /RefResourceSchema 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) Can get “live” data on demand instead of waiting for a hook. If you find yourself reaching for this - 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, you can ignore warnings about this property with the --without-style flag during zapier push.
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, 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, 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

/BasicOperationSchema

Represents the fundamental mechanics of triggers, searches, or creates.

Details

Properties

Key Required Type Description
resource no /RefResourceSchema 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

/BasicPollingOperationSchema

Represents the fundamental mechanics of a trigger.

Details

Properties

Key Required Type Description
type no string in ('polling') Clarify how this operation works (polling == pull or hook == push).
resource no /RefResourceSchema 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 a page offset?
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

/CreateSchema

How will Zapier create a new object?

Details

Examples

Anti-Examples

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.

/CreatesSchema

Enumerates the creates your app has available for users.

Details

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.

/DynamicFieldsSchema

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

Details

Examples

Anti-Examples


/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

Examples

Anti-Examples

Properties

Key Required Type Description
value yes string The actual value that is sent into the Zap. Should match sample exactly.
sample yes string Displayed as light grey text in the editor. It’s important that the value match the sample. Otherwise, the actual value won’t match what the user picked, which is confusing.
label yes string A human readable label for this value.

/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

Examples

Anti-Examples


/FieldOrFunctionSchema

Represents an array of fields or functions.

Details

Examples

Anti-Examples


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

Details

Examples

Anti-Examples

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') The type of this value.
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.
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 Can a user provide multiples of this field?
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)?
altersDynamicFields no boolean Does the value of this field affect the definitions of other fields in the set?
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”).

/FieldsSchema

An array or collection of fields.

Details


/FlatObjectSchema

An object whose values can only be primitives

Details

Examples

Anti-Examples

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.

/FunctionRequireSchema

A path to a file that might have content like module.exports = (z, bundle) => [{id: 123}];.

Details

Examples

Properties

Key Required Type Description
require yes string No description given.

/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

Examples

Anti-Examples


/FunctionSourceSchema

Source code like {source: "return 1 + 2"} which the system will wrap in a function for you.

Details

Examples

Anti-Examples

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.

/HydratorsSchema

A bank of named functions that you can use in z.hydrate('someName') to lazily load data.

Details

Properties

Key Required Type Description
^[a-zA-Z]+[a-zA-Z0-9]*$ no /FunctionSchema Any unique key can be used in z.hydrate('uniqueKeyHere').

/KeySchema

A unique identifier for this item.

Details


/MiddlewaresSchema

List of before or after middlewares. Can be an array of functions or a single function

Details


/RedirectRequestSchema

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

Details

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.

/RefResourceSchema

Reference a resource by key and the data it returns. In the format of: {resource_key}.{foreign_key}(.{human_label_key}).

Details

Examples

Anti-Examples


/RequestSchema

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

Details

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 }

/ResourceMethodCreateSchema

How will we find create a specific object given inputs? Will be turned into a create automatically.

Details

Examples

Anti-Examples

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.

/ResourceMethodGetSchema

How will we get a single object given a unique identifier/id?

Details

Examples

Anti-Examples

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.

/ResourceMethodHookSchema

How will we get notified of new objects? Will be turned into a trigger automatically.

Details

Examples

Anti-Examples

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.

/ResourceMethodListSchema

How will we get a list of new objects? Will be turned into a trigger automatically.

Details

Examples

Anti-Examples

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.

/ResourceMethodSearchSchema

How will we find a specific object given filters or search terms? Will be turned into a search automatically.

Details

Examples

Anti-Examples

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.

/ResourceSchema

Represents a resource, which will in turn power triggers, searches, or creates.

Details

Examples

Anti-Examples

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?

/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

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.

/ResultsSchema

An array of objects suitable for returning in perform calls.

Details


/SearchOrCreateSchema

Pair an existing search and a create to enable “Find or Create” functionality in your app

Details

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

/SearchOrCreatesSchema

Enumerates the search-or-creates your app has available for users.

Details

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.

/SearchSchema

How will Zapier search for existing objects?

Details

Examples

Anti-Examples

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.

/SearchesSchema

Enumerates the searches your app has available for users.

Details

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.

/TriggerSchema

How will Zapier get notified of new objects?

Details

Examples

Anti-Examples

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.

/TriggersSchema

Enumerates the triggers your app has available for users.

Details

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.

/VersionSchema

Represents a simplified semver string, from 0.0.0 to 999.999.999.

Details

Examples

Anti-Examples