# How it works

URL: https://submitator.com/docs/how-it-works

> The life of a project and its listings, every status, how long it takes, and the words these docs use.

## The life of a project

1. **Draft.** You create a project from your client's URL and we fill in the name, tagline and short description from the site. You add a logo, 1 to 5 screenshots and a contact email; a draft costs nothing and you can delete it.
2. **Launch.** The launch uses 1 launch from your balance and gives the project an allowance of 100 directories. It creates one listing per directory picked, each in `pending`.
3. **Listings move.** Each listing is prepared, sent to its directory and reviewed there. Most listings go live within a week.
4. **Completed.** The project is `completed` when no listing is `pending`, `in_progress` or `action_required` and nothing is left to add. Listings in `submitted` can still go live after that.

A launched project stays: it cannot be deleted, and its `contact_email` can no longer change.

## Listing statuses

| Status | What it means | What you do |
| --- | --- | --- |
| `pending` | Waiting to start. Up to 100 of your listings are in progress at once; the rest wait here. | Nothing. |
| `in_progress` | Being prepared and sent to the directory. | Nothing. |
| `action_required` | Waiting on you or your client; `action` says what. | Follow `action`. |
| `submitted` | The directory has the listing and is reviewing it. | Nothing. |
| `live` | Published. `live_url` points to the listing. | Share it with your client. |
| `not_accepted` | The directory declined it, could not take it, or took it down; `reason` says which. | Nothing: its place in the allowance comes back. |
| `cancelled` | Withdrawn before it reached the directory. | Nothing: its place in the allowance comes back. |

The usual path is `pending` → `in_progress` → `submitted` → `live`. A listing can go from `in_progress` to `action_required` and back, and some listings go live without `submitted`.

### Corrections

Rarely a status changes after it looked final, and each change sends its own event:

- `live` → `not_accepted` with `reason` `removed`, when a directory takes a listing down.
- `live` → `submitted`, when a published listing goes back under review.
- `not_accepted` or `cancelled` → `pending`, `in_progress`, `submitted` or `live`. The listing keeps its `lst_` id.

To keep your records right, store the status of each event as it arrives. Do not assume that `live`, `not_accepted` or `cancelled` are the end.

## Project statuses

When more than one fits, the first in this list wins.

| Status | When |
| --- | --- |
| `on_hold` | Work is paused. `hold_reason` is `review` while we review the project, which clears without action from you, or `paused`. |
| `action_required` | You or your client need to act; `action` says what. |
| `in_progress` | Listings are moving and nobody needs to act. |
| `completed` | No listing is `pending`, `in_progress` or `action_required`, and nothing is left to add. |
| `draft` | Not launched yet. |

## Actions

A project or a listing in `action_required` carries an `action` with a `code` and the side it waits on in `waiting_on`.

- **`install_badge`** waits on your client. Some directories list a product only while their badge shows on its site: forward `client_message` to your client as it is, then verify the badge.
- **`add_assets`** waits on you. The project needs a logo or a screenshot.

New codes can appear. For a code you do not know, show `client_message`, or a general prompt when it is `null`.

## Timing

Most listings go live within a week. Each directory reviews on its own schedule, and the listing shows `submitted` while it waits.

Up to 100 of your listings are in progress at once, across all your projects. Above that, new listings wait in `pending` and start as others finish; a launch is accepted either way. `GET /account` shows the count in `capacity`.

Listing times (`created_at`, `submitted_at`, `live_at`) are rounded down to the hour. An event's `created_at` is exact to the second and comes within about a minute of the change.

In test mode the same life takes about 15 minutes, and nothing reaches a directory: see [Test mode](https://submitator.com/docs/test-mode). Every change is an event you can read from `GET /events` or receive as a webhook.

## The allowance

Each launch covers up to 100 directories for one project. The allowance counts them in `total`, `used`, `reserved` and `available`.

- A listing in `pending`, `in_progress` or `action_required` reserves its place.
- A listing that reached its directory, `submitted` or `live`, uses its place.
- A listing that ends `not_accepted` or `cancelled` gives its place back, and `POST /projects/{project_id}/listings` adds directories from the available places.

With `auto_replace` on, we add fitting directories from the available places for you: after a listing ends `not_accepted` or `cancelled`, after the badge passes verification, and when a new directory joins the catalog. New projects start with it on, and a launch with `include` turns it off.

## Glossary

| Term | Meaning |
| --- | --- |
| Project | One of your client's products, from draft to its last listing. Ids start with `prj_`. |
| Launch | What you buy: 1 launch starts 1 project on up to 100 directories. Your balance is in `GET /account`. |
| Allowance | The 100 directories a launch covers for its project, and how many are used, reserved and available. |
| Listing | One project at one directory, with its status and, once published, its `live_url`. Ids start with `lst_`. |
| Directory | A site that lists products, such as BetaList or SaaSHub. Ids start with `dir_`; `GET /directories` is the catalog. |
| Domain Rating | A 0 to 100 score of a site's backlink profile, measured by Ahrefs. Directories and projects carry it as `domain_rating`. |
| Event | One recorded change to a project, listing or report. Ids start with `evt_`, and the feed keeps 90 days. |
| Test mode | Every call made with a `sbm_test_` key: test data, listings that move on their own, nothing spent. |
| Webhook endpoint | An HTTPS URL of yours that receives events as they happen. Ids start with `we_`. |