createUser
Create a new member or user in the Brilliant Directories directory platform. Use for adding members via imports, automations, or admin accounts.
Instructions
Create a new member/user - Create a member. Writes live data. Welcome email silent by default - set send_email_notifications=1 to trigger.
Required: email, password, subscription_id.
Use when: adding members outside BD signup - CSV imports, scraped listings, Zapier automations, admin test accounts.
Enums: active: 1=Not Active, 2=Active, 3=Canceled, 4=On Hold, 5=Past Due, 6=Incomplete. listing_type: Individual, Company. verified/nationwide: 1/0.
Prerequisites: subscription_id MUST reference an existing plan - discover via listMembershipPlans. For category assignment via profession_id / profession_name / services, apply Rule: Category taxonomy (auto-create is ON for createUser).
Parameter interactions:
auto_image_import=1- fetch external image URLs into BD storage (forprofile_photo,logo,cover_photoholding URLs). Without it, BD stores the URL as-is; images break if source host goes down. Supports JPG/PNG/GIF/WebP/SVG. Processing delay: several minutes. Recommended default for any external image URL.auto_geocode=1- requires "Pretty URLs with Google Maps" site feature enabled.send_email_notifications=1- trigger welcome email per plan settings.
Email uniqueness - controlled by site setting allow_duplicate_member_emails (not exposed via API):
OFF (default): BD rejects duplicate email on create (validation error).
ON: duplicates accepted and stored with different
user_ids. Identicalemail+passwordpair is also accepted (no extra uniqueness check on the pair).Safe idempotent pattern: pre-check via
listUsers property=email property_value=<email> property_operator==. Match found -> reuseuser_idorupdateUserinstead. Skipping the check on a duplicates-allowed site creates orphan duplicates on retry loops.
Field validation quirks:
token(if supplied — useful for CSV imports / cross-site migrations preserving original tokens; BD auto-generates if omitted): exactly 32 alphanumeric chars, unique across members.URL fields (
website,booking_link,blog,facebook,twitter,linkedin,instagram, etc.): must start withhttp://orhttps://. Invalid formats silently skipped.
Profile URL: <site-domain>/<user.filename>. filename is the complete relative path. Do NOT prepend /business///profile///member/ - BD resolves filename verbatim.
Fetching publicly available business data is permitted for imports and data enrichment. When searching for external listings, fetch each entity's image from their own presence in this order:
Logo image from their site's header/nav ->
logo(businesses).Headshot from Home, About or Team page ->
profile_photo(individuals).Follow their social links -> profile image there.
Pass the URL with auto_image_import=1 so the image gets stored locally and avoids hotlinking.
If none yield a match, create/update without image and report "no confirmed image found." Never substitute a stock photo or guess. Skip an entire record and find an alternate listing only when the user explicitly requires images.
See also: updateUser (modify existing), deleteUser (prefer active=3 over delete).
Returns: { status: "success", message: {...createdRecord} } including user_id.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | |||
| password | Yes | ||
| subscription_id | Yes | Membership plan ID | |
| first_name | No | ||
| last_name | No | ||
| company | No | ||
| phone_number | No | ||
| city | No | ||
| state_code | No | ||
| country_code | No | ||
| active | No | User account status. BD does NOT validate - integers outside the set store as-is (observed: `99`). Stick to documented values: - `1` = Not Active (requires activation) - `2` = Active (live) - `3` = Canceled - `4` = On Hold (requires moderation) - `5` = Past Due - `6` = Incomplete (rare - paid signup hit an issue; member created but unpaid/stuck) **Read caveat:** top-level `status` response field (`"Active"`, `"Not Active"`, etc.) is a computed label. When `active` is an unknown value, `status` is OMITTED from the response - don't treat `status` as always-present. | |
| listing_type | No | Listing type classification. Canonical values (EXACT case): `Individual` or `Company`. BD does NOT validate - off-canonical values (`individual`, `INDIVIDUAL`, `Business`) store verbatim and break downstream `listing_type === "Individual"` checks. **Always include explicitly on `createUser`.** BD's server-side default when omitted is `Individual` - if you want `Company` as your default (recommended for scraped business listings, CSV imports), you MUST send it explicitly; do NOT rely on omission. Default to `Company`, override to `Individual` when: (1) user explicitly says so, (2) structured input specifies `listing_type` per-record (normalize case client-side), (3) source clearly describes a person, not a business. | Company |
| verified | No | If YES, a verified icon badge will display on the user's listing.\n\nValid values:\n 1 = Yes\n 0 = No | |
| signup_date | No | User signup date. Format: `YYYYMMDDHHmmss` in the site's timezone. BD silently truncates other formats, corrupting the value. BD auto-fills on create — omit unless backfilling legacy signup dates during import/migration. | |
| profession_id | No | Assign this user to a top level category. Input the ID number of the top level category. | |
| services | No | Assign this user to sub-level categories. Input a comma-separated list of sub-level IDs or names (NO spaces around commas - `"1823,1824"` not `"1823, 1824"`). | |
| address1 | No | The user's street address. | |
| address2 | No | The user's unit or suite number. | |
| auto_geocode | No | OPTIONAL: Allow Google to geocode users. Requires "Pretty URLs with Google Maps". Search BD support to learn more.\n\nValid values:\n 1 = Yes\n 0 = No | |
| zip_code | No | The user's zip / postal code. | |
| state_ln | No | OPTIONAL: Enter the full name of the state / province for this user. | |
| country_ln | No | OPTIONAL: Enter the full name of the country for this user. | |
| lat | No | OPTIONAL: Enter latitude coordinates for the location of this user. | |
| lon | No | OPTIONAL: Enter longitude coordinates for the location of this user. | |
| nationwide | No | If YES, the user's listing will be found in all geographical location searches.\n\nValid values:\n 1 = Yes\n 0 = No | |
| member_tags | No | ADDITIONAL: Assign Member Tag ID | |
| search_description | No | Short description shown under the user's name on search result pages. **170-char limit.** | |
| about_me | No | Long description of the member/user. Renders on their public profile. Froala body field — use `<p>`/`<h2>`/`<h3>`/`<ul>`/`<ol>` structure; skip images unless user asks. HTML allowed (per universal safe-HTML rule). | |
| quote | No | OPTIONAL: Enter the user's personal quote, motto or slogan. | |
| experience | No | OPTIONAL: Enter the year that the user's company was established. Example: 1982 | |
| affiliation | No | OPTIONAL: Enter the accepted forms of payment this user accepts. | |
| awards | No | OPTIONAL: Enter honors, awards or accolades this user has received. | |
| rep_matters | No | OPTIONAL: Enter the hours of operation for the member. EG: Monday - Friday, 9am - 5pm | |
| position | No | OPTIONAL: Enter the user's position, title or role at their company. Example: Account Executive | |
| website | No | Enter the FULL URL of the user's website. Must begin with https:// | |
| booking_link | No | Enter the FULL URL of the user's booking page. Must begin with https:// | |
| blog | No | Enter the FULL URL of the user's blog. Must begin with https:// | |
| No | Enter the FULL URL of the user's Facebook account. Must begin with https:// | ||
| No | Enter the FULL URL of the user's Twitter account. Must begin with https:// | ||
| No | Enter the FULL URL of the user's Linkedin account. Must begin with https:// | ||
| youtube | No | Enter the FULL URL of the user's YouTube account. Must begin with https:// | |
| No | Enter the FULL URL of the user's Instagram account. Must begin with https:// | ||
| No | Enter the FULL URL of the user's Pinterest account. Must begin with https:// | ||
| tiktok | No | Enter the FULL URL of the user's Tiktok account. Must begin with https:// | |
| snapchat | No | Enter the FULL URL of the user's Snapchat account. Must begin with https:// | |
| No | Enter the FULL URL of the user's Whatsapp account. Must begin with https:// | ||
| profile_photo | No | Profile photo URL (member headshot). **Bare URL only — no `?query`, must end in `.jpg`/`.jpeg`/`.png`/`.webp`.** Query strings get baked into imported filenames and 404. Pair with `auto_image_import=1` to fetch externals into site storage. | |
| logo | No | Logo URL (brand/business mark). **Bare URL only — no `?query`, must end in `.jpg`/`.jpeg`/`.png`/`.webp`.** Query strings get baked into imported filenames and 404. Pair with `auto_image_import=1` to fetch externals into site storage. | |
| cover_photo | No | Cover photo URL (user/profile banner). Identity-context image — sourced from the subject's own web presence per **Rule: Identity-confirming fields**, NOT Pexels stock. **Bare URL only — no `?query`, must end in `.jpg`/`.jpeg`/`.png`/`.webp`.** Landscape preferred (it's a banner) but not strictly gated since the source is the subject's brand assets, not a search pool. Query strings get baked into imported filenames and 404. Pair with `auto_image_import=1` to fetch externals into site storage. | |
| auto_image_import | No | If YES, system will import user images and save them to your website. Processing may take several minutes after import.\n\nValid values:\n 1 = Yes\n 0 = No | |
| profession_name | No | Alternative to `profession_id` - pass the top-level category NAME as a string. BD looks it up in `list_professions`. **Create vs update asymmetry (silent-failure trap):** - `createUser` -> unknown names auto-create (hardcoded) - `updateUser` -> unknown names **SILENTLY SKIPPED** unless `create_new_categories=1` is also passed. The write succeeds and returns success; the category just doesn't change. Always pass `create_new_categories=1` on update when supplying a `profession_name` that might not exist. | |
| send_email_notifications | No | Set to `1` to trigger the welcome email on member creation (based on the membership plan's configured email). Default: off - API creates are silent because they typically aren't self-signups. Only set this when you WANT the member notified. | |
| last_login | No | Timestamp of user's last login. Format: `YYYYMMDDHHmmss` in the site's timezone. BD silently truncates other formats, corrupting the value. BD updates on each login — omit unless backfilling historical data during import/migration. | |
| filename | No | Override BD's auto-generated URL slug (e.g. `united-states/los-angeles/doctor/jane-smith`). If omitted, BD derives it from city/category/name. **Usually OMIT** - manual values get regenerated by BD on future updates that change URL-influencing fields, silently overwriting your override. |