Nudgeflare
Sign inGet started

DEV3 Nudgeflare REST API

Base URL /api/v1 · Authenticate with Authorization: Bearer nf_sk_… · OpenAPI 3.1 JSON

get/api/v1/sitesscope: campaigns:read

List sites (VAPID public key included, private key never)

get/api/v1/sites/{id}scope: campaigns:read

Get a site

Parameters: id (path)

get/api/v1/subscribersscope: subscribers:read

List subscribers (masked endpoint hash, never the endpoint or keys)

Parameters: siteId (query), status (query), tag (query), country (query), externalId (query), limit (query), cursor (query)

get/api/v1/subscribers/{id}scope: subscribers:read

Get a subscriber

Parameters: id (path)

patch/api/v1/subscribers/{id}scope: subscribers:write

Update tags, attributes or the external id

Parameters: id (path)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "addTags": {
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[A-Za-z0-9][A-Za-z0-9 _:.\\-/]{0,63}$"
      }
    },
    "removeTags": {
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[A-Za-z0-9][A-Za-z0-9 _:.\\-/]{0,63}$"
      }
    },
    "attributes": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9_]{0,31}$"
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string",
            "maxLength": 200
          },
          {
            "type": "number"
          },
          {
            "type": "boolean"
          }
        ]
      }
    },
    "externalId": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "additionalProperties": false
}
delete/api/v1/subscribers/{id}scope: subscribers:write

Delete a subscriber

Parameters: id (path)

get/api/v1/segmentsscope: subscribers:read

List segments

post/api/v1/segmentsscope: subscribers:write

Create a segment (allow-listed rule builder)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "siteIds": {
      "default": [],
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[0-9a-f]{24}$"
      }
    },
    "rules": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "name",
    "siteIds",
    "rules"
  ],
  "additionalProperties": false
}
post/api/v1/segments/estimatescope: subscribers:read

Estimate the audience of a saved segment or of ad-hoc rules

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "segmentId": {
      "type": "string",
      "pattern": "^[0-9a-f]{24}$"
    },
    "siteIds": {
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[0-9a-f]{24}$"
      }
    },
    "rules": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "additionalProperties": false
}
get/api/v1/segments/{id}scope: subscribers:read

Get a segment

Parameters: id (path)

patch/api/v1/segments/{id}scope: subscribers:write

Update a segment

Parameters: id (path)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "siteIds": {
      "default": [],
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[0-9a-f]{24}$"
      }
    },
    "rules": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "additionalProperties": false
}
delete/api/v1/segments/{id}scope: subscribers:write

Delete a segment

Parameters: id (path)

get/api/v1/campaignsscope: campaigns:read

List campaigns

Parameters: status (query), limit (query)

post/api/v1/campaignsscope: campaigns:write

Create a draft campaign (title ≤ 65, body ≤ 240, ≤ 2 buttons, optional A/B)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 160
    },
    "siteIds": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[0-9a-f]{24}$"
      }
    },
    "segmentIds": {
      "default": [],
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[0-9a-f]{24}$"
      }
    },
    "variants": {
      "minItems": 1,
      "maxItems": 4,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "pattern": "^[A-D]$"
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 65
          },
          "body": {
            "type": "string",
            "minLength": 1,
            "maxLength": 240
          },
          "icon": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2048
              },
              {
                "type": "null"
              }
            ]
          },
          "image": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2048
              },
              {
                "type": "null"
              }
            ]
          },
          "buttons": {
            "default": [],
            "maxItems": 2,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 24
                },
                "url": {
                  "type": "string",
                  "maxLength": 2048
                }
              },
              "required": [
                "label",
                "url"
              ],
              "additionalProperties": false
            }
          },
          "url": {
            "type": "string",
            "maxLength": 2048
          },
          "utm": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "source": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "medium": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "campaign": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "term": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "content": {
                    "type": "string",
                    "maxLength": 120
                  }
                },
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "key",
          "title",
          "body",
          "buttons",
          "url"
        ],
        "additionalProperties": false
      }
    },
    "ab": {
      "default": {
        "enabled": false,
        "testPct": 20,
        "metric": "ctr",
        "decideAfterHours": 4,
        "minClicks": 100,
        "fallback": "A"
      },
      "type": "object",
      "properties": {
        "enabled": {
          "default": false,
          "type": "boolean"
        },
        "testPct": {
          "default": 20,
          "type": "integer",
          "minimum": 5,
          "maximum": 50
        },
        "metric": {
          "default": "ctr",
          "type": "string",
          "const": "ctr"
        },
        "decideAfterHours": {
          "default": 4,
          "type": "integer",
          "minimum": 1,
          "maximum": 168
        },
        "minClicks": {
          "default": 100,
          "type": "integer",
          "minimum": 1,
          "maximum": 100000
        },
        "fallback": {
          "default": "A",
          "type": "string",
          "enum": [
            "A",
            "both"
          ]
        }
      },
      "required": [
        "enabled",
        "testPct",
        "metric",
        "decideAfterHours",
        "minClicks",
        "fallback"
      ],
      "additionalProperties": false
    },
    "schedule": {
      "default": {
        "mode": "now",
        "throttlePerMin": 0
      },
      "type": "object",
      "properties": {
        "mode": {
          "default": "now",
          "type": "string",
          "enum": [
            "now",
            "at",
            "local"
          ]
        },
        "at": {},
        "localDate": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        "localTime": {
          "type": "string",
          "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
        },
        "throttlePerMin": {
          "default": 0,
          "type": "integer",
          "minimum": 0,
          "maximum": 1000000
        }
      },
      "required": [
        "mode",
        "throttlePerMin"
      ],
      "additionalProperties": false
    },
    "ttl": {
      "default": 86400,
      "type": "integer",
      "minimum": 0,
      "maximum": 2419200
    },
    "urgency": {
      "default": "normal",
      "type": "string",
      "enum": [
        "very-low",
        "low",
        "normal",
        "high"
      ]
    }
  },
  "required": [
    "name",
    "siteIds",
    "segmentIds",
    "variants",
    "ab",
    "schedule",
    "ttl",
    "urgency"
  ],
  "additionalProperties": false
}
get/api/v1/campaigns/{id}scope: campaigns:read

Get a campaign

Parameters: id (path)

patch/api/v1/campaigns/{id}scope: campaigns:write

Replace a draft campaign

Parameters: id (path)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 160
    },
    "siteIds": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[0-9a-f]{24}$"
      }
    },
    "segmentIds": {
      "default": [],
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[0-9a-f]{24}$"
      }
    },
    "variants": {
      "minItems": 1,
      "maxItems": 4,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "pattern": "^[A-D]$"
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 65
          },
          "body": {
            "type": "string",
            "minLength": 1,
            "maxLength": 240
          },
          "icon": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2048
              },
              {
                "type": "null"
              }
            ]
          },
          "image": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2048
              },
              {
                "type": "null"
              }
            ]
          },
          "buttons": {
            "default": [],
            "maxItems": 2,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 24
                },
                "url": {
                  "type": "string",
                  "maxLength": 2048
                }
              },
              "required": [
                "label",
                "url"
              ],
              "additionalProperties": false
            }
          },
          "url": {
            "type": "string",
            "maxLength": 2048
          },
          "utm": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "source": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "medium": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "campaign": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "term": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "content": {
                    "type": "string",
                    "maxLength": 120
                  }
                },
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "key",
          "title",
          "body",
          "buttons",
          "url"
        ],
        "additionalProperties": false
      }
    },
    "ab": {
      "default": {
        "enabled": false,
        "testPct": 20,
        "metric": "ctr",
        "decideAfterHours": 4,
        "minClicks": 100,
        "fallback": "A"
      },
      "type": "object",
      "properties": {
        "enabled": {
          "default": false,
          "type": "boolean"
        },
        "testPct": {
          "default": 20,
          "type": "integer",
          "minimum": 5,
          "maximum": 50
        },
        "metric": {
          "default": "ctr",
          "type": "string",
          "const": "ctr"
        },
        "decideAfterHours": {
          "default": 4,
          "type": "integer",
          "minimum": 1,
          "maximum": 168
        },
        "minClicks": {
          "default": 100,
          "type": "integer",
          "minimum": 1,
          "maximum": 100000
        },
        "fallback": {
          "default": "A",
          "type": "string",
          "enum": [
            "A",
            "both"
          ]
        }
      },
      "required": [
        "enabled",
        "testPct",
        "metric",
        "decideAfterHours",
        "minClicks",
        "fallback"
      ],
      "additionalProperties": false
    },
    "schedule": {
      "default": {
        "mode": "now",
        "throttlePerMin": 0
      },
      "type": "object",
      "properties": {
        "mode": {
          "default": "now",
          "type": "string",
          "enum": [
            "now",
            "at",
            "local"
          ]
        },
        "at": {},
        "localDate": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        "localTime": {
          "type": "string",
          "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
        },
        "throttlePerMin": {
          "default": 0,
          "type": "integer",
          "minimum": 0,
          "maximum": 1000000
        }
      },
      "required": [
        "mode",
        "throttlePerMin"
      ],
      "additionalProperties": false
    },
    "ttl": {
      "default": 86400,
      "type": "integer",
      "minimum": 0,
      "maximum": 2419200
    },
    "urgency": {
      "default": "normal",
      "type": "string",
      "enum": [
        "very-low",
        "low",
        "normal",
        "high"
      ]
    }
  },
  "required": [
    "name",
    "siteIds",
    "segmentIds",
    "variants",
    "ab",
    "schedule",
    "ttl",
    "urgency"
  ],
  "additionalProperties": false
}
delete/api/v1/campaigns/{id}scope: campaigns:write

Delete a draft or cancelled campaign

Parameters: id (path)

post/api/v1/campaigns/{id}/sendscope: campaigns:send

Send now (exactly one delivery per subscriber, even if called twice)

Parameters: id (path)

post/api/v1/campaigns/{id}/schedulescope: campaigns:send

Schedule at a UTC time or at a local time per timezone

Parameters: id (path)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "at",
        "local"
      ]
    },
    "at": {
      "type": "string"
    },
    "localDate": {
      "type": "string"
    },
    "localTime": {
      "type": "string"
    },
    "throttlePerMin": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "mode"
  ],
  "additionalProperties": false
}
post/api/v1/campaigns/{id}/cancelscope: campaigns:send

Cancel a campaign

Parameters: id (path)

get/api/v1/campaigns/{id}/statsscope: campaigns:read

Results per variant and per timezone wave

Parameters: id (path)

post/api/v1/automations/{key}/triggerscope: automations:trigger

Trigger an API automation for subscribers (idempotent per key)

Parameters: key (path)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "externalIds": {
      "maxItems": 1000,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 128
      }
    },
    "subscriberIds": {
      "maxItems": 1000,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[0-9a-f]{24}$"
      }
    },
    "segmentId": {
      "type": "string",
      "pattern": "^[0-9a-f]{24}$"
    },
    "idempotencyKey": {
      "type": "string",
      "minLength": 8,
      "maxLength": 128
    },
    "override": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "maxLength": 65
        },
        "body": {
          "type": "string",
          "maxLength": 240
        },
        "url": {
          "type": "string",
          "maxLength": 2048
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "idempotencyKey"
  ],
  "additionalProperties": false
}
post/api/v1/notificationsscope: automations:trigger

One-off transactional push to an external id

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "externalId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "siteId": {
      "type": "string",
      "pattern": "^[0-9a-f]{24}$"
    },
    "idempotencyKey": {
      "type": "string",
      "minLength": 8,
      "maxLength": 128
    },
    "content": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "maxLength": 65
        },
        "body": {
          "type": "string",
          "maxLength": 240
        },
        "url": {
          "type": "string",
          "maxLength": 2048
        },
        "icon": {
          "type": [
            "string",
            "null"
          ]
        },
        "image": {
          "type": [
            "string",
            "null"
          ]
        },
        "buttons": {
          "maxItems": 2,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string",
                "maxLength": 24
              },
              "url": {
                "type": "string",
                "maxLength": 2048
              }
            },
            "required": [
              "label",
              "url"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "title",
        "body",
        "url"
      ],
      "additionalProperties": false
    },
    "ttl": {
      "type": "integer",
      "minimum": 0,
      "maximum": 2419200
    },
    "urgency": {
      "type": "string",
      "enum": [
        "very-low",
        "low",
        "normal",
        "high"
      ]
    }
  },
  "required": [
    "externalId",
    "idempotencyKey",
    "content"
  ],
  "additionalProperties": false
}
get/api/v1/analyticsscope: analytics:read

Daily delivery and click analytics

Parameters: siteId (query), campaignId (query), from (query), to (query)