AI quickstart

The customer-api-quickstart repository is a starting point for building integrations with the Go, PHP, Python, or TypeScript SDK. It includes runnable examples, pinned dependencies, and instructions that help AI coding tools use the correct SDK interfaces.

Clone and choose a language

If you are unsure which starter to use, read Choose your SDK for task-based recommendations and tradeoffs. Prefer the language your team already maintains when adding an integration to an existing application.

git clone https://github.com/seventhingsCompany/customer-api-quickstart.git
cd customer-api-quickstart

Open the repository in your editor or AI coding tool. You only need the runtime and package manager for the language you choose:

Starter	Requirements	Setup instructions
TypeScript	Node.js 22+, npm	TypeScript starter
Python	Python 3.10+	Python starter
Go	Go 1.25+	Go starter
PHP	PHP 8.5+, Composer 2	PHP starter

Configure your instance

Copy .env.example to .env in the repository root and set:

• SEVENTHINGS_INSTANCE_URL — your instance root, such as https://your-instance.seventhings.com, without /customer-api/v1.
• SEVENTHINGS_TOKEN — an existing bearer token; or leave it empty and set SEVENTHINGS_USERNAME, SEVENTHINGS_PASSWORD, and SEVENTHINGS_CLIENT_ID.

Export these variables into the terminal where you run the starter. The programs read environment variables; .env is not loaded automatically. The repository’s README includes shell-specific instructions. See Authentication for the API’s login flow.

Follow your starter’s installation instructions, then run its hello command. It prints a ping result, the instance’s asset field definitions, and up to 100 objects. An empty object list is a valid result.

Build with your AI coding tool

The repository’s AGENTS.md routes your coding tool to the selected SDK, language-specific guidance, and relevant recipes. Instructions for Claude and GitHub Copilot point to the same guidance.

For example, ask:

Read AGENTS.md. Use the Python starter to export all inventory objects matching a configurable field and substring as JSON Lines. Discover the instance’s field keys rather than guessing them. Explain how to configure and run the integration, and run the offline checks.

Replace the language and task with your integration’s requirements. The repository contains a pinned API schema and endpoint index so your coding tool can inspect the API contract locally.

Run an integration recipe

All four starters accept the same action names:

Action	What it does
hello	Check connectivity, discover fields, and read one page of objects
export	Export all matching objects as JSON Lines, following pagination
lookup	Find an object by its raw barcode
create / update	Create an object or patch an existing UUID from a JSON payload
attach	Upload a file and link it to an object’s attachment field
history	Export all recorded changes for an object as JSON Lines

The recipe guides describe the required environment variables, expected output, and verification steps. create, update, and attach perform writes. Field keys and required values depend on your instance; inspect field definitions before preparing a payload. Attachment recipes report partial-success responses instead of treating them as complete success.

Verify and adapt

The repository provides offline checks that exercise each installed SDK against a local HTTP fixture, including authentication, pagination, filtering, uploads, and error handling. The fixture runner requires Python 3.10+ in addition to your selected starter’s runtime. Follow the verification instructions.

Copy the selected starter, its dependency manifest and lockfile, and the MIT license into your own integration project. Keep the relevant AI guidance with it if you want to use it outside the quickstart repository. Internal SDK contributors can also use the repository’s workspace and local override instructions.

For additional SDK methods, continue with the language guides and common workflows.