Go SDK

The Go SDK is a dependency-free wrapper around the customer API. It uses only the Go standard library and exposes resource methods directly on *client.Client. See the SDKs overview for concepts shared with the PHP SDK and common workflows for side-by-side examples.

• Repository: github.com/SeventhingsCompany/customer-api-go
• Requires Go 1.25 or newer.

Installation

go get github.com/SeventhingsCompany/customer-api-go

Creating a client

All constructors live in the client package and take your instance URL. The SDK appends /customer-api/v1 for you.

import (
    "net/http"
    "time"

    "github.com/SeventhingsCompany/customer-api-go/client"
)

Use credentials when your application should log in during client setup:

c, err := client.NewWithCredentials(
    ctx,
    "https://your-instance.seventhings.com",
    "user@example.com",
    "password",
    "your-client-id",
)
if err != nil {
    // handle login failure
}

Use an existing token when another part of your application already completed the auth flow:

c := client.NewWithToken(
    "https://your-instance.seventhings.com",
    "access-token",
    client.WithClientID("your-client-id"),
)

Use client.New for manual login or custom transport setup:

httpClient := &http.Client{Timeout: 30 * time.Second}
c := client.New(
    "https://your-instance.seventhings.com",
    client.WithHTTPClient(httpClient),
    client.WithClientID("your-client-id"),
)

tok, err := c.Login(ctx, "user@example.com", "password", "your-client-id")
if err != nil {
    // handle login failure
}
// Login stores tok.AccessToken on the client.

Related auth methods are c.Refresh(ctx, refreshToken), c.LoginSSO(ctx, provider, authCode, clientID, appTarget), and c.RevokeTokens(ctx). You can read or replace the current bearer token with c.Token() and c.SetToken(token). c.ClientID() returns the stored OAuth client ID.

Resource methods

Resource methods hang directly off Client, and every method takes a context.Context as its first argument.

objects, err := c.ObjectsList(ctx, nil)
uuid, err := c.ObjectCreate(ctx, map[string]any{
    "inventory_name": "MacBook Pro 16",
})
object, err := c.ObjectGet(ctx, uuid)
err = c.ObjectPatch(ctx, uuid, map[string]any{"inventory_name": "MacBook Pro 16 M4"})
err = c.ObjectDelete(ctx, uuid)

Objects, rooms, locations, and persons use map[string]any because their field keys are configured per instance. Tasks, rental cases, users, files, field definitions, and CircularityHub orders use typed values in the models package. Optional request fields are represented as pointers.

Listing and filtering

Use models.ListOptions for objects, rooms, locations, rental cases, and CircularityHub list endpoints. You can build it as a struct literal or with the fluent helpers.

import "github.com/SeventhingsCompany/customer-api-go/models"

opts := models.NewListOptions().
    WithPage(1).
    WithPerPage(50).
    SortBy("updated_at", models.SortDESC).
    Where(models.Like("inventory_name", "Laptop")).
    Where(models.In("status", "active", "pending"))

objects, err := c.ObjectsList(ctx, opts)

Users and persons have dedicated option types:

users, err := c.UsersList(ctx,
    models.NewUserListOptions().
        WithPerPage(50).
        WithSort(models.UserSortByEmail, models.UserSortOrderAsc),
)

persons, err := c.PersonsList(ctx,
    models.NewPersonListOptions().
        WithPerPage(50).
        WithSort("last_name", models.UserSortOrderAsc),
)

Tasks use models.TaskListOptions; the API returns up to 10,000 matching tasks instead of using the shared page/per-page query model.

Pagination iterators

For resources that use regular page/per-page pagination, the Go SDK provides iterator helpers that walk all pages for you:

for object, err := range c.ObjectsAll(ctx, models.NewListOptions().WithPerPage(100)) {
    if err != nil {
        return err
    }
    _ = object["inventory_name"]
}

Available iterators are ObjectsAll, RoomsAll, LocationsAll, CircularityHubItemsAll, RentalCasesAll, PersonsAll, and UsersAll. opts.Page is ignored because the iterator controls paging. opts.PerPage sets the page size and defaults to 100.

Field definitions and mandatory fields

Use field definitions to discover instance-specific fields for assets, rooms, and persons:

defs, err := c.FieldDefinitionsList(ctx, models.AssetTrackingTemplateAsset)

The Go SDK also has helpers for required fields. System-managed keys are filtered out because the server fills them in.

fields := map[string]any{
    "inventory_name": "MacBook Pro 16",
}

missing, err := c.MissingMandatoryFields(ctx, models.AssetTrackingTemplateAsset, fields)
if err != nil {
    return err
}
if len(missing) > 0 {
    // prompt for the missing field keys before calling ObjectCreate
}

Error handling

Methods follow the idiomatic (value, error) convention. Any HTTP response with status code 400 or higher is returned as a *models.APIError, which you can inspect with errors.As:

objects, err := c.ObjectsList(ctx, nil)
if err != nil {
    var apiErr *models.APIError
    if errors.As(err, &apiErr) {
        if apiErr.IsStatusCode(401) {
            // refresh the token, set it on the client, then retry
        }
    }
    return err
}

Connection-level failures are returned as the underlying transport error, not as APIError.