---
title: "Create the account and onboarding session"
method: POST
path: "/api/fma/v1/create-account"
tags: ["Managed Custody KYC"]
---

# Create the account and onboarding session

`POST /api/fma/v1/create-account`

Mints or reuses the user's URID, provisions the UR-managed wallet, and opens an onboarding session. This is the first step of both Managed Custody KYC paths: the SDK path starts in state ConfirmYourCountryOfResidence and the shared-token path starts in state PartnerDataIngestion. Repeated calls with the same X-External-User-Id while a session is active return the existing session with idempotentReplay set to true.

## Headers

- `X-External-User-Id` string, required
- `X-Api-Signature` string, required
- `X-Api-Deadline` string, required
- `X-Api-PublicKey` string, required

## Request body

- KycCreateAccountRequest — Body for create-account. The user's identity travels in the X-External-User-Id header, not the body. Do not send a Sumsub applicantId on either KYC path; the applicant is assigned or handed off later.
  - `email` string, required — The user's email address. Must be unique across UR partners; reusing the same email under a different partner returns L1_CONFLICT (code 30015).
  - `nationality` string — ISO 3166-1 alpha-3 country code. Sending it lets UR fail country gates before the URID is minted.
  - `residency` string — ISO 3166-1 alpha-3 country code of residence.
  - `dob` string — Date of birth in YYYY-MM-DD format.
  - `documentExpiry` string — Passport or ID expiry date in YYYY-MM-DD format.

## Response `200`

Business result envelope. code 0 means success; business rejections return HTTP 200 with a non-zero code.

- KycCreateAccountResponse
  - `code` integer — Business result code. 0 means success; business rejections return HTTP 200 with a non-zero code.
  - `message` string — Human-readable diagnostic for non-zero codes.
  - `data` object
    - `sessionId` string — UUID for this onboarding attempt. Constant for the lifetime of the attempt; use it in every subsequent KYC endpoint.
    - `urId` integer — The user's URID, equal to the on-chain NFT token id. Stable for the user's lifetime across all retries.
    - `evmAddress` string — The user's UR-managed wallet address. Form A is signed by this address.
    - `state` string — Session entry state: ConfirmYourCountryOfResidence on the SDK path, PartnerDataIngestion on the shared-token path.
    - `idempotentReplay` boolean — True when an active onboarding session already exists for (partnerId, X-External-User-Id). The existing session is returned unchanged so repeated calls cannot mint duplicate URIDs.

---

[API](https://skmtc.net/ur/apis/ur-api.md) · [All operations](https://skmtc.net/ur/apis/ur-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ur/ur-api/revisions/087dcf516ce2/schema)