Developer Reference

SocialMGR API

A bearer-token REST API over the whole service desk. Everything you can do in the panel, you can automate here.

https://social-demo.scriptgain.com/api/v1 OpenAPI Spec

Authentication

Every request needs a bearer token in the Authorization header. A store owner mints one in the admin panel under Settings → API Tokens. Tokens start with vlt_ and are shown once.

curl https://social-demo.scriptgain.com/api/v1/tickets \
  -H "Authorization: Bearer vlt_your_token_here" \
  -H "Accept: application/json"

Conventions

Base URL: https://social-demo.scriptgain.com/api/v1
Format: JSON request + response bodies. Send Accept: application/json.
Pagination: List endpoints return a paginator. Use ?per_page=25 (max 100) and ?page=N.
Filtering: Most lists accept ?q= for search and resource-specific filters (see each endpoint).
Rate limit: 120 requests per minute per token. Exceeding it returns 429 with X-RateLimit headers.
Errors: 401 unauthenticated, 403 forbidden, 404 not found, 422 validation (with an errors object), 429 rate limited.
Money: Amounts are read as integer cents plus a formatted string. Totals are never writable over the API.

Service Requests

Incoming requests captured from the intake form or logged by staff.

GET /service-requests

List service requests

Query: q, per_page, page, status, priority

GET /service-requests/{id}

Retrieve a service request

POST /service-requests

Create a service request

Body: name, email, phone?, subject, description?, service_id?, priority?, address?

PUT /service-requests/{id}

Update a service request

DELETE /service-requests/{id}

Delete a service request

POST /service-requests/{id}/convert-ticket

Convert into a ticket

POST /service-requests/{id}/convert-work-order

Convert into a work order

POST /service-requests/{id}/close

Close the request

Response fields

Tickets

The service-desk conversation. Replies may be public or internal staff notes.

GET /tickets

List tickets

Query: q, per_page, page, status, priority, assigned_user_id, customer_id

GET /tickets/{id}

Retrieve a ticket

POST /tickets

Create a ticket

Body: subject, description?, customer_id?, priority?, assigned_user_id?

PUT /tickets/{id}

Update a ticket

DELETE /tickets/{id}

Delete a ticket

GET /tickets/{id}/replies

List replies

Query: include_internal

POST /tickets/{id}/replies

Post a reply

Body: body, is_internal?

POST /tickets/{id}/status

Change status

Body: status

POST /tickets/{id}/assign

Assign a technician

Body: assigned_user_id

POST /tickets/{id}/work-order

Spawn a work order from this ticket

Body: title?, scheduled_at?

Response fields

id number subject description status (open|pending|in_progress|resolved|closed) priority customer_id service_request_id project_id assigned_user_id last_reply_at resolved_at closed_at created_at updated_at

Work Orders

Scheduled service visits. Completing one generates an invoice.

GET /work-orders

List work orders

Query: q, per_page, page, status, upcoming

GET /work-orders/{id}

Retrieve a work order

POST /work-orders

Create a work order

Body: customer_id?, title, scheduled_at?, duration_minutes?, assigned_user_id?, address?, items[] {service_id?, name, quantity, unit_price}

PUT /work-orders/{id}

Update a work order

DELETE /work-orders/{id}

Delete a work order

POST /work-orders/{id}/status

Change status

Body: status

POST /work-orders/{id}/complete

Mark complete and generate an invoice

POST /work-orders/{id}/cancel

Cancel the work order

Body: reason?

POST /work-orders/{id}/reschedule

Reschedule

Body: scheduled_at, duration_minutes?

Response fields

id number title notes status (scheduled|in_progress|on_hold|completed|cancelled) scheduled_at duration_minutes address subtotal_cents subtotal_formatted customer_id ticket_id project_id assigned_user_id invoice_order_id items[] created_at updated_at

Projects

Engagements that group tickets and work orders.

GET /projects

List projects

Query: q, per_page, page, status

GET /projects/{id}

Retrieve a project

POST /projects

Create a project

Body: name, description?, customer_id?, assigned_user_id?, starts_on?, due_on?, status?

PUT /projects/{id}

Update a project

DELETE /projects/{id}

Delete a project

POST /projects/{id}/status

Change status

Body: status

Response fields

id number name description status (planning|active|on_hold|completed|cancelled) progress_percent starts_on due_on customer_id assigned_user_id created_at updated_at

Invoices

Read-only view of invoices (the billable orders behind work orders).

GET /invoices

List invoices

Query: q, per_page, page, financial_status

GET /invoices/{id}

Retrieve an invoice

Response fields

id number financial_status currency subtotal_cents tax_cents total_cents total_formatted refunded_cents paid_at work_order_id project_id customer_id items[] created_at

Services

Read-only catalog of the services offered.

GET /services

List services

Query: q, per_page, page

GET /services/{id}

Retrieve a service

Response fields

id name slug description status

Booking Types

The kinds of appointment offered, with durations and pricing.

GET /booking-types

List booking types

Query: q, per_page, page, is_active

GET /booking-types/{id}

Retrieve a booking type

POST /booking-types

Create a booking type

Body: name, duration_minutes, price?, buffer_before_minutes?, buffer_after_minutes?, assigned_user_id?, is_active?

PUT /booking-types/{id}

Update a booking type

DELETE /booking-types/{id}

Delete a booking type

Response fields

id name slug description duration_minutes buffer_before_minutes buffer_after_minutes total_minutes price_cents price_formatted assigned_user_id color is_active position

Availability

A staff member's weekly working hours, exceptions, and timezone.

GET /users/{user}/availability

Get a staff member's availability

PUT /users/{user}/availability

Replace availability

Body: timezone, days {0-6: {enabled, start, end}}, exceptions[] {date, is_available, start?, end?, reason?}

Response fields

user_id timezone rules[] {weekday, start_time, end_time, is_active} exceptions[] {date, is_available, start_time, end_time, reason}

Customers

The people who submit requests and pay invoices.

GET /customers

List customers

Query: q, per_page, page

GET /customers/{id}

Retrieve a customer

POST /customers

Create a customer

PUT /customers/{id}

Update a customer

Response fields

id name email phone created_at

Account

The authenticated token's own context.

GET /me

The staff account this token belongs to

Response fields

id name email role

Machine-readable schema: openapi.json. Import it into Postman or an OpenAPI client to generate a request collection.