Managing organization users

Organization users are the members of your organization who work on loans: loan officers, loan officer assistants, processors, and admins. The API lets you provision these users programmatically — including their roles, state licenses, processing fees, and contact details — instead of creating them one at a time in the Command Center. All write operations live under the organization mutation namespace, and user creation is authorized with the create:users scope.

Roles

Every user is created with one or more roles. Roles determine what the user can do, and they also determine which other fields the creation input requires or rejects:

Role	Description	Additional requirements
Admin	Full administrative access to your organization.	May optionally carry state licenses.
Loan Officer	Licensed professional who originates and manages loans.	Must supply at least one state license.
Loan Officer Assistant	Supports loan officers on their pipeline.	—
Processor	Processes loans within your organization.	Requires `processorFeeAmount` and `companyName`.
Third-Party Processor	External processor outside your organization.	Requires `processorFeeAmount` and `companyName`. May use an email address outside your organization’s domain.

Roles are passed by ID. Query organizationRoles to list the roles available to your organization and find their IDs:

query {
  organizationRoles {
    edges {
      node {
        id
        name
        description
      }
    }
  }
}

Creating a user

Use the createOrganizationUser mutation with CreateOrganizationUserInput:

mutation CreateOrganizationUser($input: CreateOrganizationUserInput!) {
  organization {
    createOrganizationUser(input: $input) {
      organizationUser {
        id
        email
        firstName
        lastName
      }
      internalUserCreated
      userErrors {
        message
      }
    }
  }
}

Example variables for a loan officer licensed in California and Texas:

{
  "input": {
    "email": "jane.doe@yourcompany.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "organizationRoles": ["<loan-officer-role-id>"],
    "phoneNumber": "555-123-4567",
    "individualNmlsId": "1234567",
    "licenses": [
      { "state": "CA", "licenseNumber": "CA-DBO-123456", "expirationYear": 2027 },
      { "state": "TX", "licenseNumber": "TX-987654", "expirationYear": 2027 }
    ]
  }
}

Input fields

Field	Required	Description
`email`	Yes	The user’s email address. Must belong to your organization’s email domain, except for third-party processors (who are external and may use any domain).
`firstName`	Yes	The user’s first name.
`lastName`	Yes	The user’s last name.
`organizationRoles`	Yes	Role IDs to assign, from the `organizationRoles` query.
`licenses`	For loan officers	Individual state licenses. Required for loan officers, optional for admins, and rejected for all other roles. See Licenses.
`processorFeeAmount`	For processors	Processing fee in dollars. Required when the assigned role is a processor or third-party processor; not applicable otherwise.
`companyName`	For processors	Payee company name for the processing fee. Required when the assigned role is a processor or third-party processor. This is the name the fee is paid to on closing costs — for all other roles the user carries your organization’s name automatically.
`phoneNumber`	No	The user’s phone number.
`individualNmlsId`	No	The user’s individual NMLS identifier.
`companyAddress`	No	Your company’s NMLS address. Pylon auto-fills company fields from your organization’s records; supply this to override the address on file.
`accessType`	No	Where the user is provisioned. Defaults to `CommandCenterAccess`. See Access types.

Licenses

Each entry in licenses uses OrganizationUserLicenseInput:

Field	Description
`state`	The US state the license is held in (two-letter abbreviation).
`licenseNumber`	The state-issued license number.
`expirationYear`	The year the license expires. The expiration date is set to December 31st of this year.

Loan officers must be created with at least one license — they can only be assigned to loans in states where they hold an active license. Licensed users are assignable to loans immediately after creation.

Access types

The accessType field controls where the new user is provisioned:

Value	Behavior
`CommandCenterAccess` (default)	Creates a full Command Center user: a login is provisioned and an invitation email is sent so the user can set their password and sign in.
`InternalOnly`	Creates the user as a loan-origination file contact only. No Command Center login is created and no invitation email is sent — use this for people who need to appear on loans (e.g., a processor collecting a fee) but will never sign in.

The response shape differs between the two:

For CommandCenterAccess, success returns the new user in organizationUser.
For InternalOnly, there is no Command Center user to return, so organizationUser is null and success is signalled by internalUserCreated: true.

If your organization uses single sign-on (SSO), no separate password invitation is sent — the new user signs in through your identity provider as usual.

Error handling

Validation problems are returned in userErrors rather than as GraphQL errors, so always check that array:

{
  "organization": {
    "createOrganizationUser": {
      "organizationUser": null,
      "internalUserCreated": false,
      "userErrors": [
        { "message": "At least one license is required for the loan officer role." }
      ]
    }
  }
}

Common validation errors:

Error	Cause
`At least one license is required for the loan officer role.`	A loan officer was created without any `licenses`.
`Licenses may only be attached to admin or loan officer roles.`	`licenses` were supplied for a role that doesn’t support them.
`A processing fee is required for processor and third-party processor roles.`	A processor was created without `processorFeeAmount`.
`A company name is required for processor and third-party processor roles.`	A processor was created without `companyName`.
`Fee amount must be non-negative.`	`processorFeeAmount` was negative.
`Internal-only users must have a role that can be represented as a file contact.`	`accessType: InternalOnly` was used with a role that cannot appear on a loan file. Internal-only users exist purely as loan-file contacts, so they need at least one loan-facing role.

Processor fees, payee company names, licenses, contact details, and internal-only access are part of an expanded user-provisioning capability. If you receive the error

Creating users with processor fees, company names, licenses, contact details, or internal-only access is not enabled for this organization.

, contact Pylon to enable it for your organization.

Updating a user’s details

Use the updateOrganizationUserDetails mutation with UpdateOrganizationUserDetailsInput to change a user’s names, phone number, or individual NMLS identifier after creation. It is authorized with the update:users scope.

mutation UpdateOrganizationUserDetails($input: UpdateOrganizationUserDetailsInput!) {
  organization {
    updateOrganizationUserDetails(input: $input) {
      organizationUser {
        id
        firstName
        lastName
        phoneNumber
        individualNmlsId
      }
      userErrors {
        message
      }
    }
  }
}

Field	Description
`id`	The user to update.
`firstName`	New first name. Omit or pass `null` to leave unchanged — names cannot be cleared.
`lastName`	New last name. Omit or pass `null` to leave unchanged — names cannot be cleared.
`phoneNumber`	New phone number. Omit to leave unchanged; pass `null` to clear.
`individualNmlsId`	New individual NMLS identifier. Omit to leave unchanged; pass `null` to clear.

Email addresses and licenses cannot be changed through this mutation. Roles are updated separately via updateOrganizationUserRoles (see Other user operations).

Reading user details

The organizationUser query returns a user’s contact details and licenses alongside the basics (organizationUsers list nodes carry only id, email, firstName, and lastName — fetch the individual user for the full detail):

query {
  organizationUser(id: "<user-id>") {
    id
    email
    firstName
    lastName
    phoneNumber
    individualNmlsId
    licenses {
      state
      licenseNumber
    }
    organizationRoles {
      id
      name
    }
  }
}

licenses reflects the state licenses on the user’s loan-officer record and is null for users without one. License expiration dates are not returned.

Other user operations

The organization namespace and top-level queries cover the rest of the user lifecycle:

Operation	Type	Scope	Description
`organizationUsers`	Query	`read:users`	List users in your organization.
`organizationUser`	Query	`read:users`	Fetch a single user by ID.
`updateOrganizationUserDetails`	Mutation	`update:users`	Update a user’s names, phone number, or individual NMLS ID. See Updating a user’s details.
`updateOrganizationUserRoles`	Mutation	`update:users`	Replace a user’s assigned roles.
`sendOrganizationUserInvitationEmail`	Mutation	`update:users`	Re-send the invitation email to a user who hasn’t signed in yet.
`deleteOrganizationUser`	Mutation	`delete:users`	Remove a user from your organization.

For example, listing users (useful for finding loan officers to assign to a loan):

query {
  organizationUsers {
    totalCount
    edges {
      node {
        id
        email
        firstName
        lastName
      }
    }
  }
}

GET STARTED

EXAMPLES

ELEMENTS

CORE ENTITIES

Roles

Creating a user

Input fields

Licenses

Access types

Error handling

Updating a user’s details

Reading user details

Other user operations

​Roles

​Creating a user

​Input fields

​Licenses

​Access types

​Error handling

​Updating a user’s details

​Reading user details

​Other user operations

Roles

Creating a user

Input fields

Licenses

Access types

Error handling

Updating a user’s details

Reading user details

Other user operations