---
title: "Create users"
description: "Learn how to create and manage users in Snag using the metadata endpoint, including wallet address requirements and supported wallet types"
keywords: ["create users API", "user management Web3", "loyalty user API", "programmatic user creation"]
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://docs.snagsolutions.io/llms.txt). Append `.md` to any page URL for its markdown version.

After getting your API key, the next step is to create users in your Snag system. This guide explains how to use the metadata endpoint to add users and manage their information.

## Overview

The `POST /api/users/metadatas` endpoint allows you to create or update user objects in Snag's system. This is essential for migrating users from your existing system or adding new users to your loyalty program.

<Info>
  Only the `walletAddress` property is required as this is the unique identifier for the user being created.
</Info>

## Wallet Address Requirements

A wallet address is **required** for creating a Snag user. We currently support the following wallet types:

- **EVM** - Ethereum and EVM-compatible chains (Polygon, BSC, etc.)
- **SVM** - Solana Virtual Machine
- **TON** - The Open Network
- **SUI** - Sui blockchain
- **Cosmos** - Cosmos ecosystem chains

<Tip>
  The wallet address serves as the unique identifier for each user in the Snag system. If your users don't have wallet addresses, see our [wallet generation guide](https://docs.snagsolutions.io/loyalty/development/generate-wallet-addresses).
</Tip>

## Creating a User

### Basic User Creation

Here's how to create a user with just the required wallet address:

<RequestExample>

```bash cURL
curl -X POST 'https://admin.snagsolutions.io/api/users/metadatas' \
  -H 'x-api-key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "walletAddress": "0x1234567890abcdef1234567890abcdef12345678"
  }'
```

</RequestExample>

<ResponseExample>

```json Success
{
  "id": "user-123",
  "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```

</ResponseExample>

### User with Metadata

You can also include additional metadata when creating a user:

<RequestExample>

```bash cURL
curl -X POST 'https://admin.snagsolutions.io/api/users/metadatas' \
  -H 'x-api-key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "discordUser": "discord-user",
    "twitterUser": "twitter-user",
    "emailAddress": "user@example.com",
    "telegramUsername": "telegram-user",
    "displayName": "John Doe",
    "logoUrl": "https://example.com/avatar.png",
    "externalIdentifier": "your-internal-user-id"
  }'
```

</RequestExample>

<ResponseExample>

```json Success
{
  "id": "user-123",
  "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "discordUser": "discord-user",
  "twitterUser": "twitter-user",
  "emailAddress": "user@example.com",
  "telegramUsername": "telegram-user",
  "displayName": "John Doe",
  "logoUrl": "https://example.com/avatar.png",
  "externalIdentifier": "your-internal-user-id",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```

</ResponseExample>

## Using the Snag SDK

```javascript
import SnagSolutions from '@snagsolutions/sdk'

const client = new SnagSolutions({
  apiKey: 'your-api-key-here',
})

// Create a basic user
const user = await client.users.createMetadata({
  walletAddress: '0x1234567890abcdef1234567890abcdef12345678',
})

// Create a user with metadata
const userWithMetadata = await client.users.createMetadata({
  walletAddress: '0x1234567890abcdef1234567890abcdef12345678',
  discordUser: 'discord-user',
  discordUserId: 'discord-user-id',
  twitterUser: 'twitter-user',
  twitterUserId: 'twitter-user-id',
  telegramUsername: 'telegram-user',
  telegramUserId: 'telegram-user-id',
  displayName: 'John Doe',
  externalIdentifier: 'your-internal-user-id',
})
```

## External Identifier

The `externalIdentifier` field allows you to maintain your own user ID system while using Snag. This is particularly useful when migrating from an existing system:

```javascript
// Map your internal user ID to Snag
const user = await client.users.createMetadata({
  walletAddress: '0x1234567890abcdef1234567890abcdef12345678',
  externalIdentifier: 'your-internal-user-id-12345',
})
```

<Tip>
  Use the external identifier to maintain a mapping between your internal user IDs and Snag user IDs for easier integration.
</Tip>

## Updating User Metadata

The same endpoint can be used to update existing user metadata. Simply provide the wallet address and the fields you want to update:

```javascript
// Update user metadata
const updatedUser = await client.users.createMetadata({
  walletAddress: '0x1234567890abcdef1234567890abcdef12345678',
  displayName: 'Updated Name',
  emailAddress: 'newemail@example.com',
})
```

<Info>
  The endpoint is idempotent - calling it multiple times with the same wallet address will update the user rather than create duplicates.
</Info>

## Next Steps

Now that you can create users, learn how to:

<Columns cols={2}>
  <Card title="Generate Wallet Addresses" icon="wallet" href="/loyalty/development/generate-wallet-addresses">
    Learn how to programmatically generate wallet addresses for users who don't have them.
  </Card>
  <Card title="Migrate Users" icon="arrow-right-arrow-left" href="/loyalty/development/migrate-users">
    Step-by-step guide for migrating your existing user base to Snag.
  </Card>
  <Card title="Manage User Groups" icon="users" href="/loyalty/development/manage-user-groups">
    Learn how to connect multiple wallets to a single user using user groups.
  </Card>
  <Card title="Connect Social Accounts" icon="share" href="/loyalty/development/connect-social-accounts">
    Integrate social media platforms with your users for enhanced loyalty features.
  </Card>
</Columns>