Public API - Shor Documentation

The public API is available to enabled employer workspaces. Ask Shor to enable your workspace before connecting an integration. Administrators create credentials in Settings → API keys. Copy the secret when it is shown; it cannot be retrieved later. Choose only the scopes the integration needs and an expiry date. Rotate before expiry, update your secret store, then revoke the old credential. Never put keys in browser code or source control. Use the API base URL supplied for your environment. All resource paths start with /v1. Test credentials are accepted only by the matching test environment. The current contract is available without authentication at /v1/openapi.json; a downloadable reference is included here. Connecting an AI assistant instead? Start with Connect AI assistants. The MCP tool reference maps every supported tool to its HTTP route, inputs, scopes, and confirmation requirements.

curl "$SHOR_API_URL/v1/business" \
  -H "Authorization: Bearer $SHOR_API_KEY"

Keys act as the membership that created them. Leaving the workspace revokes access permanently. A role change applies immediately, including to retries. Admins can manage keys; members can read and create drafts when granted the corresponding scopes; viewers can only read. Timesheet and milestone approvals and rejections require an admin and the corresponding write scope.

Scope	Operations
`read`	Business, contracts, timesheets, milestones, payments and balances
`contracts:write`	Initialize a contract draft
`timesheets:write`	Approve or reject a submitted timesheet
`milestones:write`	Approve or reject a submitted milestone

Responses contain a curated public representation. Single resources are bare objects; lists return { data, hasMore, nextCursor }. Money is a decimal string with currency precision. Keep it as a string or use a decimal library. Payroll dates use YYYY-MM-DD; timestamps use UTC ISO 8601.

Create a draft

POST /v1/contracts initializes a draft for completion and review in Shor. It accepts title, description, professional email, employment/contract type, country of employment, start/end dates and an optional external reference. It does not sign or activate a contract or accept the dashboard’s nested compensation/wizard payload. Every POST requires Content-Type: application/json and Idempotency-Key, a unique intent identifier of 16–128 letters, digits, underscores or hyphens. Generate it once, persist it in your integration, and reuse it with exactly the same request for retries. Generate a new identifier for each intentional new action, even when its arguments are identical.

curl "$SHOR_API_URL/v1/contracts" \
  -H "Authorization: Bearer $SHOR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $INTENT_ID" \
  -d '{"title":"Design project","externalReference":"your-system-record-123"}'

Successful operation results are retained for seven days. A completed retry returns the original result with Idempotency-Replayed: true; current resource state may since have changed. Never reuse an old key after retention. externalReference provides durable draft correlation after operation retention and is unique within the workspace and integration principal. Key rotation preserves that principal. An independently created key or a different MCP grant is a different integration.

Approve work

Fetch the timesheet or milestone, review its amount, currency and payment date, then send its version as expectedVersion to /timesheets/{id}/approve or /milestones/{id}/approve. Rejection uses /reject and also requires a nonempty reason. A changed review returns STALE_RESOURCE_VERSION. Fetch and review again before creating a new intent. Approval creates a payment; it does not mean the worker has been paid. Timesheet processing follows its due date and effective auto-pay setting. Milestone approval attempts payment processing immediately. Follow paymentId and poll the payment resource for pending, processing, completed or failed state.

Errors and retries

Errors return { error: { type, code, message, status, requestId, details? } }. Retain the request ID when contacting support; do not log credentials or sensitive request bodies.

Status/code	Next step
401 `INVALID_CREDENTIAL`	Check credential, expiry and environment
403 `INSUFFICIENT_SCOPE`	Check grant and current membership role
403 `INTEGRATION_DISABLED` / `WRITES_DISABLED`	Contact the workspace administrator or Shor
409 `STALE_RESOURCE_VERSION`	Fetch and review current state before a new intent
409 `IDEMPOTENCY_KEY_REUSED`	Use the original payload or a new intentional operation
409 `OPERATION_IN_PROGRESS`	Retry the same request after a short delay
409 `OPERATION_EXPIRED`	Reconcile resource state; do not blindly repeat the action
409 `EXTERNAL_REFERENCE_EXISTS`	Look up the contract using `externalReference`
429	Honor `Retry-After`
503	Retry with backoff; balance is unavailable, not zero

Limits currently allow 600 reads and 60 writes per principal per minute, with a shared workspace ceiling of 2,000 requests per minute. Failed-auth admission has a separate limit. Responses include rate-limit headers. Retry transient network/502/503/504 errors with exponential backoff, preserving the key and payload for writes. Resolve validation, authorization and state conflicts before retrying.

​Create a draft

​Approve work

​Errors and retries

Create a draft

Approve work

Errors and retries