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
- 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.
- 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. - Listings move. Each listing is prepared, sent to its directory and reviewed there. Most listings go live within a week.
- Completed. The project is
completedwhen no listing ispending,in_progressoraction_requiredand nothing is left to add. Listings insubmittedcan 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_acceptedwithreasonremoved, when a directory takes a listing down.live→submitted, when a published listing goes back under review.not_acceptedorcancelled→pending,in_progress,submittedorlive. The listing keeps itslst_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_badgewaits on your client. Some directories list a product only while their badge shows on its site: forwardclient_messageto your client as it is, then verify the badge.add_assetswaits 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. 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_progressoraction_requiredreserves its place. - A listing that reached its directory,
submittedorlive, uses its place. - A listing that ends
not_acceptedorcancelledgives its place back, andPOST /projects/{project_id}/listingsadds 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_. |