REST API Account Creation Guide

This guide explains the attributes you can send to the User Creation API, as well as which fields are mandatory or optional, and what the requirements are - which differ based on userLevel and locationType.

Note: If you are looking for our full REST API (technical) documentation, please click HERE.

Core Identity Fields

The following fields are mandatory for all user types, and must be present in every payload:

• <userID> – User's unique identifier (aka Login ID / Username)

• <password> – User's login password

• <userLevel> – Defines the hierarchy level (varies per user type)

• <timezone> – User's preferred time zone

• <role> – Role(s) assigned to the user

• <firstname>

• <lastname>

• <city>

• <state>

• <phone1>

• <email>

Account Behavior Controls

The following fields are optional, but important, so review carefully to determine whether or not they are required for your use case:

• User Type: <type>
  • Values: Normal (default) OR Guest
    • If Guest:
      • Requires: <expirationTime> (which will automatically expire the account's access)
  • Use case: Temporary access for auditors, trainees, or vendors
• World Manager Access: <wmAccess>
  • Values: N (default) OR Y
    • If Y:
      • Requires: <wmAccountGroup>, <wmCountry> AND <wmEmployeeType> 
  • Use case: Training & Development access for users

User Types and Their Specific Requirements

1. Corporate

1.1 User Level

• <userLevel> = Corporate

1.2 Additional Mandatory Field(s)

• N/A

Note: Typically used for HQ-level users. No additional hierarchy mappings required.

2. Divisional

2.1 User Level

• <userLevel> = Divisional

2.2 Additional Mandatory Field(s)

• <division>

3. Regional

3.1 User Level

• <userLevel> = Regional

3.2 Additional Mandatory Field(s)

• <region>

4. Franchise

4.1 User Level

• <userLevel> = Employee OR Owner

4.2 Additional Mandatory Field(s)

• <locationType> = Franchise OR MUID OR Entity
  • If Franchise:
    • Requires: <franchiseeReferenceId> (franchise name / reference ID) OR <franchiseeNo> (franchise number)
  • If MUID:
    • Requires: <muidValue>
  • If Entity:
    • Requires: <entityName>
• <userType> = New (creates a new account) OR Existing (links to an existing record)
  • If Existing and <userLevel> = Owner:
    • Requires: A valid/existing owner record in the system, otherwise you'll face errors

Important: When using Existing, ensure an exact match of identifiers to avoid duplication and/or mismatch errors.

4.3 Optional Field(s)

• <canAddEmployee> = N (default) / Y (grants the user permission to create other users)

Common Scenarios to Avoid

1. Missing Dependent and Mandatory Fields

• Ensure dependent fields are configured correctly, such as:
  • <wmAccess> = Y without the additional (required) WM attributes
  • <locationType> without the required mapping fields

2. Incorrect User Level

• Ensure <userLevel> aligns with the hierarchy field, such as:
  • Divisional → <division> required
  • Regional → <region> required

3. Guest User Without Expiration

• If <type> = Guest, always include <expirationTime>

4. Existing Record Mismatch

• When <userType> = Existing, ensure:
  • Exact spelling
  • Correct identifiers

If you require any further assistance using the REST API, please contact our Support Team at helpdesk@franconnect.com.