Developers

Integration API

Connect your ERP, billing system or HRMS to AurDesk so nobody retypes data between screens. Version 1.0.

Base URL: https://aurdesk.com

The AurDesk Integration API lets your systems (ERP, billing, HRMS, internal tools) work with AurDesk without anyone retyping data between screens.

Authentication. Every /api/v1 call needs an API key from an integration client created by an organisation admin in AurDesk settings. Send it as Authorization: Bearer <key> or X-Api-Key: <key>. A missing or too-short key returns 401 {"error":"API key required."}; an unknown or revoked key returns 401 {"error":"Invalid or revoked API key."}. Keys are shown once when created.

Scope. A client is limited to the organisation(s), and optionally the departments, categories, statuses and priorities, chosen when it was created. Requests outside that scope behave as if the record does not exist (404).

Permissions. Each client also carries switches: create tickets, reply, close tickets, see internal notes. A call that needs a switch the client lacks returns 403.

Rate limit. 60 requests per minute. Beyond that the API returns 429.

Errors. Ticket and embed endpoints return Laravel's standard validation shape on 422: {"message": "...", "errors": {"field": ["..."]}}. The data-push endpoints (financials, attendance, employees) return {"error": "Validation failed.", "details": {"field": ["..."]}}.

Idempotency. The data-push endpoints require an idempotency_key. Repeating a key already accepted returns 200 {"status":"duplicate_ack"} and does nothing. If a batch fails permanently after being accepted, its key is released so a retry is processed.

Webhooks. AurDesk can also call you. See the webhooks section at the end for events, headers and how to verify the signature.

Download the OpenAPI 3.1 file to import into Postman, Insomnia or a code generator.

Tickets

Requests raised by or visible to your integration client.

GET /api/v1/tickets

List tickets in this client's scope

Newest first, 25 per page. Use page to move through results.

Parameters

status	query	Exact status to filter by.
priority	query
search	query	Matches subject or ticket code.
page	query

Responses

200A page of tickets.
401API key missing, invalid or revoked.
429More than 60 requests in a minute. Wait and retry.

POST /api/v1/tickets

Create a ticket

Needs the client's create tickets switch.

Idempotent by external_ticket_id. If you send an external_ticket_id already used by this client, the existing ticket is returned with 200 and "duplicate": true instead of creating another.

Linking the customer. Send merchant_id (the customer's ID as stored in AurDesk) or, for ERP-driven flows, merchant_ref (the customer's code in your ERP, registered on the customer record in AurDesk). merchant_id is tried first; merchant_ref is the fallback. If neither matches, the ticket is still created, just not linked to a customer — an unknown reference is never an error.

Request body (JSON)

external_ticket_id	string	Your own ID; makes the call idempotent.
subject *	string
description	string
requester_name	string
requester_email	string
priority	string — one of: low, normal, high, urgent
category_id	integer
merchant_id	string	The customer's ID as stored in AurDesk.
merchant_ref	object	The customer's code in an external system such as your ERP. Used only when `merchant_id` is absent or unmatched.
merchant_ref.system *	string	Case-insensitive, for example sap, tally, zoho.
merchant_ref.id *	string

* required

Example

{
    "external_ticket_id": "INV-2026-00412",
    "subject": "Invoice 412 shows the wrong GST amount",
    "description": "Please re-issue the invoice with the corrected tax.",
    "requester_name": "Priya Nair",
    "requester_email": "priya@example.com",
    "priority": "high",
    "merchant_ref": {
        "system": "sap",
        "id": "0010004711"
    }
}

Responses

201Ticket created.
200A ticket with this `external_ticket_id` already exists; it is returned unchanged.
401API key missing, invalid or revoked.
403The client lacks the permission switch this call needs.
422The request body failed validation.
429More than 60 requests in a minute. Wait and retry.

GET /api/v1/tickets/{ticket}

Get one ticket with its messages

Internal notes are included only if the client has the see internal notes switch.

Parameters

ticket

path, required

AurDesk ticket ID.

Responses

200The ticket and its message thread, oldest first.
401API key missing, invalid or revoked.
404The record does not exist, or is outside this client's scope.
429More than 60 requests in a minute. Wait and retry.

POST /api/v1/tickets/{ticket}/replies

Add a public reply to a ticket

Needs the client's reply switch. HTML tags in body are stripped.

Parameters

ticket

path, required

Request body (JSON)

body *	string
sender_name	string	Shown as the author; defaults to the client's name.

* required

Responses

201Reply added.
401API key missing, invalid or revoked.
403The client lacks the permission switch this call needs.
404The record does not exist, or is outside this client's scope.
422The request body failed validation.
429More than 60 requests in a minute. Wait and retry.

POST /api/v1/ingest/ewards

Create a ticket (eWards alias)

Identical to POST /api/v1/tickets. Kept so existing eWards connections keep working.

Request body (JSON)

external_ticket_id	string	Your own ID; makes the call idempotent.
subject *	string
description	string
requester_name	string
requester_email	string
priority	string — one of: low, normal, high, urgent
category_id	integer
merchant_id	string	The customer's ID as stored in AurDesk.
merchant_ref	object	The customer's code in an external system such as your ERP. Used only when `merchant_id` is absent or unmatched.
merchant_ref.system *	string	Case-insensitive, for example sap, tally, zoho.
merchant_ref.id *	string

* required

Responses

201Ticket created.
200A ticket with this `external_ticket_id` already exists; it is returned unchanged.
401API key missing, invalid or revoked.
403The client lacks the permission switch this call needs.
422The request body failed validation.

Embed

Open AurDesk inside your own application.

POST /api/v1/embed/token

Get a short-lived URL to show AurDesk inside your application

Call this from your backend just before rendering an iframe. What the URL opens depends on the client's embed audience, set when the client was created:

limited — a scoped ticket list for the client's scope.
staff — the full staff workspace, signed in as the active staff user whose email you send.
client — the customer portal, signed in as the active portal user whose email you send.

For staff and client, user_email must match an active account in the connected organisation, otherwise 422. The URL expires after the client's configured lifetime.

Request body (JSON)

user_email *	string
user_id	string	Your own identifier for this user.
user_name	string
context	string	Free-text hint about where the user came from.

* required

Responses

200Embed URL issued.
401API key missing, invalid or revoked.
422The request body failed validation.
429More than 60 requests in a minute. Wait and retry.

Billing data

Push customer financial data from your ERP or billing system.

POST /api/v1/integrations/{integration}/financials

Push one customer's financial summary

{integration} is the integration's slug, shown in AurDesk settings. The integration must be active and belong to an organisation your client may access, otherwise 404.

The request is accepted and processed in the background (202). Include the customer's ID in your system as merchant_external_id.

Recognised keys inside payload (all optional): status, health, outstanding_amount, current_mrr, churn_status, next_renewal_date, primary_contact_name, primary_contact_email. Any other keys are stored as received and kept with the record.

Parameters

integration

path, required

Integration slug.

Request body (JSON)

merchant_external_id *	string
idempotency_key *	string
payload *	object
payload.status	string
payload.health	string
payload.outstanding_amount	number
payload.current_mrr	number
payload.churn_status	string
payload.next_renewal_date	string
payload.primary_contact_name	string
payload.primary_contact_email	string

* required

Example

{
    "merchant_external_id": "0010004711",
    "idempotency_key": "sap-sync-2026-10-09-0010004711",
    "payload": {
        "status": "active",
        "outstanding_amount": 68912.5,
        "next_renewal_date": "2027-03-31"
    }
}

Responses

202Accepted for processing.
200This `idempotency_key` was already accepted; nothing was done.
401API key missing, invalid or revoked.
404Integration not found, not active, wrong type, or not in an organisation this client may access.
422The request body failed validation.
429More than 60 requests in a minute. Wait and retry.

HR data

Push attendance and employee directory data from your HRMS.

POST /api/v1/integrations/{integration}/attendance

Push a batch of attendance events

Up to 1,000 events per call. The integration must be an active attendance integration.

Parameters

integration

path, required

Request body (JSON)

idempotency_key *	string
events *	array
events[].employee_external_id *	string
events[].event_type *	string — one of: check_in_office, check_in_wfh, check_out, leave_full, leave_half_first, leave_half_second, absent
events[].effective_date *	string
events[].source_timestamp *	string

* required

Responses

202Accepted for processing.
200This `idempotency_key` was already accepted; nothing was done.
401API key missing, invalid or revoked.
404Integration not found, not active, wrong type, or not in an organisation this client may access.
422The request body failed validation.
429More than 60 requests in a minute. Wait and retry.

POST /api/v1/integrations/{integration}/employees

Push a batch of employee records

Up to 1,000 employees per call. The integration must be an active directory integration.

Parameters

integration

path, required

Request body (JSON)

idempotency_key *	string
employees *	array
employees[].employee_external_id *	string
employees[].name *	string
employees[].email *	string
employees[].department	string or null
employees[].job_title	string or null
employees[].is_department_head	boolean
employees[].employment_status *	string — one of: active, left
employees[].reporting_manager_external_id	string or null

* required

Responses

202Accepted for processing.
200This `idempotency_key` was already accepted; nothing was done.
401API key missing, invalid or revoked.
404Integration not found, not active, wrong type, or not in an organisation this client may access.
422The request body failed validation.
429More than 60 requests in a minute. Wait and retry.

Webhooks

Webhook subscriptions (target URL, secret, and which events) are created by an organisation admin in AurDesk settings. A subscription can listen to specific events or * for all.

Events: ticket.created, ticket.status_changed, ticket.assigned, ticket.escalated, ticket.reply_added, ticket.customer_replied, staff.login, work_log.day_report.

Headers on every delivery

X-SLAV-Webhook-Event — the event name.
X-SLAV-Delivery-ID — a UUID, identical across retries of the same delivery. Use it to ignore repeats.
X-SLAV-Webhook-Signature — sha256= followed by the hex HMAC-SHA256 of the raw request body, keyed with the subscription's secret. Compute it over the exact bytes you received, compare in constant time, and reject on mismatch.

Delivery. Respond with any 2xx within 10 seconds. Anything else, or a timeout, is retried up to 3 attempts in total, waiting about 10 seconds, then about 100 seconds. Attempts are logged in AurDesk. Deliveries run after the change is saved, in the background, and never block the user's action.

Replies and echoes. ticket.reply_added fires for every public reply: staff replies carry reply.author = "team"; replies posted through this API or the embedded view carry reply.author = "integration" with the posting client's integration_client_id. A system that both posts replies and subscribes should ignore events carrying its own integration_client_id (or any author = "integration"), so its own reply is never treated as new input.

Customer replies. ticket.customer_replied fires when a customer sends a follow-up on an existing ticket, on any channel: reply.channel is email, whatsapp, sms, chat_widget, aurapost or portal. It does not fire for the first message of a new ticket (ticket.created announces that), and it is a separate event from ticket.reply_added so subscribing to one never changes what you receive on the other. For email, reply.body is the new text without the quoted earlier thread.

Privacy. work_log.day_report carries only who, which date and a signal (submitted, unreported or late_report) — never log content.