# Lookup endpoints

> Find the ids the create endpoints need: communities you can post in, service categories, job options, places and icons.

Source: https://docs.urnextdoor.com/reference/lookups/

All paths are relative to `https://urnextdoor.com/api/v1`. See [API reference](https://docs.urnextdoor.com/reference.md) for the envelope and headers every endpoint shares.

| Endpoint | What it does | Scope | Daily quota |
| --- | --- | --- | --- |
| [`GET /communities/postable`](https://docs.urnextdoor.com/reference/lookups/#listPostableCommunities) | Communities you can post in | `read` | not counted |
| [`GET /service-categories`](https://docs.urnextdoor.com/reference/lookups/#listServiceCategories) | Service categories | `read` | not counted |
| [`GET /job-options`](https://docs.urnextdoor.com/reference/lookups/#getJobOptions) | Job options | `read` | not counted |
| [`GET /geo`](https://docs.urnextdoor.com/reference/lookups/#getGeo) | Countries, states, districts and cities | `read` | not counted |
| [`GET /community-icons`](https://docs.urnextdoor.com/reference/lookups/#listCommunityIcons) | Community icons | `read` | not counted |

## Communities you can post in {#listPostableCommunities}

`GET https://urnextdoor.com/api/v1/communities/postable`

Lists the communities you may post into (you are an editor or above). Use id as community_id or slug as community on any create.

- **Auth:** your API key (Bearer or X-API-Key)
- **Scope:** `read`
- **Daily quota:** not counted
- **operationId:** `listPostableCommunities`

### Example

**cURL**

```bash
curl "https://urnextdoor.com/api/v1/communities/postable" \
  -H "Authorization: Bearer $UND_API_KEY"
```

**JavaScript**

```js
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**

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

### Responses

| Status | Meaning | Codes |
| --- | --- | --- |
| `200 OK` | Communities you can post in. |   |
| `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` |

## Service categories {#listServiceCategories}

`GET https://urnextdoor.com/api/v1/service-categories`

Returns the Marketplace category tree. Use a category id as category_id when you list a service.

- **Auth:** your API key (Bearer or X-API-Key)
- **Scope:** `read`
- **Daily quota:** not counted
- **operationId:** `listServiceCategories`

### Example

**cURL**

```bash
curl "https://urnextdoor.com/api/v1/service-categories" \
  -H "Authorization: Bearer $UND_API_KEY"
```

**JavaScript**

```js
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**

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

### Responses

| Status | Meaning | Codes |
| --- | --- | --- |
| `200 OK` | The category tree. |   |
| `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` |

## Job options {#getJobOptions}

`GET https://urnextdoor.com/api/v1/job-options`

Returns the allowed values for employment_type, work_mode, experience_level and salary_period on POST /jobs.

- **Auth:** your API key (Bearer or X-API-Key)
- **Scope:** `read`
- **Daily quota:** not counted
- **operationId:** `getJobOptions`

### Example

**cURL**

```bash
curl "https://urnextdoor.com/api/v1/job-options" \
  -H "Authorization: Bearer $UND_API_KEY"
```

**JavaScript**

```js
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**

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

### Responses

| Status | Meaning | Codes |
| --- | --- | --- |
| `200 OK` | Allowed values. |   |
| `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` |

## Countries, states, districts and cities {#getGeo}

`GET https://urnextdoor.com/api/v1/geo`

Looks up places for service and job locations. level=countries (items have a code), level=states&country=IN, level=districts&state=19, or level=cities&state=19 (optionally &district=329).

- **Auth:** your API key (Bearer or X-API-Key)
- **Scope:** `read`
- **Daily quota:** not counted
- **operationId:** `getGeo`

### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `level` | query | Yes | Which list to return. One of: `countries`, `states`, `districts`, `cities`. |
| `country` | query | No | ISO 3166-1 alpha-2 code. Needed for level=states. |
| `state` | query | No | State id. Needed for level=districts and level=cities. |
| `district` | query | No | District id. Narrows level=cities. |

### Example

**cURL**

```bash
curl "https://urnextdoor.com/api/v1/geo?level=states&country=IN" \
  -H "Authorization: Bearer $UND_API_KEY"
```

**JavaScript**

```js
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**

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

### Responses

| Status | Meaning | Codes |
| --- | --- | --- |
| `200 OK` | Places at that level. |   |
| `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` |

## Community icons {#listCommunityIcons}

`GET https://urnextdoor.com/api/v1/community-icons`

Returns the built-in icons a community may use. Pass one as icon_url on POST /communities.

- **Auth:** your API key (Bearer or X-API-Key)
- **Scope:** `read`
- **Daily quota:** not counted
- **operationId:** `listCommunityIcons`

### Example

**cURL**

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

**JavaScript**

```js
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**

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

### Responses

| Status | Meaning | Codes |
| --- | --- | --- |
| `200 OK` | Icon paths. |   |
| `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` |