Basic Concepts - Salsa GraphQL API

Welcome to the Salsa GraphQL API! This guide will walk you through some fundamental concepts and key points to help you get started using our API.

What is GraphQL?

GraphQL is a query language for APIs that allows clients to request exactly the data they need. It provides a flexible, powerful way to interact with APIs, ensuring efficient data retrieval and reducing over-fetching.

In Salsa’s case, our GraphQL API powers our embedded components and internal tooling, which means it can embed advanced payroll functionality directly into your applications. For a quick introduction, see the Basic Concepts section below, and you will be ready to play in our Sandbox. If you want to go deeper, we recommend starting with Introduction to GraphQL and How to GraphQL.

Basic Concepts

To get the most out of Salsa’s GraphQL API, it's essential to understand a few key concepts. Below are the building blocks that will help you interact with our API.

Queries

In GraphQL, queries are used to fetch data. A query allows you to ask for specific fields and get exactly what you need in a single request. Here's an example of a basic query to retrieve payroll run data:

📘

You can always log into the Salsa Dashboard and copy identifiers to play with the API (e.g., an employer id)

query {
  employer(id: "er_123") {
    id
    legalName
    businessName
  }
}

This query fetches the employer's business name and its legal name by its ID

Mutations

Mutations in GraphQL are used to modify data, such as creating or updating records. For example, you can use a mutation to create an address for an employer. An Employer Address can be flagged as a work location, filing address (legal address), or mailing address representing a principal address for the employer.

mutation CreateEmployerAddress {
  createEmployerAddress(input: {
    employerId: "er_200010001",
    employerAddressInput: {
      address: {
        addressLine1: "6834 Hollywood Blvd",
        addressLine2: "null",
        administrativeArea: "CA",
        country: "US",
        locality: "Los Angeles",
        postalCode: "90028"
      },
      isWorkLocation: true,
      name: "Address that is work-loctaion"
    },
    setAsEmployerDefaultWorkLocation: true,
    setAsEmployerFilingAddress: false,
    setAsEmployerMailingAddress: false
  }) {
    employerAddress {
      id
      isWorkLocation
      address {
        addressLine1
      }
      isEmployerFilingAddress
      isWorkLocation
    }
  }
}

This mutation adds a new default work location to the employer. It means any worker without a work location will be assigned to it. After the input for this mutation, we are querying the id of the object, and the fields isWorkLocation, addressLine1, and the booleans isEmployerFilingAddress, isWorkLocation

Variables

GraphQL supports the use of variables to pass dynamic values into queries and mutations. This allows you to reuse queries with different inputs, making your requests more flexible.

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

In this example, the $employerId variable can be passed dynamically when executing the query.

Error Handling

Errors in GraphQL are returned within the errors field of the response, allowing you to handle them gracefully. For example, if you request data that doesn’t exist, you'll receive an error message like this:

{
  "errors": [
    {
      "message": "er_00001 not found",
      "path": [
        "employer"
      ],
      "extensions": {
        "traceId": "9076530f39a1113e2f6915f9de5e5d56",
        "errorType": "NOT_FOUND",
        "debugInfo": {
          "argumentValues": {
            "id": "er_100101"
          }
        }
      }
    }
  ],
  "data": null
}

In this example, we tried to query employer information using the id er_00001. The data field is null, and the errors field is populated.

Schema and Types

To understand the queries and mutations available in a GraphQL API, what they do, and what they return, check out its schema. The schema outlines and documents all the types in the API. This works because GraphQL APIs are strongly typed, covering queries, mutations, their inputs, and outputs.

The easiest way to discover a GraphQL API is by using an API Explorer.

Conclusion

The Salsa GraphQL API provides a flexible and efficient way to access payroll and related data. By understanding queries, mutations, and other core concepts, you can build powerful integrations tailored to your needs. Make sure to authenticate your requests and be mindful of rate limits.

For more details, please refer to the full GraphQL API documentation or contact our team for support.

Happy coding!