Menu Ur Next DoorAPI Docs Get an API key

Look up ids for communities, categories, jobs and places

Use the read scope lookups to get community ids, service category ids, job option values, places and community icons instead of guessing them.

View as Markdown

Several create fields take an id or a value from a fixed list. Never guess them: fetch them from these lookups. They need the read scope and do not count against daily quotas (they do count toward the 60 requests a minute).

You needForLookup
community_id or communityAny create, to post inside a communityGET /api/v1/communities/postable
category_idServicesGET /api/v1/service-categories
employment_type, work_mode, experience_level, salary_periodJobsGET /api/v1/job-options
country_code, state_id, district_id, city_idServices and jobsGET /api/v1/geo
icon_urlCommunitiesGET /api/v1/community-icons

Communities you can post in

Lists the communities where you are an editor, admin or creator (up to 200, by name). Use id as community_id, or slug as community.

cURL
curl "https://urnextdoor.com/api/v1/communities/postable" \
  -H "Authorization: Bearer $UND_API_KEY"
JavaScript
const res = await fetch("https://urnextdoor.com/api/v1/communities/postable", {
  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/communities/postable",
    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/communities/postable');
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": [
    {
      "id": 5,
      "slug": "morning-runners-pune",
      "name": "Morning Runners Pune",
      "verified": null,
      "icon": "/avatars/community/running.png",
      "role": "creator"
    }
  ],
  "next_offset": 1,
  "has_more": false,
  "request_id": "9f8e7d6c5b4a3921"
}

If a community is missing, you are not an editor there. Ask one of its admins, or post without a community.

Service categories

A two level tree. Use a child's id as category_id.

cURL
curl "https://urnextdoor.com/api/v1/service-categories" \
  -H "Authorization: Bearer $UND_API_KEY"
JavaScript
const res = await fetch("https://urnextdoor.com/api/v1/service-categories", {
  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/service-categories",
    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/service-categories');
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,
  "categories": [
    {
      "id": 3,
      "name": "Development",
      "slug": "development",
      "icon": null,
      "description": "Websites, apps and software.",
      "count": 42,
      "children": [
        {
          "id": 12,
          "name": "Web development",
          "slug": "web-development",
          "count": 17
        }
      ]
    }
  ],
  "request_id": "9f8e7d6c5b4a3921"
}

Job options

cURL
curl "https://urnextdoor.com/api/v1/job-options" \
  -H "Authorization: Bearer $UND_API_KEY"
JavaScript
const res = await fetch("https://urnextdoor.com/api/v1/job-options", {
  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/job-options",
    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/job-options');
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,
  "employment_types": [
    "full_time",
    "part_time",
    "contract",
    "internship",
    "temporary"
  ],
  "work_modes": [
    "remote",
    "hybrid",
    "onsite"
  ],
  "experience_levels": [
    "entry",
    "mid",
    "senior",
    "lead",
    "executive"
  ],
  "salary_periods": [
    "yearly",
    "monthly",
    "hourly",
    "project"
  ],
  "request_id": "9f8e7d6c5b4a3921"
}

Places

Walk down one level at a time:

  1. GET /api/v1/geo?level=countries: every country, with a code (use as country_code), and a suggested default.
  2. GET /api/v1/geo?level=states&country=IN: states, each with an id for state_id.
  3. GET /api/v1/geo?level=districts&state=19: districts for district_id.
  4. GET /api/v1/geo?level=cities&state=19&district=329: cities for city_id (the district filter is optional).
cURL
curl "https://urnextdoor.com/api/v1/geo?level=states&country=IN" \
  -H "Authorization: Bearer $UND_API_KEY"
JavaScript
const res = await fetch("https://urnextdoor.com/api/v1/geo?level=states&country=IN", {
  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/geo",
    headers={
        "Authorization": f"Bearer {api_key}",
    },
    params={
        "level": "states",
        "country": "IN",
    },
    timeout=30,
)
print(response.status_code, response.json())
PHP
<?php
$apiKey = getenv('UND_API_KEY');

$ch = curl_init('https://urnextdoor.com/api/v1/geo?level=states&country=IN');
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": [
    {
      "id": 19,
      "name": "Maharashtra",
      "slug": "maharashtra"
    },
    {
      "id": 20,
      "name": "Manipur",
      "slug": "manipur"
    }
  ],
  "request_id": "9f8e7d6c5b4a3921"
}

An unknown level answers 422 validation_failed.

Community icons

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"
}

Cache what rarely changes

Categories, job options, countries, states and icons change rarely. Fetch them once a day (or once per agent session) and reuse the result, rather than calling the lookup before every create.

Next steps

Last updated