Users API

Manage user profiles, company accounts, and RBAC permissions.

Overview

The Users API provides:

• User Profiles — Manage user information
• Company Accounts — B2B company management
• RBAC — Role-based access control
• Permissions — Scope-based authorization

Base URL

https://api.huntrecht.com/api/v1/users

Required Scopes

Scope	Permission
users:read	View user profiles
users:write	Modify user profiles

Get Current User

GET /users/me

Get the authenticated user's profile.

user = client.users.get_me()

Response

{
  "id": "user_abc123",
  "email": "buyer@company.com",
  "first_name": "John",
  "last_name": "Buyer",
  "company_name": "Acme Corporation",
  "role": "buyer",
  "permissions": [
    "orders:read",
    "orders:write",
    "subscriptions:read",
    "credit:read"
  ],
  "company_id": "comp_xyz789",
  "shopify_customer_id": "gid://shopify/Customer/123",
  "created_at": "2025-06-15T10:00:00Z",
  "last_login": "2026-01-11T09:00:00Z"
}

Update User Profile

PUT /users/me

Update the authenticated user's profile.

Request Body

Field	Type	Description
first_name	string	First name
last_name	string	Last name
phone	string	Phone number
address	object	Address object
preferences	object	User preferences

user = client.users.update_me({
    "first_name": "John",
    "last_name": "Smith",
    "phone": "+1-555-987-6543",
    "address": {
        "street": "456 New Street",
        "city": "Business City",
        "state": "CA",
        "postal_code": "90211",
        "country": "US"
    },
    "preferences": {
        "email_notifications": true,
        "sms_alerts": false
    }
})

Get User by ID

GET /users/{user_id}

Get a specific user's profile (admin only).

user = client.users.get("user_abc123")

List Users

GET /users

List users in your organization (admin only).

Query Parameters

Parameter	Type	Description
company_id	string	Filter by company
role	string	Filter by role
status	string	Filter by status
page	integer	Page number
limit	integer	Results per page

users = client.users.list(
    company_id="comp_xyz789",
    role="buyer",
    page=1,
    limit=50
)

Roles & Permissions

Available Roles

Role	Description	Permissions
super_admin	Full system access	All permissions
admin	Company admin	All company permissions
manager	Department manager	orders, payments, subscriptions
buyer	Standard buyer	orders, payments:read, subscriptions:read
viewer	Read-only access	orders:read, subscriptions:read
accountant	Financial access	payments, orders:read
api_client	API-only access	Configurable scopes

Role Hierarchy

super_admin
  └── admin
        ├── manager
        │     ├── buyer
        │     │     └── viewer
        │     └── accountant
        └── api_client

Permissions Reference

Permission	Description
orders:read	View orders
orders:write	Create/modify orders
orders:delete	Delete/cancel orders
payments:read	View payments
payments:write	Process payments
subscriptions:read	View subscriptions
subscriptions:write	Manage subscriptions
credit:read	View credit scores
credit:write	Request credit assessments
kyc:read	View KYC status
kyc:write	Submit KYC documents
users:read	View user profiles
users:write	Manage users
storefront:read	Access storefront API
price_drops:read	View price drops

Company Account

Get Company

GET /users/company/{company_id}

Get company details.

company = client.users.get_company("comp_xyz789")

Response

{
  "id": "comp_xyz789",
  "name": "Acme Corporation",
  "tax_id": "12-3456789",
  "status": "verified",
  "credit_limit": 50000.00,
  "available_credit": 42500.00,
  "subscription_tier": "standard",
  "members": [
    {
      "user_id": "user_abc123",
      "email": "buyer@company.com",
      "role": "admin",
      "joined_at": "2025-06-15T10:00:00Z"
    }
  ],
  "addresses": [
    {
      "type": "billing",
      "street": "123 Business Ave",
      "city": "Commerce City",
      "state": "CA",
      "postal_code": "90210",
      "country": "US"
    }
  ],
  "bank_accounts": [
    {
      "id": "bank_abc123",
      "bank_name": "First National Bank",
      "last_four": "1234",
      "verified": true
    }
  ],
  "created_at": "2025-06-15T10:00:00Z",
  "shopify_company_id": "gid://shopify/Company/456"
}

Update Company

PUT /users/company/{company_id}

Update company details (admin only).

company = client.users.update_company("comp_xyz789", {
    "name": "Acme Corporation Inc.",
    "billing_address": {
        "street": "789 Corporate Blvd",
        "city": "Finance City",
        "state": "NY",
        "postal_code": "10001",
        "country": "US"
    }
})

Invite Team Member

POST /users/invite

Invite a new user to your company.

Request Body

Field	Type	Required	Description
email	string	Yes	User email
role	string	Yes	User role
permissions	array	No	Additional permissions

invite = client.users.invite({
    "email": "newmember@company.com",
    "role": "buyer",
    "permissions": ["orders:read", "orders:write"]
})

Response

{
  "invitation_id": "inv_abc123",
  "email": "newmember@company.com",
  "role": "buyer",
  "status": "pending",
  "expires_at": "2026-01-18T10:00:00Z",
  "invitation_link": "https://huntrecht.com/join/inv_abc123"
}

Accept Invitation

POST /users/accept-invitation

Accept a team invitation.

result = client.users.accept_invitation({
    "invitation_id": "inv_abc123",
    "first_name": "Jane",
    "last_name": "Member"
})

Webhook Events

Event	Description
user.created	New user registered
user.updated	User profile updated
user.invited	Team invitation sent
user.joined	User accepted invitation
user.removed	User removed from company
company.updated	Company details updated

Error Codes

Code	Description
USER_NOT_FOUND	User ID not found
COMPANY_NOT_FOUND	Company ID not found
EMAIL_EXISTS	Email already registered
INVALID_ROLE	Invalid role specified
INSUFFICIENT_PERMISSIONS	Cannot modify this resource

Next Steps

• Authentication
• B2B Onboarding Guide