Skip to main content

Python Client SDK Generated by Speakeasy.

Project description

gusto

Developer-friendly & type-safe Python SDK specifically catered to leverage gusto API.

Summary

Gusto API: Welcome to Gusto's Embedded Payroll API documentation!

Table of Contents

SDK Installation

[!NOTE] Python version upgrade policy

Once a Python version reaches its official end of life date, a 3-month grace period is provided for users to upgrade. Following this grace period, the minimum python version supported in the SDK will be updated.

The SDK can be installed with either pip or poetry package managers.

PIP

PIP is the default package installer for Python, enabling easy installation and management of packages from PyPI via the command line.

pip install gusto_embedded

Poetry

Poetry is a modern tool that simplifies dependency management and package publishing by using a single pyproject.toml file to handle project metadata and dependencies.

poetry add gusto_embedded

Shell and script usage with uv

You can use this SDK in a Python shell with uv and the uvx command that comes with it like so:

uvx --from gusto_embedded python

It's also possible to write a standalone Python script without needing to set up a whole project like so:

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.9"
# dependencies = [
#     "gusto_embedded",
# ]
# ///

from gusto_embedded import Gusto

sdk = Gusto(
  # SDK arguments
)

# Rest of script here...

Once that is saved to a file, you can run it with uv run script.py where script.py can be replaced with the actual file name.

IDE Support

PyCharm

Generally, the SDK will work well with most IDEs out of the box. However, when using PyCharm, you can enjoy much better integration with Pydantic by installing an additional plugin.

Example Usage

Example

# Synchronous Example
from gusto_embedded import Gusto
import os

auth_token = os.getenv("GUSTO_COMPANY_ACCESS_AUTH", None)
if auth_token is None:
	raise ValueError("GUSTO_COMPANY_ACCESS_AUTH is not set")

with Gusto(company_access_auth=auth_token) as gusto:
    res = gusto.introspection.get_info()

    # Handle response
    print(res)

The same SDK client can also be used to make asychronous requests by importing asyncio.

# Asynchronous Example
import asyncio
from gusto_embedded import Gusto
import os

async def main():
  auth_token = os.getenv("GUSTO_COMPANY_ACCESS_AUTH", None)
  if auth_token is None:
    raise ValueError("GUSTO_COMPANY_ACCESS_AUTH is not set")

  async with Gusto(company_access_auth=auth_token) as gusto:
      res = gusto.introspection.get_info_async()

      # Handle response
      print(res)

asyncio.run(main())

Common workflows

A common workflow, as documented in our docs, is to create a new partner managed company. In this section we will illustrate using a system access token to create a partner managed company. Then we will use the returned company access token for subsequent requests. We'll do this in the following steps.

  1. Create a Partner Managed Company
  2. View and Accept Terms of Service
  3. Create a Company Location
# Synchronous Example
from gusto_embedded import Gusto, PostV1PartnerManagedCompaniesSecurity
import os

system_auth_token = os.getenv("GUSTO_SYSTEM_ACCESS_AUTH", None)
if system_auth_token is None:
	raise ValueError("GUSTO_SYSTEM_ACCESS_AUTH is not set")

security = PostV1PartnerManagedCompaniesSecurity(system_access_auth=system_auth_token)
system_gusto = Gusto()
partner_managed_company_res = system_gusto.companies.create_partner_managed(
  security=security,
  user={
    "first_name": "Frank",
    "last_name": "Ocean",
    "email": "frank@example.com",
    "phone": "2345558899",
  },
  company={
      "name": "Frank's Ocean, LLC",
      "trade_name": "Frank’s Ocean",
      "ein": "123432989",
      "contractor_only": False,
  }
)

company_access_token = partner_managed_company_res.access_token
company_refresh_token = partner_managed_company_res.refresh_token
company_uuid = partner_managed_company_res.company_uuid

with Gusto(company_access_auth=company_access_token) as gusto:
    # Get company admin
    company_res = gusto.companies.get(company_id=company_uuid)
    primary_admin = company_res.primary_payroll_admin

    # Accept terms of service
    terms_of_service_res = gusto.companies.accept_terms_of_service(
      company_uuid=company_uuid,
      email=primary_admin.email,
      ip_address="...",
      external_user_id="..."
    )

    # Create a company location
    location_res = gusto.locations.create(
      company_id=company_uuid,
      phone_number="8009360383",
      street_1="425 2nd Street",
      city="San Francisco",
      state="CA",
      zip_code="94107",
      street_2="Suite 602"
    )

Authentication

Per-Client Security Schemes

This SDK supports the following security scheme globally:

Name Type Scheme Environment Variable
company_access_auth http HTTP Bearer GUSTO_COMPANY_ACCESS_AUTH

To authenticate with the API the company_access_auth parameter must be set when initializing the SDK client instance. For example:

from gusto_embedded import Gusto
import os


with Gusto(
    company_access_auth=os.getenv("GUSTO_COMPANY_ACCESS_AUTH", ""),
) as gusto:

    res = gusto.introspection.get_info()

    # Handle response
    print(res)

Per-Operation Security Schemes

Some operations in this SDK require the security scheme to be specified at the request level. For example:

import gusto_embedded
from gusto_embedded import Gusto
import os


with Gusto() as gusto:

    res = gusto.companies.create_partner_managed(security=gusto_embedded.PostV1PartnerManagedCompaniesSecurity(
        system_access_auth=os.getenv("GUSTO_SYSTEM_ACCESS_AUTH", ""),
    ), user={
        "first_name": "Frank",
        "last_name": "Ocean",
        "email": "frank@example.com",
        "phone": "2345558899",
    }, company={
        "name": "Frank's Ocean, LLC",
        "trade_name": "Frank’s Ocean",
        "ein": "123456789",
        "contractor_only": False,
    })

    # Handle response
    print(res)

Available Resources and Operations

Available methods

ach_transactions

  • get_all - Get all ACH transactions for a company

bank_accounts

  • create - Create a company bank account
  • get - Get all company bank accounts
  • verify - Verify a company bank account
  • create_from_plaid_token - Create a bank account from a plaid processor token

companies

companies.suspensions

  • get - Get suspensions for this company
  • suspend - Suspend a company's account

company_attachment

  • get_download_url - Get a temporary url to download the Company Attachment file

company_attachments

  • get_details - Get Company Attachment Details
  • get_list - Get List of Company Attachments
  • create - Create Company Attachment and Upload File

company_benefits

company_forms

  • get_all - Get all company forms
  • get - Get a company form
  • get_pdf - Get a company form pdf
  • sign - Sign a company form

contractor_documents

  • get_all - Get all contractor documents
  • get - Get a contractor document
  • get_pdf - Get the contractor document pdf
  • sign - Sign a contractor document

contractor_forms

  • list - Get all contractor forms
  • get - Get a contractor form
  • get_pdf - Get the contractor form pdf
  • generate1099 - Generate a 1099 form [DEMO]

contractor_payment_groups

  • create - Create a contractor payment group
  • get_list - Get contractor payment groups for a company
  • preview - Preview a contractor payment group
  • get - Fetch a contractor payment group
  • delete - Cancel a contractor payment group
  • fund - Fund a contractor payment group [DEMO]

contractor_payment_method

  • get_bank_accounts - Get all contractor bank accounts
  • get - Get a contractor's payment method
  • update - Update a contractor's payment method

contractor_payment_methods

contractor_payments

  • get_receipt - Get a single contractor payment receipt
  • fund - Fund a contractor payment [DEMO]
  • create - Create a contractor payment
  • list - Get contractor payments for a company
  • get - Get a single contractor payment
  • delete - Cancel a contractor payment
  • preview - Preview contractor payment debit date

contractors

departments

earning_types

  • create - Create a custom earning type
  • list - Get all earning types for a company
  • update - Update an earning type
  • delete - Deactivate an earning type

employee_addresses

employee_benefits

employee_employments

employee_forms

  • generate_w2 - Generate a W2 form [DEMO]
  • list - Get all employee forms
  • get - Get an employee form
  • get_pdf - Get the employee form pdf
  • sign - Sign an employee form

employee_payment_method

employee_payment_methods

employee_tax_setup

employees

events

  • get - Get all events

external_payrolls

federal_tax_details

  • get - Get Federal Tax Details
  • update - Update Federal Tax Details

flows

garnishments

generated_documents

  • get - Get a generated document

historical_employees

  • update - Update a historical employee

holiday_pay_policies

  • get - Get a company's holiday pay policy
  • create - Create a holiday pay policy for a company
  • update - Update a company's holiday pay policy
  • delete - Delete a company's holiday pay policy
  • add_employees - Add employees to a company's holiday pay policy
  • remove_employees - Remove employees from a company's holiday pay policy
  • preview_paid_holidays - Preview a company's paid holidays

i9_verification

industry_selection

  • get - Get a company industry selection
  • update - Update a company industry selection

introspection

invoices

  • get - Retrieve invoicing data for companies

jobs_and_compensations

locations

notifications

pay_schedules

payment_configs

  • get - Get a company's payment configs
  • update - Update a company's payment configs

payrolls

recovery_cases

  • get - Get all recovery cases for a company
  • redebit - Initiate a redebit for a recovery case

reports

signatories

  • create - Create a signatory
  • list - Get all company signatories
  • invite - Invite a signatory
  • update - Update a signatory
  • delete - Delete a signatory

tax_requirements

  • get - Get State Tax Requirements
  • update_state - Update State Tax Requirements
  • get_all - Get All Tax Requirement States

time_off_policies

webhooks

wire_in_requests

  • get - Get a single Wire In Request
  • submit - Submit a wire in request
  • list - Get all Wire In Requests for a company

File uploads

Certain SDK methods accept file objects as part of a request body or multi-part request. It is possible and typically recommended to upload files as a stream rather than reading the entire contents into memory. This avoids excessive memory consumption and potentially crashing with out-of-memory errors when working with very large files. The following example demonstrates how to attach a file stream to a request.

[!TIP]

For endpoints that handle file uploads bytes arrays can also be used. However, using streams is recommended for large files.

import gusto_embedded
from gusto_embedded import Gusto
import os


with Gusto(
    company_access_auth=os.getenv("GUSTO_COMPANY_ACCESS_AUTH", ""),
) as gusto:

    res = gusto.company_attachments.create(company_id="<id>", document={
        "file_name": "example.file",
        "content": open("example.file", "rb"),
    }, category=gusto_embedded.PostV1CompaniesAttachmentCategory.GEP_NOTICE)

    # Handle response
    print(res)

Retries

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide a RetryConfig object to the call:

from gusto_embedded import Gusto
from gusto_embedded.utils import BackoffStrategy, RetryConfig
import os


with Gusto(
    company_access_auth=os.getenv("GUSTO_COMPANY_ACCESS_AUTH", ""),
) as gusto:

    res = gusto.introspection.get_info(,
        RetryConfig("backoff", BackoffStrategy(1, 50, 1.1, 100), False))

    # Handle response
    print(res)

If you'd like to override the default retry strategy for all operations that support retries, you can use the retry_config optional parameter when initializing the SDK:

from gusto_embedded import Gusto
from gusto_embedded.utils import BackoffStrategy, RetryConfig
import os


with Gusto(
    retry_config=RetryConfig("backoff", BackoffStrategy(1, 50, 1.1, 100), False),
    company_access_auth=os.getenv("GUSTO_COMPANY_ACCESS_AUTH", ""),
) as gusto:

    res = gusto.introspection.get_info()

    # Handle response
    print(res)

Error Handling

Handling errors in this SDK should largely match your expectations. All operations return a response object or raise an exception.

By default, an API error will raise a models.APIError exception, which has the following properties:

Property Type Description
.status_code int The HTTP status code
.message str The error message
.raw_response httpx.Response The raw HTTP response
.body str The response content

When custom error responses are specified for an operation, the SDK may also raise their associated exceptions. You can refer to respective Errors tables in SDK docs for more details on possible exception types for each operation. For example, the create_partner_managed_async method may raise the following exceptions:

Error Type Status Code Content Type
models.UnprocessableEntityErrorObject 422 application/json
models.APIError 4XX, 5XX */*

Example

import gusto_embedded
from gusto_embedded import Gusto, models
import os


with Gusto() as gusto:
    res = None
    try:

        res = gusto.companies.create_partner_managed(security=gusto_embedded.PostV1PartnerManagedCompaniesSecurity(
            system_access_auth=os.getenv("GUSTO_SYSTEM_ACCESS_AUTH", ""),
        ), user={
            "first_name": "Frank",
            "last_name": "Ocean",
            "email": "frank@example.com",
            "phone": "2345558899",
        }, company={
            "name": "Frank's Ocean, LLC",
            "trade_name": "Frank’s Ocean",
            "ein": "123456789",
            "contractor_only": False,
        })

        # Handle response
        print(res)

    except models.UnprocessableEntityErrorObject as e:
        # handle e.data: models.UnprocessableEntityErrorObjectData
        raise(e)
    except models.APIError as e:
        # handle exception
        raise(e)

Server Selection

Select Server by Name

You can override the default server globally by passing a server name to the server: str optional parameter when initializing the SDK client instance. The selected server will then be used as the default on the operations that use it. This table lists the names associated with the available servers:

Name Server Description
demo https://api.gusto-demo.com Demo
prod https://api.gusto.com Prod

Example

from gusto_embedded import Gusto
import os


with Gusto(
    server="prod",
    company_access_auth=os.getenv("GUSTO_COMPANY_ACCESS_AUTH", ""),
) as gusto:

    res = gusto.introspection.get_info()

    # Handle response
    print(res)

Override Server URL Per-Client

The default server can also be overridden globally by passing a URL to the server_url: str optional parameter when initializing the SDK client instance. For example:

from gusto_embedded import Gusto
import os


with Gusto(
    server_url="https://api.gusto-demo.com",
    company_access_auth=os.getenv("GUSTO_COMPANY_ACCESS_AUTH", ""),
) as gusto:

    res = gusto.introspection.get_info()

    # Handle response
    print(res)

Custom HTTP Client

The Python SDK makes API calls using the httpx HTTP library. In order to provide a convenient way to configure timeouts, cookies, proxies, custom headers, and other low-level configuration, you can initialize the SDK client with your own HTTP client instance. Depending on whether you are using the sync or async version of the SDK, you can pass an instance of HttpClient or AsyncHttpClient respectively, which are Protocol's ensuring that the client has the necessary methods to make API calls. This allows you to wrap the client with your own custom logic, such as adding custom headers, logging, or error handling, or you can just pass an instance of httpx.Client or httpx.AsyncClient directly.

For example, you could specify a header for every request that this sdk makes as follows:

from gusto_embedded import Gusto
import httpx

http_client = httpx.Client(headers={"x-custom-header": "someValue"})
s = Gusto(client=http_client)

or you could wrap the client with your own custom logic:

from gusto_embedded import Gusto
from gusto_embedded.httpclient import AsyncHttpClient
import httpx

class CustomClient(AsyncHttpClient):
    client: AsyncHttpClient

    def __init__(self, client: AsyncHttpClient):
        self.client = client

    async def send(
        self,
        request: httpx.Request,
        *,
        stream: bool = False,
        auth: Union[
            httpx._types.AuthTypes, httpx._client.UseClientDefault, None
        ] = httpx.USE_CLIENT_DEFAULT,
        follow_redirects: Union[
            bool, httpx._client.UseClientDefault
        ] = httpx.USE_CLIENT_DEFAULT,
    ) -> httpx.Response:
        request.headers["Client-Level-Header"] = "added by client"

        return await self.client.send(
            request, stream=stream, auth=auth, follow_redirects=follow_redirects
        )

    def build_request(
        self,
        method: str,
        url: httpx._types.URLTypes,
        *,
        content: Optional[httpx._types.RequestContent] = None,
        data: Optional[httpx._types.RequestData] = None,
        files: Optional[httpx._types.RequestFiles] = None,
        json: Optional[Any] = None,
        params: Optional[httpx._types.QueryParamTypes] = None,
        headers: Optional[httpx._types.HeaderTypes] = None,
        cookies: Optional[httpx._types.CookieTypes] = None,
        timeout: Union[
            httpx._types.TimeoutTypes, httpx._client.UseClientDefault
        ] = httpx.USE_CLIENT_DEFAULT,
        extensions: Optional[httpx._types.RequestExtensions] = None,
    ) -> httpx.Request:
        return self.client.build_request(
            method,
            url,
            content=content,
            data=data,
            files=files,
            json=json,
            params=params,
            headers=headers,
            cookies=cookies,
            timeout=timeout,
            extensions=extensions,
        )

s = Gusto(async_client=CustomClient(httpx.AsyncClient()))

Resource Management

The Gusto class implements the context manager protocol and registers a finalizer function to close the underlying sync and async HTTPX clients it uses under the hood. This will close HTTP connections, release memory and free up other resources held by the SDK. In short-lived Python programs and notebooks that make a few SDK method calls, resource management may not be a concern. However, in longer-lived programs, it is beneficial to create a single SDK instance via a context manager and reuse it across the application.

from gusto_embedded import Gusto
import os
def main():

    with Gusto(
        company_access_auth=os.getenv("GUSTO_COMPANY_ACCESS_AUTH", ""),
    ) as gusto:
        # Rest of application here...


# Or when using async:
async def amain():

    async with Gusto(
        company_access_auth=os.getenv("GUSTO_COMPANY_ACCESS_AUTH", ""),
    ) as gusto:
        # Rest of application here...

Debugging

You can setup your SDK to emit debug logs for SDK requests and responses.

You can pass your own logger class directly into your SDK.

from gusto_embedded import Gusto
import logging

logging.basicConfig(level=logging.DEBUG)
s = Gusto(debug_logger=logging.getLogger("gusto_embedded"))

You can also enable a default debug logger by setting an environment variable GUSTO_DEBUG to true.

Development

Maturity

This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.

Contributions

While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.

SDK Created by Speakeasy

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gusto_embedded-0.2.4.tar.gz (284.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

gusto_embedded-0.2.4-py3-none-any.whl (671.1 kB view details)

Uploaded Python 3

File details

Details for the file gusto_embedded-0.2.4.tar.gz.

File metadata

  • Download URL: gusto_embedded-0.2.4.tar.gz
  • Upload date:
  • Size: 284.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.1.2 CPython/3.9.21 Linux/6.8.0-1025-azure

File hashes

Hashes for gusto_embedded-0.2.4.tar.gz
Algorithm Hash digest
SHA256 1aa5ef12557fc038fcb02c8d4faa53cba74730356adfbdbcbe8f5c222c787a55
MD5 d581f48850411f9ce338dd76cb4ab4ae
BLAKE2b-256 68966450dc628390eba6441834e0884563df5fb6b0111c98479d471a45525400

See more details on using hashes here.

File details

Details for the file gusto_embedded-0.2.4-py3-none-any.whl.

File metadata

  • Download URL: gusto_embedded-0.2.4-py3-none-any.whl
  • Upload date:
  • Size: 671.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.1.2 CPython/3.9.21 Linux/6.8.0-1025-azure

File hashes

Hashes for gusto_embedded-0.2.4-py3-none-any.whl
Algorithm Hash digest
SHA256 4694c393b644754857421bcb579961de4a342e8e0214ad0ca68285cb90db0dd8
MD5 530611654d2d2c4d0334a72ec43870de
BLAKE2b-256 e140a52cbf530fea5f521540810d5e97f9ff71f4f5e3f1fd096e4b81b6e7408b

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page