# Register user Source: https://docs.settlemint.com/docs/developer-guides/user-management/register-user Register users in the identity registry via API for compliance tracking and token eligibility. This guide explains how to register users in the identity registry via API - a required step for compliance tracking and token eligibility. For the web interface approach, see the [user guide](/docs/user-guides/user-management/register-user). ## Prerequisites [#prerequisites] * Platform URL (e.g., `https://your-platform.example.com`) * API key from a user with the **Identity Manager** role (see [Getting Started](/docs/developer-guides/api-integration/getting-started) for API key setup) * Wallet verification method enabled on your account (e.g., pincode or 2FA) * User must have an on-chain identity (see [Create Users](/docs/developer-guides/user-management/create-users)) ## About identity registry [#about-identity-registry] The identity registry is an on-chain system that: * Tracks all verified identities for your organization * Links wallet addresses to identity contracts * Enforces jurisdictional rules ### Identity states [#identity-states] | State | Description | Can receive assets | | ------------------------ | ---------------------------------- | ------------------ | | **Pending Registration** | Has identity but not in registry | No | | **Registered** | In registry, awaiting verification | Depends on rules | | **Verified** | Has required verifications | Yes | ## Registering users [#registering-users] ### Identify user to register [#identify-user-to-register] The user must already have an on-chain identity. Query the user to get their wallet address: ```bash curl -X GET "https://your-platform.example.com/api/user/search?query=user@example.com" \ -H "X-Api-Key: YOUR_API_KEY" ``` **Response:** ```json [ { "id": "usr_abc123", "name": "John Doe", "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "role": "member" } ] ``` Save the `wallet` address from the first result for the registration step. ### Select jurisdiction [#select-jurisdiction] Choose the ISO 3166-1 alpha-2 country code for the user's jurisdiction. Country selection can be used in compliance rules but doesn't automatically apply specific rules. Choose based on user's legal residence or incorporation, not temporary location. ### Execute registration [#execute-registration] Register the identity in the selected jurisdiction: ```bash curl -X PUT "https://your-platform.example.com/api/system/identity" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "country": "BE", "walletVerification": { "secretVerificationCode": "YOUR_PINCODE" } }' ``` **Response:** ```json { "id": "0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890", "account": { "id": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "contractName": null }, "isContract": false, "hasIdentity": true, "registered": { "isRegistered": true, "country": "BE" }, "claims": [] } ``` ### Verify registration [#verify-registration] Query the identity to confirm the user is now registered. Use the `/api/system/identity/by-wallet` endpoint (not `/api/user/search`, which excludes identity data): ```bash curl -X GET "https://your-platform.example.com/api/system/identity/by-wallet/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" \ -H "X-Api-Key: YOUR_API_KEY" ``` **Response when registered:** ```json { "id": "0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890", "account": { "id": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "contractName": null }, "isContract": false, "hasIdentity": true, "registered": { "isRegistered": true, "country": "BE" }, "claims": [] } ``` **Key fields to verify:** * `registered.isRegistered` = `true` (confirms registration) * `registered.country` = the country code you specified (e.g., "BE") ## Request parameters [#request-parameters] | Parameter | Type | Required | Description | | -------------------- | ------ | -------- | ------------------------------------------------------------------- | | `wallet` | string | Yes | Wallet address of user to register (0x...) | | `country` | string | Yes | ISO 3166-1 alpha-2 country code (e.g., "BE", "DE") | | `walletVerification` | object | Yes | Your wallet verification (PINCODE or TOTP) to authorize transaction | ### Wallet verification object [#wallet-verification-object] | Field | Type | Description | | ------------------------ | ------ | ---------------------------------------------- | | `secretVerificationCode` | string | 6-digit pincode or TOTP code | | `verificationType` | string | "PINCODE" (default), "SECRET\_CODES", or "OTP" | ## Best practices [#best-practices] ### Jurisdiction selection [#jurisdiction-selection] * Use user's legal residence or incorporation * Verify jurisdiction through documentation * Consider tax and regulatory implications * Update if user's status changes ## Integration with compliance [#integration-with-compliance] ### Token transfers [#token-transfers] * Registered identities can receive assets (with proper verifications) * Non-registered identities are blocked from asset transactions ### Compliance modules [#compliance-modules] * Identity verification module checks registry registration * Transfer restrictions enforce registration requirements * Compliance reporting tracks registered vs. non-registered users ### Verification process [#verification-process] * Registration is prerequisite for issuing verifications * Verifications can only be added to registered identities * Multiple verifications can be issued per registered identity ## Troubleshooting [#troubleshooting] | Issue | Solution | | --------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `401 Unauthorized` | API key is invalid, expired, or disabled | | `403 USER_NOT_AUTHORIZED` | Ensure your account has `identityManager` role (Identity Manager) | | `400 Identity not found` | User must have an on-chain identity; see [Create Users](/docs/developer-guides/user-management/create-users) | | `400 Identity already registered` | User already registered; proceed to KYC verification | | Invalid country code | Use ISO 3166-1 alpha-2 codes: BE, DE, GB, FR, etc. | | Cannot verify registration | Use `/api/system/identity/by-wallet/{wallet}` endpoint, not `/api/user/search` (which excludes identity data) | ## Related guides [#related-guides] * [Create Users](/docs/developer-guides/user-management/create-users) - Create user accounts with wallet and identity * [Verify KYC](/docs/developer-guides/compliance/verify-kyc) - Issue verifications after registration * [Getting Started](/docs/developer-guides/api-integration/getting-started) - API key setup * [Register User (User Guide)](/docs/user-guides/user-management/register-user) - Web interface approach