Notification endpoints

Read your notifications, count the unread ones, and mark one or all of them as read.

All paths are relative to https://urnextdoor.com/api/v1. See API reference for the envelope and headers every endpoint shares.

Endpoint	What it does	Scope	Daily quota
`GET /notifications`	Read your notifications	`notifications`	not counted
`GET /notifications/count`	Count unread notifications	`notifications`	not counted
`POST /notifications/{id}/read`	Mark a notification read	`notifications`	not counted
`POST /notifications/read-all`	Mark all notifications read	`notifications`	not counted

Read your notifications

GET https://urnextdoor.com/api/v1/notifications

Your newest notifications.

Auth: your API key (Bearer or X-API-Key)
Scope: notifications
Daily quota: not counted
operationId: listNotifications

Parameters

Name	In	Required	Description
`limit`	query	No	1 to 50 (default 20).

Example

cURL

curl "https://urnextdoor.com/api/v1/notifications" \
  -H "Authorization: Bearer $UND_API_KEY"

JavaScript

const res = await fetch("https://urnextdoor.com/api/v1/notifications", {
  headers: {
    Authorization: `Bearer ${process.env.UND_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os

import requests

api_key = os.environ["UND_API_KEY"]

response = requests.get(
    "https://urnextdoor.com/api/v1/notifications",
    headers={
        "Authorization": f"Bearer {api_key}",
    },
    timeout=30,
)
print(response.status_code, response.json())

PHP

<?php
$apiKey = getenv('UND_API_KEY');

$ch = curl_init('https://urnextdoor.com/api/v1/notifications');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

echo $status, PHP_EOL, $body, PHP_EOL;

Responses

Status	Meaning	Codes
`200 OK`	{items, unread_shown}.
`401 Unauthorized`	No key, or the key is unknown, malformed, revoked or expired, or the member is not active.	`missing_api_key`, `invalid_api_key`
`403 Forbidden`	The key lacks the scope, or the member may not do this.	`insufficient_scope`, `forbidden`
`404 Not Found`	Unknown route or item, or the item is not yours.	`not_found`
`421 Misdirected Request`	Called on a community subdomain. Use https://urnextdoor.com.	`wrong_host`
`422 Unprocessable Content`	Field errors, or an Idempotency-Key reused with a different body.	`validation_failed`, `idempotency_key_reused`
`429 Too Many Requests`	Over 60 requests a minute from this member (or too many failed key checks from one address), or today's quota for this action is used up.	`rate_limited`, `quota_exceeded`
`500 Internal Server Error`	Our fault. Safe to retry with the same Idempotency-Key.	`server_error`
`503 Service Unavailable`	The API is switched off.	`api_disabled`

Count unread notifications

GET https://urnextdoor.com/api/v1/notifications/count

How many notifications are unread.

Auth: your API key (Bearer or X-API-Key)
Scope: notifications
Daily quota: not counted
operationId: countNotifications

Example

cURL

curl "https://urnextdoor.com/api/v1/notifications/count" \
  -H "Authorization: Bearer $UND_API_KEY"

JavaScript

const res = await fetch("https://urnextdoor.com/api/v1/notifications/count", {
  headers: {
    Authorization: `Bearer ${process.env.UND_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os

import requests

api_key = os.environ["UND_API_KEY"]

response = requests.get(
    "https://urnextdoor.com/api/v1/notifications/count",
    headers={
        "Authorization": f"Bearer {api_key}",
    },
    timeout=30,
)
print(response.status_code, response.json())

PHP

<?php
$apiKey = getenv('UND_API_KEY');

$ch = curl_init('https://urnextdoor.com/api/v1/notifications/count');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

echo $status, PHP_EOL, $body, PHP_EOL;

Responses

Status	Meaning	Codes
`200 OK`	{unread}.
`401 Unauthorized`	No key, or the key is unknown, malformed, revoked or expired, or the member is not active.	`missing_api_key`, `invalid_api_key`
`403 Forbidden`	The key lacks the scope, or the member may not do this.	`insufficient_scope`, `forbidden`
`404 Not Found`	Unknown route or item, or the item is not yours.	`not_found`
`421 Misdirected Request`	Called on a community subdomain. Use https://urnextdoor.com.	`wrong_host`
`429 Too Many Requests`	Over 60 requests a minute from this member (or too many failed key checks from one address), or today's quota for this action is used up.	`rate_limited`, `quota_exceeded`
`500 Internal Server Error`	Our fault. Safe to retry with the same Idempotency-Key.	`server_error`
`503 Service Unavailable`	The API is switched off.	`api_disabled`

Mark a notification read

POST https://urnextdoor.com/api/v1/notifications/{id}/read

Mark one notification read.

Auth: your API key (Bearer or X-API-Key)
Scope: notifications
Daily quota: not counted
Idempotency-Key: supported (see Idempotency)
operationId: markNotificationRead

Parameters

Name	In	Required	Description
`id`	path	Yes	The notification id.

Example

cURL

curl -X POST "https://urnextdoor.com/api/v1/notifications/41/read" \
  -H "Authorization: Bearer $UND_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

JavaScript

const res = await fetch("https://urnextdoor.com/api/v1/notifications/41/read", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UND_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
  },
});
console.log(res.status, await res.json());

Python

import os
import uuid

import requests

api_key = os.environ["UND_API_KEY"]

response = requests.post(
    "https://urnextdoor.com/api/v1/notifications/41/read",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    timeout=30,
)
print(response.status_code, response.json())

PHP

<?php
$apiKey = getenv('UND_API_KEY');

$ch = curl_init('https://urnextdoor.com/api/v1/notifications/41/read');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

echo $status, PHP_EOL, $body, PHP_EOL;

Responses

Status	Meaning	Codes
`200 OK`	{unread}.
`400 Bad Request`	The body is not a JSON object, or the Idempotency-Key header is malformed.	`invalid_json`, `invalid_idempotency_key`
`401 Unauthorized`	No key, or the key is unknown, malformed, revoked or expired, or the member is not active.	`missing_api_key`, `invalid_api_key`
`403 Forbidden`	The key lacks the scope, or the member may not do this.	`insufficient_scope`, `forbidden`
`404 Not Found`	Unknown route or item, or the item is not yours.	`not_found`
`409 Conflict`	Conflicts with the current state, or the same Idempotency-Key is still being processed.	`conflict`, `idempotency_in_progress`
`413 Payload Too Large`	The body is over the limit, or the image is over 8 MB.	`payload_too_large`
`415 Unsupported Media Type`	Wrong Content-Type, or a file type that is not allowed.	`unsupported_media_type`
`421 Misdirected Request`	Called on a community subdomain. Use https://urnextdoor.com.	`wrong_host`
`422 Unprocessable Content`	Field errors, or an Idempotency-Key reused with a different body.	`validation_failed`, `idempotency_key_reused`
`429 Too Many Requests`	Over 60 requests a minute from this member (or too many failed key checks from one address), or today's quota for this action is used up.	`rate_limited`, `quota_exceeded`
`500 Internal Server Error`	Our fault. Safe to retry with the same Idempotency-Key.	`server_error`
`503 Service Unavailable`	The API is switched off.	`api_disabled`

Mark all notifications read

POST https://urnextdoor.com/api/v1/notifications/read-all

Mark every notification read.

Auth: your API key (Bearer or X-API-Key)
Scope: notifications
Daily quota: not counted
Idempotency-Key: supported (see Idempotency)
operationId: markAllNotificationsRead

Example

cURL

curl -X POST "https://urnextdoor.com/api/v1/notifications/read-all" \
  -H "Authorization: Bearer $UND_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

JavaScript

const res = await fetch("https://urnextdoor.com/api/v1/notifications/read-all", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UND_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
  },
});
console.log(res.status, await res.json());

Python

import os
import uuid

import requests

api_key = os.environ["UND_API_KEY"]

response = requests.post(
    "https://urnextdoor.com/api/v1/notifications/read-all",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    timeout=30,
)
print(response.status_code, response.json())

PHP

<?php
$apiKey = getenv('UND_API_KEY');

$ch = curl_init('https://urnextdoor.com/api/v1/notifications/read-all');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

echo $status, PHP_EOL, $body, PHP_EOL;

Responses

Status	Meaning	Codes
`200 OK`	{marked, unread}.
`400 Bad Request`	The body is not a JSON object, or the Idempotency-Key header is malformed.	`invalid_json`, `invalid_idempotency_key`
`401 Unauthorized`	No key, or the key is unknown, malformed, revoked or expired, or the member is not active.	`missing_api_key`, `invalid_api_key`
`403 Forbidden`	The key lacks the scope, or the member may not do this.	`insufficient_scope`, `forbidden`
`404 Not Found`	Unknown route or item, or the item is not yours.	`not_found`
`409 Conflict`	Conflicts with the current state, or the same Idempotency-Key is still being processed.	`conflict`, `idempotency_in_progress`
`413 Payload Too Large`	The body is over the limit, or the image is over 8 MB.	`payload_too_large`
`415 Unsupported Media Type`	Wrong Content-Type, or a file type that is not allowed.	`unsupported_media_type`
`421 Misdirected Request`	Called on a community subdomain. Use https://urnextdoor.com.	`wrong_host`
`422 Unprocessable Content`	Field errors, or an Idempotency-Key reused with a different body.	`validation_failed`, `idempotency_key_reused`
`429 Too Many Requests`	Over 60 requests a minute from this member (or too many failed key checks from one address), or today's quota for this action is used up.	`rate_limited`, `quota_exceeded`
`500 Internal Server Error`	Our fault. Safe to retry with the same Idempotency-Key.	`server_error`
`503 Service Unavailable`	The API is switched off.	`api_disabled`

Last updated October 16, 2026