canonical: https://jentic.com/apis/cirqll.nl/cirqll

# Cirqll Nl Cirqll API

Cirqll is a Dutch SaaS platform that gives field-service and operations teams a structured workflow over customers, assignments, and tasks. The Cirqll API exposes 6 endpoints over https://api.cirqll.nl, secured with OAuth 2.0 authorization-code flow that issues 15-day access tokens and 30-day refresh tokens with read and write scopes. The API supports pagination, filtering, ordering, eager loading, partial field selection, and webhook integrations for event-driven workflows so back-office systems and AI agents can read customer records, list assignments, and create tasks.

## For AI agents

Read Cirqll customers and assignments, create tasks, and exchange OAuth 2.0 tokens to drive field-service automation. Six endpoints with read and write scopes.

## Scope

Does not handle invoicing, payroll, or marketing - use for Cirqll customers, assignments, and task management only.

## Capabilities

- List Cirqll customers with pagination, filtering, and partial field selection
- List assignments tied to customers for field-service scheduling
- Create a new Cirqll task to drive an assigned worker through the next step
- Exchange an OAuth 2.0 authorization code for a 15-day access token
- Refresh an expired Cirqll access token via the refresh endpoint
- Use eager loading to inline related resources in customer or assignment responses

## Use cases

### Field-Service Task Creation From Inbound Email

When a customer email arrives at a service inbox, an automation can identify the customer, look up their open assignments via GET /assignments, and create a new task with POST /tasks linking it to the right assignment. Eager loading on the assignments endpoint pulls the customer record inline, removing a second round-trip.

Example prompt: GET /assignments?filter[customer_id]=12345&include=customer, then POST /tasks with the matching assignment_id and a description from the email body.

### Customer Sync Into a Data Warehouse

An ETL job can paginate GET /customers nightly and load the records into a warehouse for analytics. Partial field selection keeps the payload small, and the OAuth refresh-token rotation lets the job run unattended for 30 days before re-authorisation. Cirqll's filtering and ordering mean only changed customers can be pulled.

Example prompt: GET /customers?fields=id,name,updated_at&filter[updated_after]=2026-06-01&page=1 and load each page into the warehouse staging table.

### Token Lifecycle Automation

Long-running integrations need a clean refresh story. Cirqll's POST `/oauth/token/refresh` accepts a refresh token and returns a fresh access token within the 30-day refresh window. A scheduled job that rotates tokens proactively avoids the 401 failure mode common in OAuth integrations that only refresh on demand.

Example prompt: POST `/oauth/token/refresh` with the stored refresh token to obtain a new access token before the 15-day expiry.

### AI Agent Service Dispatch

An AI dispatch agent invoked through Jentic can take an inbound request, identify the customer in Cirqll, and create a task on the appropriate assignment. Jentic holds the OAuth tokens in your Jentic One instance and refreshes them transparently, so the agent never handles credentials or runs into expired-token errors.

Example prompt: Search Jentic for 'create a task in Cirqll', load POST /tasks, and create a task linked to assignment 678 with the dispatched description.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/customers` | List customers with pagination and filtering |
| GET | `/assignments` | List assignments with eager loading |
| POST | `/tasks` | Create a new task |
| GET | `/oauth/authorize` | OAuth 2.0 authorization endpoint |
| POST | `/oauth/token` | Exchange authorization code for access token |
| POST | `/oauth/token/refresh` | Refresh an expired access token |

## Key resources

- **Customers** — Read customer records with pagination, filtering, and field selection
- **Assignments** — Read assignments linked to customers with eager loading support
- **Tasks** — Create new tasks linked to assignments
- **Authentication** — OAuth 2.0 authorization, token, and refresh endpoints

## Why Jentic

- **Setup:** Wiring the Cirqll API by hand means running its OAuth authorization-code flow, handling token refresh, and threading customers, assignments, and tasks through the right endpoints yourself. Through Jentic you install once, import the Cirqll API from the API Directory, store the OAuth credential once, and your agent calls it.
- **Permission scoping:** Cirqll takes the task and assignment target in the request body rather than the URL path, so scope the agent to the operations it needs, such as reading customers and assignments and creating tasks. You choose the operations it may call, so it runs only the ones you include.
- **Credential handling:** Your Cirqll OAuth credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list customer assignments' or 'create a task', and Jentic returns the matching Cirqll operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Circle Community API** — Circle hosts customer communities while Cirqll runs the operational task management.
- **CINNOX API** — CINNOX manages the inbound customer conversation that triggers a Cirqll task.
- **Cisco API** — Cisco infrastructure tooling complements Cirqll's customer and task workflows.

## FAQ

### What authentication does the Cirqll API use?

Cirqll uses OAuth 2.0 authorization-code flow with 15-day access tokens and 30-day refresh tokens. Scopes are read and write. Through Jentic, both tokens are stored encrypted in your Jentic One instance and refreshed automatically before expiry.

### Can I create tasks programmatically with the Cirqll API?

Yes. POST /tasks creates a new task. Tasks are typically linked to assignments, which themselves belong to customers - fetch the assignment via GET /assignments first to obtain the assignment_id.

### What are the rate limits for the Cirqll API?

Cirqll does not document hard rate limits in the OpenAPI spec; throttling is governed by your account tier. Plan paginated reads on /customers and /assignments and let Jentic surface 429 responses for retry.

### How do I list Cirqll customers through Jentic?

Run pip install jentic, then search Jentic for 'list customers in Cirqll'. Jentic returns GET /customers with pagination and field-selection parameters in the schema. Execute it with the desired page and filter. Get started with Jentic One, the self-hosted execution layer.

### Does Cirqll support partial field selection?

Yes. The API supports the fields query parameter so a request like GET /customers?fields=id,name returns only those attributes. This is useful for syncing into a warehouse without pulling unused payload.

### How long do Cirqll tokens last?

Access tokens are valid for 15 days; refresh tokens are valid for 30 days. Use POST `/oauth/token/refresh` proactively before the 15-day expiry to keep long-running integrations live without re-prompting the user.

### Can I limit what my agent is allowed to do with the Cirqll API?

Yes. Because Jentic One is self-hosted, you decide which Cirqll operations the agent may call, so you can allow it to read customers and assignments while blocking anything else. Cirqll takes the task and assignment target in the request body rather than the URL path, so scoping happens at the operation level: for example, you can permit creating tasks while withholding operations you do not want it to run. The agent runs only the operations and credentials your own rules include.