actionxm surveys

Manage VoC (Voice of Customer) surveys.

`actionxm surveys list`

List all surveys in the current project.

bash

actionxm surveys list

Example:

bash

$ actionxm surveys list
Name                      Type    Status  Questions  Created          ID
AI & Croissants Feedback  custom  active  3          Feb 28, 2026     a1b2c3d4-...
NPS Q1 2026               nps     draft   1          Feb 15, 2026     e5f6a7b8-...

`actionxm surveys view <survey-id>`

View detailed information about a survey.

bash

actionxm surveys view <survey-id>

Example:

bash

$ actionxm surveys view a1b2c3d4-...
Name:       AI & Croissants Feedback
Type:       custom
Status:     active
Questions:  3
Thank You:  Thank you for your feedback!
Created:    Feb 28, 2026
ID:         a1b2c3d4-...

Questions:
  1. * [open_text] Did you find the course useful?
  2. * [open_text] In what format would you like to continue learning?
  3. * [open_text] What could be improved?

`actionxm surveys create`

Create a new survey.

bash

actionxm surveys create --name <name> --type <type> [options]

Required flags:

Flag	Description
`--name <name>`	Survey name
`--type <type>`	Survey type: `nps`, `csat`, `ces`, or `custom`

Optional flags:

Flag	Description
`--questions <file>`	Path to a JSON file with question definitions
`--from-prompt <prompt>`	Generate questions from a natural language description using AI
`--theme <file>`	Path to a JSON file with theme configuration
`--theme-from-url <url>`	Auto-detect brand colors and fonts from a website URL
`--no-powered-by`	Remove the "Powered by ActionXM" footer from the survey
`--description <desc>`	Survey description text
`--og-title <title>`	Social preview title (og:title)
`--og-description <desc>`	Social preview description (og:description)
`--og-image <url>`	Social preview image URL (og:image)

--from-prompt and --questions are mutually exclusive

Use --from-prompt for AI-generated questions or --questions for a hand-crafted JSON file — not both.

AI question generation:

The --from-prompt flag sends a natural language description to Claude (via the tenant's configured Anthropic API key) and generates survey questions automatically. The generated questions are previewed before the survey is created.

bash

$ actionxm surveys create --name "Post-Purchase" --type nps \
    --from-prompt "Post-purchase survey for an electronics store"

Generating survey questions with AI...
Generated 5 questions (claude-sonnet-4-6)

  1. * [nps] How likely are you to recommend our store to a friend?
  2. * [csat] How satisfied were you with the delivery experience?
  3.   [single_choice] How would you rate product quality?
     - Excellent
     - Good
     - Average
     - Poor
  4.   [open_text] What could we improve?
  5.   [single_choice] Would you purchase from us again?
     - Definitely
     - Probably
     - Not sure
     - Unlikely

Creating survey...
✓ Survey created: Post-Purchase
  ID:     abc123-...
  Status: draft
  Type:   nps

Auto-theme detection:

The --theme-from-url flag fetches the given URL and extracts brand colors and fonts from the page CSS. This is useful for matching a survey's appearance to an organization's brand — even when the organization doesn't have a web project in ActionXM.

bash

actionxm surveys create --name "Feedback" --type custom \
  --questions questions.json \
  --theme-from-url https://www.example.com \
  --no-powered-by

Example output:

bash

$ actionxm surveys create --name "Q1 Feedback" --type custom \
    --questions questions.json --theme-from-url https://www.example.com
Theme detected:
  Colors: #2d6a4f, #40916c, #52b788
  Fonts:  Montserrat

✓ Survey created: Q1 Feedback
  ID:     a1b2c3d4-...
  Status: draft
  Type:   custom

`actionxm surveys edit <survey-id>`

Edit an existing survey — update its name, description, questions, theme, or thank-you message.

bash

actionxm surveys edit <survey-id> [options]

Optional flags:

Flag	Description
`--name <name>`	New survey name
`--description <desc>`	New description
`--questions <file>`	Path to a JSON file with updated question definitions (replaces all questions)
`--theme <file>`	Path to a JSON file with theme configuration
`--theme-from-url <url>`	Auto-detect brand colors and fonts from a website URL
`--no-powered-by`	Remove the "Powered by ActionXM" footer
`--thank-you <message>`	Thank-you message shown after submission

At least one flag must be provided. The --questions flag replaces the entire questions array — include all questions in the file, not just the ones you want to change.

Example — update questions from a file:

bash

$ actionxm surveys edit a1b2c3d4-... --questions updated-questions.json
✓ Survey updated: AI & Croissants Feedback
  ID:        a1b2c3d4-...
  Status:    draft
  Questions: 5

Example — rename and update theme:

bash

$ actionxm surveys edit a1b2c3d4-... \
    --name "Q2 Feedback" \
    --theme-from-url https://www.example.com \
    --no-powered-by
Theme detected:
  Colors: #2d6a4f, #40916c, #52b788
  Fonts:  Montserrat

✓ Survey updated: Q2 Feedback
  ID:        a1b2c3d4-...
  Status:    draft
  Questions: 3

Questions JSON format

The --questions flag accepts a path to a JSON file containing an array of question definitions.

QuestionDefinition shape

json

{
  "id": "string (unique within survey)",
  "type": "nps | csat | ces | rating | single_choice | multi_choice | open_text",
  "text": "string (max 500 chars)",
  "required": true,
  "order": 0,
  "config": {}
}

Field	Type	Required	Description
`id`	`string`	Yes	Unique identifier within the survey (e.g. `"q1"`, `"nps_main"`)
`type`	`string`	Yes	One of: `nps`, `csat`, `ces`, `rating`, `single_choice`, `multi_choice`, `open_text`
`text`	`string`	Yes	Question text shown to the respondent (max 500 characters)
`required`	`boolean`	No	Whether the respondent must answer before submitting (default: `true`)
`order`	`number`	No	Display order (0-based). Questions are sorted ascending by this value
`config`	`object`	No	Type-specific configuration (see below). Defaults apply when omitted

Per-type config reference

`nps` — Net Promoter Score

Config Field	Type	Default	Description
`labels`	`string[3]`	`["Not likely", "Neutral", "Very likely"]`	Labels for low / neutral / high ends

Scale is always 0–10 (not configurable).

json

{ "id": "q1", "type": "nps", "text": "How likely are you to recommend us?", "config": {} }

`csat` — Customer Satisfaction

Config Field	Type	Default	Description
`min`	`number`	`1`	Minimum value
`max`	`number`	`5`	Maximum value
`labels`	`string[]`	`["Very unsatisfied", "Unsatisfied", "Neutral", "Satisfied", "Very satisfied"]`	One label per scale point
`icon`	`string`	`"star"`	Display icon: `"star"`, `"heart"`, or `"number"`

json

{ "id": "q2", "type": "csat", "text": "Rate your satisfaction", "config": { "max": 7, "icon": "number" } }

`ces` — Customer Effort Score

Config Field	Type	Default	Description
`labels`	`string[7]`	`["Strongly disagree", ..., "Strongly agree"]`	One label per scale point (7 items)

Scale is always 1–7 (not configurable).

json

{ "id": "q3", "type": "ces", "text": "It was easy to resolve my issue", "config": {} }

`rating` — Generic numeric rating

Config Field	Type	Default	Description
`min`	`number`	`1`	Minimum value
`max`	`number`	`5`	Maximum value
`icon`	`string`	`"star"`	Display icon: `"star"`, `"heart"`, or `"number"`
`labels`	`string[]`	—	Optional labels (one per scale point)

json

{ "id": "q4", "type": "rating", "text": "Rate the content quality", "config": { "max": 10, "icon": "number" } }

`single_choice` — Single-select

Config Field	Type	Default	Description
`options`	`(string \| {label, value})[]`	—	Required. Minimum 2 options
`allow_other`	`boolean`	`false`	Show a free-text "Other" option

Options can be simple strings or objects with separate display labels and stored values:

json

{
  "id": "q5", "type": "single_choice", "text": "How did you hear about us?",
  "config": {
    "options": ["Search engine", "Social media", "Friend referral", "Advertisement"],
    "allow_other": true
  }
}

json

{
  "id": "q5b", "type": "single_choice", "text": "Select your plan",
  "config": {
    "options": [
      { "label": "Free tier", "value": "free" },
      { "label": "Pro ($29/mo)", "value": "pro" },
      { "label": "Enterprise", "value": "enterprise" }
    ]
  }
}

`multi_choice` — Multi-select

Config Field	Type	Default	Description
`options`	`(string \| {label, value})[]`	—	Required. Minimum 2 options
`allow_other`	`boolean`	`false`	Show a free-text "Other" option

Same option format as single_choice. Respondents can select multiple values.

json

{
  "id": "q6", "type": "multi_choice", "text": "Which features do you use?",
  "config": {
    "options": ["Heatmaps", "Session Replay", "Funnels", "Surveys", "Experience Graph"]
  }
}

`open_text` — Free text

Config Field	Type	Default	Description
`max_length`	`number`	`2000`	Maximum character count
`placeholder`	`string`	—	Placeholder text shown in the input

json

{ "id": "q7", "type": "open_text", "text": "Any additional feedback?", "config": { "placeholder": "Tell us more..." } }

Full multi-type example

json

[
  {
    "id": "nps_main",
    "type": "nps",
    "text": "How likely are you to recommend us to a colleague?",
    "required": true,
    "order": 0,
    "config": {}
  },
  {
    "id": "csat_support",
    "type": "csat",
    "text": "How satisfied were you with the support you received?",
    "required": true,
    "order": 1,
    "config": { "icon": "star" }
  },
  {
    "id": "channel",
    "type": "single_choice",
    "text": "How did you contact support?",
    "required": true,
    "order": 2,
    "config": {
      "options": ["Live chat", "Email", "Phone", "Help center"],
      "allow_other": true
    }
  },
  {
    "id": "features_used",
    "type": "multi_choice",
    "text": "Which product areas have you used?",
    "required": false,
    "order": 3,
    "config": {
      "options": [
        { "label": "Heatmaps", "value": "heatmaps" },
        { "label": "Session Replay", "value": "replay" },
        { "label": "Funnels", "value": "funnels" },
        { "label": "Surveys", "value": "surveys" }
      ]
    }
  },
  {
    "id": "effort",
    "type": "ces",
    "text": "The product makes it easy to understand my users",
    "required": true,
    "order": 4,
    "config": {}
  },
  {
    "id": "content_quality",
    "type": "rating",
    "text": "Rate the quality of our documentation",
    "required": false,
    "order": 5,
    "config": { "max": 10, "icon": "number" }
  },
  {
    "id": "feedback",
    "type": "open_text",
    "text": "What could we improve?",
    "required": false,
    "order": 6,
    "config": { "max_length": 1000, "placeholder": "Share your thoughts..." }
  }
]

Validation rules

Every question must have a unique id within the survey
type must be one of the 7 supported types listed above
text is required and cannot exceed 500 characters
single_choice and multi_choice require config.options with at least 2 entries
nps scale is fixed at 0–10; ces scale is fixed at 1–7
csat and rating min must be less than max
When using object-format options ({label, value}), both fields are required
order values do not need to be contiguous but must be non-negative integers

`actionxm surveys publish <survey-id>`

Publish a draft survey (transition to active status).

bash

actionxm surveys publish <survey-id>

Example:

bash

$ actionxm surveys publish a1b2c3d4-...
✓ Survey published and active.

`actionxm surveys test <survey-id>`

Generate a test link for a survey. Works with draft surveys — no need to publish first.

bash

actionxm surveys test <survey-id>

Example:

bash

$ actionxm surveys test a1b2c3d4-...
✓ Test link generated:

  https://app.action-xm.com/s/abc123def456...

Open this URL to preview and submit the survey as a test.

Test submissions are marked with channel='test' and excluded from campaign analytics.

actionxm surveys ​

actionxm surveys list ​

actionxm surveys view <survey-id> ​

actionxm surveys create ​

actionxm surveys edit <survey-id> ​

Questions JSON format ​

QuestionDefinition shape ​

Per-type config reference ​

nps — Net Promoter Score ​

csat — Customer Satisfaction ​

ces — Customer Effort Score ​

rating — Generic numeric rating ​

single_choice — Single-select ​

multi_choice — Multi-select ​

open_text — Free text ​

Full multi-type example ​

Validation rules ​

actionxm surveys publish <survey-id> ​

actionxm surveys test <survey-id> ​

actionxm surveys

`actionxm surveys list`

`actionxm surveys view <survey-id>`

`actionxm surveys create`

`actionxm surveys edit <survey-id>`

Questions JSON format

QuestionDefinition shape

Per-type config reference

`nps` — Net Promoter Score

`csat` — Customer Satisfaction

`ces` — Customer Effort Score

`rating` — Generic numeric rating

`single_choice` — Single-select

`multi_choice` — Multi-select

`open_text` — Free text

Full multi-type example

Validation rules

`actionxm surveys publish <survey-id>`

`actionxm surveys test <survey-id>`