GraphQL API

Salsa’s GraphQL API

Our GraphQL API powers the entirety of our UI experiences, and we are expanding and adding more functionality to it every day. While the specific schema of the types will likely change as we roll this out wider in the coming months, you can access our current API and explore its schema and capabilities.

📘

If you are new to GraphQL, we recommend checking out this guide with basic concepts

Endpoint

Sandbox environment: https://api.sandbox.salsa.dev/api/graphql

Authorization

Our GraphQL API can be accessed using an API Token or a User Token. See the documentation on Authorization for details.

Api Limits

We use a traditional depth + complexity score to grade api requests and reject requests the violate this score. We may vary this over time, and assign specific weighting to some more expensive entities.

MetricLimit
Max Query Depth15
Max Query Complexity700

These are calculated with the follow base weights;

  • Complexity per scalar field - 1
  • Complexity per list field - 10

Exploring the API

By specifying the endpoint and authorization header you can use whatever preferred GraphQL IDE that you like to explore our API’s schema and execute operations. However, if you do not have one setup already, you can use Apollo’s sandbox Explorer on the web to try it out.

Browse the API in Apollo sandbox Explorer

1. Open this link for Salsa’s Sandbox environment

2. Expand the request Headers section at the bottom and replace the placeholder text with a User Token created or your API Token if you are calling from your backend

3. To run this particular query for an employer’s data, expand the variables and enter the employer id that this User Token has access to, or your API Token

4. Execute the query!

You can now explore the API’s schema and experiment with operations as you please.

Sample Operations

While we encourage you to explore the API on your own as much as you’d like, we believe having some sample operations illustrating common use cases can greatly help to jumpstart your exploration. For each sample operation below you need only specify the required variables in order to try them out.

Queries

Fetch basic employer information

query EmployerBasicInfo($employerId: ID!) {
  employer(id: $employerId) {
    id
    externalId
    businessName
  }
}

Get an employer’s details

query EmployerDetails($employerId: ID!) {
  employer(id: $employerId) {
    id
    externalId
    businessName
    workLocations {
      id
      address {
        ...AddressFields
      }
    }
    workerPayGroups {
      id
      name
    }
    ...EmployerTaxesSetups
  }
}

fragment AddressFields on Address {
  addressLine1
  administrativeArea
  locality
  postalCode
}

fragment EmployerTaxesSetups on Employer {
  taxesSetupByJurisdiction {
    jurisdiction {
      name
    }
    taxIdentifiers {
      type {
        name
      }
      value
    }
  }
}

List the workers of an employer

query SimpleWorkersList($employerId: ID!) {
  employer(id: $employerId) {
    id
    workers {
      ...WorkerBasicInfo
    }
  }
}

fragment WorkerBasicInfo on Worker {
  id
  externalId
  firstName
  lastName
  displayName
}

Get a worker’s details

query WorkerDetails($workerId: ID!) {
  worker(id: $workerId) {
    ...WorkerBasicInfo
    personalInformation {
      dateOfBirth
      gender {
        name
      }
      homeAddress {
        address {
          ...AddressFields
        }
      }
    }
    taxesSetupByJurisdiction {
      jurisdiction {
        name
      }
      taxAllowances {
        type {
          name
        }
        value
      }
      additionalTaxWithholdings {
        type {
          name
        }
        value
      }
    }
  }
}

fragment WorkerBasicInfo on Worker {
  id
  externalId
  firstName
  lastName
  displayName
}

fragment AddressFields on Address {
  addressLine1
  administrativeArea
  locality
  postalCode
}

List the payslips of a worker

query WorkerPayslips($workerId: ID!) {
  worker(id: $workerId) {
    ...WorkerBasicInfo
    payslips {
      id
      payDate
      payPeriod {
        period {
          start
          end
        }
      }
      grossPay
      netPay
    }
  }
}

fragment WorkerBasicInfo on Worker {
  id
  externalId
  firstName
  lastName
  displayName
}

Get a payslip’s details

query PayslipDetails($employeePayslipId: ID!) {
  employeePayslip(id: $employeePayslipId) {
    id
    employeeDetails {
      worker {
        id
      }
      displayName
    }
    payDate
    payPeriod {
      period {
        start
        end
      }
    }
    grossPay
    netPay
    totals {
      totalCompensations {
        ...PayslipAmountsFragment
      }
      totalNonTaxDeductions {
        ...PayslipAmountsFragment
      }
      totalTaxDeductions {
        ...PayslipAmountsFragment
      }
      totalNonTaxContributions {
        ...PayslipAmountsFragment
      }
      totalTaxContributions {
        ...PayslipAmountsFragment
      }
    }
    pay {
      description
      amounts {
        ...PayslipAmountsFragment
      }
    }
    nonTaxDeductions {
      description
      amounts {
        ...PayslipAmountsFragment
      }
    }
    taxDeductions {
      description
      amounts {
        ...PayslipAmountsFragment
      }
    }
    nonTaxContributions {
      description
      amounts {
        ...PayslipAmountsFragment
      }
    }
    taxContributions {
      description
      amounts {
        ...PayslipAmountsFragment
      }
    }
  }
}

fragment PayslipAmountsFragment on PayslipAmounts {
  amount
  ytdAmount
}

Get a payroll run’s details

query PayrollRunDetails($payrollRunId: ID!) {
  payrollRun(id: $payrollRunId) {
    id
    status
    payPeriod {
      payDate
      period {
        start
        end
      }
    }
    workerPayrollRuns {
      id
      worker {
        displayName
      }
      ... on WorkerPayrollRunInclusion {
        results {
          totals {
            grossPay
            netPay
            contribution
            payrollCost
          }
        }
      
        elements {
          pay {
            description
            amount
            amountStrategy {
              ... on FixedAmountStrategy {
                amount
              }
              ... on FrequencyBasedStrategy {
                frequency
              }
              ... on RateBasedStrategy {
                multiplier
                rate
                rateUnit
                rateUnitAmount
              }
            }
          }
          deductions {
            amount
            description
          }
          timeOffAccrued {
            typeId
            money {
              amount
            }
            time {
              amount
            }
            
          }
        }
      }
    }
  }
}

List the payslip PDF documents in a payroll run

query PayrollRunPayslipDocuments($payrollRunId: ID!) {
  payrollRun(id: $payrollRunId) {
    id
    workerPayrollRuns {
      id
      worker {
        displayName
      }
      ... on WorkerPayrollRunInclusion {
        payslip {
          document {
            id
            mediaType
            status
          }
        }
      }
    }
  }
}

List the worker pay groups of an employer

query WorkerPayGroupsList($employerId: ID!) {
  employer(id: $employerId) {
    id
    workerPayGroups {
      id
      name
      paySchedule {
        definition {
          frequency
        }
        nextPeriod {
          payDate
          period {
            start
            end
          }
        }
      }
      workers {
        id
        displayName
      }
    }
  }
}

Mutations

Create a payroll run

This creates a payroll run for a worker pay group (i.e. all workers assigned to the “weekly” schedule), for the period specified.

mutation CreatePayrollRunForPayGroup(
  $input: CalculatePayrollRunFromPayrollInput!
) {
  calculatePayrollRunFromPayroll(input: $input) {
    id
    status
    confirmBy
    payPeriod {
      payDate
      period {
        end
        start
      }
    }
  }
}

Example variables for this:

{
  "input": {
    "workerPayGroupId": "payrl_0e63231f-1264-401a-abea-8be9fb6a8c34",
    "calculatePayrollRunInput": {
      "payPeriodOverride": {
        "startDate": "2022-01-07",
        "endDate": "2022-01-13",
        "payDate": "2022-01-20"
      }
    }
  },
}

Delete a pending (”draft”) payroll run

mutation DeletePendingPayrollRun($deletePayrollRunInput: DeletePayrollRunInput!) {
  deletePayrollRun(input: $deletePayrollRunInput) {
    id
  }
}

Example variables:

{
  "deletePayrollRunInput": {
    "id": "payrl_0e63231f-1264-401a-abea-8be9fb6a8c34"
  },
}

Confirm a payroll run

mutation ConfirmPayrollRun($confirmPayrollRunInput: ConfirmPayrollRunInput!) {
  confirmPayrollRun(input: $confirmPayrollRunInput) {
    id
    status
    totals {
      payrollCost
      toBeDebited
    }
  }
}

Example variables:

{
  "confirmPayrollRunInput": {
    "id": "payrun_6f85c730-cb7a-40fa-984f-9b6271f6a3eb"
  },
}

Get a signed URL for a PDF document

Beware that a signed URL is publicly accessible and thus have a short expiration and should be shared carefully.

mutation GetPayslipPdfDocumentSignedUrl($documentId: ID!) {
  createDocumentLinks(input: {documentIds:[$documentId]}) {
    documentLinks {
      url
      expiresAt
    }
  }
}

Example variables:

{
  "documentId": "doc_00a8f4db-6355-4853-9f59-4211ca02a1b1"
}

Create a worker pay group with weekly schedule

mutation CreateWeeklyWorkerPayGroup($input: CreateWorkerPayGroupInput!) {
  createWorkerPayGroup(input: $input) {
    workerPayGroup {
      id
      name
      paySchedule {
        definition {
          frequency
        }
        nextPeriod {
          payDate
          period {
            start
            end
          }
        }
      }
    }
  }
}

Example variables:

{
  "input": {
    "employerId": "er_76d38aae-fs1a-4341-a011-f1ecde658fe3",
    "name": "Weekly",
    "paySchedule": {
      "weekly": {
        "periodDefinition": {
          "payday": "FRIDAY",
          "periodEndRelativeDays": 7
        },
        "initialPayDate": "2023-06-02",
        "initialPayPeriodEndDate": "2023-05-26"
      }
    },
    "workerIds": []
  }
}