Users API

Users API Reference

Manage user accounts, authentication, and KYC/KYB processes. The Users API allows you to create, link, and manage user accounts on the Waffy platform.

Overview

The Users API is the foundation of the Waffy platform. It handles user account creation, authentication token management, and the linking process that connects external users to the Waffy ecosystem.

Key Features

• User account creation and management
• Authentication token generation
• KYC/KYB process integration
• Multi-party contract participation

Authentication

All Users API endpoints require a valid API key in the Authorization header.

Base URL

Production:

https://api.waffyapp.com/v1

Sandbox:

https://sandbox-api.waffyapp.com/v1

POSTLink User

Create or link a user to the Waffy platform

Endpoint

POST /users/link

Request Body

{
  "email": "user@example.com",
  "phone": "+1234567890",
  "name": "John Doe",
  "metadata": {
    "source": "web_app",
    "campaign_id": "summer_2024"
  }
}

Parameters

Parameter	Type	Required	Description
email	string	Required	User's email address
phone	string	Required	Phone number in E.164 format
name	string	Required	User's full name
metadata	object	Optional	Additional metadata for the user

Response (200 OK)

{
  "success": true,
  "data": {
    "user_id": "usr_1a2b3c4d5e6f",
    "waffy_token": "wft_1a2b3c4d5e6f7g8h",
    "status": "linked",
    "verification_required": false,
    "created_at": "2024-01-15T10:30:00Z",
    "metadata": {
      "source": "web_app",
      "campaign_id": "summer_2024"
    }
  },
  "meta": {
    "request_id": "req_1a2b3c4d5e6f",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

GETGet User

Retrieve user information by user ID

Endpoint

GET /users/{user_id}

Path Parameters

Parameter	Type	Description
user_id	string	The unique identifier for the user (e.g., usr_1a2b3c4d5e6f)

Response (200 OK)

{
  "success": true,
  "data": {
    "user_id": "usr_1a2b3c4d5e6f",
    "email": "user@example.com",
    "phone": "+1234567890",
    "name": "John Doe",
    "status": "verified",
    "waffy_token": "wft_1a2b3c4d5e6f7g8h",
    "verification_status": {
      "email_verified": true,
      "phone_verified": true,
      "kyc_status": "approved"
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_2b3c4d5e6f7g",
    "timestamp": "2024-01-15T11:00:00Z"
  }
}

PUTUpdate User

Update user information

Endpoint

PUT /users/{user_id}

Request Body

{
  "name": "John Smith",
  "phone": "+1987654321",
  "metadata": {
    "updated_source": "mobile_app"
  }
}

Error Responses

400 Bad Request

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": {
      "field": "email",
      "value": "invalid-email"
    }
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "User with ID usr_1a2b3c4d5e6f not found"
  }
}

Rate Limiting

The Users API implements rate limiting to ensure fair usage:

• Sandbox: 100 requests per minute
• Production: 1000 requests per minute

Rate limit headers are included in all responses to help you track your usage.

Try the API

Test the Users API in our interactive playground

Open API Playground

JavaScript SDK

Use our official SDK for easier integration

View SDK Documentation