Contacts & Companies

⚠️ Preview — not yet in the public API

The endpoints on this page are part of the AurionAI helpdesk and are currently accessible only through an authenticated dashboard session. They are not yet exposed through public API keys — a request authenticated with X-API-Key returns 403. Public API-key access is planned. The reference below documents the intended contract.

The Contacts API (v2) manages end-user identities in the Aurion CS helpdesk. Contacts are the people who submit support requests; companies group contacts by organization.

The contact and company CRUD endpoints live under /api/v2/* and the sync endpoints under /api/v1/contacts/*. Both are reached today through a dashboard session and are gated by tenant RBAC permissions (see Required Scopes). The X-API-Key: itsm_sk_live_… examples below document the intended future public-API contract.

List Contacts

cURL

curl "https://apps.aurionai.net/api/v2/contacts?limit=10&search=smith" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Python

import requests

response = requests.get(
    "https://apps.aurionai.net/api/v2/contacts",
    headers={"X-API-Key": "itsm_sk_live_xxxx"},
    params={"limit": 10, "search": "smith"},
)
contacts = response.json()

TypeScript

const response = await fetch(
  "https://apps.aurionai.net/api/v2/contacts?limit=10&search=smith",
  {
    headers: { "X-API-Key": "itsm_sk_live_xxxx" },
  }
);
const contacts = await response.json();

Response:

The list envelope is resource-named (items), not data:

{
  "items": [
    {
      "id": "ct_456",
      "company_id": "co_789",
      "company_name": "Acme Corp",
      "email": "jane@example.com",
      "phone": "+33612345678",
      "client_id": null,
      "external_id": null,
      "first_name": "Jane",
      "last_name": "Smith",
      "role": "IT Manager",
      "locale": "fr",
      "timezone": "Europe/Paris",
      "last_seen_at": "2026-04-01T08:30:00Z",
      "conversation_count": 4,
      "unsubscribed_from_emails": false,
      "custom_attrs": {},
      "tags": ["vip"],
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-04-01T08:30:00Z",
      "deleted_at": null
    }
  ],
  "total": 3,
  "limit": 10,
  "offset": 0
}

Query Parameters:

Parameter	Type	Description
`search`	string	Search by name or email
`company_id`	string	Filter by company
`tag`	string	Filter by a single tag (max length 100). Single value — no comma-separated multi-tag support.
`contact_kind`	string	Filter by kind: `end_user`, `agent_proxy`, or `vendor`
`include_deleted`	boolean	Include soft-deleted contacts (default: `false`)
`limit`	integer	Results per page (default: 50, max: 200)
`offset`	integer	Number of results to skip (default: 0)

Create Contact

At least one of email, first_name, last_name, phone, or external_id is required. There is no name field — use first_name / last_name.

curl -X POST "https://apps.aurionai.net/api/v2/contacts" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "+33698765432",
    "company_id": "co_789",
    "role": "Engineer",
    "locale": "en",
    "timezone": "Europe/Paris",
    "external_id": "crm-1042",
    "client_id": "acct-77",
    "unsubscribed_from_emails": false,
    "tags": ["engineering"],
    "custom_attrs": {}
  }'

Returns 201 Created with the full ContactV2 object (same shape as the list items above).

Accepted body fields: company_id, email (max 255), phone (max 50), external_id, first_name (max 100), last_name (max 100), role (max 100), locale (max 10), timezone (max 50), client_id (max 120), unsubscribed_from_emails (default false), tags, custom_attrs.

Error responses:

409 Conflict — { "detail": "..." } when the email (or external_id) already belongs to a contact in this tenant.
422 Unprocessable Entity — Pydantic validation errors, the "at least one of email/first_name/last_name/phone/external_id" requirement, or business-rule violations (FK / constraint failures may return a { "detail": { "business_rule_errors": [...] } }-style body).

Get Contact

curl "https://apps.aurionai.net/api/v2/contacts/ct_456" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Returns the ContactV2 object, or 404 Not Found ({ "detail": "Contact not found" }).

Update Contact

curl -X PATCH "https://apps.aurionai.net/api/v2/contacts/ct_456" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+33698765432",
    "tags": ["vip", "engineering"]
  }'

All body fields are optional on PATCH; only the provided fields are updated.

Delete & Restore Contact

Contacts are soft-deleted (not permanently removed) and can be restored:

Delete

curl -X DELETE "https://apps.aurionai.net/api/v2/contacts/ct_456" \
  -H "X-API-Key: itsm_sk_live_xxxx"

DELETE returns 204 No Content (empty body) on success, or 404 Not Found if the contact does not exist.

Restore

curl -X POST "https://apps.aurionai.net/api/v2/contacts/ct_456/restore" \
  -H "X-API-Key: itsm_sk_live_xxxx"

restore returns the restored ContactV2 object, 404 Not Found ({ "detail": "Contact not found or not deleted" }) if the contact is not soft-deleted, or 409 Conflict if restoring would collide with a live contact's email or external_id.

Search Contacts

Multi-field fuzzy lookup (used by the dashboard caller-identification modal):

curl -X POST "https://apps.aurionai.net/api/v2/contacts/search" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "first_name": "Jane",
    "phone": "+33612345678",
    "phone_region": "FR",
    "limit": 10
  }'

Body fields: email (max 320), first_name (max 120), last_name (max 120), phone (max 40), phone_region (ISO 3166-1 alpha-2, max 2), client_id (max 120), limit (default 10, 1–50).

Response:

{
  "results": [
    {
      "id": "ct_456",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "phone": "+33612345678",
      "client_id": null,
      "company_id": "co_789",
      "company_name": "Acme Corp"
    }
  ]
}

Contact Activity

View the activity history for a contact — conversation events, field changes, and related metadata:

curl "https://apps.aurionai.net/api/v2/contacts/ct_456/activity?limit=20" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Query Parameters:

Parameter	Type	Description
`activity_type`	string	Filter by activity type
`limit`	integer	Results per page (default: 50, max: 200)
`offset`	integer	Number of results to skip (default: 0)

Response:

{
  "items": [
    {
      "id": "ev_001",
      "conversation_id": "cv_321",
      "conversation_subject": "Laptop won't boot",
      "activity_type": "status_change",
      "actor_id": "us_12",
      "actor_name": "Agent Lee",
      "field_name": "status",
      "old_value": "open",
      "new_value": "resolved",
      "metadata": {},
      "created_at": "2026-04-01T09:00:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Contact Attachments

List files attached to a contact's conversations:

curl "https://apps.aurionai.net/api/v2/contacts/ct_456/attachments?limit=20" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Query Parameters:

Parameter	Type	Description
`limit`	integer	Results per page (default: 50, max: 200)
`offset`	integer	Number of results to skip (default: 0)

Response:

{
  "items": [
    {
      "id": "at_900",
      "conversation_id": "cv_321",
      "conversation_subject": "Laptop won't boot",
      "message_id": "msg_55",
      "uploader_id": "ct_456",
      "uploader_name": "Jane Smith",
      "filename": "screenshot.png",
      "content_type": "image/png",
      "size_bytes": 20480,
      "storage_backend": "local",
      "source": "email",
      "created_at": "2026-04-01T09:05:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Companies

Companies group contacts by organization and enable company-level reporting.

List Companies

curl "https://apps.aurionai.net/api/v2/companies?search=acme" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Query Parameters:

Parameter	Type	Description
`search`	string	Search by company name
`tag`	string	Filter by a single tag (max length 100). Single value — no comma-separated multi-tag support.
`include_deleted`	boolean	Include soft-deleted companies (default: `false`)
`limit`	integer	Results per page (default: 50, max: 200)
`offset`	integer	Number of results to skip (default: 0)

Response:

The envelope is items (not data); each item is a CompanyV2 object:

{
  "items": [
    {
      "id": "co_789",
      "name": "Acme Corp",
      "domain": "acme.com",
      "industry": "Manufacturing",
      "size": "200-500",
      "plan": "enterprise",
      "website": "https://acme.com",
      "logo_url": null,
      "monthly_spend": 1200.0,
      "sla_tier": "gold",
      "tags": ["enterprise"],
      "custom_attrs": {},
      "notes": null,
      "contact_count": 12,
      "conversation_count": 34,
      "created_at": "2026-01-10T10:00:00Z",
      "updated_at": "2026-04-01T08:30:00Z",
      "deleted_at": null
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Create Company

curl -X POST "https://apps.aurionai.net/api/v2/companies" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "domain": "acme.com",
    "industry": "Manufacturing",
    "size": "200-500",
    "plan": "enterprise",
    "website": "https://acme.com",
    "sla_tier": "gold",
    "tags": ["enterprise"],
    "custom_attrs": {},
    "notes": "Strategic account"
  }'

name is required (1–255 chars). Returns 201 Created with the CompanyV2 object.

Update Company

curl -X PATCH "https://apps.aurionai.net/api/v2/companies/co_789" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["enterprise", "priority"]
  }'

Delete / Restore Company

Companies are soft-deleted and can be restored:

Delete

curl -X DELETE "https://apps.aurionai.net/api/v2/companies/co_789" \
  -H "X-API-Key: itsm_sk_live_xxxx"

DELETE returns 200 OK with the IDs of unlinked contacts (it does not return 204):

{
  "id": "co_789",
  "unlinked_contacts": 12
}

Restore

curl -X POST "https://apps.aurionai.net/api/v2/companies/co_789/restore" \
  -H "X-API-Key: itsm_sk_live_xxxx"

restore returns the restored CompanyV2 object, or 404 Not Found ({ "detail": "Company not found or not deleted" }).

Contact Sync

Sync contacts from your external CS provider (Freshdesk or Zendesk). These endpoints are under /api/v1/contacts and require a dashboard admin session (require_config_admin) — they are not callable with an API key and are not in the public API-key allowlist.

Trigger Contact Sync

curl -X POST "https://apps.aurionai.net/api/v1/contacts/sync?mode=manual" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Query Parameters:

Parameter	Type	Description
`mode`	string	`manual` (differential, default) or `full` (with reconciliation — deactivates stale records)

Response:

{
  "success": true,
  "message": "Contact sync completed",
  "synced": 17,
  "created": 12,
  "updated": 5,
  "deactivated": 0,
  "errors": 0,
  "duration_seconds": 3.42
}

Get Sync Settings

curl "https://apps.aurionai.net/api/v1/contacts/settings" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

{
  "auto_sync_enabled": true,
  "sync_interval_hours": 8,
  "last_synced_at": "2026-04-09T06:00:00Z"
}

When no settings have been saved, the defaults are auto_sync_enabled: false, sync_interval_hours: 24, last_synced_at: null.

Update Sync Settings

curl -X PUT "https://apps.aurionai.net/api/v1/contacts/settings" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_sync_enabled": true,
    "sync_interval_hours": 12
  }'

sync_interval_hours must be between 1 and 168 when provided.

Sync History

View recent sync operations and their outcomes. The response wraps the records under entries:

curl "https://apps.aurionai.net/api/v1/contacts/sync-history?limit=10" \
  -H "X-API-Key: itsm_sk_live_xxxx"

limit defaults to 10 (1–50).

Response:

{
  "entries": [
    {
      "id": "sh_001",
      "sync_type": "contact",
      "provider_type": "freshdesk",
      "mode": "manual",
      "started_at": "2026-04-09T06:00:00Z",
      "completed_at": "2026-04-09T06:00:03Z",
      "status": "completed",
      "stats": { "created": 12, "updated": 5 },
      "error_message": null
    }
  ]
}

Contacts vs Requesters

Contacts (v2) are identities in the Aurion CS helpdesk — managed via this API
Requesters (v1) are identities synced from your external ITSM provider (Freshservice, HaloITSM, etc.)

Both can coexist when running ITSM + CS simultaneously.

Conversations — Manage conversations for contacts
Custom Fields — Add custom data fields to contacts
Webhooks — Subscribe to contact.* events (contact.created, contact.updated, contact.deleted)

Required Scopes

Contacts and companies use separate resources, and the contact/company endpoints are enforced as tenant RBAC permissions through a dashboard session — these are not the {resource}:{read|write} pairs derived for API keys, and the underlying /api/v2/* paths are denied to API keys regardless. The v1 sync endpoints require a dashboard admin session (require_config_admin), not a config:* API-key scope.

Permission	Endpoints
`contacts:read`	`GET /v2/contacts`, `GET /v2/contacts/:id`, `GET /v2/contacts/:id/activity`, `GET /v2/contacts/:id/attachments`, `POST /v2/contacts/search`
`contacts:write`	`POST /v2/contacts`, `PATCH /v2/contacts/:id`
`contacts:delete`	`DELETE /v2/contacts/:id`, `POST /v2/contacts/:id/restore`
`companies:read`	`GET /v2/companies`, `GET /v2/companies/:id`
`companies:write`	`POST /v2/companies`, `PATCH /v2/companies/:id`
`companies:delete`	`DELETE /v2/companies/:id`, `POST /v2/companies/:id/restore`
Dashboard admin (`require_config_admin`)	`POST /v1/contacts/sync`, `GET /v1/contacts/settings`, `PUT /v1/contacts/settings`, `GET /v1/contacts/sync-history`

Contacts & Companies

On this page