SDKs

seventhings maintains four official client libraries for the customer API:

• Go SDK - github.com/SeventhingsCompany/customer-api-go
• PHP SDK - seventhings/customer-api-php
• Python SDK - seventhings-customer-api (import seventhings)
• TypeScript SDK - @seventhingscompany/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.

Start an integration

Not sure which language fits your project? Choose your SDK based on your existing stack, integration goal, deployment environment, and team experience.

Use the AI quickstart for runnable starters in all four languages, shared configuration, and practical integration recipes. The customer-api-quickstart repository includes instructions for AI coding tools, pinned dependencies, a local API reference, and offline checks for the examples.

Support matrix

Area	Go SDK	PHP SDK	Python SDK	TypeScript SDK	Notes
Runtime	Go 1.25+, standard library only	PHP 8.5+, Guzzle 7	Python 3.10+, httpx	Node.js 22+, Bun, Deno, browsers; no dependencies	All SDKs append /customer-api/v1 internally.
Client creation	client.New, NewWithCredentials, NewWithToken	Client::withCredentials, Client::withToken	Client(url, token=...), Client.with_credentials; AsyncClient for asyncio	SeventhingsClient.withCredentials, new SeventhingsClient({ token })	All support password login, existing tokens, and manual login.
Auth flows	password, refresh token, SSO auth code, revoke	password, refresh token, SSO auth code, revoke	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	Services on client, for example client.objects	Services on client, for example client.objects	Resource names match the API reference.
Schema-free records	map[string]any	array	dict plus Fields accessors	Record<string, unknown> plus Fields accessors	Objects, rooms, locations, and persons use instance-specific field keys.
Typed workflows	models.* structs and constants	readonly models and backed enums	frozen dataclasses and str enums	camelCase interfaces and as const 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	exceptions, API failures as APIError	rejected promises, API failures as ApiError	Network failures are transport errors in Go, NetworkException in PHP, and NetworkError in Python and TypeScript.
Pagination	Manual paging plus *All iterators for several list endpoints	Manual paging plus all() generators for several list endpoints	Manual paging plus all() iterators (sync and async) for several list endpoints	Manual paging plus all() async iterators for several list endpoints	Tasks and files have API-specific list limits; see the language pages.

Instance URL, not the API path

All SDKs take your instance URL:

https://your-instance.seventhings.com

Do not pass the full API path. The SDKs append /customer-api/v1 before making requests.

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

All 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

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][]=Laptop

Available 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

All SDKs are intentionally thin. They do not currently:

• automatically refresh expired tokens,
• retry failed requests,
• rate-limit requests,
• cache API responses.

All SDKs provide iterator helpers that walk every page of the regularly paginated resources. Tasks and files still use their endpoint-specific list behaviour.