Skip to main content
You can create incoming and outgoing automations directly through the API rather than navigating the Stairoids UI. This is especially useful when provisioning automations programmatically for multiple workspaces, deploying automation configs from version control, or building internal tooling that manages your GTM workflow. A new automation is inactive by default — you control exactly when it goes live.
Set enabled: false at creation to keep the automation paused while you validate trigger conditions and action mappings. Update it to enabled: true once you are confident it behaves as expected.

​
Endpoint

POST https://api.stairoids.com/v1/automations

​
Authentication

Authorization: Bearer <api-key>

​
Request Body

​
name
string
required
A human-readable label for the automation. Use something descriptive enough to identify its purpose at a glance — for example, "Flag High-Intent Pricing Visits for SDR Outreach".
​
type
string
required
The direction of data flow. Use incoming for automations that ingest signals into Stairoids from external sources, or outgoing for automations that push enriched signal data to downstream tools when a trigger fires.
​
enabled
boolean
default:"false"
Set to true to activate the automation immediately upon creation. Defaults to false, leaving the automation in a paused state so you can test it first.
​
trigger
object
required
Defines the conditions under which the automation fires. The shape of this object differs depending on type.
​
action
object
Defines what Stairoids does when the trigger fires. Required for outgoing automations; omit for incoming automations.

​
Request Examples

curl -X POST https://api.stairoids.com/v1/automations \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Update HubSpot Deal on Form Submit",
    "type": "outgoing",
    "enabled": false,
    "trigger": {
      "event": "signal.created",
      "conditions": [
        {
          "field": "signal.type",
          "operator": "eq",
          "value": "form_submit"
        },
        {
          "field": "signal.score",
          "operator": "gt",
          "value": "40"
        }
      ]
    },
    "action": {
      "type": "hubspot",
      "config": {
        "object": "deal",
        "pipeline_id": "pipeline_001",
        "stage_id": "stage_qualified",
        "owner_id": "hs_owner_88",
        "field_mappings": {
          "dealname": "{{account.name}} — {{signal.type}}",
          "hs_lead_status": "IN_PROGRESS"
        }
      }
    }
  }'

​
Response

A successful request returns HTTP 201 Created with the full automation object in the response body. 
{
  "id": "auto_k9l0m1n2",
  "name": "Update HubSpot Deal on Form Submit",
  "type": "outgoing",
  "enabled": false,
  "trigger": {
    "event": "signal.created",
    "conditions": [
      {
        "field": "signal.type",
        "operator": "eq",
        "value": "form_submit"
      },
      {
        "field": "signal.score",
        "operator": "gt",
        "value": "40"
      }
    ]
  },
  "action": {
    "type": "hubspot",
    "config": {
      "object": "deal",
      "pipeline_id": "pipeline_001",
      "stage_id": "stage_qualified",
      "owner_id": "hs_owner_88",
      "field_mappings": {
        "dealname": "{{account.name}} — {{signal.type}}",
        "hs_lead_status": "IN_PROGRESS"
      }
    }
  },
  "created_at": "2024-10-15T11:00:00Z",
  "updated_at": "2024-10-15T11:00:00Z"
}

​
HTTP Status Codes

StatusMeaning
201 CreatedThe automation was created successfully.
400 Bad RequestA required field is missing or a field value is invalid. The response body includes a message describing the issue.
401 UnauthorizedThe API key is missing or invalid.
422 Unprocessable EntityThe request body is structurally valid JSON but the automation config contains a logical conflict (e.g., an outgoing automation with no action).
429 Too Many RequestsRate limit exceeded. Check the Retry-After header.