Developers

The API behind
the back office.

Everything your firm runs on Shrkity — services, orders, packages, clients, companies, billing — is reachable over one REST API. Connect your ERP, sync your CRM, power a branded client app through your own backend, or create orders straight from your systems. Same engine, same audit trail, your code.

Start building API reference

Protocol: REST + JSON, versioned at /api/v1
Keys: Scoped, IP-restrictable keys
Retries: Idempotent retries built in

Same engine the desktop uses

Audited like every other action

Your first call

curl https://api.shrkity.com/api/v1/orders \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-7f3a" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Require-Subject: 1" \
  -d '{
    "service_definition_id": 18
  }'

# 201 · X-Shirkty-Mode: subject
{
  "mode": "subject",
  "data": {
    "request": { "id": 1208, "status": "pending" },
    "steps": [ …instantiated from your workflow… ]
  }
}

A real client order through the same engine the desktop uses — steps, SLA clocks and audit included.

Guide

From key to first order in minutes.

API access is part of the Scale and Enterprise plans. Keys are minted by your workspace owner inside the desktop app, scoped to exactly what your integration needs, and shown once. A deeper BFF walkthrough is also published as plain Markdown at https://api.shrkity.com/api/v1/docs/integrator.md (no auth).

Mint a key

In Shrkity Business, open Settings · Organization · API Access and create a key. Pick its scopes (BFF template or ops template), pin it to your servers' IPs when the key carries execute scopes, and copy the secret — it is shown exactly once.

Authenticate

Send the key on every request as Authorization: Bearer shk_live_… or in the X-Api-Key header. Server to server only — never from a browser or mobile app.

Make your first call

List published services with GET /services (subject headers filter personal vs company catalog), then create an order. Every response mirrors what your team sees on the desktop.

Ship safely

Send an Idempotency-Key on writes, prefer X-Shirkty-Require-Subject: 1 on client order create, assert X-Shirkty-Mode: subject in tests, and rotate keys by minting a new one and revoking the old.

Base URL https://api.shrkity.com/api/v1 Your exact base URL is shown in the API Access tab.

Creating an order: ops vs subject

POST /orders is dual-mode. The same path serves staff automation and branded-client backends — the difference is the subject headers. Successful responses set X-Shirkty-Mode: subject|operator. Operator creates also send X-Shirkty-Mode-Warning so white-label BFFs can fail CI if they forget the client header.

Ops (no subject headers)

Creates as the workspace machine principal. Optionally set created_by_user_id / client_user_id to pin the client owner, and company_id when the service needs a company. Response envelope stays the classic ops shape.

Subject / BFF

Send X-Shirkty-Client-User-Id (required) and optional X-Shirkty-Company-Id. The order is created as that client. Body ids must match the headers or you get subject_mismatch. Membership is re-checked under your workspace.

White-label safety rail: send X-Shirkty-Require-Subject: 1 (or ?require_subject=1) on POST /orders so a missing client header returns 422 subject_required instead of a silent ops create.

Full client journey after create (start step, form complete, document upload, offline pay/sign) needs orders:execute, attachments:write, and usually attachments:read — see Provider BFF.

Service catalog: personal vs company

In subject mode, GET /services matches Shrkity Client Mobile: visibility is driven by requires_company, not by workflow applies_to.

Personal (client header only)

Lists services with requires_company = false. Order create must not send a company.

Company (+ company header)

Lists services with requires_company = true. Use for company / employee orders; requires_employee also needs company_employee_id.

applies_to (company · employee · individual) is returned for UI badges only. Operator mode (no subject) returns the full published list and accepts optional ?requires_company= / ?audience= filters. Each row includes order_context: { personal_ok, company_ok, employee_ok }.

Authentication

A key is a credential,
not a password you reuse.

Keys act for your whole organization within the scopes you grant them. Shrkity stores only a hash — if a key is lost, revoke it and mint another.

Scoped by resource. orders:write can create orders; it cannot touch coupons. There is no invoices:write — invoices are system-issued; use invoices:read + PDF. Grant only what the integration needs.

IP allowlist required for execute. Keys that include orders:execute, attachments:write, or documents:write must be pinned to server IPs or CIDR ranges at mint/update (422 without it). Strongly recommended on every production key.

Plan-enforced, instantly revocable. Access is re-checked on every request (including a missing subscription → plan_required), and a revoked key stops working within a minute everywhere.

Authenticate

# bearer token (recommended)
curl https://api.shrkity.com/api/v1/services \
  -H "Authorization: Bearer shk_live_…"

# or the X-Api-Key header
curl https://api.shrkity.com/api/v1/services \
  -H "X-Api-Key: shk_live_…"

Keys look like shk_live_ followed by 40 characters. Anything else is rejected before it touches your data.

Errors

Every error is JSON with a human message and, where it helps your code branch, a machine code. Authentication and authorization failures always name their reason.

invalid_api_key

401

The key is unknown, malformed, revoked (revoked_api_key) or expired (expired_api_key).

plan_required

403

The workspace's current plan does not include API access (or the subscription is missing).

ip_not_allowed

403

The key is pinned to specific source IPs and this call came from elsewhere.

insufficient_scope

403

The key lacks the required grant; the response names it in required_scope.

subject_forbidden

403

The subject headers name a client who is not a member of this workspace (no matching access context).

company_not_verified

409

The company is WaitingVerification or Rejected and cannot be used for writes.

subject_required · subject_mismatch · subject_invalid

422

BFF routes need X-Shirkty-Client-User-Id, a body field disagreed with the subject headers, or the subject id was not a positive integer.

payment_method_not_supported

422

Order-step offline pay was called with an online wallet (subscription checkout does support online wallets separately).

422

validation

The request body failed validation; the message says exactly what to fix.

429

rate limit

Too many requests; back off for Retry-After seconds.

Error shape

{
  "message": "The API key does not have the required scope.",
  "code": "insufficient_scope",
  "required_scope": "orders:write"
}

Pagination

Every list takes page (default 1) and per_page (default 10, max 200) and returns a meta object beside the data. Walk pages until has_next is false.

GET /orders?page=2&per_page=50

{
  "data": [ …50 orders… ],
  "meta": {
    "total": 412,
    "per_page": 50,
    "current_page": 2,
    "last_page": 9,
    "has_next": true,
    "has_previous": true
  }
}

Idempotency

Networks fail mid-request. Send an Idempotency-Key header on any POST and the first successful response is held for 24 hours; an identical retry gets the stored response back — flagged with Idempotency-Replayed: true — instead of creating a duplicate. For BFF subject calls the cache key also includes the subject headers so one API key serving many clients cannot cross-replay responses.

Use a stable value per logical action, like your own order reference. New action, new key.

Retry-safe create

curl https://api.shrkity.com/api/v1/orders \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "Idempotency-Key: erp-po-10422" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Require-Subject: 1" \
  -d '{ "service_definition_id": 18 }'

# run it twice — one order exists.

Rate limits

Each key may make 180 requests per minute. Every response carries your remaining budget; a 429 tells you exactly how long to wait. Order creation is additionally subject to your plan's monthly order allowance. Daily usage rollups are available in the desktop API Access drawer.

Response headers

X-RateLimit-Limit: 180
X-RateLimit-Remaining: 177
# on 429 only:
Retry-After: 21

Versioning

The contract is the URL. Responses under /api/v1 only ever gain fields; nothing is renamed or removed within v1. A breaking change means a parallel /api/v2 with a deprecation window, never a silent edit. Build against the fields you use and ignore the rest. The OpenAPI document is currently 1.1.1 (Provider BFF, dual-mode rails, package checkout, attachment scope split, overview + rich client-tasks).

Provider BFF

Brand a client app on your own backend.

Mobile and web UIs you own should never hold an API key. Your server authenticates with the key, maps the signed-in person to a Shrkity client, and calls /api/v1 with subject headers. Shrkity re-checks membership and ownership under your workspace.

Ops mode

API key only — tenant-wide lists and staff automations (ERP, CRM, finance). No subject headers. Use a key without orders:execute / attachments:* / documents:write when you only need ops. Desktop offers an ops template for this.

Subject (BFF) mode

Send X-Shirkty-Client-User-Id (required) and optional X-Shirkty-Company-Id. Lists fence to that client; step execute, attachments, quotation accept, overview, client-tasks, and subscription checkout always require the subject.

Recommended BFF scopes

services:read · packages:read · subscriptions:read · subscriptions:write · orders:read · orders:write · orders:execute · clients:read · companies:read · documents:read · documents:write · attachments:read · attachments:write · invoices:read · quotations:read · quotations:write

GET /tenant/api-keys/scopes (desktop session) returns the grantable catalog and bff_recommended_scopes. IP allowlist is required when the key includes execute / attachment-write / document-write scopes.

Always-subject routes (missing header → 422 subject_required): /client-tasks, /overview, step execute / sign / pay, /attachments*, quotation accept/reject, subscription checkout / preview-coupon / client pay.

Client home & inbox. GET /overview returns home counts (active orders, actionable tasks, expiring docs). GET /client-tasks returns paginated inbox cards (service name, order reference, step labels, SLA, links to order/step) with filters: status, step_type, service_definition_id, subject_kind. Load full form/payment/signature config via GET …/steps/{key}.

Attachments. POST /attachments needs attachments:write; GET /attachments/{id}/download needs attachments:read (or legacy write). Staging files are private object storage with short-lived signed delivery — not public disk paths.

Webhooks deliver signed POSTs (including step.client_action_required) so your backend can push “action required” without polling. Order-step pay accepts offline wallets only; package subscription checkout supports offline proof and online hosted payment URLs.

End users never authenticate to Shrkity with your API key. Your session, your branding; Shrkity is the system of record.

Subject call

curl https://api.shrkity.com/api/v1/client-tasks \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42"

# X-Shirkty-Mode: subject

Overview

curl https://api.shrkity.com/api/v1/overview \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001"

Dual-mode checklist (white-label)

Separate ops vs BFF API keys (BFF has execute + attachments; IP allowlist required).
Never put the key in the mobile app — only your backend.
Every client-facing call: Authorization + X-Shirkty-Client-User-Id (+ company when needed).
Client order create: subject headers and prefer X-Shirkty-Require-Subject: 1.
Assert X-Shirkty-Mode: subject in integration tests for client paths.
Map mobile user → Shirkty client id only after membership is valid (access_contexts).

Client self-serve

Packages & subscriptions on the BFF.

With subject headers and packages:read + subscriptions:read + subscriptions:write, your branded app can browse packages and complete checkout without the desktop. Without subject headers the same paths keep ops/staff behaviour (full catalog, assign, pause, resume, renew).

GET /packages

browse

Subject → client catalog for this tenant. Show package detail with GET /packages/{id}.

GET /subscriptions

mine

Subject → holder-only list/show of the client’s subscriptions.

POST /subscriptions

start

Body { package_id, linked_company_id? }. Free packages activate; paid return needs_payment plus wallets.

POST /subscriptions/preview-coupon

coupon

Always subject. Preview a code before checkout.

POST /subscriptions/checkout

pay

Always subject. Create subscription + pay in one step: offline proof or chargeable online wallet_id (hosted payment_url for WebView).

…/payment-options · …/pay · …/payment/cancel

pending

Always subject. Continue payment on a pending/grace subscription; online returns a hosted URL; cancel lets the client start over.

…/apply-coupon · …/remove-coupon · …/link-company · …/cancel

manage

Subject-scoped coupon edits on pending pay, company link, and cancel at period end.

Paid · online

Preview coupon → checkout with chargeable online wallet → open payment_url in a WebView → gateway webhook activates the subscription.

Paid · offline

Checkout with offline wallet + proof attachment → staff verify on desktop → active. Order-step offline pay remains offline-only; package checkout is the surface that supports both channels.

Checkout (illustrative)

curl https://api.shrkity.com/api/v1/subscriptions/checkout \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "Idempotency-Key: sub-checkout-9c2e" \
  -d '{
    "package_id": 12,
    "wallet_id": 3
  }'

Reference

Every endpoint, by resource.

Generated from the same OpenAPI document the platform serves at /api/v1/openapi.json (currently 1.1.1), so what you read here is what the server enforces. The long-form BFF guide is also at /api/v1/docs/integrator.md.

Services

Published service catalog (read-only).

3 endpoints

GET /services List published services

List published services

Scope: services:read

Parameters

search

query · string

Matches name, Arabic name, or code

200 · Paginated list

Example request

curl https://api.shrkity.com/api/v1/services \
  -H "Authorization: Bearer shk_live_…"

GET /services/{id} Get a published service with order prerequisites

The list fields plus starts_at_price (whether the price depends on runtime choices) and the eligibility checks that will gate an order for this service.

Scope: services:read

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)404 · Error

Example request

curl https://api.shrkity.com/api/v1/services/{id} \
  -H "Authorization: Bearer shk_live_…"

GET /services/{id}/required-documents List the documents a service's workflow will request

Aggregated across the workflow's document steps, in execution order. Use it to collect files from your side before or while the order runs.

Scope: services:read

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)404 · Error

Example request

curl https://api.shrkity.com/api/v1/services/{id}/required-documents \
  -H "Authorization: Bearer shk_live_…"

Orders

Service requests.

16 endpoints

GET /orders List orders

List orders

Scope: orders:read

Parameters

status

query · string

company_id

query · integer

service_definition_id

query · integer

priority

query · string

search

query · string

created_from

query · string

created_to

query · string

200 · Paginated list

Example request

curl https://api.shrkity.com/api/v1/orders \
  -H "Authorization: Bearer shk_live_…"

POST /orders Create an order

Creates a service request for a published service. Subject to the plan's monthly order limit (422 when reached). Supports Idempotency-Key.

Scope: orders:write

Body fields

service_definition_id

integer · required

A published service (see GET /services)

client_user_id

integer

Alias for created_by_user_id; must match X-Shirkty-Client-User-Id when subject header present

created_by_user_id

integer

Operator path: pin order creator; subject path must match header or omit

company_id

integer

Required when the service requires a company context; must match X-Shirkty-Company-Id when both set

company_employee_id

integer

The worker the order is for, when the service requires an employee

priority

string · low | normal | high | urgent

201 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)422 · Error

Example request

curl https://api.shrkity.com/api/v1/orders \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "service_definition_id": 42,
    "client_user_id": 42,
    "created_by_user_id": 42,
    "company_id": 42,
    "company_employee_id": 42
  }'

GET /orders/{id} Get an order with its steps and price breakdown

Get an order with its steps and price breakdown

Scope: orders:read

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)404 · Error

Example request

curl https://api.shrkity.com/api/v1/orders/{id} \
  -H "Authorization: Bearer shk_live_…"

PATCH /orders/{id} Update an order

Update an order

Scope: orders:write

Parameters

id

path · integer · required

Body fields

priority

string · low | normal | high | urgent

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/orders/{id} \
  -X PATCH \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "priority": "low"
  }'

GET /orders/{id}/steps/{step_key} Get one step of an order

Get one step of an order

Scope: orders:read

Parameters

id

path · integer · required

step_key

path · string · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/orders/{id}/steps/{step_key} \
  -H "Authorization: Bearer shk_live_…"

POST /orders/{id}/cancel Cancel an order

Cancel an order

Scope: orders:write

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/orders/{id}/cancel \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

POST /orders/{id}/apply-coupon Apply a coupon code to an order

Apply a coupon code to an order

Scope: orders:write

Parameters

id

path · integer · required

Body fields

code

string · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/orders/{id}/apply-coupon \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WELCOME10"
  }'

DELETE /orders/{id}/coupon Remove the applied coupon from an order

Remove the applied coupon from an order

Scope: orders:write

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/orders/{id}/coupon \
  -X DELETE \
  -H "Authorization: Bearer shk_live_…"

POST /orders/{id}/steps/{step_key}/start Start a client-actor step (subject)

Scope: orders:execute. Always subject.

Scope: orders:execute

Parameters

id

path · integer · required

step_key

path · string · required

X-Shirkty-Client-User-Id

header · integer · required

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

Optional company context for the subject

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/orders/{id}/steps/{step_key}/start \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42"

POST /orders/{id}/steps/{step_key}/complete Complete a form_input step as the subject

Scope: orders:execute.

Scope: orders:execute

Parameters

id

path · integer · required

step_key

path · string · required

X-Shirkty-Client-User-Id

header · integer · required

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

Optional company context for the subject

Body fields

response_data

object

notes

string

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/orders/{id}/steps/{step_key}/complete \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "response_data": "…",
    "notes": "…"
  }'

POST /orders/{id}/steps/{step_key}/complete-manual Complete a manual_task step as the subject

Complete a manual_task step as the subject

Scope: orders:write

Parameters

id

path · integer · required

step_key

path · string · required

X-Shirkty-Client-User-Id

header · integer · required

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

Optional company context for the subject

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/orders/{id}/steps/{step_key}/complete-manual \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42"

POST /orders/{id}/steps/{step_key}/complete-document Complete a document_request step with staged attachments

Scope: orders:execute. Upload files via POST /attachments first.

Scope: orders:execute

Parameters

id

path · integer · required

step_key

path · string · required

X-Shirkty-Client-User-Id

header · integer · required

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

Optional company context for the subject

Body fields

document_records

array · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/orders/{id}/steps/{step_key}/complete-document \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "document_records": []
  }'

GET /orders/{id}/steps/{step_key}/signature/document Download the offline signature source document

Download the offline signature source document

Scope: orders:read

Parameters

id

path · integer · required

step_key

path · string · required

X-Shirkty-Client-User-Id

header · integer · required

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

Optional company context for the subject

200 · File stream

Example request

curl https://api.shrkity.com/api/v1/orders/{id}/steps/{step_key}/signature/document \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42"

POST /orders/{id}/steps/{step_key}/signature/sign Record offline signature with staged attachment_id

Scope: orders:execute. Offline channel only.

Scope: orders:execute

Parameters

id

path · integer · required

step_key

path · string · required

X-Shirkty-Client-User-Id

header · integer · required

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

Optional company context for the subject

Body fields

attachment_id

integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/orders/{id}/steps/{step_key}/signature/sign \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "attachment_id": 42
  }'

GET /orders/{id}/steps/{step_key}/payment-options List offline payment wallets and amount due for a payment step

Scope: orders:read. Online wallets are not listed (BFF offline-only).

Scope: orders:read

Parameters

id

path · integer · required

step_key

path · string · required

X-Shirkty-Client-User-Id

header · integer · required

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

Optional company context for the subject

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/orders/{id}/steps/{step_key}/payment-options \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42"

POST /orders/{id}/steps/{step_key}/pay Submit offline payment for a payment step

Scope: orders:execute. Offline wallets only; online → payment_method_not_supported.

Scope: orders:execute

Parameters

id

path · integer · required

step_key

path · string · required

X-Shirkty-Client-User-Id

header · integer · required

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

Optional company context for the subject

Body fields

wallet_id

integer · required

proof_attachment_id

integer

proof_reference

string

proof_notes

string

201 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)422 · Error

Example request

curl https://api.shrkity.com/api/v1/orders/{id}/steps/{step_key}/pay \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_id": 42,
    "proof_attachment_id": 42,
    "proof_reference": "…",
    "proof_notes": "…"
  }'

ClientTasks

Client-actionable step inbox for a BFF subject.

2 endpoints

GET /client-tasks List client-actionable steps for the subject

Scope: orders:read

Parameters

X-Shirkty-Client-User-Id

header · integer · required

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

Optional company context for the subject

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)422 · Error

Example request

curl https://api.shrkity.com/api/v1/client-tasks \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42"

GET /overview Subject home overview (BFF)

Always requires X-Shirkty-Client-User-Id. Scope: orders:read. Returns paginated inbox cards (service name, order reference, step definition labels, SLA, links) with filters status, step_type, service_definition_id, subject_kind. Returns counts (active_orders, actionable_tasks, expiring_documents) and recent_orders for the subject under this tenant.

Scope: orders:read

Parameters

X-Shirkty-Client-User-Id

header · integer · required

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

Optional company context for the subject

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)422 · Error

Example request

curl https://api.shrkity.com/api/v1/overview \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42"

Attachments

Staged file upload/download for BFF subjects. POST requires attachments:write; GET download requires attachments:read (or legacy attachments:write). Always requires subject headers. Invoices are read-only (invoices:read).

2 endpoints

POST /attachments Stage a multipart file upload as the subject

Scope: attachments:write. Supports Idempotency-Key. Use returned attachment_id for document/payment/signature steps. Download uses attachments:read.

Scope: attachments:write

Parameters

X-Shirkty-Client-User-Id

header · integer · required

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

Optional company context for the subject

201 · Staged attachment

Example request

curl https://api.shrkity.com/api/v1/attachments \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42" \
  -F "file=@/path/to/document.pdf"

GET /attachments/{id}/download Stream a staged attachment uploaded by the subject

Scope: attachments:read (preferred) or attachments:write (legacy). Always subject.

Scope: attachments:read

Parameters

id

path · integer · required

X-Shirkty-Client-User-Id

header · integer · required

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

Optional company context for the subject

200 · File stream403 · Error

Example request

curl https://api.shrkity.com/api/v1/attachments/{id}/download \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42"

Clients

Tenant clients.

3 endpoints

GET /clients List clients

List clients

Scope: clients:read

200 · Paginated list

Example request

curl https://api.shrkity.com/api/v1/clients \
  -H "Authorization: Bearer shk_live_…"

POST /clients Create a client

Create a client

Scope: clients:write

Body fields

name

string · required

email

string · required

phone_number

string

201 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)422 · Error

Example request

curl https://api.shrkity.com/api/v1/clients \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Trading Co.",
    "email": "finance@acme.sa",
    "phone_number": "…"
  }'

GET /clients/{client_id} Show one client if they have an access_context under this tenant

Show one client if they have an access_context under this tenant

Scope: clients:read

Parameters

client_id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)404 · Error

Example request

curl https://api.shrkity.com/api/v1/clients/{client_id} \
  -H "Authorization: Bearer shk_live_…"

Companies

Client companies and their workers.

7 endpoints

GET /companies List companies

List companies

Scope: companies:read

200 · Paginated list

Example request

curl https://api.shrkity.com/api/v1/companies \
  -H "Authorization: Bearer shk_live_…"

POST /companies Create a company

Create a company

Scope: companies:write

Body fields

Company payload — legal_name, type, and registration fields; see the portal's Add Company form for the field set.

201 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)422 · Error

Example request

curl https://api.shrkity.com/api/v1/companies \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ …see field reference… }'

PUT /companies/{id} Update a company

Update a company

Scope: companies:write

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/companies/{id} \
  -X PUT \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ …see field reference… }'

GET /companies/{company_id}/workers List a company's workers

List a company's workers

Scope: companies:read

Parameters

company_id

path · integer · required

200 · Paginated list

Example request

curl https://api.shrkity.com/api/v1/companies/{company_id}/workers \
  -H "Authorization: Bearer shk_live_…"

POST /companies/{company_id}/workers Add a worker to a company

Creates a company employee — the person an employee-scoped order is for. Field set mirrors the portal's Add Worker form.

Scope: companies:write

Parameters

company_id

path · integer · required

201 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)422 · Error

Example request

curl https://api.shrkity.com/api/v1/companies/{company_id}/workers \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ …see field reference… }'

PATCH /companies/{company_id}/workers/{id} Update a worker

Update a worker

Scope: companies:write

Parameters

company_id

path · integer · required

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/companies/{company_id}/workers/{id} \
  -X PATCH \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ …see field reference… }'

DELETE /companies/{company_id}/workers/{id} Remove a worker

Remove a worker

Scope: companies:write

Parameters

company_id

path · integer · required

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/companies/{company_id}/workers/{id} \
  -X DELETE \
  -H "Authorization: Bearer shk_live_…"

Packages

Tenant-authored packages (read-only).

2 endpoints

GET /packages List packages

List packages

Scope: packages:read

200 · Paginated list

Example request

curl https://api.shrkity.com/api/v1/packages \
  -H "Authorization: Bearer shk_live_…"

GET /packages/{id} Get a package

Get a package

Scope: packages:read

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/packages/{id} \
  -H "Authorization: Bearer shk_live_…"

Subscriptions

Package subscriptions.

9 endpoints

POST /subscriptions/checkout Client paid package checkout (BFF subject)

Always requires X-Shirkty-Client-User-Id. Scope: subscriptions:write. Body: package_id, wallet_id (offline or chargeable online), optional coupon_code, linked_company_id, proof_*. Online wallets return payment_url.

Scope: subscriptions:write

Parameters

X-Shirkty-Client-User-Id

header · integer · required

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

Optional company context for the subject

201 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)422 · Error

Example request

curl https://api.shrkity.com/api/v1/subscriptions/checkout \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42"

POST /subscriptions/preview-coupon Preview subscription coupon (BFF subject)

Always subject. Scope: subscriptions:write.

Scope: subscriptions:write

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/subscriptions/preview-coupon \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

GET /subscriptions List package subscriptions

List package subscriptions

Scope: subscriptions:read

200 · Paginated list

Example request

curl https://api.shrkity.com/api/v1/subscriptions \
  -H "Authorization: Bearer shk_live_…"

POST /subscriptions Assign a package subscription

Assign a package subscription

Scope: subscriptions:write

Body fields

package_id plus the holder (company_id or client user), mirroring the portal's Assign flow.

201 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/subscriptions \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ …see field reference… }'

GET /subscriptions/{id} Get a subscription with allocations

Get a subscription with allocations

Scope: subscriptions:read

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/subscriptions/{id} \
  -H "Authorization: Bearer shk_live_…"

POST /subscriptions/{id}/pause Pause an active subscription

Pause an active subscription

Scope: subscriptions:write

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)409 · Error

Example request

curl https://api.shrkity.com/api/v1/subscriptions/{id}/pause \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

POST /subscriptions/{id}/resume Resume a paused subscription

Resume a paused subscription

Scope: subscriptions:write

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)409 · Error

Example request

curl https://api.shrkity.com/api/v1/subscriptions/{id}/resume \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

POST /subscriptions/{id}/cancel Cancel a subscription

Cancel a subscription

Scope: subscriptions:write

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)409 · Error

Example request

curl https://api.shrkity.com/api/v1/subscriptions/{id}/cancel \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

POST /subscriptions/{id}/renew Renew an expired renewable subscription

Renew an expired renewable subscription

Scope: subscriptions:write

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)409 · Error

Example request

curl https://api.shrkity.com/api/v1/subscriptions/{id}/renew \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

Coupons

Discount coupons.

6 endpoints

GET /coupons List coupons

List coupons

Scope: coupons:read

200 · Paginated list

Example request

curl https://api.shrkity.com/api/v1/coupons \
  -H "Authorization: Bearer shk_live_…"

POST /coupons Create a coupon

Create a coupon

Scope: coupons:write

Body fields

code

string · required

name

string · required

description

string

discount_type

string · fixed | percentage · required

discount_value

number · required

max_discount_amount

number

min_order_amount

number

valid_from

string

valid_until

string

usage_limit_total

integer

usage_limit_per_subject

integer

is_active

boolean

201 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)422 · Error

Example request

curl https://api.shrkity.com/api/v1/coupons \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WELCOME10",
    "name": "Acme Trading Co.",
    "discount_type": "fixed",
    "discount_value": 250,
    "description": "…"
  }'

GET /coupons/{id} Get a coupon

Get a coupon

Scope: coupons:read

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/coupons/{id} \
  -H "Authorization: Bearer shk_live_…"

PATCH /coupons/{id} Update a coupon

Update a coupon

Scope: coupons:write

Parameters

id

path · integer · required

Body fields

code

string · required

name

string · required

description

string

discount_type

string · fixed | percentage · required

discount_value

number · required

max_discount_amount

number

min_order_amount

number

valid_from

string

valid_until

string

usage_limit_total

integer

usage_limit_per_subject

integer

is_active

boolean

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/coupons/{id} \
  -X PATCH \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WELCOME10",
    "name": "Acme Trading Co.",
    "discount_type": "fixed",
    "discount_value": 250,
    "description": "…"
  }'

DELETE /coupons/{id} Delete a coupon

Delete a coupon

Scope: coupons:write

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/coupons/{id} \
  -X DELETE \
  -H "Authorization: Bearer shk_live_…"

GET /coupons/{id}/redemptions List a coupon's redemptions

List a coupon's redemptions

Scope: coupons:read

Parameters

id

path · integer · required

200 · Paginated list

Example request

curl https://api.shrkity.com/api/v1/coupons/{id}/redemptions \
  -H "Authorization: Bearer shk_live_…"

Quotations

Bespoke priced proposals.

7 endpoints

GET /quotations List quotations

List quotations

Scope: quotations:read

200 · Paginated list

Example request

curl https://api.shrkity.com/api/v1/quotations \
  -H "Authorization: Bearer shk_live_…"

POST /quotations Create a quotation

Create a quotation

Scope: quotations:write

Body fields

Recipient + line items, mirroring the portal's New Quotation form.

201 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/quotations \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ …see field reference… }'

GET /quotations/{id} Get a quotation

Get a quotation

Scope: quotations:read

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/quotations/{id} \
  -H "Authorization: Bearer shk_live_…"

POST /quotations/{id}/send Send a quotation to its recipient

Send a quotation to its recipient

Scope: quotations:write

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/quotations/{id}/send \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

POST /quotations/{id}/withdraw Withdraw a sent quotation

Withdraw a sent quotation

Scope: quotations:write

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/quotations/{id}/withdraw \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

POST /quotations/{id}/accept Accept a quotation as the subject client

Scope: quotations:write. Always subject.

Scope: quotations:write

Parameters

id

path · integer · required

X-Shirkty-Client-User-Id

header · integer · required

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

Optional company context for the subject

Body fields

linked_company_id

integer

Required when quote needs a company link (personal subject)

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/quotations/{id}/accept \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "linked_company_id": 42
  }'

POST /quotations/{id}/reject Reject a quotation as the subject client

Reject a quotation as the subject client

Scope: quotations:write

Parameters

id

path · integer · required

X-Shirkty-Client-User-Id

header · integer · required

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

Optional company context for the subject

Body fields

reason

string · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/quotations/{id}/reject \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "…"
  }'

Invoices

System-issued invoices (read-only).

3 endpoints

GET /invoices List invoices

List invoices

Scope: invoices:read

200 · Paginated list

Example request

curl https://api.shrkity.com/api/v1/invoices \
  -H "Authorization: Bearer shk_live_…"

GET /invoices/{id} Get an invoice

Get an invoice

Scope: invoices:read

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/invoices/{id} \
  -H "Authorization: Bearer shk_live_…"

GET /invoices/{id}/pdf Get an invoice's PDF (302 to the file)

Get an invoice's PDF (302 to the file)

Scope: invoices:read

Parameters

id

path · integer · required

302 · Redirect to the rendered PDF

Example request

curl https://api.shrkity.com/api/v1/invoices/{id}/pdf \
  -H "Authorization: Bearer shk_live_…"

Connections

Client-to-tenant connection requests.

4 endpoints

GET /connections List connection requests and active connections

List connection requests and active connections

Scope: connections:read

Parameters

status

query · string

e.g. pending, active, rejected, revoked

200 · Paginated list

Example request

curl https://api.shrkity.com/api/v1/connections \
  -H "Authorization: Bearer shk_live_…"

POST /connections/{id}/approve Approve a pending connection

The client gains access to the shared record; orders and documents start flowing.

Scope: connections:write

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)409 · Error

Example request

curl https://api.shrkity.com/api/v1/connections/{id}/approve \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

POST /connections/{id}/reject Reject a pending connection

Optionally pass {"reason": "…"}.

Scope: connections:write

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)409 · Error

Example request

curl https://api.shrkity.com/api/v1/connections/{id}/reject \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

POST /connections/{id}/revoke Revoke an active connection

Ends the relationship; optionally pass {"reason": "…"}.

Scope: connections:write

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)409 · Error

Example request

curl https://api.shrkity.com/api/v1/connections/{id}/revoke \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

Documents

Customer compliance document records.

3 endpoints

GET /documents List customer compliance documents

Document records across the companies you serve: CR, licenses, Iqama and other compliance items with status and expiry. Combine company_id with expiring_soon=true (or expires_from/expires_to) for the renewal pipeline.

Scope: documents:read

Parameters

company_id

query · integer

company_employee_id

query · integer

document_type_id

query · integer

status

query · string

expiring_soon

query · boolean

Only documents inside their renewal window

expires_from

query · string

expires_to

query · string

search

query · string

200 · Paginated list

Example request

curl https://api.shrkity.com/api/v1/documents \
  -H "Authorization: Bearer shk_live_…"

GET /documents/{id} Get a document record

Get a document record

Scope: documents:read

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)404 · Error

Example request

curl https://api.shrkity.com/api/v1/documents/{id} \
  -H "Authorization: Bearer shk_live_…"

GET /document-types List tenant document types

List tenant document types

Scope: documents:read

200 · Paginated list

Example request

curl https://api.shrkity.com/api/v1/document-types \
  -H "Authorization: Bearer shk_live_…"

Webhooks

Outbound event subscriptions: signed POSTs for the audit events you subscribe to.

7 endpoints

GET /webhooks List webhooks (secrets are never included — rotate to obtain a fresh one)

List webhooks (secrets are never included — rotate to obtain a fresh one)

Scope: webhooks:read

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/webhooks \
  -H "Authorization: Bearer shk_live_…"

POST /webhooks Create a webhook

Deliveries are POSTs signed with X-Shirkty-Signature: t=<unix>,v1=<hex hmac-sha256(secret, t + '.' + body)>. The signing secret is returned once here and once per rotation. Retries back off 1m/5m/30m/2h/8h, then the delivery is marked dead; redirects are never followed. URLs must be public https endpoints — private and reserved network ranges are rejected. De-duplicate on delivery_id. Max 5 webhooks per workspace.

Scope: webhooks:write

Body fields

name

string · required

url

string · required

https required (http allowed for localhost during development)

events

array · required

Audit action slugs, prefix wildcards (order.*) or * — e.g. ["order.*", "quotation.accepted"]

is_active

boolean

201 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)422 · Error

Example request

curl https://api.shrkity.com/api/v1/webhooks \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Trading Co.",
    "url": "…",
    "events": [],
    "is_active": true
  }'

PATCH /webhooks/{id} Update a webhook (name, url, events, is_active)

Update a webhook (name, url, events, is_active)

Scope: webhooks:write

Parameters

id

path · integer · required

Body fields

name

string · required

url

string · required

https required (http allowed for localhost during development)

events

array · required

Audit action slugs, prefix wildcards (order.*) or * — e.g. ["order.*", "quotation.accepted"]

is_active

boolean

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/webhooks/{id} \
  -X PATCH \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Trading Co.",
    "url": "…",
    "events": [],
    "is_active": true
  }'

DELETE /webhooks/{id} Delete a webhook

Delete a webhook

Scope: webhooks:write

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/webhooks/{id} \
  -X DELETE \
  -H "Authorization: Bearer shk_live_…"

POST /webhooks/{id}/test Send a synthetic webhook.test event now

Sends a synthetic webhook.test event synchronously and reports a coarse outcome: {ok, category} where category is ok | non_2xx | connect_failed | invalid_url. Tightly rate limited.

Scope: webhooks:write

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/webhooks/{id}/test \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

GET /webhooks/{id}/deliveries List recent deliveries with status and attempts

List recent deliveries with status and attempts

Scope: webhooks:read

Parameters

id

path · integer · required

200 · Paginated list

Example request

curl https://api.shrkity.com/api/v1/webhooks/{id}/deliveries \
  -H "Authorization: Bearer shk_live_…"

POST /webhooks/{id}/rotate-secret Rotate the signing secret (returned once)

Rotate the signing secret (returned once)

Scope: webhooks:write

Parameters

id

path · integer · required

200 · Single resource (shape mirrors the portal's response for the same resource; fields are additive-only within v1)

Example request

curl https://api.shrkity.com/api/v1/webhooks/{id}/rotate-secret \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

Ready to build on Shrkity?

API access ships with the Scale and Enterprise plans. Mint your first key from the desktop app and your systems are talking to your back office today.

Request a demo See pricing

The API behind the back office.

From key to first order in minutes.

Mint a key

Authenticate

Make your first call

Ship safely

Creating an order: ops vs subject

Service catalog: personal vs company

A key is a credential,not a password you reuse.

Errors

Pagination

Idempotency

Rate limits

Versioning

Brand a client app on your own backend.

Ops mode

Subject (BFF) mode

Recommended BFF scopes

Dual-mode checklist (white-label)

Packages & subscriptions on the BFF.

Paid · online

Paid · offline

Every endpoint, by resource.

Services

Orders

ClientTasks

Attachments

Clients

Companies

Packages

Subscriptions

Coupons

Quotations

Invoices

Connections

Documents

Webhooks

Ready to build on Shrkity?

The API behind
the back office.

A key is a credential,
not a password you reuse.