SDKs
seventhings maintains two official client libraries for the customer API:
The SDKs intentionally stay close to the HTTP API. Use these pages for client setup, authentication, common workflows, and language-specific behaviour. Use the API Reference for the authoritative endpoint schemas, response fields, and error codes.
Support matrix
Section titled “Support matrix”| Area | Go SDK | PHP SDK | Notes |
|---|---|---|---|
| Runtime | Go 1.25+, standard library only | PHP 8.5+, Guzzle 7 | Both SDKs append /customer-api/v1 internally. |
| Client creation | client.New, NewWithCredentials, NewWithToken |
Client::withCredentials, Client::withToken |
Both support password login, existing tokens, and manual login. |
| Auth flows | password, refresh token, SSO auth code, revoke | password, refresh token, SSO auth code, revoke | Refresh is explicit; tokens are not refreshed automatically. |
| Resources | Flat methods on *client.Client |
Services on $client, for example $client->objects |
Resource names match the API reference. |
| Schema-free records | map[string]any |
array |
Objects, rooms, locations, and persons use instance-specific field keys. |
| Typed workflows | models.* structs and constants |
readonly models and backed enums | Tasks, rental cases, users, files, field definitions, and CircularityHub orders are typed. |
| Errors | (value, error), API failures as *models.APIError |
exceptions, API failures as ApiException |
Network failures are transport errors in Go and NetworkException in PHP. |
| Pagination | Manual paging plus *All iterators for several list endpoints |
Manual paging | Tasks and files have API-specific list limits; see the language pages. |
Instance URL, not the API path
Section titled “Instance URL, not the API path”Both SDKs take your instance URL:
https://your-instance.seventhings.comDo not pass the full API path. The SDKs append /customer-api/v1 before making
requests.
Authentication model
Section titled “Authentication model”The auth flow matches the Authentication guide: the
same auth_token endpoint, grant types (password, refresh_token,
sso_auth_code), and bearer-token scheme. Each SDK supports three client
creation paths:
- With credentials - pass username, password, and
client_id; the SDK logs in and stores the access token. - With a token - pass an access token you obtained elsewhere.
- Manual login - construct a client, call the login method, then use the returned token.
When refreshing a token, the SDK uses the client_id stored on the client.
Revoking tokens issues DELETE /customer-api/v1/auth_token.
Resource model
Section titled “Resource model”Both SDKs cover the same resource groups:
- Objects, rooms, and locations
- Persons and users
- Files
- Tasks and rental cases
- Field definitions
- CircularityHub
Objects, rooms, locations, and persons are schema-free because their field keys depend on your seventhings instance. The SDKs accept and return maps or arrays for those resources. Use field definitions when you need to discover which custom keys exist for a template.
create calls return the new resource identifier from the response headers.
Most resources use UUID strings. CircularityHub items and orders use integer
IDs.
Listing, filtering, and pagination
Section titled “Listing, filtering, and pagination”Objects, rooms, locations, rental cases, and CircularityHub list calls use the
shared list-options model: page, perPage, sort, and filters. Filters are
encoded as PHP-style deep-object query parameters:
filter[inventory_name][like][]=LaptopAvailable filter operators are eq, neq, gt, gt_or_null, gte,
gte_or_null, lt, lt_or_null, lte, lte_or_null, like, not_like,
in, and nin. Users, persons, and tasks have dedicated list-option types
because their API query parameters differ.
See common workflows for side-by-side examples.
Limitations
Section titled “Limitations”Both SDKs are intentionally thin. They do not currently:
- automatically refresh expired tokens,
- retry failed requests,
- rate-limit requests,
- cache API responses.
PHP pagination is manual. Go provides iterator helpers for several paginated resources, but tasks and files still use their endpoint-specific list behaviour.