# Reach more directories

URL: https://submitator.com/docs/guides/reach-more-directories

> See what keeps a project from more directories, unlock them with the badge, competitors, a promo code and the audience marks, and fill the free allowance after launch.

## What you'll build

A project that reaches as many of its 100 directories as it can. Before the launch you raise the number the preview shows; after it, you add directories from the places in the allowance that free up.

## Before you start

- **A project**, a draft or launched: see [Onboard a client's product](https://submitator.com/docs/guides/onboard-a-clients-product).
- **What your client can offer**: the products theirs is an alternative to, a discount code, and the badge on their site.

## 1. Read what would unlock more

The readiness preview lists the changes that would add directories, most directories first, and the directories that do not take this kind of product.

```bash
curl https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/readiness \
  -H "Authorization: Bearer $SUBMITATOR_API_KEY"
```

```js
const res = await fetch(
  "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/readiness",
  { headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` } },
);
const { unlocks, not_matching } = await res.json();
console.log(unlocks, not_matching);
```

```python
import os
import requests

readiness = requests.get(
    "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/readiness",
    headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"},
).json()
print(readiness["unlocks"], readiness["not_matching"])
```

Response 200 (some fields left out):

```json
{
  "object": "readiness",
  "directories": { "selected": 87, "limit": 100, "top_domain_rating": 92, "median_domain_rating": 48 },
  "unlocks": [
    { "requirement": "badge", "directories": 9, "how": "Install the badge on https://ledgerly.test and verify it." },
    { "requirement": "competitors", "directories": 3, "how": "Add at least 1 competitor in competitors." },
    { "requirement": "promo_code", "directories": 1, "how": "Add a promo code in promo_code." }
  ],
  "not_matching": { "b2b_only": 4, "ai_only": 7, "directories_only": 2, "other": 0 }
}
```

`unlocks[].requirement` is an open list: show `how` for a value you do not know. `not_matching.other` counts directories that no field of the project changes.

## 2. Add competitors and a promo code

Some directories list a product only next to its competitors, and some only with a discount for their readers. Both are fields of the project.

```bash
curl -X PATCH https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP \
  -H "Authorization: Bearer $SUBMITATOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"competitors": [{"name": "Bookwell", "url": "https://bookwell.test"}], "promo_code": "LEDGER30", "promo_description": "30% off the first 3 months"}'
```

```js
const res = await fetch("https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    competitors: [{ name: "Bookwell", url: "https://bookwell.test" }],
    promo_code: "LEDGER30",
    promo_description: "30% off the first 3 months",
  }),
});
console.log(await res.json());
```

```python
import os
import requests

res = requests.patch(
    "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP",
    headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"},
    json={
        "competitors": [{"name": "Bookwell", "url": "https://bookwell.test"}],
        "promo_code": "LEDGER30",
        "promo_description": "30% off the first 3 months",
    },
)
print(res.json())
```

A project takes up to 20 competitors, each a name of up to 100 characters and a URL of up to 500. Sending `competitors` replaces the whole list, so send every one each time.

## 3. Check the audience marks

`audience` has 3 marks: `b2b` for a product that sells to businesses, `ai` for one built around AI, and `directory` for one that is itself a list of products. Each mark opens the directories that take only that kind of product, which `not_matching` counts.

```bash
curl -X PATCH https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP \
  -H "Authorization: Bearer $SUBMITATOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audience": {"b2b": true, "ai": false, "directory": false}}'
```

```js
const res = await fetch("https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ audience: { b2b: true, ai: false, directory: false } }),
});
console.log(await res.json());
```

```python
import os
import requests

res = requests.patch(
    "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP",
    headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"},
    json={"audience": {"b2b": True, "ai": False, "directory": False}},
)
print(res.json())
```

Set a mark only when it is true for the product: those directories review what they list. Send all 3 marks each time, since `audience` replaces the whole object.

## 4. Browse the catalog

`GET /directories` is the catalog a launch picks from, highest Domain Rating first. Filter it by `topic`, `min_dr`, `requires` or `audience`, or search names with `q`.

```bash
curl "https://api.submitator.com/v1/directories?requires=none&min_dr=50&limit=50" \
  -H "Authorization: Bearer $SUBMITATOR_API_KEY"
```

```js
const res = await fetch("https://api.submitator.com/v1/directories?requires=none&min_dr=50&limit=50", {
  headers: { Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}` },
});
console.log(await res.json());
```

```python
import os
import requests

res = requests.get(
    "https://api.submitator.com/v1/directories",
    headers={"Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}"},
    params={"requires": "none", "min_dr": 50, "limit": 50},
)
print(res.json())
```

One directory from the response:

```json
{
  "object": "directory",
  "id": "dir_2Lm8Wq3Zk7Rt1Xc5Vb9NdF",
  "name": "BetaList",
  "url": "https://betalist.com",
  "domain_rating": 73,
  "topic": "startups",
  "backlink": "dofollow",
  "requires": [],
  "audience": []
}
```

Before your first purchase, test keys see the top 20 directories only. Use a directory's `id` in `include`, `exclude` and `excluded_directories`.

## 5. Add directories after the launch

The allowance counts what a launch covers: 100 places, `used` by listings that reached their directory and `reserved` by those on their way. A listing that ends `not_accepted` or `cancelled` gives its place back, and `POST /projects/{project_id}/listings` fills `available` places.

```bash
curl https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/listings \
  -H "Authorization: Bearer $SUBMITATOR_API_KEY" \
  -H "Idempotency-Key: crm_8812-add-1" \
  -H "Content-Type: application/json" \
  -d '{"directories": "auto"}'
```

```js
const res = await fetch(
  "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/listings",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SUBMITATOR_API_KEY}`,
      "Idempotency-Key": "crm_8812-add-1",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ directories: "auto" }),
  },
);
console.log(await res.json());
```

```python
import os
import requests

res = requests.post(
    "https://api.submitator.com/v1/projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/listings",
    headers={
        "Authorization": f"Bearer {os.environ['SUBMITATOR_API_KEY']}",
        "Idempotency-Key": "crm_8812-add-1",
    },
    json={"directories": "auto"},
)
print(res.json())
```

Response 202 (some fields left out):

```json
{
  "object": "project",
  "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP",
  "status": "in_progress",
  "allowance": { "total": 100, "used": 53, "reserved": 39, "available": 8 },
  "progress": { "total": 96, "pending": 9, "in_progress": 30, "action_required": 0, "submitted": 31, "live": 22, "not_accepted": 3, "cancelled": 1 }
}
```

On a launched project, the readiness preview shows what this call would add. To add one directory you chose, send `{"directories": {"include": ["dir_3Vb8Qm2Xk6Lt9Wr4Nc1ZpG"]}}`.

## 6. Let auto-replace do it, or not

`auto_replace` is on for new projects. It adds fitting directories from the free allowance for you: after a listing ends `not_accepted` or `cancelled`, after the badge passes verification, and when a new directory joins the catalog.

To keep a directory out of every launch, add and auto-replace, list it in `excluded_directories`. A launch with `include` turns `auto_replace` off unless the launch sends `"auto_replace": true`.

## Check it worked

- `GET /projects/prj_4QzX1m9Lr2Vb7Nc8Tk3HwP/readiness` shows a higher `directories.selected`, or fewer `unlocks`.
- After the launch, `allowance.available` falls as directories are added, and `progress.total` grows.
- Each addition sends a `project.listings_added` event with the count in `data.listings_added`.

## What can go wrong

| Code | Status | Fix |
| --- | --- | --- |
| [`allowance_exhausted`](https://submitator.com/docs/errors#allowance_exhausted) | 422 | Listings use or reserve all 100 places, or the project has not launched. |
| [`invalid_directories`](https://submitator.com/docs/errors#invalid_directories) | 422 | A directory you named is unknown, already has a listing, or is not open to the project yet; `errors` says which. |
| [`nothing_to_submit`](https://submitator.com/docs/errors#nothing_to_submit) | 422 | No directory fits right now. Nothing was added. |
| [`validation_failed`](https://submitator.com/docs/errors#validation_failed) | 422 | A field breaks a rule, such as a 21st competitor. |

## Next steps

- [Install the badge](https://submitator.com/docs/guides/install-the-badge): the unlock that often adds the most directories.
- [Launch and track](https://submitator.com/docs/guides/launch-and-track): spend the launch and follow the listings.
- [Directories](https://submitator.com/docs/api/directories): the catalog's filters in full.