> ## Documentation Index > Fetch the complete documentation index at: https://docs.pylon.mortgage/llms.txt > Use this file to discover all available pages before exploring further. # Managing organization users > Create and manage users in your organization — loan officers, processors, and admins — through the organization GraphQL mutations 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](https://sandbox.pylon.mortgage/documentation/graphql/index.html#mutation-organization) 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`](https://sandbox.pylon.mortgage/documentation/graphql/index.html#query-organizationRoles) to list the roles available to your organization and find their IDs: ```graphql theme={null} query { organizationRoles { edges { node { id name description } } } } ``` ## Creating a user Use the `createOrganizationUser` mutation with [`CreateOrganizationUserInput`](https://sandbox.pylon.mortgage/documentation/graphql/index.html#definition-CreateOrganizationUserInput): ```graphql theme={null} 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: ```json theme={null} { "input": { "email": "jane.doe@yourcompany.com", "firstName": "Jane", "lastName": "Doe", "organizationRoles": [""], "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`](https://sandbox.pylon.mortgage/documentation/graphql/index.html#query-organizationRoles) query. | | `licenses` | For loan officers | Individual state licenses. Required for loan officers, optional for admins, and rejected for all other roles. See [Licenses](#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](#access-types). | ### Licenses Each entry in `licenses` uses [`OrganizationUserLicenseInput`](https://sandbox.pylon.mortgage/documentation/graphql/index.html#definition-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: ```json theme={null} { "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`](https://sandbox.pylon.mortgage/documentation/graphql/index.html#definition-UpdateOrganizationUserDetailsInput) to change a user's names, phone number, or individual NMLS identifier after creation. It is authorized with the `update:users` scope. ```graphql theme={null} 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](#other-user-operations)). ## Reading user details The [`organizationUser`](https://sandbox.pylon.mortgage/documentation/graphql/index.html#query-organizationUser) query returns a user's contact details and licenses alongside the basics ([`organizationUsers`](https://sandbox.pylon.mortgage/documentation/graphql/index.html#query-organizationUsers) list nodes carry only `id`, `email`, `firstName`, and `lastName` — fetch the individual user for the full detail): ```graphql theme={null} query { organizationUser(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`](https://sandbox.pylon.mortgage/documentation/graphql/index.html#query-organizationUsers) | Query | `read:users` | List users in your organization. | | [`organizationUser`](https://sandbox.pylon.mortgage/documentation/graphql/index.html#query-organizationUser) | Query | `read:users` | Fetch a single user by ID. | | [`updateOrganizationUserDetails`](https://sandbox.pylon.mortgage/documentation/graphql/index.html#definition-UpdateOrganizationUserDetailsInput) | Mutation | `update:users` | Update a user's names, phone number, or individual NMLS ID. See [Updating a user's details](#updating-a-users-details). | | [`updateOrganizationUserRoles`](https://sandbox.pylon.mortgage/documentation/graphql/index.html#definition-UpdateOrganizationUserRolesInput) | Mutation | `update:users` | Replace a user's assigned roles. | | [`sendOrganizationUserInvitationEmail`](https://sandbox.pylon.mortgage/documentation/graphql/index.html#definition-SendOrganizationUserInvitationEmailInput) | Mutation | `update:users` | Re-send the invitation email to a user who hasn't signed in yet. | | [`deleteOrganizationUser`](https://sandbox.pylon.mortgage/documentation/graphql/index.html#definition-DeleteOrganizationUserInput) | Mutation | `delete:users` | Remove a user from your organization. | For example, listing users (useful for finding loan officers to [assign to a loan](/guides/getting-started/e2e-build)): ```graphql theme={null} query { organizationUsers { totalCount edges { node { id email firstName lastName } } } } ```