POST
/
api
/
v2
/
apps
/
{app}
/
choices
/
{prefill}
/

If a need that comes back from the Get Action Details endpoint has a prefill key, then this endpoint can be used to get the choices for that prefill.

​
Dependent needs

If a need has any values in its depends_on array, the values for each of the needs in depends_on must be included in the params in the body of the POST to get prefill choices.

As an example, the action_needs list for the add_row action for the GoogleSheetsV2API app from Get action details and needs includes a spreadsheet and a worksheet need:

{
  "action_needs": [
    {
      "key": "spreadsheet",
      "label": "Spreadsheet",
      "prefill": "spreadsheet.id.title",
      "depends_on": []
    },
    {
      "key": "worksheet",
      "label": "Worksheet",
      "prefill": "worksheet.id.title",
      "depends_on": ["spreadsheet"]
    }
  ]
}

This means that, in order to get the worksheet.id.title prefill choices, you need to include a spreadsheet value in the request to this endpoint:

{
  "params": { "spreadsheet": "SOME_SPREADHSEET_ID" }
}

SOME_SPREADHSEET_ID would have come from a call to get prefill choices for the spreadsheet.id.title value.

​
Caching

By default, responses from this endpoint for a given app, prefill, params, and user will be cached for 24 hours.

When this endpoint is first hit, a background job is started that will paginate through all of the available choices.

While this background job is running, the results from this endpoint will return with "is_loading": true.

If is_loading is true, then the endpoint should be polled every ~1 second until is_loading is false, at which point all of the available results are returned.

The time that the cache was last updated is returned with last_refresh_seconds_ago.

To force a refresh of the cache, the force_refresh query parameter can be set to true.

force_refresh should only be used when the choices are expected to have changed, and should only be used with a single request.

Repeated reqeusts with force_refresh set to true will cause results to continuously load.

Authorizations

Authorization
string
headerrequired

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

app
string
required

The app that the prefill belongs to.

prefill
string
required

The prefill to get choices for.

Query Parameters

authentication_id
integer | null

ID of the authentication to use for the app.

Authentications available to the user can be listed using the List Authentications For App endpoint.

account_id
integer

The Zapier account ID to use.

Account IDs available to the user can be listed using the Get Account List endpoint

query
string | null

Optional query to filter results by.

force_refresh
boolean
default: false

The list of prefill options for each user/app/prefill combo is cached for 24 hours.

If force_refresh is set to true, the cache will be refreshed. This should only be used when the list of prefill options is known to have changed.

Best practice is to offer a "Refresh" button to the user that sets this to true for one request.

Body

application/json
params
object
required

A dictionary of key-value pairs, where the key is a need key and the value is a selected value for that need.

Response

200 - application/json
is_loading
boolean
required

If this is true, then it means that the list of prefill options is still being loaded.

While this is true, the endpoint should be polled (in general every second) until it returns false.

last_refresh_seconds_ago
integer | null
required

Seconds that have elapsed since the list of options for this prefill has been refreshed.

To refresh the list, use the force_refresh query parameter.

results
object[]
required
Get action details and needsApp Health Check