Create a community

Create an Ur Next Door community with the API: a unique name, HTML description, visibility and icon. Create it now (201) or schedule it (202).

View as Markdown

A community is a topical group with its own feed and its own address ({slug}.urnextdoor.com). Creating one with the API works like the website's create form: you choose a name, and optionally a description, who can see and join it, and an icon.

Endpoint: POST /api/v1/communities · Scope: content · Quota: community

Fields

Field	Type	Required	Description
`name`	string	Yes	The community name. It must be unique.
`description`	string	No	What the community is about, as HTML.
`visibility`	string	No	Who can see and join it. One of: `public`, `ask_to_join`, `private`.
`icon_url`	string	No	One of the paths returned by GET /community-icons.
`scheduled_at`	string (date-time)	No	Publish later instead of now. ISO 8601 with an offset or Z, at least 5 minutes and at most 180 days ahead. Stored in UTC.

Visibility

Value	Meaning
`public`	Anyone can join. Content is public and indexed by search engines.
`ask_to_join`	Discoverable, but content is for members only. People ask to join.
`private`	Invite only, and hidden from non-members.

Non-public communities are not indexed by search engines. You can change visibility later in the community's settings on the website.

Pick an icon

icon_url must be one of the built-in icons. Get the list from GET /api/v1/community-icons (scope read) and send one of the paths exactly as returned:

cURL

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

JavaScript

const res = await fetch("https://urnextdoor.com/api/v1/community-icons", {
  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/community-icons",
    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/community-icons');
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;

Sample response: 200 OK

JSON

{
  "ok": true,
  "items": [
    "/avatars/community/running.png",
    "/avatars/community/books.png"
  ],
  "request_id": "9f8e7d6c5b4a3921"
}

Create a community now

A successful create answers 201 Created with the new community's id, slug, url and web_url:

cURL

curl -X POST "https://urnextdoor.com/api/v1/communities" \
  -H "Authorization: Bearer $UND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "Morning Runners Pune",
  "description": "<p>Early runs, routes and race plans around Pune.</p>",
  "visibility": "public",
  "icon_url": "/avatars/community/running.png"
}'

JavaScript

const res = await fetch("https://urnextdoor.com/api/v1/communities", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UND_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    name: "Morning Runners Pune",
    description: "<p>Early runs, routes and race plans around Pune.</p>",
    visibility: "public",
    icon_url: "/avatars/community/running.png",
  }),
});
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/communities",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "name": "Morning Runners Pune",
        "description": "<p>Early runs, routes and race plans around Pune.</p>",
        "visibility": "public",
        "icon_url": "/avatars/community/running.png",
    },
    timeout=30,
)
print(response.status_code, response.json())

PHP

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

$payload = [
    'name' => 'Morning Runners Pune',
    'description' => '<p>Early runs, routes and race plans around Pune.</p>',
    'visibility' => 'public',
    'icon_url' => '/avatars/community/running.png',
];

$ch = curl_init('https://urnextdoor.com/api/v1/communities');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

echo $status, PHP_EOL, $body, PHP_EOL;

Sample response: 201 Created

JSON

{
  "ok": true,
  "id": 5,
  "slug": "morning-runners-pune",
  "url": "/communities/morning-runners-pune",
  "web_url": "https://urnextdoor.com/communities/morning-runners-pune",
  "item": {
    "id": 5,
    "type": "community",
    "slug": "morning-runners-pune",
    "name": "Morning Runners Pune"
  },
  "request_id": "9f8e7d6c5b4a3921"
}

The name must be unique. If a community with that name already exists, the request answers 409 conflict.

Schedule a community

With scheduled_at, the community is not created yet. Ur Next Door keeps your request and creates the community at the time you chose. The response is 202 Accepted, and its id is a scheduled-creation id, not a community id:

cURL

curl -X POST "https://urnextdoor.com/api/v1/communities" \
  -H "Authorization: Bearer $UND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "Morning Runners Pune",
  "description": "<p>Early runs, routes and race plans around Pune.</p>",
  "visibility": "ask_to_join",
  "scheduled_at": "2026-10-20T09:30:00Z"
}'

JavaScript

const res = await fetch("https://urnextdoor.com/api/v1/communities", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UND_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    name: "Morning Runners Pune",
    description: "<p>Early runs, routes and race plans around Pune.</p>",
    visibility: "ask_to_join",
    scheduled_at: "2026-10-20T09:30:00Z",
  }),
});
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/communities",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "name": "Morning Runners Pune",
        "description": "<p>Early runs, routes and race plans around Pune.</p>",
        "visibility": "ask_to_join",
        "scheduled_at": "2026-10-20T09:30:00Z",
    },
    timeout=30,
)
print(response.status_code, response.json())

PHP

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

$payload = [
    'name' => 'Morning Runners Pune',
    'description' => '<p>Early runs, routes and race plans around Pune.</p>',
    'visibility' => 'ask_to_join',
    'scheduled_at' => '2026-10-20T09:30:00Z',
];

$ch = curl_init('https://urnextdoor.com/api/v1/communities');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

echo $status, PHP_EOL, $body, PHP_EOL;

Sample response: 202 Accepted

JSON

{
  "ok": true,
  "status": "scheduled",
  "type": "community",
  "id": 5,
  "name": "Morning Runners Pune",
  "scheduled_at": "2026-10-20T09:30:00Z",
  "request_id": "9f8e7d6c5b4a3921"
}

What to know about scheduled communities:

Use the scheduled-creation id with the scheduling endpoints and the type community: GET /api/v1/scheduled lists it, and you can reschedule it, publish (create) it now, or cancel it. See Manage scheduled content.
The name is checked when you schedule and again when the time comes. If someone else takes the name in between, the creation fails and you are notified.
Until it is created there is no community page, so url and edit_url are null in the scheduled list.
It counts against today's community quota when you schedule it.

After it is created

You can post into the new community with its id or slug (see Create a post), and manage its settings, members and editors on the website as usual.

Common errors

Status and code	Cause	Fix
`409 conflict`	A community with that name exists	Choose another name
`422 validation_failed`	Missing name, an unknown `visibility`, or an `icon_url` that is not a built-in icon	Fix the field named in `errors`
`429 quota_exceeded`	Today's community quota is used up (it is small: 2 a day on Free)	Wait until 00:00 UTC

Next steps

Create a post in your new community.
Manage scheduled content, including scheduled communities.
Rate limits and daily quotas.

Last updated October 15, 2026