API Reference - Users

Link: https://support.brilliantdirectories.com/support/solutions/articles/12000108047

← Back to API Reference | Getting Started

Users

Users (members) are the core of every Brilliant Directories website. This resource maps to the users_data database table. Every user belongs to a membership level (subscription type) and has a status code that controls their access to the site.

Model name in URL: user — DB table: users_data

The User Object

Field	Type	Description
`user_id`	integer	Unique user ID (primary key, read-only)
`first_name`	string	User's first name
`last_name`	string	User's last name
`email`	string	Email address — must be unique across the site required on create
`password`	string	Password (plain text on create/update; stored as a hash). Write-only — never returned in any API response required on create
`subscription_id`	integer	Membership level ID required on create
`active`	integer	Account status: `1`=Inactive, `2`=Active, `3`=Cancelled, `4`=On Hold, `5`=Past Due
`company`	string	Business or company name
`phone_number`	string	Phone number
`address1`	string	Street address line 1
`address2`	string	Street address line 2
`city`	string	City
`zip_code`	string	ZIP or postal code
`state_code`	string	2-letter state/province code (e.g. `CA`)
`state_ln`	string	Full state/province name (e.g. `California`)
`country_code`	string	2-letter country code (e.g. `US`)
`country_ln`	string	Full country name (e.g. `United States`)
`website`	string	User's website URL
`twitter`	string	Twitter/X profile URL
`youtube`	string	YouTube channel URL
`facebook`	string	Facebook profile/page URL
`linkedin`	string	LinkedIn profile URL
`instagram`	string	Instagram profile URL
`pinterest`	string	Pinterest profile URL
`snapchat`	string	Snapchat handle
`whatsapp`	string	WhatsApp contact number
`about_me`	text	About Me biography (HTML allowed)
`quote`	string	Tagline or quote displayed on profile
`experience`	integer	Year experience began (e.g. `2015`)
`affiliation`	text	Professional affiliations
`awards`	text	Awards and achievements
`credentials`	text	Professional credentials or certifications
`position`	string	Job title or position
`profession_id`	integer	Industry/profession category ID
`featured`	integer	`1` if user is featured, `0` otherwise
`nationwide`	integer	`1` if user serves clients nationwide
`lat`	number	Latitude coordinate
`lon`	number	Longitude coordinate
`signup_date`	string	Date user signed up (format: `YYYYMMDDHHmmss`)
`last_login`	string	Date/time of last login (format: `YYYYMMDDHHmmss`)
`modtime`	timestamp	Last modified timestamp (auto-updated)
`filename`	string	URL-friendly profile slug
`parent_id`	integer	Parent user ID for sub-accounts
`verified`	integer	`1` if email verified
`blog`	text	Blog URL or blog content
`no_geo`	string	Flag to disable geocoding for this user
`user_consent`	text	Record of user consent (GDPR/privacy compliance)
`search_description`	text	Custom description displayed in search results
`token`	string	Login token (auto-generated). Not returned by default — available only through the opt-in flow described under Sensitive Fields & the Login Token below
`cookie`	string	Session cookie token. Never returned in any API response
`ref_code`	string	Referral code or signup source (e.g. `Manually Added`)
`bitly`	string	Bitly URL shortening flag or shortened URL
`facebook_id`	string	Facebook account ID (for Facebook login integration)
`google_id`	string	Google account ID (for Google login integration)
`cv`	text	Curriculum vitae or resume content
`work_experience`	text	Work experience details
`rep_matters`	text	Business hours or additional reputation information
`gmap`	string	Google Maps embed URL or place ID
`listing_type`	string	Listing type classification. Enum — only supports 2 string values, either: "Individual" or "Company" (exact case). Misclassifying breaks site logic.

Special Update Parameters

Parameter	Type	Description
`member_tag_action`	integer	Set to `1` to apply tag changes
`member_tags`	string	Comma-separated tag IDs to assign (e.g. `1,2,3`)
`credit_action`	string	`add`, `deduct`, or `override` credits
`credit_amount`	number	Credit amount for the credit action
`images_action`	string	`remove_all`, `remove_cover_image`, `remove_logo_image`, or `remove_profile_image`
`services`	string	Comma-separated list of sub-category names or IDs to assign to the member. For sub-sub nesting, use the format `SubCategory=>SubSubCategory1,SubSubCategory2`. By default, any names that don't already exist under the member's profession are ignored.
`create_new_categories`	integer	Set to `1` to auto-create any category names in `services` that don't already exist under the member's profession. Requires a valid `profession_id` either on the request or already set on the member. New rows are inserted into `list_services` under the member's profession and linked to the member in `rel_services`.
`delete_categories`	integer	Set to `1` to wipe all of the member's existing category assignments (all `rel_services` rows for the member) before any new `services` in the same request are applied. The category definitions in `list_services` are not affected. Combine with `services=` (and optionally `create_new_categories=1`) to replace the entire category list in a single call.
`auto_geocode`	integer	`1` to automatically geocode the user's address

Profession scope requirement: All category lookups and inserts are scoped by the member's profession_id. If the member's profession_id is 0 and no profession_id (or profession_name) is included on the request, the services parameter has no effective scope and no rel_services rows will be written for that member. Always set the top-level category first (or pass it alongside services) when adding sub-categories.

List Users

GET /api/v2/user/get

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

Example Request

Copy

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

Example Response

Copy

{
  "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

GET /api/v2/user/get/{user_id}

Returns a single user by their user_id.

Example Request

Copy

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

Example Response

Copy

{
  "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.

Treat the login token like a password: POST /api/v2/user/login accepts the token in place of the member's password, and on sites with the enable_login_token_link Advanced Setting enabled it logs the member in directly via /login/token/{token}. Every token retrieval is audit-logged with the API key ID and member ID.

Example Request (with login token)

Copy

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

POST /api/v2/user/create

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

Required Fields

Parameter	Type	Description
`email`	string	Required
`password`	string	Required
`subscription_id`	integer	Required — membership level ID

Example Request

Copy

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

Copy

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

Update a User

PUT /api/v2/user/update

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

Example Request

Copy

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

Copy

{
  "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.

Copy

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.

Copy

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.

Copy

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.

Copy

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

Copy

{
  "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": []
      }
    ]
  }
}

Need finer control? For managing individual category definitions (create a new sub or sub-sub category, delete a category record) use the list_services endpoints. For managing individual member-to-category links by rel_id without touching the whole list, use the rel_services endpoints.

Delete a User

DELETE /api/v2/user/delete

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

Copy

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

Copy

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

Search Users

POST /api/v2/user/search

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

Search Parameters

Parameter	Type	Description
`q`	string	Keyword to search across member data
`pid`	integer	Top-level category ID to filter by
`tid`	integer	Sub-level category ID to filter by
`ttid`	integer	Sub-sub-level category ID to filter by
`address`	string	Location to search near (e.g. `Los Angeles, CA`)
`sort`	string	Sort order: `reviews`, `name ASC`, `name DESC`, `last_name_asc`, `last_name_desc`
`page`	integer	Page number
`limit`	integer	Results per page
`dynamic`	integer	Set to `1` to use Dynamic Category Filter search mode
`output_type`	string	`array` (default) or `html`

Example Request

Copy

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

POST /api/v2/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

Copy

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

Copy

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

User Transactions

POST /api/v2/user/transactions

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

Example Request

Copy

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

POST /api/v2/user/subscriptions

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

Example Request

Copy

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

What Do You Need Help With?

API Reference - Users

Users

The User Object

Special Update Parameters

List Users

Example Request

Example Response

Retrieve a User

Example Request

Example Response

Sensitive Fields & the Login Token

Example Request (with login token)

Create a User

Required Fields

Example Request

Example Response

Update a User

Example Request

Example Response

Managing Member Categories

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

Clear all of a member's categories

Replace a member's entire category list in one call

Read a member's categories as a nested tree

Delete a User

Example Request

Example Response

Search Users

Search Parameters

Example Request

User Login

Example Request

Example Response

User Transactions

Example Request

User Subscriptions

Example Request

Related Articles