# Creating your account Account creation runs through the onboarding wizard. End-to-end (signup → verified, API key in hand) typically takes 15–30 minutes of active time plus however long KYB and Stripe Connect need to clear. You'll need the information listed in [Getting started](/for-creditor-partners/creditor-onboarding/getting-started.md). The wizard mirrors the seven steps the platform actually walks through: 1. Account / company info 2. Business details (EIN, address, industry) 3. Beneficial owners (UBO ≥ 25%) 4. KYB submission 5. Bank link (Stripe Connect Express) 6. MSA acceptance (click-through) 7. API key issuance You can leave the wizard and come back — your progress is stored against a short-lived onboarding JWT (24 hours) and the wizard re-fetches `/v1/creditors/me/status` to figure out where you left off. ## Step 1 — Account info Open the onboarding wizard in the dashboard and fill in: * **Company display name** — what shows up in the dashboard. * **URL slug** — lowercase letters, digits, and dashes only (3–64 chars). Must be unique across the platform. * **Legal entity name** — exactly as registered with your state. * **Contact email** — used as the audit-log identity for actions taken through this onboarding session. * **Contact name** — optional. Submitting this step calls `POST /v1/creditors`. The platform creates a `pending_signup` creditor, returns an onboarding JWT (TTL 24 hours), and writes a `creditor.signup_started` audit event. No API key is minted yet. > The endpoint is rate-limited to **5 signups per hour per IP**. If you're testing repeatedly from one network you may hit a 429 — wait an hour or test from a different network. ## Step 2 — Business details `PATCH /v1/creditors/me` with: * **EIN** (federal tax ID). * **Industry** — free-text label today; there's no controlled vocabulary or industry block-list enforced in code. * **Business address** — line 1, city, postal code, and ISO-2 country code (US, CA, etc.). State is optional in the schema but you should fill it in for US entities. > Heads up: the legal entity name you enter at signup is what feeds the KYB lookup, the MSA, the 1099, and (after verification) what our voice agent uses on calls. ## Step 3 — Beneficial owners Add the ultimate beneficial owners (UBOs) — anyone with ≥ 25% ownership is the typical bar. For each owner: full name, ownership percentage, country, optionally date of birth and title. The wizard persists these on the creditor via the same `PATCH /v1/creditors/me`. At least one UBO is required before KYB will run. ## Step 4 — KYB When the required inputs (legal name, EIN, address, industry, UBOs) are populated, the wizard calls `POST /v1/creditors/me/submit-kyb`. The platform runs the configured KYB adapter (Middesk in production/staging via the `KYB_PROVIDER` setting; mock in dev/test) and screens the entity + UBOs against sanctions (OFAC or Comply Advantage, depending on `SANCTIONS_PROVIDER`). Outcomes: * **Clean** — the creditor moves to `pending_bank_link`. Continue to step 5. * **Needs review** — the creditor stays in `pending_verification` for an operator to triage. Common cause: a UBO matched a watchlist (often a false positive on a common name). * **Failed** — the creditor moves to `rejected`. This is terminal; a rejected creditor cannot be flipped back. Email if you think it's a mistake. * **Pending** — Middesk is still working. The webhook handler will re-apply the result when the vendor completes. Every outcome writes a `creditor.kyb_completed` audit event; sanctions hits write a separate `creditor.sanctions_hit` event. ## Step 5 — Bank link (Stripe Connect Express) The wizard calls `POST /v1/creditors/me/bank-link/start` to mint a Stripe Connect Express onboarding URL and redirects you to Stripe. Complete Stripe's onboarding (identity, business info, bank account). When Stripe sends the `account.updated` webhook with `payouts_enabled=true`, the platform transitions you to `pending_agreement`. If the AccountLink expires before you finish, the dashboard's "the link expired, get a new one" CTA calls `POST /v1/creditors/me/bank-link/refresh` to mint a fresh URL. > We never assert payouts-enabled client-side. The flag flips only in response to the Stripe webhook, so the wizard may briefly show "waiting on Stripe" until the webhook lands. ## Step 6 — MSA acceptance `GET /v1/agreements/current` renders the active MSA (today: `msa_v1`) with your contingency rate substituted in. `POST /v1/agreements/accept` records the acceptance with your IP, User-Agent, and a SHA-256 hash over the canonical document bytes, and returns a signed URL (1-hour TTL) for the audit certificate PDF. Download and save it. After acceptance the platform transitions you to `verified`. ## Step 7 — API key issuance `POST /v1/creditors/me/issue-api-key` mints your long-lived API key. The plaintext key (`ca_{prefix}_{secret}`) is returned **exactly once** — there is no recovery path. Copy it to your secret store immediately. If you lose it, the only path forward is admin rotation. The endpoint refuses to issue the key until: * `status == verified`, * Stripe Connect `payouts_enabled == true`, and * the current MSA version has been accepted. If any gate fails, you'll get a 409 / 422 with a `reason` code (`not_verified`, `payouts_disabled`, or `no_agreement`) and actionable copy. ## Account defaults at signup Every new creditor lands with these defaults (you can change them later from **Settings**): * **Tier:** `standard` * **Contingency:** 25% * **Posture default:** `preserve` (see [Configuring your strategy](/for-creditor-partners/creditor-onboarding/configuring-your-strategy.md)) ## Admin-approved path (pilot partners) If you're a pilot partner and our team is approving you out-of-band, an admin can call `POST /v1/admin/creditors/{id}/approve` with a written `bypass_justification`. This walks the FSM through every state synthetically and mints your API key, which the admin shares with you over a secure channel. The audit trail records that the verification method was `manual_admin` plus the justification text. ## TODO * Screenshot: wizard step 1 (account info form). * Screenshot: wizard step 4 (KYB review state). * Screenshot: Stripe Connect return page in wizard. * Screenshot: MSA click-through. * Screenshot: one-time API key reveal. *** Last reviewed: 2026-05-24 by Customer Success. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.moderncollections.io/for-creditor-partners/creditor-onboarding/creating-your-account.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.