POST
/
api
/
v2
/
apps
/
{app}
/
actions
/
{action}
curl --request POST \
  --url https://actions.zapier.com/api/v2/apps/{app}/actions/{action}/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "params": {}
}'
{
  "results": [
    {
      "action_has_custom_needs_probability": 123,
      "action": {
        "type": "<string>",
        "key": "<string>",
        "name": "<string>",
        "noun": "<string>",
        "description": "<string>",
        "is_important": true,
        "is_hidden": true,
        "needs": [
          {
            "key": "<string>",
            "type": "int",
            "label": "<string>",
            "required": true,
            "prefill": "<string>",
            "searchfill": "<string>",
            "capabilities": [
              "<string>"
            ],
            "custom_field": true,
            "depends_on": [
              "<string>"
            ],
            "from_search": true,
            "from_write": true,
            "input_format": [
              "<any>"
            ],
            "language": "<string>",
            "parent_key": "<string>",
            "send_in_json": true,
            "regex": "<string>",
            "alters_custom_fields": true,
            "choices": [
              {
                "key": "<string>",
                "label": "<string>",
                "sample": "<string>"
              }
            ],
            "default": "<string>",
            "help_text": "<string>",
            "placeholder": "<string>",
            "default_guessable": true,
            "list": true,
            "format": "<string>"
          }
        ],
        "meta": {
          "hook": {
            "directions": "<string>",
            "is_notification": true,
            "is_pollable": true,
            "is_polling_notification": true,
            "is_subscription": true,
            "url": "<string>"
          }
        },
        "popularity": 123,
        "app_name": "<string>"
      },
      "action_gives": [
        {
          "key": "<string>",
          "score": 123,
          "subscore": 123,
          "label": "<string>",
          "type": "<string>",
          "zap_meta_sample": "<any>",
          "custom_field": false,
          "important": false
        }
      ],
      "action_needs": [
        {
          "key": "<string>",
          "type": "int",
          "label": "<string>",
          "required": true,
          "prefill": "<string>",
          "searchfill": "<string>",
          "capabilities": [
            "<string>"
          ],
          "custom_field": true,
          "depends_on": [
            "<string>"
          ],
          "from_search": true,
          "from_write": true,
          "input_format": [
            "<any>"
          ],
          "language": "<string>",
          "parent_key": "<string>",
          "send_in_json": true,
          "regex": "<string>",
          "alters_custom_fields": true,
          "choices": [
            {
              "key": "<string>",
              "label": "<string>",
              "sample": "<string>"
            }
          ],
          "default": "<string>",
          "help_text": "<string>",
          "placeholder": "<string>",
          "default_guessable": true,
          "list": true,
          "format": "<string>"
        }
      ],
      "action_sample": {}
    }
  ]
}

“Needs” are the values that need to be provided when the action is run. Needs that are not provided will be guessed by the AI when the action is run.

“Gives” are the values that the action returns when it is run.

“Sample” is a sample of what the action returns when it is run.

When you Run a stateless action, “needs” are provided to the endpoint. For each need, you can either have AI guess a value for it or you can ask the user to provide a specific value.

​
Custom fields

The list of needs that this returns can change based on the params provided in the request body.

As such, this endpoint may need to be hit multiple times as needs are chosen by the user.

This endpoint needs to be hit again whenever the selected value for a need changes and any of the following are true:

  • The changed need has alters_custom_fields set to true
  • The changed need is in the depends_on array of another need
  • The changed need has custom_field set to true

As an example, when using the GoogleSheetsV2API API with the add_row action, the first time you get the action you will get back these action_needs:

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

In order to get the column names of the spreadsheet, you’ll have to get the prefill choices. See Get Prefill Choices for more information.

In this example scenario, after getting values for the spreadsheet and worksheet prefills, another call can be made to this endpoint.

This time, in the body of the POST, we can include the selected values:

{
  "params": {
    "spreadsheet": "SOME_SPREADSHEET_ID", // this is the ID of a spreadsheet in Google Sheets
    "worksheet": "0" // the first worksheet in the spreadsheet
  }
}

Now, the action details will include the columns from the spreadsheet as custom fields:

{
  "action_details": [
    // ... same results as above, in addition to...
    {
      "key": "COL$A",
      "label": "My first column",
      "prefill": null,
      "custom_field": true,
      "depends_on": [],
      "alters_custom_fields": null
    },
    {
      "key": "COL$B",
      "label": "My second column",
      "prefill": null,
      "custom_field": true,
      "depends_on": [],
      "alters_custom_fields": null
    },
    {
      "key": "COL$C",
      "label": "My third column",
      "prefill": null,
      "custom_field": true,
      "depends_on": [],
      "alters_custom_fields": null
    }
  ]
}

​
Choices

If the need has a choices array, then the value being chosen should come from that list.

Often, you will see this with boolean fields.

For example, the SlackAPI API’s direct_message action contains the following need (irrelevant fields removed):

{
  "key": "as_bot",
  "type": "boolean",
  "label": "Send as a bot?",
  "choices": [
    {
      "key": "no",
      "label": "No"
    },
    {
      "key": "yes",
      "label": "Yes"
    }
  ],
  "default": "yes",
  "format": "SELECT"
}

​
Other field types

See Field definitions and types in the Zapier Platform documentation for details on the other types of fields that a need can have.

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
app
string
required

The app that the action belongs to.

​
action
string
required

The action to get details for.

Query Parameters

​
action_type
enum<string>
default:write

The type of the action to get details for.

This can be:

  • write: Actions that have side effects (such as sending an email or updating a spreadsheet)
  • search: Actions that return results (such as searching for a contact or getting a list of emails)
Available options:
read,
write,
search,
read_bulk,
search_or_write,
search_and_write
​
account_id
integer

The Zapier account ID to use.

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

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

​
action_extra
enum<string>[]

What kind of information to return with the action details.

List of:

  • action_needs: Include the needs of the action. These are what are provided when running the action.
  • action_gives: Include the gives of the action. These are what the action returns when it runs.
  • action_sample: Include a sample of the action. Note: This will dramatically slow down the response from this endpoint. Only use it if you really need the sample.
Available options:
action_needs,
action_gives,
action_sample

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
OK
​
results
object[]
required

Was this page helpful?