Getting started

The Uysot Open API gives external systems access to a company's UYSOT data — leads, contracts, payment schedules and calls — over plain HTTPS + JSON.

https://api.service.app.uysot.uz/v1/open-api/<resource>
X-Open-Api-Token: uysot_...

Base URL	https://api.service.app.uysot.uz
OAuth base URL	https://service.app.uysot.uz — only POST /v1/open-api/oauth/token and POST /v1/open-api/oauth/revoke (OAuth)
Version	/v1 — additive within v1, breaking changes ship as /v2
Format	application/json; charset=utf-8 for both requests and responses
Auth	The X-Open-Api-Token header on every request
Rate limit	60 requests per minute, per token

---

1. Your first request in 3 steps

Step 1. Get a token

Building an integration that only touches your own company's data? Create a PRIVATE application in UYSOT and issue a personal access token (PAT). Shipping an app to other companies? Register a PUBLIC application and use the OAuth 2.0 flow.

PATs are covered in Authentication; the OAuth flow has its own guide, OAuth 2.0.

Step 2. Verify the token

This endpoint needs no extra grant — it tells you whether your token is alive and what it may do:

curl -s https://api.service.app.uysot.uz/v1/open-api/token/info \
  -H "X-Open-Api-Token: uysot_pat_..."

{
  "accept": true,
  "data": {
    "application": { "id": 12, "name": "Acme CRM sync", "type": "PRIVATE" },
    "company": { "id": 34, "name": "Uysot Demo" },
    "kind": "PAT",
    "expiresAt": 1798070399,
    "expiresInDays": 118,
    "permissions": [
      { "permission": "PERMISSION_OPEN_API_CONTRACT", "scope": "READ" }
    ]
  }
}

Step 3. Fetch your first list

List endpoints are POST .../filter with page / size / orders in the body:

curl -s -X POST https://api.service.app.uysot.uz/v1/open-api/contract/filter \
  -H "X-Open-Api-Token: uysot_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
        "page": 1,
        "size": 15,
        "statuses": ["ACTIVE"],
        "orders": { "CONTRACT_DATE": "DESC" }
      }'

{
  "accept": true,
  "message": "Success",
  "error": null,
  "errors": [],
  "requestId": null,
  "data": {
    "totalPages": 27,
    "currentPage": 1,
    "totalElements": 398,
    "data": [ { "id": 10241, "number": "A-1024", "status": "ACTIVE" } ]
  }
}

That's it — every other endpoint repeats this shape.

---

2. Core concepts

Concept	What it means
Application	Your integration as registered in UYSOT. PRIVATE — built by a company for itself; PUBLIC — a third-party app distributed to many companies
Connection	One (application ↔ company) pair — also called an installation. Permissions live here
Grant	A (permission, scope) pair, e.g. PERMISSION_OPEN_API_CONTRACT:READ
Token	The X-Open-Api-Token value: a PAT (uysot_pat_…) or an OAuth access token (uysot_at_…)
Company (tenant)	Every request only ever sees data belonging to the token's company

:::tip Permission changes don't invalidate tokens Grants live on the connection, not inside the token. When a company widens or narrows what your app may do, the existing token immediately reflects it — no re-issue needed. :::

---

3. The four kinds of endpoint

Kind	Example	What it does
List (filter)	POST /v1/open-api/contract/filter	Paginated search and sorting
Single object	GET /v1/open-api/contract/{id}	One record in full
Reference data	GET /v1/open-api/contract-field	Rarely-changing lookups — custom fields, pipelines, currencies, employees, addresses
Write	POST /v1/open-api/lead	Asynchronous — returns a requestId; poll GET /v1/open-api/request/{requestId}. A 200 here means "queued", not "saved"

Details in Formats and conventions.

---

4. Where to go next

• Authentication — tokens, grants and how to inspect them
• OAuth 2.0 — connect your app to many companies: consent, refresh, revoke
• Rate limits — the per-minute budget and how to live within it
• Formats and conventions — envelope, pagination, dates, enums
• Errors — status codes and stable message codes
• Webhooks — receive events instead of polling
• Embedded applications — render your app inside the CRM
• API Reference — the full specification of every endpoint

---

5. Reporting a problem

When you contact us, include: the request path and method, the approximate time (epoch seconds), the last 4 characters of your X-Open-Api-Token (never the whole token), the HTTP status, and the message from the response body (plus error.messageCode when the body has one — most errors don't, see Errors). For an asynchronous write, the requestId is the single most useful thing you can give us.