Quickstart

In five minutes you will send a notification to your phone and get a decision back in your code.

You need an account on app.notific.me and Node.js 18 or later (the SDK also runs on Bun, Deno, Cloudflare Workers and browsers).

Create a service. In app.notific.me, open Services & tokens and create a service, for example billing or deploy-bot. The service slug becomes the source of your events.
Create a token. On the same page, create a token for the service with the Agent package: events:write, asks:write and asks:read. Copy the value (nm_svc_…): it is shown only once.

A service token is a secret. Keep it on your server or in your secret manager, never in a browser or mobile app you ship.
Set the environment. The SDK reads both variables. The SDKs page of app.notific.me shows the API address of your account.
Terminal window
```
export NOTIFICME_URL="https://api.notific.me"
export NOTIFICME_TOKEN="nm_svc_..."
```
Install the SDK.
Terminal window
```
npm install @notificme/sdk
```
Until the package is on npm, download the tarball from SDKs in app.notific.me and install it from the file: npm install ./notificme-sdk-latest.tgz.
Install the app and turn on notifications. Sign in to app.notific.me on your phone, install it as an app (PWA) and allow notifications. See App, PWA and push.

import { NotificMe } from "@notificme/sdk";

// Reads NOTIFICME_URL and NOTIFICME_TOKEN from the environment.
const notific = new NotificMe({ source: "billing" });

const result = await notific.send({
  type: "invoice.failed",
  severity: "high",
  summary: "Invoice #42 failed",
  payload: { invoice: 42, amount: 129.9 },
});

console.log(result.id, result.status); // "019a…", "queued"

curl -sS -X POST "$NOTIFICME_URL/v0/events" \
  -H "Authorization: Bearer $NOTIFICME_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "billing",
    "type": "invoice.failed",
    "severity": "high",
    "occurred_at": "'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'",
    "content": { "summary": "Invoice #42 failed" }
  }'

The API answers 202 Accepted with the event id. A few moments later the notification shows up in My notifications and as a push on your phone.

Ask a question and wait for the answer

TypeScript
curl

import { NotificMe } from "@notificme/sdk";

const notific = new NotificMe({ source: "billing" });

// Blocks until a person answers (or the timeout applies onTimeout).
const reply = await notific.ask({
  title: "Refund order #881 (USD 240)?",
  questions: [
    { id: "decision", type: "single", text: "What should we do?", options: ["Refund", "Partial refund", "Deny"] },
    { id: "note", type: "text", text: "Note for the customer", optional: true },
  ],
  level: 2,
  timeout: "30m",
  onTimeout: { decision: "Deny" },
});

if (reply.status === "answered" && reply.answers.decision === "Refund") {
  // …refund
}
console.log(reply.asText); // natural-language summary of the decision

# 1. Create the question set
curl -sS -X POST "$NOTIFICME_URL/v0/asks" \
  -H "Authorization: Bearer $NOTIFICME_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-881" \
  -d '{
    "title": "Refund order #881 (USD 240)?",
    "questions": [
      { "id": "decision", "type": "single", "text": "What should we do?", "options": ["Refund", "Partial refund", "Deny"] }
    ],
    "level": 2,
    "timeout": "30m",
    "on_timeout": { "decision": "Deny" }
  }'

# 2. Long-poll the answer (up to 60 s per request) with the "id" returned above
curl -sS "$NOTIFICME_URL/v0/asks/<id>?wait=60" \
  -H "Authorization: Bearer $NOTIFICME_TOKEN"

On your phone, open the notification, choose an option and confirm. Level 2 asks for biometrics on the native app, or for the 2FA code on the web app. Your code receives the signed reply:

{
  "question_set_id": "019a…",
  "version": 1,
  "status": "answered",
  "answers": [
    { "question_id": "decision", "question_text": "What should we do?", "value": "Refund" }
  ],
  "as_text": "…",
  "answered_by": { "identity": "[email protected]", "device_id": "019a…", "level_used": 2, "auth_method": "totp" },
  "answered_at": "2026-11-05T12:03:10Z",
  "content_hash": "…",
  "signature": { "alg": "Ed25519", "key_id": "…", "value": "…" }
}

Next steps

Prefer not to keep a process waiting? Use createAsk() with a callbackUrl and verify the webhook.
Make the notification richer with a card.
Connect Dokploy, GitHub or any system that sends webhooks with an incoming hook.
Let an AI agent ask for approval with the MCP server.