Create an audit event

curl --request POST \
  --url https://api.assembly.com/v1/events \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "context": {},
  "eventDescription": "Client viewed the dashboard",
  "eventType": "customEvent",
  "actorId": "a1b2c3d4-e5f6-4711-8899-aabbccddeeff",
  "companyId": "c1d2e3f4-a5b6-4712-9988-ffeeddccbbaa",
  "lastActivityAt": "2024-02-20T14:05:00Z"
}
'

import requests

url = "https://api.assembly.com/v1/events"

payload = {
    "context": {},
    "eventDescription": "Client viewed the dashboard",
    "eventType": "customEvent",
    "actorId": "a1b2c3d4-e5f6-4711-8899-aabbccddeeff",
    "companyId": "c1d2e3f4-a5b6-4712-9988-ffeeddccbbaa",
    "lastActivityAt": "2024-02-20T14:05:00Z"
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    context: {},
    eventDescription: 'Client viewed the dashboard',
    eventType: 'customEvent',
    actorId: 'a1b2c3d4-e5f6-4711-8899-aabbccddeeff',
    companyId: 'c1d2e3f4-a5b6-4712-9988-ffeeddccbbaa',
    lastActivityAt: '2024-02-20T14:05:00Z'
  })
};

fetch('https://api.assembly.com/v1/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.assembly.com/v1/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'context' => [
        
    ],
    'eventDescription' => 'Client viewed the dashboard',
    'eventType' => 'customEvent',
    'actorId' => 'a1b2c3d4-e5f6-4711-8899-aabbccddeeff',
    'companyId' => 'c1d2e3f4-a5b6-4712-9988-ffeeddccbbaa',
    'lastActivityAt' => '2024-02-20T14:05:00Z'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.assembly.com/v1/events"

	payload := strings.NewReader("{\n  \"context\": {},\n  \"eventDescription\": \"Client viewed the dashboard\",\n  \"eventType\": \"customEvent\",\n  \"actorId\": \"a1b2c3d4-e5f6-4711-8899-aabbccddeeff\",\n  \"companyId\": \"c1d2e3f4-a5b6-4712-9988-ffeeddccbbaa\",\n  \"lastActivityAt\": \"2024-02-20T14:05:00Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.assembly.com/v1/events")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"context\": {},\n  \"eventDescription\": \"Client viewed the dashboard\",\n  \"eventType\": \"customEvent\",\n  \"actorId\": \"a1b2c3d4-e5f6-4711-8899-aabbccddeeff\",\n  \"companyId\": \"c1d2e3f4-a5b6-4712-9988-ffeeddccbbaa\",\n  \"lastActivityAt\": \"2024-02-20T14:05:00Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.assembly.com/v1/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"context\": {},\n  \"eventDescription\": \"Client viewed the dashboard\",\n  \"eventType\": \"customEvent\",\n  \"actorId\": \"a1b2c3d4-e5f6-4711-8899-aabbccddeeff\",\n  \"companyId\": \"c1d2e3f4-a5b6-4712-9988-ffeeddccbbaa\",\n  \"lastActivityAt\": \"2024-02-20T14:05:00Z\"\n}"

response = http.request(request)
puts response.read_body

{
  "actorId": "a1b2c3d4-e5f6-4711-8899-aabbccddeeff",
  "actorRole": "admin",
  "actorType": "internalUser",
  "apiKeyRef": "key_01HZX8K9P2",
  "automationId": "auto_01HZX8K9P2",
  "companyId": "c1d2e3f4-a5b6-4712-9988-ffeeddccbbaa",
  "context": {},
  "createdAt": "<string>",
  "creatorId": "<string>",
  "data": "<string>",
  "eventDescription": "Client created",
  "eventDetails": "Updated billing address",
  "eventTextEntity": "Acme Corp",
  "eventTextPrefix": "Client",
  "eventType": "clientCreated",
  "id": "<string>",
  "identityId": "<string>",
  "ip": "203.0.113.42",
  "isSuperAdminTriggered": false,
  "object": "<string>",
  "previousAttributes": {},
  "ref": "<string>",
  "source": "web",
  "updatedAt": "<string>",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
}

{
  "code": "<string>",
  "data": "<unknown>",
  "message": "<string>"
}

{
  "code": "<string>",
  "data": "<unknown>",
  "message": "<string>"
}

{
  "code": "<string>",
  "data": "<unknown>",
  "message": "<string>"
}

{
  "code": "<string>",
  "data": "<unknown>",
  "message": "<string>"
}

POST

events

Create an audit event

curl --request POST \
  --url https://api.assembly.com/v1/events \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "context": {},
  "eventDescription": "Client viewed the dashboard",
  "eventType": "customEvent",
  "actorId": "a1b2c3d4-e5f6-4711-8899-aabbccddeeff",
  "companyId": "c1d2e3f4-a5b6-4712-9988-ffeeddccbbaa",
  "lastActivityAt": "2024-02-20T14:05:00Z"
}
'

import requests

url = "https://api.assembly.com/v1/events"

payload = {
    "context": {},
    "eventDescription": "Client viewed the dashboard",
    "eventType": "customEvent",
    "actorId": "a1b2c3d4-e5f6-4711-8899-aabbccddeeff",
    "companyId": "c1d2e3f4-a5b6-4712-9988-ffeeddccbbaa",
    "lastActivityAt": "2024-02-20T14:05:00Z"
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    context: {},
    eventDescription: 'Client viewed the dashboard',
    eventType: 'customEvent',
    actorId: 'a1b2c3d4-e5f6-4711-8899-aabbccddeeff',
    companyId: 'c1d2e3f4-a5b6-4712-9988-ffeeddccbbaa',
    lastActivityAt: '2024-02-20T14:05:00Z'
  })
};

fetch('https://api.assembly.com/v1/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.assembly.com/v1/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'context' => [
        
    ],
    'eventDescription' => 'Client viewed the dashboard',
    'eventType' => 'customEvent',
    'actorId' => 'a1b2c3d4-e5f6-4711-8899-aabbccddeeff',
    'companyId' => 'c1d2e3f4-a5b6-4712-9988-ffeeddccbbaa',
    'lastActivityAt' => '2024-02-20T14:05:00Z'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.assembly.com/v1/events"

	payload := strings.NewReader("{\n  \"context\": {},\n  \"eventDescription\": \"Client viewed the dashboard\",\n  \"eventType\": \"customEvent\",\n  \"actorId\": \"a1b2c3d4-e5f6-4711-8899-aabbccddeeff\",\n  \"companyId\": \"c1d2e3f4-a5b6-4712-9988-ffeeddccbbaa\",\n  \"lastActivityAt\": \"2024-02-20T14:05:00Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.assembly.com/v1/events")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"context\": {},\n  \"eventDescription\": \"Client viewed the dashboard\",\n  \"eventType\": \"customEvent\",\n  \"actorId\": \"a1b2c3d4-e5f6-4711-8899-aabbccddeeff\",\n  \"companyId\": \"c1d2e3f4-a5b6-4712-9988-ffeeddccbbaa\",\n  \"lastActivityAt\": \"2024-02-20T14:05:00Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.assembly.com/v1/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"context\": {},\n  \"eventDescription\": \"Client viewed the dashboard\",\n  \"eventType\": \"customEvent\",\n  \"actorId\": \"a1b2c3d4-e5f6-4711-8899-aabbccddeeff\",\n  \"companyId\": \"c1d2e3f4-a5b6-4712-9988-ffeeddccbbaa\",\n  \"lastActivityAt\": \"2024-02-20T14:05:00Z\"\n}"

response = http.request(request)
puts response.read_body

{
  "actorId": "a1b2c3d4-e5f6-4711-8899-aabbccddeeff",
  "actorRole": "admin",
  "actorType": "internalUser",
  "apiKeyRef": "key_01HZX8K9P2",
  "automationId": "auto_01HZX8K9P2",
  "companyId": "c1d2e3f4-a5b6-4712-9988-ffeeddccbbaa",
  "context": {},
  "createdAt": "<string>",
  "creatorId": "<string>",
  "data": "<string>",
  "eventDescription": "Client created",
  "eventDetails": "Updated billing address",
  "eventTextEntity": "Acme Corp",
  "eventTextPrefix": "Client",
  "eventType": "clientCreated",
  "id": "<string>",
  "identityId": "<string>",
  "ip": "203.0.113.42",
  "isSuperAdminTriggered": false,
  "object": "<string>",
  "previousAttributes": {},
  "ref": "<string>",
  "source": "web",
  "updatedAt": "<string>",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
}

{
  "code": "<string>",
  "data": "<unknown>",
  "message": "<string>"
}

{
  "code": "<string>",
  "data": "<unknown>",
  "message": "<string>"
}

{
  "code": "<string>",
  "data": "<unknown>",
  "message": "<string>"
}

{
  "code": "<string>",
  "data": "<unknown>",
  "message": "<string>"
}

Authorizations

X-API-KEY

string

header

required

Body

application/json

Audit event to create

context

object

required

Context carries event-specific metadata as arbitrary key/value pairs.

eventDescription

string

required

EventDescription is a human-readable description of the event (max 500 characters).

Maximum string length: 500

Example:

"Client viewed the dashboard"

eventType

string

required

CustomEventType is the event type to record (max 100 characters).

Maximum string length: 100

Example:

"customEvent"

actorId

string

ActorID is the ID of the actor the event is attributed to.

Example:

"a1b2c3d4-e5f6-4711-8899-aabbccddeeff"

companyId

string

CompanyID is the company the actor belongs to, when the actor is a client user.

Example:

"c1d2e3f4-a5b6-4712-9988-ffeeddccbbaa"

lastActivityAt

string<date-time>

LastActivityAt is the frontend's latest evidence of user activity for the session this event pertains to. On sessionEnded it stamps the entry's CreatedAt so the inactivity timer reports the actual moment the user became idle; on sessionStarted it carries the prior session's last-activity forward so the orphan backfill can stamp the synthetic sessionEnded accurately.

Example:

"2024-02-20T14:05:00Z"

Response

Created

actorId

string

ActorID is the ID of the user or system actor that triggered the event.

Example:

"a1b2c3d4-e5f6-4711-8899-aabbccddeeff"

actorRole

string

ActorRole is the normalized role of the actor (e.g. "admin", "staff"). Internal-only.

Example:

"admin"

actorType

enum<string>

ActorType identifies whether the actor is an internal user or a client user.

Available options:

internalUser,

clientUser

Example:

"internalUser"

apiKeyRef

string

APIKeyRef references the API key used for platform-API-sourced events. Internal-only.

Example:

"key_01HZX8K9P2"

automationId

string

AutomationID is the ID of the automation that triggered the event, when applicable.

Example:

"auto_01HZX8K9P2"

companyId

string

CompanyID is the ID of the company the actor belongs to, when the actor is a client user.

Example:

"c1d2e3f4-a5b6-4712-9988-ffeeddccbbaa"

context

object

Context carries event-specific metadata as arbitrary key/value pairs.

createdAt

string

creatorId

string

data

string

eventDescription

string

EventDescription is a human-readable description of the event.

Example:

"Client created"

eventDetails

string

Example:

"Updated billing address"

eventTextEntity

string

Example:

"Acme Corp"

eventTextPrefix

string

EventTextPrefix / EventTextEntity / EventDetails are computed at read time by FormatEvent (see event_formatter.go) and exposed to the internal audit log page and the CSV export so both render identical text. Not persisted, and tagged omitexternal — these are UI helpers, not part of the public platform API contract.

Prefix and Entity intentionally omit omitempty: FormatEvent sets one of them to "" on purpose for events like messageSent (entity is the linked label, no prefix). With omitempty the empty string would drop from the wire, the client would ?? back to eventDescription, and the row would render as Message sent "Message sent" instead of a single linked Message sent.

Example:

"Client"

eventType

enum<string>

EventType categorizes the event.

Available options:

userLoggedIn,

userLoggedOut,

userLoginSucceeded,

userLoginFailed,

passwordReset,

passwordChanged,

googleDelinked,

magicLinkSent,

workspaceMfaEnabled,

workspaceMfaDisabled,

clientCreated,

clientActivated,

clientUpdated,

clientDeleted,

clientInvited,

companyCreated,

companyUpdated,

companyCustomFieldsUpdated,

companyDeleted,

clientCustomFieldsUpdated,

fileCreated,

fileUpdated,

fileDeleted,

folderCreated,

folderUpdated,

folderDeleted,

linkCreated,

linkUpdated,

linkDeleted,

invoiceCreated,

invoiceInitiated,

invoicePaid,

invoiceUpdated,

invoiceDeleted,

invoiceVoided,

invoiceDownloaded,

refundRequested,

refundSucceeded,

refundFailed,

messageSent,

messageChannelCreated,

messageChannelDeleted,

taskCreated,

taskUpdated,

taskDeleted,

taskArchived,

taskCompleted,

paymentSucceeded,

paymentFailed,

subscriptionCreated,

subscriptionCancelled,

priceCreated,

productCreated,

productUpdated,

contractRequested,

contractCompleted,

contractDownloaded,

fileDownloaded,

fileBatchDownloaded,

fileBatchDeleted,

noteCreated,

noteUpdated,

noteDeleted,

internalUserCreated,

internalUserDeleted,

internalUserAccessLevelChanged,

internalUserClientVisibilitySet,

apiKeyCreated,

apiKeyDeleted,

formCreated,

formEdited,

formAssigned,

formResponseCompleted,

customEvent,

sessionStarted,

sessionEnded

Example:

"clientCreated"

string

identityId

string

IP is the client IP address that triggered the event.

Example:

"203.0.113.42"

isSuperAdminTriggered

boolean

IsSuperAdminTriggered is set when the event originated from an Assembly super-admin proxy session (the admin signed in via /admin and is acting on behalf of a portal user). Hidden from external / platform-API consumers via omitexternal.

Example:

false

object

string

previousAttributes

object

ref

string

source

enum<string>

Source indicates where the event originated from.

Available options:

web,

platform,

automation,

system

Example:

"web"

updatedAt

string

userAgent

string

UserAgent is the User-Agent header of the request that triggered the event. UserAgent and IP are intentionally exposed to external consumers (no omitexternal tag). These fields contain PII; consumers are responsible for GDPR/CCPA compliance

Example:

"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"

List audit events Get audit event by ID

⌘I

Getting started

Webhooks

Core Resources

CRM

Messaging

Billing

Files

Contracts

Forms

Tasks

Token

Others

Create an audit event

Authorizations

Body

Response