Skip to main content
An AI agent or script can sign a merchant up for Fluid without the signup form. POST /api/company creates a company and its first admin user in one request, and it takes no credentials — the merchant has no token yet. This is the supported programmatic path. Use it instead of automating the signup form or booking a demo.
The request, response, and error schemas are on the generated reference page: Create a company. This guide covers the flow around that call.
With the Fluid CLI installed, fluid signup makes this call for you. It sends the subdomain in its clean form, sends the request once, and prints the fluid login steps that sign in to the new company:
The checks in Before you start apply either way.

Before you start

If you are an agent acting for a person, check these with them first:
  • Get their consent. The request sends their name and email address to Fluid and creates a real company. Ask before you send it.
  • Use a mailbox they control. Fluid emails the confirmation link to the address you send. Someone with access to that mailbox has to open it.
  • Don’t accept agreements for them. This endpoint accepts none. Later steps that need agreement are the merchant’s to complete.
You can do everything up to the confirmation email, and everything after the merchant signs you in to the Fluid CLI or gives you an API token. Confirming the email needs the person.

Finding this flow

Fluid publishes machine-readable pointers to this endpoint: Request each one at the URL shown. ard.json and api-catalog are served only on fluid.app, and fluid.app/llms.txt redirects to docs.fluid.app/llms.txt. The API host, api.fluid.app, serves none of them.

Sign a merchant up

1

Choose a subdomain

The subdomain becomes the store’s address: <subdomain>.fluid.app. Subdomains are unique across Fluid.Send a value that is already clean: lowercase letters, digits, and hyphens, no leading or trailing hyphen, and at most 63 characters. Fluid normalizes the value you send rather than rejecting it, and a value that only becomes a duplicate after normalization fails in a way that doesn’t name the subdomain. Sending the clean form avoids both problems.
2

Create the company

Send the admin user and the company in one request to https://api.fluid.app/api/company, with no Authorization header:
user.first_name, user.last_name, user.email, company.name, and company.subdomain are required. company.color (a 3- or 6-digit hex brand colour) and company.onboarding_info are optional.Send only the fields documented on the reference page. The signup form sends extra fields for its own browser checks; an API caller should not.onboarding_info stores the merchant’s onboarding answers. Of the answers the admin signup form sends, an API caller needs only usage_type (business or employee) and website_setup (fluid-theme, import, current-site, or unsure). Fluid stores these values without validating them, so use this vocabulary: a value outside it is saved but means nothing to the admin. Fluid keeps only the answers its signup forms collect and drops any other key without an error. If you have no answers, leave onboarding_info out — an empty object is rejected.
3

Keep the company details from the response

A successful request returns 200:
Store company.id and company.fluid_shop. Read company.subdomain from the response rather than reusing what you sent — it is the value Fluid saved.The store isn’t served yet. Its storefront, portal, and account addresses return 404 until an admin of the company confirms the signup. The response lists that outstanding step under requirements.currently_due as email_confirmation. See Create a company for the response schema.A company whose signup isn’t confirmed within 14 days may be removed, and its subdomain freed for someone else. Two things confirm it: opening the confirmation link and pressing Sign in, or the merchant signing you in to the Fluid CLI with --shop set to this company’s fluid_shop (see the next steps). Other sign-ins don’t count, such as signing in at https://admin.fluid.app.
4

The merchant confirms the signup

Fluid emails a confirmation link to user.email, from love@fluid.app with the subject “Please confirm your email address”. The link opens a page with a Sign in button, and pressing it confirms the signup and signs the merchant in. Opening the link alone confirms nothing, so mail scanners that open links can’t use it up. Fluid accounts have no password. If the merchant signs you in to the Fluid CLI with --shop (next step), that confirms it too, and they don’t need the link.The same email goes to a new address and to one that already belongs to a Fluid user. The response is the same 200 either way.If no email arrives within a few minutes, ask the merchant to check their spam or junk folder. If it isn’t there, the merchant can sign in at https://admin.fluid.app with the same address. That sign-in usually sends a six-digit passcode rather than a link, so tell the merchant to type it instead of looking for a button. Some companies are set up to receive a link instead, and the same screen accepts either. While the signup is unconfirmed, the admin shows a banner in that company saying the store isn’t public yet, with a Resend email button that sends the confirmation link again. A merchant who already has another Fluid company is asked which company to open, or may already be signed in to the other one; the banner shows only in the new company.
A second company for the same email address usually gets no confirmation email for about an hour. The first send holds a window against that address, because this endpoint takes no credential and would otherwise mail any address once per throwaway subdomain. A second signup inside that window still returns 200 and still creates the company.The response never says whether the email went out. It is the same 200 when the window holds the send back, and when the send fails for any other reason.Don’t create a third company to work around it. The merchant can sign in at https://admin.fluid.app with the same address, switch to the new company, and resend the confirmation from the banner.
5

The merchant gives you access

The merchant either signs in to the Fluid CLI for you (recommended) or creates an API token at Settings → API Tokens (https://admin.fluid.app/settings/tokens) and gives it to you. Agent launch guide, Step 1 shows both.The CLI sign-in takes --shop with the fluid_shop you stored. That ties the emailed code to this company, so signing in with it also confirms the signup if the merchant hasn’t opened the link yet. It gives you the merchant’s own admin session for the company, for up to 45 days. See Authentication for token types and scopes.
6

Make authenticated calls

If the merchant signed you in to the Fluid CLI, run fluid whoami to check it is signed in to the right company, then carry on with the Agent launch guide.With an API token, send it as a Bearer token to https://api.fluid.app:
Every authenticated call acts on the company the token belongs to.

Handle errors

A 422 takes one of these forms:
  • errors names the field (for example errors.user.email or errors.company.subdomain). A required field is missing or malformed, or the subdomain is already taken. Fix that field and retry. A taken subdomain is a common failure: pick another.
  • errors.company.base. Setup failed for another reason, such as an invalid colour or a subdomain that collides after normalization. The message text is not stable, so don’t parse it.
  • errors.base. The request was rejected by a check that applies to browser signups. Remove any fields that are not documented on the reference page.
A 422 means the company was not created, apart from a rare case where Fluid loses its database connection mid-request. A 5xx, or no response at all, can arrive after the company was created. If that happens, retry once with the same subdomain before you try a new one.What the retry tells you depends on what you sent. If you sent the clean form, errors.company.subdomain is taken usually means your first request created the company, but it can’t prove it: a lost answer to a request that was refused, or another signup for the same name, looks the same. If you sent an unnormalized value, the retry fails under errors.company.base, because the taken check compares the value as sent, so it tells you nothing. In both cases, have the merchant sign in at https://admin.fluid.app and look for the company before you choose another subdomain.Either way, don’t create a second company before you have checked.

Next steps

  • Agent launch guide: connect data, start payments onboarding, and build a store preview for the merchant.
  • Authentication — token types, scopes, and how to pass a token.
  • API overview — base URLs, the response envelope, and pagination.
  • Create a company — the generated request and response reference.