Payroll employees

Payroll employees store the demographic, employment, and payment data required to calculate and deliver payslips. Use the queries and mutations below to sync Naqood with an external HRIS or onboarding workflow without exposing anything outside the public GraphQL surface.

Prerequisites

• A Naqood API secret or OAuth-issued secret scoped to the target organization
• The organization slug for every organization-scoped operation
• A role that grants Payroll permissions (employees)

Employee fields

PayrollEmployee objects expose structured fields that mirror what the Naqood UI captures.

Field	Type	Notes
id	ID!	Stable identifier for follow-up mutations.
name / email	String! / Email	Shown on payslips and used when emailing documents.
employmentType	EmploymentType!	permanent, temporary, or intern. Defaults to permanent.
dateOfJoining / probationEndDate	Date	Used for gratuity and compliance reporting.
currency	String	Defaults to the organization currency; override when paying in FX.
paymentMethod	PaymentMethod	bank, cash, or check. Determines the payment metadata required.
bankAccountHolderName / bankName / iban / swift	String	Required when paymentMethod is bank.
earnings	[PayrollEmployeeEarning!]!	Optional defaults (basic salary, housing, etc.) tied to salary components.
createdAt / updatedAt	Timestamp!	Audit timestamps.

List employees

query PayrollEmployees(
  $slug: Slug!
  $offset: Int
  $limit: Int
  $orderBy: OrderByInput
  $filter: JSONObject
) {
  organization(slug: $slug) {
    payrollEmployees(
      offset: $offset
      limit: $limit
      orderBy: $orderBy
      filter: $filter
    ) {
      count
      entries {
        id
        name
        email
        employmentType
        currency
        paymentMethod
        earnings {
          salaryComponent {
            id
            name
            type
          }
          amount
        }
      }
    }
  }
}

Use filters to restrict results by department, employment type, payment method, or any other indexed field. Standard comparison operators (equalTo, greaterThan, between, and/or, etc.) are supported.

Create employees

mutation CreatePayrollEmployee($input: CreatePayrollEmployeeInput!) {
  createPayrollEmployee(input: $input)
}

CreatePayrollEmployeeInput highlights:

Field	Required	Notes
slug	✅	Organization that owns the employee.
name	✅	Display name shown anywhere the employee appears.
email	Optional	Needed to email payslips directly to the employee.
employmentType	Optional	Defaults to permanent if omitted.
currency	Optional	Override when paying in a different currency.
paymentMethod	Optional	Drives which payment fields become mandatory.
earnings	Optional	Array of { salaryComponentId, amount } defaults injected when drafting payslips.

Update employees

mutation UpdatePayrollEmployee($input: UpdatePayrollEmployeeInput!) {
  updatePayrollEmployee(input: $input) {
    id
    updatedAt
  }
}

• Provide the id plus only the fields you want to change; unspecified properties stay untouched.
• Setting the earnings array replaces the existing defaults in a single call.

With these operations you can keep Naqood in sync with HR onboarding systems while relying on the same validation paths used by the UI.