seventhings Python SDK
Python client for the seventhings Customer API (/customer-api/v1). It offers the same features as the Go and PHP SDKs (v1.5.0) and comes with both a synchronous and an asynchronous client.
Targets API description v0.20143_c5f8b54b3_20261005.
- Python 3.10+
- The only runtime dependency is
httpx - Fully typed (
py.typed), with dataclass models
Installation
pip install seventhings-customer-api
# or
uv add seventhings-customer-api
The import name is seventhings.
Quick Start
Password authentication
from seventhings import Client
with Client.with_credentials(
"https://example.seventhings.com", "user@example.com", "password", "client-id"
) as client:
print(client.objects.count())
Pre-existing token
client = Client("https://example.seventhings.com", token="my-jwt-token")
Manual login and refresh
client = Client("https://example.seventhings.com")
tok = client.auth.login("user@example.com", "password", "client-id") # stores the access token
tok = client.auth.refresh(tok.refresh_token) # reuses the client ID from login
client.auth.revoke_tokens()
SSO authentication
from seventhings.models import SSOAppTarget, SSOProviderName
tok = client.auth.login_sso(SSOProviderName.AZURE, auth_code, "client-id", SSOAppTarget.WEB)
Async
AsyncClient has the same API as Client, except that its methods are coroutines, the all() iterators are async iterators, and you close it with aclose() or async with:
from seventhings import AsyncClient
async with await AsyncClient.with_credentials(url, user, password, client_id) as client:
obj = await client.objects.get(uuid)
async for room in client.rooms.all():
print(room.name)
Configuration
Client(
base_url, # instance URL; "/customer-api/v1" is appended
token=None, # bearer token
client_id=None, # OAuth client ID used by auth.refresh()
http_client=None, # your own httpx.Client / httpx.AsyncClient (not closed by the SDK)
timeout=30.0, # seconds; None disables the timeout
rate_limit=200, # requests per minute; 0 or None disables throttling
)
Rate limiting
Each client sends at most 200 requests per minute by default, evenly spaced (one every 300 ms) without bursts. The first request goes out immediately. Authentication, uploads and downloads count towards the same limit. Waiting requests are admitted one at a time; with AsyncClient they are admitted in arrival order, and a cancelled request leaves the queue without using up a slot. Separate client instances have separate limits.
Client(base_url, rate_limit=100) # override
Client(base_url, rate_limit=0) # disable
with_credentials() accepts rate_limit too. The SDK does not retry HTTP 429 answers itself (see Retry-After).
Usage
Ping
ping = client.ping() # unauthenticated
print(ping.status) # "OK"
Objects
Objects have a schema that differs per tenant, so they are plain dicts. The all() iterator yields Fields, a dict with typed accessors.
from seventhings.models import ListOptions, SortDirection, like
uuid = client.objects.create({"inventory_name": "Laptop", "barcode": "INV-001"})
obj = client.objects.get(uuid)
obj = client.objects.get_by_barcode("INV-001") # archived objects included
client.objects.patch(uuid, {"inventory_name": "Laptop (IT)"})
client.objects.archive(uuid)
client.objects.unarchive(uuid)
client.objects.delete(uuid)
page = client.objects.list(ListOptions(page=1, per_page=50).where(like("inventory_name", "Laptop")))
total = client.objects.count()
for obj in client.objects.all(ListOptions(per_page=100)): # walks every page
print(obj.uuid, obj.get_str("inventory_name"), obj.get_time("updated_at"))
To attach a file you have already uploaded to an attachment field, use add_files. It returns the raw Response, because the API can answer 207 Multi-Status:
from seventhings.models import FileAttachment
resp = client.objects.add_files(uuid, [FileAttachment("documents", file_uuid)])
client.objects.remove_files(uuid, [FileAttachment("documents", file_uuid)])
History
Objects, rooms, locations, persons, tasks and rental cases all have a paged history. The API defaults to page 1 with 50 entries per page (maximum 200).
from seventhings.models import HistoryListOptions
hist = client.persons.history(person_uuid, HistoryListOptions(page=1, per_page=20))
for entry in hist.items:
print(entry.occurred_at, entry.event_name, entry.details) # details is a JSON string
if hist.page * hist.per_page < hist.total:
... # fetch the next page
Object history entries are plain dicts, because their shape depends on type (asset, task, rental_case or object_merge).
PDF reports
from seventhings.models import CreateReport
templates = client.reports.list_templates()
pdf: bytes = client.reports.create(CreateReport(templates[0].uuid, [obj_uuid]))
Files
with open("photo.jpg", "rb") as fh:
file_uuid = client.files.upload("photo.jpg", fh) # or pass bytes
meta = client.files.get(file_uuid)
data = client.files.get_data(file_uuid)
thumb = client.files.get_thumbnail(file_uuid) # 150 x 100
thumb = client.files.get_thumbnail(file_uuid, width=320, height=240) # 1-2000 px each
recent = client.files.list() # the most recent files (max 20)
A custom thumbnail size keeps the aspect ratio. The API creates and caches each new size, and once a file has a certain number of sizes it answers further new sizes with 422.
Tasks
from seventhings.models import (
CreateTask,
TaskListOptions,
TaskReferenceInput,
TaskStatus,
TimeInterval,
TimeIntervalUnit,
UpdateTask,
)
task_uuid = client.tasks.create(
CreateTask(
title="Inspect",
deadline="2026-12-31",
assignees=[user_uuid],
references=[TaskReferenceInput(obj_uuid)],
reminders=[TimeInterval(TimeIntervalUnit.DAYS, 1)],
)
)
tasks = client.tasks.list(TaskListOptions(status=TaskStatus.OPEN))
client.tasks.update_status(task_uuid, TaskStatus.CLOSED)
client.tasks.update(task_uuid, UpdateTask(title="Inspect again", assignees=[user_uuid])) # PUT
client.tasks.delete(task_uuid)
reminders=None (the default) leaves reminders out of the request, reminders=[] disables them, and a zero interval (TimeInterval(TimeIntervalUnit.DAYS, 0)) reminds on the deadline.
Rental cases
from seventhings.models import (
CreateRentalCase,
RentalCaseReferenceInput,
RentalCaseRenter,
RenterType,
UpdateRentalCase,
)
rental_uuid = client.rentals.create(
CreateRentalCase(
title="Laptop loan",
renter=RentalCaseRenter(RenterType.USER, user_uuid),
references=[RentalCaseReferenceInput(obj_uuid)],
issue_date="2026-01-01 09:00:00",
due_date="2026-01-08 09:00:00",
responsible_user_uuid=user_uuid,
)
)
rental = client.rentals.get(rental_uuid)
for rc in client.rentals.all():
print(rc.title, rc.status)
# Updates are full replacements (PUT): send the complete desired state.
client.rentals.update(
rental_uuid,
UpdateRentalCase(
title="Laptop loan",
renter=RentalCaseRenter(RenterType.USER, user_uuid),
references=[RentalCaseReferenceInput(obj_uuid)],
issue_date="2026-01-01 09:00:00",
due_date="2026-01-08 09:00:00",
responsible_user_uuid=user_uuid,
comment="Updated pickup instructions",
),
)
Timed rentals: set is_full_day=False with issue_at and due_at (RFC 3339 timestamps; the return time is exclusive). Leave all three as None to let the API infer the kind on create, or to keep the stored kind on update. Responses always include is_full_day, issue_at and due_at.
create and update need a renter. The API description marks it optional, but the server currently fails with HTTP 500 when it is missing, so the SDK raises RentalCaseRenterRequiredError before sending the request.
Rooms and locations
These work like objects. The difference is that patch returns the updated record (or None if the API sends no body). Records are the flat field maps the API returns; no {uuid, fields} envelope is unwrapped.
loc_uuid = client.locations.create({"name": "HQ"})
room_uuid = client.rooms.create({"name": "Office 1", "building_id": 1})
room = client.rooms.patch(room_uuid, {"name": "Office 1a"})
Users and persons
from seventhings.models import PersonListOptions, UserListOptions, UserSortBy, UserSortOrder
users = client.users.list(UserListOptions(sort_by=UserSortBy.EMAIL, order=UserSortOrder.ASC))
me = client.users.get_by_id(tok.user_id)
person_uuid = client.persons.create({"email": "ada@example.com", "first_name": "Ada"})
person = client.persons.get(person_uuid)
print(person.email, person.fields.get_str("cost_center")) # every field is in person.fields
client.persons.patch(person_uuid, {"department": "IT"})
for p in client.persons.all(PersonListOptions(sort_by="last_name")):
...
Person records are flat field maps. person.uuid comes from person_uuid only, and person.fields holds the whole map, including custom fields and attachments.
Product catalog
Needs the product catalog feature and the matching rights on the instance.
from seventhings.models import ListOptions
page = client.catalog_items.list(ListOptions(page=1, per_page=25))
# page.items, page.page, page.per_page, page.total, page.sort
item = client.catalog_items.get(item_uuid)
item_uuid = client.catalog_items.create({"catalog_object_inventory_name": "Laptop"})
client.catalog_items.update(item_uuid, item.fields)
client.catalog_items.delete(item_uuid)
for item in client.catalog_items.all():
...
update is a PUT that replaces every field: fields you leave out are emptied. Server-maintained fields are ignored, so a field map you read can be sent back unchanged. Object field keys start with catalog_object_; catalog metadata keys have no prefix. Updating or deleting a catalog item leaves the objects created from it untouched.
Field definitions
from seventhings.models import AssetTrackingTemplate
defs = client.field_definitions.list(AssetTrackingTemplate.ASSET)
required = client.field_definitions.mandatory(AssetTrackingTemplate.ASSET)
missing = client.field_definitions.missing_mandatory_fields(AssetTrackingTemplate.ASSET, payload)
options = defs[0].field_type.allowed_values() # dropdown values
Circularity Hub
Items and orders in the Circularity Hub use integer IDs.
from seventhings.models import AddObjectEntry, FilterObject, FilterOperator
suggestions = client.circularity_hub.suggest_category(
FilterObject(filter={"uuid": {FilterOperator.IN: [obj_uuid]}})
) # None when there are no suggestions
client.circularity_hub.add_objects({obj_uuid: AddObjectEntry("chairs", "25.00")})
for item in client.circularity_hub.all_items():
...
order_id = client.circularity_hub.create_order([1, 2])
order = client.circularity_hub.get_order(order_id)
Raw requests
request() covers anything the SDK doesn't wrap:
resp = client.request("GET", "objects", query="page=1&per_page=5")
print(resp.status_code, resp.json())
Filtering and sorting
from seventhings.models import ListOptions, SortDirection, gte, in_, like
opts = (
ListOptions(page=1, per_page=50)
.sort_by("name", SortDirection.ASC)
.sort_by("created_at", SortDirection.DESC)
.where(like("name", "Laptop"), in_("status", "active", "pending"), gte("price", "100"))
)
This produces the following query string (brackets are sent literally and only the values are escaped):
page=1&per_page=50&sort[name]=ASC&sort[created_at]=DESC&filter[name][like][]=Laptop&filter[status][in][]=active&filter[status][in][]=pending&filter[price][gte]=100
| Operator | Helper | Description |
|---|---|---|
eq |
eq |
Equal |
neq |
neq |
Not equal |
gt, gte |
gt, gte |
Greater than (or equal) |
gt_or_null, gte_or_null |
gt_or_null, gte_or_null |
Greater than (or equal), including null |
lt, lte |
lt, lte |
Less than (or equal) |
lt_or_null, lte_or_null |
lt_or_null, lte_or_null |
Less than (or equal), including null |
like |
like |
Contains substring (multi-value) |
not_like |
not_like |
Does not contain substring (multi-value) |
in |
in_ |
Value in set (multi-value) |
nin |
nin |
Value not in set (multi-value) |
Error handling
Every exception derives from seventhings.SeventhingsError:
| Exception | When |
|---|---|
APIError |
The API returned a status of 400 or higher |
NetworkError |
Connection failure, timeout or another transport error (wraps the httpx exception) |
DecodeError |
The response could not be decoded, e.g. invalid JSON or a missing Location header |
RentalCaseRenterRequiredError |
A rental case create/update has no renter (raised before any request) |
from seventhings import APIError
try:
client.objects.get("nonexistent")
except APIError as err:
print(err.status_code, err.body)
if err.is_not_found: # also: is_unauthorized, is_forbidden, is_conflict,
... # is_rate_limited, is_server_error, is_feature_inactive
is_feature_inactive is true when the endpoint's module (for example rentals) is not active on the instance. err.headers holds a copy of the response headers; they are not part of the exception message.
Retry-After
APIError.retry_after(now=None) parses the standard Retry-After header, given either as seconds or as an HTTP date, and returns a timedelta:
from datetime import datetime, timezone
try:
client.objects.list()
except APIError as err:
if err.is_rate_limited:
now = datetime.now(timezone.utc)
delay = err.retry_after(now)
if delay is not None:
retry_at = now + delay # requeue the operation no earlier than this
else:
... # header missing or invalid: use your own bounded backoff
A date in the past gives a zero delay. A missing, repeated or invalid header gives None. The helper also works for other statuses that send the header (for example 503). It does not sleep or retry: the SDK sends each request once, and your application decides whether a retry is safe.
Pagination
list() methods fetch a single page. The all() iterators on objects, rooms, locations, rentals, users, persons, catalog items and Circularity Hub items (all_items()) walk through every page:
- they ignore
opts.page; - they use
opts.per_pageas the page size, defaulting to 100; - they stop at the first page that is shorter than the page size.
Tasks and files have no paging. History is paged manually.
Scope and limitations
- No automatic token refresh. Call
client.auth.refresh(refresh_token)yourself when the access token expires. - No automatic retry. Use
APIError.retry_after()and your own retry policy, or pass anhttpxclient that uses a retrying transport. Requests are throttled to 200 per minute per client by default (see Rate limiting). - Dates are strings, as the API sends them (
Y-m-d H:i:s, UTC).Fields.get_time()parses them. - Unknown enum values from newer API versions are kept as plain strings rather than raising an error.
Development
uv sync
uv run pytest # unit tests; each one runs against both Client and AsyncClient
uv run ruff check . && uv run ruff format --check .
uv run mypy # strict
uv run python scripts/unasync.py # regenerate the sync client after editing _async/client.py
The synchronous client (src/seventhings/_sync/client.py) is generated from src/seventhings/_async/client.py, so edit the async file and regenerate. CI runs scripts/unasync.py --check. Request building and response decoding live in src/seventhings/_operations.py, which does no I/O and is shared by both clients.
Integration tests
The integration tests run against a live instance and create, then delete, their own test data. Use a test instance: some tests create users or field definitions that cannot be deleted, the Circularity Hub order tests check out existing items, and uploaded files stay because the API has no file-delete endpoint.
cp .env.example .env # fill in SEVENTHINGS_BASE_URL/USERNAME/PASSWORD/CLIENT_ID
scripts/run-integration.sh # or: uv run pytest -m integration
scripts/run-integration.sh -k person # forward pytest args
examples/demo/ walks through the SDK end to end and uses the same environment variables.
License
MIT
Metadata
Release files for seventhings-customer-api 1.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| seventhings_customer_api-1.5.0.tar.gz | 107.4 kB | With provenance | Details for seventhings_customer_api-1.5.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| seventhings_customer_api-1.5.0-py3-none-any.whl | Python 3 | none | any | Details for seventhings_customer_api-1.5.0-py3-none-any.whl |
Total release size: 154.4 kB
Release files / seventhings_customer_api-1.5.0.tar.gz
| Download URL | seventhings_customer_api-1.5.0.tar.gz |
|---|---|
| Size | 107.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d1a8a087e4be21986e518cc6f38cee0611e21516e5874c9bb8f785031068c32c
|
|
BLAKE2b-256 checksum How to use checksums |
de78167695e35063e78cad5dd464a3e207b028442f8410ca883ecb1038bf7194
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logRelease files / seventhings_customer_api-1.5.0-py3-none-any.whl
| Download URL | seventhings_customer_api-1.5.0-py3-none-any.whl |
|---|---|
| Size | 47.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4c97bc7643ec7b3fedee4318e5fdcbddb988838cfba3c9f238abf49e9baeaa05
|
|
BLAKE2b-256 checksum How to use checksums |
10722483ad3e7f14a19d6900a84a6afd51bbb691a40c3bcd6a5370335965a86e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logSecurity for seventhings-customer-api 1.5.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for seventhings_customer_api-1.5.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.