Create an application

An application is one applicant’s run through one flow. Creating it is a single call, and it returns the URL you hand to the applicant.

Note

Every example here uses placeholders. {form_slug} is your flow and $UPPASS_API_TOKEN is your API token — Values you need says where to find each one. The full request and response schema is in the API reference.

Before you start: get an API token

Every call carries a bearer token that belongs to your workspace.

1. Open the Portal and select your workspace.

2. In the left-hand menu, open API Token.

3. Generate a token. It is shown once — copy it now.

4. Store it in your secret manager, and expose it to your backend as an environment variable:

   export UPPASS_API_TOKEN='...'

Keep it server-side only — never in browser or mobile-app code. See Authentication for the 401 / 403 behaviour.

The call

cURL

curl --request POST \
  'https://app.uppass.io/en/api/forms/{form_slug}/create/' \
  --header 'Authorization: Bearer '"$UPPASS_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{ "answers": {} }'

Node.js

const res = await fetch(`https://app.uppass.io/en/api/forms/${FORM_SLUG}/create/`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.UPPASS_API_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ answers: {} }),
});

// 201 Created — not 200.
const { detail, form_url } = await res.json();

Python

res = requests.post(
    f"https://app.uppass.io/en/api/forms/{FORM_SLUG}/create/",
    headers={
        "Authorization": f"Bearer {os.environ['UPPASS_API_TOKEN']}",
        "Content-Type": "application/json",
    },
    json={"answers": {}},
    timeout=30,
)
res.raise_for_status()   # 201 Created on success
body = res.json()

201 Created

{
  "info": "https://app.uppass.io/en/api/forms/{form_slug}/applied-forms/{slug}/info/",
  "detail": {
    "form": "{form_slug}",
    "step": "personal",
    "section": "personal",
    "submitted_at": null,
    "slug": "{slug}"
  },
  "form_url": "https://app.uppass.io/en/form/{form_slug}/{slug}/"
}

Three things to note in the response

1. The status is 201, not 200. A client asserting 200 fails on every successful create.

2. detail.slug is your correlation key — store it now. It comes back in the webhook as application.slug, and nothing else reliably ties the result to your record.

3. step and section are flow-specific. Read them from the response; do not hard-code them. They are whatever the first step of your flow happens to be.

Hand the applicant the link

Send the applicant to form_url. The verification experience is mobile web only — a desktop visitor is prompted to switch devices, so if your own journey starts on desktop, present the link as a QR code rather than a redirect that dead-ends.

Treat form_url as private

form_url embeds the application slug, which lets the holder resume that specific unfinished application — that is what makes a dropped-off applicant able to come back and finish. Deliver it to the applicant only, and keep it out of logs, analytics and referrer-leaking redirects. See Authentication for exactly what the slug does and does not expose.

Then wait for the submission webhook. Polling is for progress indicators, not for driving business logic.

Language

The {lang} path segment sets the locale the form renders in. It accepts en, th, zh-hans, zh-hant, km, my, lo, ms, vi, id, ja, hi, ar, ru, de, es and fr.

Caution

An unrecognised value is not rejected. The request is answered with a 302 to a path prefixed with the platform default locale, which will not resolve. Validate the locale before you build the URL.

Next

• Authentication — the API token, and what the slug is for.
• Set up your workspace — the Portal steps to complete once.
• Reading the result — before you write decision logic.