REST · JSON · v1

StaqOn External API

Connect your CRM or system to StaqOn external-team threads — push messages in, read replies (with member consent), raise escalations, and receive webhooks.

Get started Postman collection

Authentication

Every request must send your API key in a header:

X-API-Key: sk_live_xxx

Base URL

All endpoints are relative to [base_url]:

https://stagestaqon.one/api/v1/external

Members

Key context + usage

Returns the workspace, team, and current rate-limit context for your API key.

GET[base_url]/status.php

Sample request

curl -X GET \
  'https://stagestaqon.one/api/v1/external/status.php' \
  -H 'X-API-Key: sk_live_xxx'

Sample response 200

{"ok":true,"workspace":"…","team":"…","team_type":"external","total_members":42,"active_members":40,"api_key_usage":120,"rate_limit":1000,"rate_remaining":880}

Error response

{"ok":false,"error":"key's team is not an active external team"}

List members

Paginated list of the members in your external team.

GET[base_url]/members.php

Query fields

Field	Type	Description
page	integer	Page number.
limit	integer	Page size.
search	string	Filter by name/email.

Sample request

curl -X GET \
  'https://stagestaqon.one/api/v1/external/members.php' \
  -H 'X-API-Key: sk_live_xxx'

Sample response 200

{"ok":true,"members":[{"id":1,"name":"Rahul","email":"rahul@abc.com","status":"active","joined_at":"…","last_message_at":"…","messages_sent":12}],"total":42,"page":1,"pages":1}

Get member

Fetch a single member by email.

GET[base_url]/member.php

Query fields

Field	Type	Description
emailreq	string	Member email (must be in your team).

Sample request

curl -X GET \
  'https://stagestaqon.one/api/v1/external/member.php' \
  -H 'X-API-Key: sk_live_xxx'

Sample response 200

{"ok":true,"member":{"id":1,"name":"Rahul","email":"rahul@abc.com","joined_at":"…","last_active":"…","messages_sent":12,"has_mpin":true}}

Error response

{"ok":false,"error":"Member not found in this team"}

Add member

Add a member to your external team.

POST[base_url]/add-member.php

Request fields

Field	Type	Description
namereq	string	Member display name.
emailreq	string	Member email.
phone	string	Optional phone.
metadata	object	Optional key/values.

Sample request

curl -X POST \
  'https://stagestaqon.one/api/v1/external/add-member.php' \
  -H 'X-API-Key: sk_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Rahul Sharma",
  "email": "rahul@abc.com"
}'

Sample response 200

{"ok":true,"member_id":1,"conversation_id":45,"status":"created","login_url":"…"}

Error response

{"ok":false,"error":"name and email are required"}

Remove member

Remove a member from the team.

POST[base_url]/remove-member.php

Request fields

Field	Type	Description
emailreq	string	Member email.

Sample request

curl -X POST \
  'https://stagestaqon.one/api/v1/external/remove-member.php' \
  -H 'X-API-Key: sk_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "rahul@abc.com"
}'

Sample response 200

{"ok":true,"removed":true,"member_id":1}

Error response

{"ok":false,"error":"Member is not in this external team"}

Messaging

Send message

Send a message into a member's thread — attributed to your workspace (Direction In).

POST[base_url]/message.php

Request fields

Field	Type	Description
emailreq	string	Member email.
messagereq	string	Message text — max 60000 chars.

Sample request

curl -X POST \
  'https://stagestaqon.one/api/v1/external/message.php' \
  -H 'X-API-Key: sk_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "rahul@abc.com",
  "message": "Your loan is approved!"
}'

Sample response 200

{"ok":true,"message_id":123,"conversation_id":45}

Error response

{"ok":false,"error":"message is too long (max 60000 chars)"}

ℹ️

Length limit. message is capped at 60000 characters. Over-limit requests are rejected with 400 'message is too long (max 60000 chars)' — never truncated.

Post comment

Post a comment by username, tagged source=api + your external_ref (Direction In).

POST[base_url]/comment.php

Request fields

Field	Type	Description
usernamereq	string	Member username (must be in your team).
commentreq	string	Comment text — max 60000 chars.
external_ref	string	Your id for this post (echo-dedup on read-back).

Sample request

curl -X POST \
  'https://stagestaqon.one/api/v1/external/comment.php' \
  -H 'X-API-Key: sk_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "4821k9037",
  "comment": "Your documents are verified.",
  "external_ref": "crm-msg-1001"
}'

Sample response 200

{"ok":true,"message_id":123,"conversation_id":45,"sent_at":"2026-01-01 12:00:00"}

Error response

{"ok":false,"error":"comment is too long (max 60000 chars)"}

ℹ️

Length limit. comment is capped at 60000 characters → 400 'comment is too long (max 60000 chars)'.

Read conversation

Read the chat thread (Direction Out). Link-gated — requires an approved account link (member consent).

GET[base_url]/messages.php

Query fields

Field	Type	Description
usernamereq	string	Member username.
limit	integer	Page size.
before	integer	Older page cursor.
after	integer	Newer page cursor.

Sample request

curl -X GET \
  'https://stagestaqon.one/api/v1/external/messages.php' \
  -H 'X-API-Key: sk_live_xxx'

Sample response 200

{"ok":true,"conversation_id":45,"member":{"username":"4821k9037","name":"Rahul"},"messages":[{"id":1,"sender_side":"member","sender_name":"Rahul","content":"…","content_type":"text","source":"app","external_ref":null,"sent_at":"…","edited":false,"deleted":false,"attachments":[]}],"paging":{"mode":"before","limit":50,"returned":1,"has_more":false,"next_before":null}}

Error response

{"ok":false,"error":"No approved link for this member"}

ℹ️

Consent required. Returns 403 'No approved link for this member' until the member approves a link via /link-request.php, and again the instant they revoke (kill-switch). Use before or after, not both.

Escalations

Raise escalation

Raise an escalation case against a member.

POST[base_url]/escalation.php

Request fields

Field	Type	Description
emailreq	string	Member email.
titlereq	string	Title (≥2 chars).
descriptionreq	string	Case description.
due_datereq	string	YYYY-MM-DD, at least tomorrow.
priority	string	low \| medium \| high \| critical (default medium).

Sample request

curl -X POST \
  'https://stagestaqon.one/api/v1/external/escalation.php' \
  -H 'X-API-Key: sk_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "rahul@abc.com",
  "title": "Missing documents",
  "description": "KYC docs not uploaded",
  "priority": "high",
  "due_date": "2026-12-31"
}'

Sample response 200

{"ok":true,"matter_id":15}

Error response

{"ok":false,"error":"due_date must be a future date (YYYY-MM-DD, at least tomorrow)"}

Account Linking

Link request

Request a consent link to read a member's thread (idempotent while pending).

POST[base_url]/link-request.php

Request fields

Field	Type	Description
usernamereq	string	Member username.
external_ref	string	Unique within your team.

Sample request

curl -X POST \
  'https://stagestaqon.one/api/v1/external/link-request.php' \
  -H 'X-API-Key: sk_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "4821k9037",
  "external_ref": "crm-cust-123"
}'

Sample response 200

{"ok":true,"link_id":17,"status":"pending","expires_at":"…"}

Error response

{"ok":false,"error":"external_ref already linked to another member"}

ℹ️

Consent handshake. The link becomes active only when the member approves it. You're notified via the link.approved / link.declined / link.revoked webhooks.

Webhooks

StaqOn POSTs a JSON callback to your subscribed URL when an external-team event fires. Subscribe per external team in Workspace → Settings → API → Webhooks. Each webhook has its own secret.

ℹ️

Verify every request. HMAC-SHA256 of the raw request body, keyed by your webhook secret, hex-encoded — sent as header X-StaqOn-Signature (plus X-StaqOn-Event). Reject if it doesn't match.

Envelope (all events)

{
  "event": "<name>",
  "timestamp": "<ISO-8601>",
  "data": { }
}

Events

Event	Fires when	data
`member.joined`	external member self-joins a team	member_id, name, team_id
`member.message`	a message is posted into a member's external thread (outbound to you)	member_id, email or username, message, direction:"outbound", message_id (+ origin:"api", external_ref via Comment API)
`member.removed`	a member is removed from the team	member_id, email, team_id
`escalation.created`	an escalation case is raised	matter_id, title, priority, status:"open", scope, target_member_id, target_email
`escalation.resolved`	an escalation case is resolved	matter_id, status:"resolved", resolved_by, resolution_notes
`link.approved`	member approves an account link	user_id, username, link_id, external_ref
`link.declined`	member declines an account link	user_id, username, link_id, external_ref
`link.revoked`	member revokes a previously-approved link (kill-switch)	user_id, username, link_id, external_ref

Postman collection

Import the full collection — set apiKey + baseUrl once and run every endpoint.

Download the Postman collection

A project by VistarKriya Marketings Private Limited