Create the account and onboarding session

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.

post

/api/fma/v1/create-account

Authorizations

X-Api-SignaturestringRequired

Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide.

Header parameters

X-External-User-IdstringRequired

Your partner-side user id. This endpoint identifies the user by X-External-User-Id only; there is no X-Ur-Id yet.

X-Api-SignaturestringRequired

Partner Auth EIP-191 signature over the canonical message plus the deadline.

X-Api-DeadlinestringRequired

Unix timestamp in seconds after which the signature is no longer valid.

X-Api-PublicKeystringRequired

Partner public key used to verify the signature.

Body

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.

emailstringRequired

The user's email address. Must be unique across UR partners; reusing the same email under a different partner returns L1_CONFLICT (code 30015).

nationalitystringOptional

ISO 3166-1 alpha-3 country code. Sending it lets UR fail country gates before the URID is minted.

residencystringOptional

ISO 3166-1 alpha-3 country code of residence.

dobstringOptional

Date of birth in YYYY-MM-DD format.

documentExpirystringOptional

Passport or ID expiry date in YYYY-MM-DD format.

Responses

200

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

application/json

codeintegerOptional

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

messagestringOptional

Human-readable diagnostic for non-zero codes.

post/api/fma/v1/create-account

POST /api/fma/v1/create-account HTTP/1.1
Host: openapi.ur.app
X-Api-Signature: text
X-External-User-Id: text
X-Api-Deadline: text
X-Api-PublicKey: text
Content-Type: application/json
Accept: */*
Content-Length: 115

{
  "email": "[e-mail]",
  "nationality": "CHN",
  "residency": "CHN",
  "dob": "1994-01-06",
  "documentExpiry": "2036-05-05"
}

200

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

{
  "code": 0,
  "message": "",
  "data": {
    "sessionId": "223d567f-ea11-4629-ba2a-94664edc26f6",
    "urId": 5643568810,
    "evmAddress": "0x7c8173c8Fe47D55b9Ee848e89da1149A52632193",
    "state": "ConfirmYourCountryOfResidence",
    "idempotentReplay": false
  }
}