PHP SDK

The PHP SDK wraps the customer API with Guzzle and exposes each resource as a service on Seventhings\Client. See the SDKs overview for shared concepts and common workflows for side-by-side examples.

• Repository: github.com/SeventhingsCompany/customer-api-php
• Requires PHP 8.5 or newer.
• Runtime dependency: guzzlehttp/guzzle ^7.0.

Installation

The package is installed from GitHub, so add it as a VCS repository in your composer.json first:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "git@github.com:SeventhingsCompany/customer-api-php.git"
        }
    ]
}

Then install:

composer require seventhings/customer-api-php

Creating a client

Client has a private constructor. Create it through one of the named static factories. Each takes your instance URL, and the SDK appends /customer-api/v1 for you.

use Seventhings\Client;

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

$client = Client::withCredentials(
    'https://your-instance.seventhings.com',
    'user@example.com',
    'password',
    'your-client-id',
);

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

$client = Client::withToken(
    'https://your-instance.seventhings.com',
    'access-token',
);

Use manual login when you want to control when the token is fetched:

$client = Client::withToken('https://your-instance.seventhings.com', '');

$token = $client->auth->login('user@example.com', 'password', 'your-client-id');
$client->setToken($token->accessToken);

Related auth methods live on $client->auth: refresh($refreshToken), loginSSO($provider, $authCode, $clientId, $appTarget), revokeTokens(), and ping(). After refreshing, call $client->setToken($refreshed->accessToken).

Service properties

Resources are exposed as sub-services:

Service	Purpose
$client->objects	Assets/objects, archive/unarchive, file attachments
$client->rooms	Rooms and room counts
$client->locations	Locations and location counts
$client->persons	Person list/get/create/update/delete and create-user
$client->users	User list/get by UUID/get by numeric ID
$client->files	Upload, metadata, data, and thumbnails
$client->tasks	Task list/create/get/update/status/delete
$client->rentals	Rental-case list/create/get/update/delete
$client->fieldDefinitions	Template field definition list/get/create/update
$client->circularityHub	CircularityHub suggestions, items, orders

Objects, rooms, locations, and persons take plain array payloads because their fields are instance-specific. Tasks, rental cases, field definitions, users, files, and CircularityHub orders use readonly model classes and backed enums under Seventhings\Models.

Listing and filtering

Use ListOptions for objects, rooms, locations, rental cases, and CircularityHub list endpoints.

use Seventhings\Models\FilterEntry;
use Seventhings\Models\ListOptions;
use Seventhings\Models\Enums\FilterOperator;
use Seventhings\Models\Enums\SortDirection;

$options = new ListOptions(
    page: 1,
    perPage: 50,
    sort: ['updated_at' => SortDirection::Desc],
    filters: [
        new FilterEntry('inventory_name', FilterOperator::Like, ['Laptop']),
    ],
);

$objects = $client->objects->list($options);

Users, persons, and tasks have dedicated option classes because their API query parameters differ:

use Seventhings\Models\TaskListOptions;
use Seventhings\Models\UserListOptions;
use Seventhings\Models\Enums\TaskStatus;
use Seventhings\Models\Enums\UserSortBy;
use Seventhings\Models\Enums\UserSortOrder;

$users = $client->users->list(new UserListOptions(
    page: 1,
    perPage: 50,
    sortBy: UserSortBy::Email,
    order: UserSortOrder::Asc,
));

$tasks = $client->tasks->list(new TaskListOptions(
    status: TaskStatus::Open,
));

Pagination is manual in PHP. Advance page until the API returns fewer records than perPage, or use the corresponding count() method when the resource provides one.

$page = 1;
$perPage = 100;

do {
    $items = $client->objects->list(new ListOptions(
        page: $page,
        perPage: $perPage,
    ));

    foreach ($items as $item) {
        // process each item
    }

    $page++;
} while (count($items) === $perPage);

Error handling

The SDK throws on failure. Any HTTP response with status code 400 or higher throws an ApiException. Connection-level failures throw a NetworkException. Both extend \RuntimeException.

use Seventhings\Models\ApiException;
use Seventhings\Models\NetworkException;

try {
    $objects = $client->objects->list();
} catch (ApiException $e) {
    if ($e->isStatusCode(401)) {
        // refresh the token, set it on the client, then retry
    }

    // $e->statusCode, $e->status, and $e->body expose the API response.
    throw $e;
} catch (NetworkException $e) {
    // The original Guzzle exception is available as $e->getPrevious().
    throw $e;
}