← Back to API Reference | Getting Started

Users

The User Object

Special Update Parameters

List Users

Returns a paginated list of users. Supports filtering and sorting via query parameters.

Example Request

curl -X GET "https://www.yourdomain.com/api/v2/user/get?limit=25" \
  -H "X-Api-Key: your-api-key-here"

Example Response

{
  "status": "success",
  "total": 84,
  "current_page": 1,
  "total_pages": 4,
  "next_page": "MipfKjI1",
  "message": [
    {
      "user_id": 1,
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "company": "Acme Corp",
      "active": 2,
      "subscription_id": 1,
      "city": "Los Angeles",
      "state_code": "CA",
      "country_code": "US",
      "signup_date": "20240115143000"
    },
    ...
  ]
}

Retrieve a User

Returns a single user by their user_id.

Example Request

curl -X GET "https://www.yourdomain.com/api/v2/user/get/42" \
  -H "X-Api-Key: your-api-key-here"

Example Response

{
  "status": "success",
  "total": 1,
  "current_page": 1,
  "total_pages": 1,
  "message": [
    {
      "user_id": 42,
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "company": "Tech Solutions LLC",
      "active": 2,
      "subscription_id": 3,
      "phone_number": "555-867-5309",
      "city": "San Francisco",
      "state_code": "CA",
      "country_code": "US",
      "website": "https://www.techsolutions.com",
      "signup_date": "20230901090000"
    }
  ]
}

Sensitive Fields & the Login Token

Every /api/v2/user/* response omits the password, token, and cookie fields. password and cookie are never returned under any circumstances. The member's login token can be returned on an opt-in, per-key basis — all three of the following conditions must hold at the same time:

• The request is a single-record retrieve (GET /api/v2/user/get/{user_id}). List and paginated requests never include the token.
• The request sends include_user_token=1.
• The API key has been granted the Include User Token permission, found in the Sensitive Data section of the key's API Permissions (Developer Hub » API Keys). This permission is off by default on every key, and the bulk enable-all control deliberately skips it — it can only be switched on individually.

Example Request (with login token)

curl -X GET "https://www.yourdomain.com/api/v2/user/get/35?include_user_token=1" \
  -H "X-Api-Key: your-api-key-here"

Create a User

Creates a new user. The email, password, and subscription_id fields are required.

Required Fields

Example Request

curl -X POST "https://www.yourdomain.com/api/v2/user/create" \
  -H "X-Api-Key: your-api-key-here" \
  -d "email=jane@example.com" \
  -d "password=SecurePass123" \
  -d "subscription_id=1" \
  -d "first_name=Jane" \
  -d "last_name=Smith" \
  -d "company=Acme+Corp" \
  -d "phone_number=555-555-1234" \
  -d "city=Los+Angeles" \
  -d "state_code=CA" \
  -d "country_code=US"

Example Response

{
  "status": "success",
  "message": {
    "user_id": 101,
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "company": "Acme Corp",
    "active": 1,
    "subscription_id": 1
  }
}

Subscription Start Date & Billing Cycle

A member can be created with a subscription that is already established, rather than one that necessarily begins on the day the record is created. Sending subscription_start_date and billing_cycle together on the create call writes the member's billing record with the supplied start date, a next due date one full billing cycle later, and the requested cycle. Carrying members over from another platform with their original renewal dates intact is one common reason to use this, but the two parameters apply to any member whose subscription needs a specific start date. Both are optional, and omitting them leaves the existing behavior unchanged: the subscription starts on the day the member is created, on the plan's default cycle.

Not every website offers all six intervals. Membership plans store a separate price for each one, and plans that have no price set for the requested interval reject it, so checking the plan's pricing before choosing a cycle avoids the error. Older websites commonly carry only a monthly and a yearly price, which means the quarterly, semiannual, biennial and triennial values are rejected on those sites.

Example Request (with subscription dates)

curl -X POST "https://www.yourdomain.com/api/v2/user/create" \
  -H "X-Api-Key: your-api-key-here" \
  -d "email=jane@example.com" \
  -d "password=SecurePass123" \
  -d "subscription_id=1" \
  -d "first_name=Jane" \
  -d "last_name=Smith" \
  -d "subscription_start_date=2024-06-15" \
  -d "billing_cycle=annually"

Example Error Response

{
  "status": "error",
  "message": "subscription_start_date cannot be more than 1 billing cycle (monthly) in the past"
}

Update a User

Updates an existing user. The user_id is required in the request body. Only include the fields you want to change.

Example Request

curl -X PUT "https://www.yourdomain.com/api/v2/user/update" \
  -H "X-Api-Key: your-api-key-here" \
  -d "user_id=101" \
  -d "company=New+Company+Name" \
  -d "active=2" \
  -d "phone_number=555-999-8888"

Example Response

{
  "status": "success",
  "message": {
    "user_id": 101,
    "first_name": "Jane",
    "last_name": "Smith",
    "company": "New Company Name",
    "active": 2,
    "phone_number": "555-999-8888"
  }
}

Managing Member Categories

Member categories (sub-categories under a profession) are assigned through the same /api/v2/user/update endpoint using the services parameter together with create_new_categories and delete_categories. Categories themselves live in list_services and the member-to-category relations live in rel_services. Both are scoped by the member's profession_id, so make sure the member has a valid top-level profession set before managing their sub-categories.

Add categories to a member (auto-creating missing ones)

Sends three category names. Any name that already exists under the member's profession is linked to the member; any name that doesn't yet exist is first inserted into list_services under the member's profession and then linked.

curl -X PUT "https://www.yourdomain.com/api/v2/user/update" \
  -H "X-Api-Key: your-api-key-here" \
  -d "user_id=35" \
  -d "services=Appliances+%26+Repair,Home+Cleaning,Handyman+Services" \
  -d "create_new_categories=1"

Clear all of a member's categories

Wipes every rel_services row for the member. The underlying categories in list_services are left in place.

curl -X PUT "https://www.yourdomain.com/api/v2/user/update" \
  -H "X-Api-Key: your-api-key-here" \
  -d "user_id=35" \
  -d "delete_categories=1"

Replace a member's entire category list in one call

Combines delete_categories, services, and create_new_categories to clear the existing assignments and reassign a new set atomically. This mirrors the "delete all and re-add" workflow available in the admin UI.

curl -X PUT "https://www.yourdomain.com/api/v2/user/update" \
  -H "X-Api-Key: your-api-key-here" \
  -d "user_id=35" \
  -d "delete_categories=1" \
  -d "services=Plumbing,Electrical,HVAC" \
  -d "create_new_categories=1"

Read a member's categories as a nested tree

GET /api/v2/user/categories/{user_id} returns the member's assigned top-level category with their assigned sub- and sub-sub-categories nested inside — the read-side companion to the services parameter above. This is a standard endpoint, allowed by default for every API key.

curl -X GET "https://www.yourdomain.com/api/v2/user/categories/35" \
  -H "X-Api-Key: your-api-key-here"

{
  "status": "success",
  "message": {
    "profession_id": 1,
    "name": "Home Services",
    "filename": "home-services",
    "sub_categories": [
      {
        "service_id": 1,
        "name": "Plumbing",
        "filename": "plumbing",
        "profession_id": 1,
        "master_id": 0,
        "sub_sub_categories": []
      }
    ]
  }
}

Delete a User

Permanently deletes a user and all associated data. The user_id is required. Set delete_images to 1 to also remove the user's uploaded image files.

Example Request

curl -X DELETE "https://www.yourdomain.com/api/v2/user/delete" \
  -H "X-Api-Key: your-api-key-here" \
  -d "user_id=101" \
  -d "delete_images=1"

Example Response

{
  "status": "success",
  "message": "user record was deleted"
}

Search Users

Performs a full member directory search with keyword, category, and location filtering. This endpoint mirrors the front-end member search functionality.

Search Parameters

Example Request

curl -X POST "https://www.yourdomain.com/api/v2/user/search" \
  -H "X-Api-Key: your-api-key-here" \
  -d "q=plumber" \
  -d "address=Chicago%2C+IL" \
  -d "limit=10"

User Login

Validates a user's email and password. Returns a success or error status indicating whether the credentials are valid. This endpoint does not return user profile data — use GET /api/v2/user/get to retrieve user details after confirming credentials.

Example Request

curl -X POST "https://www.yourdomain.com/api/v2/user/login" \
  -H "X-Api-Key: your-api-key-here" \
  -d "email=jane@example.com" \
  -d "password=SecurePass123"

Example Response

{
  "status": "success",
  "message": "credentials are valid"
}

User Transactions

Returns billing transactions for a specific user. Pass the user's user_id as a POST body parameter.

Example Request

curl -X POST "https://www.yourdomain.com/api/v2/user/transactions" \
  -H "X-Api-Key: your-api-key-here" \
  -d "user_id=42"

User Subscriptions

Returns the subscription/membership history for a specific user. Pass the user's user_id as a POST body parameter.

Example Request

curl -X POST "https://www.yourdomain.com/api/v2/user/subscriptions" \
  -H "X-Api-Key: your-api-key-here" \
  -d "user_id=42"