Custom Push Source API

curl --request POST \
  'https://api.us-east-1.livingsecurity.ai/api/v1/push-ingest/custom-phishing-sim/events' \
  --header 'Authorization: Bearer <access-key>' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "email": "person@example.com",
      "event_at": "2026-09-21T14:30:00Z",
      "action": "reported"
    }
  ]'

curl --request POST \
  'https://api.us-east-1.livingsecurity.ai/api/v1/push-ingest/custom-phishing-sim/events' \
  --header 'Authorization: Bearer <access-key>' \
  --header 'Content-Type: text/csv' \
  --data-binary '@events.csv'

{
  "runId": "01a0c45f-ae40-7e5f-8a9b-0c1d2e3f4a5b",
  "recordsAccepted": 1,
  "integrationKey": "custom-phishing-sim",
  "streamName": "events"
}

{
  "statusCode": 400,
  "timestamp": "2026-09-22T14:30:00.000Z",
  "path": "/api/v1/push-ingest/custom-phishing-sim/events",
  "message": "Request body is not valid JSON. Send a JSON array of objects, or set Content-Type: text/csv to push a CSV.",
  "error": "Bad Request"
}

curl --request POST \
  'https://api.us-east-1.livingsecurity.ai/api/v1/push-ingest/custom-phishing-sim/events' \
  --header 'Authorization: Bearer <access-key>' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "email": "person@example.com",
      "event_at": "2026-09-21T14:30:00Z",
      "action": "reported"
    }
  ]'

curl --request POST \
  'https://api.us-east-1.livingsecurity.ai/api/v1/push-ingest/custom-phishing-sim/events' \
  --header 'Authorization: Bearer <access-key>' \
  --header 'Content-Type: text/csv' \
  --data-binary '@events.csv'

{
  "runId": "01a0c45f-ae40-7e5f-8a9b-0c1d2e3f4a5b",
  "recordsAccepted": 1,
  "integrationKey": "custom-phishing-sim",
  "streamName": "events"
}

{
  "statusCode": 400,
  "timestamp": "2026-09-22T14:30:00.000Z",
  "path": "/api/v1/push-ingest/custom-phishing-sim/events",
  "message": "Request body is not valid JSON. Send a JSON array of objects, or set Content-Type: text/csv to push a CSV.",
  "error": "Bad Request"
}

Use a Custom Push Source when a system sends records to Living Security instead of being polled by a Catalog connector. The sender can submit JSON arrays or CSV files to a regional HTTPS endpoint.

Before you begin

You need:

permission to manage integrations and access keys in Living Security
a server-side sender that can make HTTPS POST requests
the Living Security region for your organization
a stable source name and at least one stream name

Source names and stream names are permanent routing keys. Source names must be 1–64 lowercase letters, digits, or hyphens. Stream names also allow underscores. Both must start with a letter or digit.

Treat the API access key as a secret. Do not place it in browser code, commit it to source control, or send it in a support ticket.

1. Register the source and streams

Open Custom Push Source

Go to Settings → Integrations → Catalog, find Custom Push Source, and select Add.

Name the source

Enter the source routing key and an optional description. For example, use custom-phishing-sim rather than a display name with spaces.

Add streams

Add each stream the sender will use. The source and stream pair must exist before the first push; an unknown pair returns 404 Not Found.

Save the source

After creation, open the source under Settings → Integrations → Connected. Its Push via API view shows the endpoint pattern and recent runs.

2. Create a push-ingest key

Go to Settings → Access Keys, select Create Access Key, and choose the Push Ingest scope. Copy the generated value immediately; it is shown only once. The key is bound to one Living Security organization. The push request does not need an organization header. See API Access Keys for rotation and revocation.

3. Choose the regional endpoint

Use the hostname for the Living Security organization:

Region	Base URL
United States	`https://api.us-east-1.livingsecurity.ai/api/v1`
European Union	`https://api.eu-west-1.livingsecurity.ai/api/v1`

Append /push-ingest/{integrationKey}/{streamName}. The path is case-sensitive and must exactly match the registered source and stream.

string

required

The registered source name. Use 1–64 lowercase letters, digits, or hyphens, starting with a letter or digit.

string

required

The registered stream name. The same rules apply, and underscores are also allowed.

string

required

Send the push-ingest access key as Bearer <access-key>.

string

Use application/json for JSON or text/csv for CSV. The server can also detect a JSON array when this header is omitted.

string

Optional organization UUID. The access key already determines the organization. If you send this header, it must match the key’s organization; it cannot select another organization.

Request body

Send a top-level, non-empty JSON array of objects or CSV file bytes with a header row. There is no named JSON wrapper field. Each batch can contain up to 10,000 records and 10 MB.

4. Send a JSON batch

Send a non-empty JSON array whose elements are objects. Content-Type: application/json is recommended and is required by many sending products even though Living Security can detect an array body without it.

curl --request POST \
  'https://api.us-east-1.livingsecurity.ai/api/v1/push-ingest/custom-phishing-sim/events' \
  --header 'Authorization: Bearer <access-key>' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "email": "person@example.com",
      "event_at": "2026-09-21T14:30:00Z",
      "action": "reported"
    }
  ]'

curl --request POST \
  'https://api.us-east-1.livingsecurity.ai/api/v1/push-ingest/custom-phishing-sim/events' \
  --header 'Authorization: Bearer <access-key>' \
  --header 'Content-Type: text/csv' \
  --data-binary '@events.csv'

A successful request returns 202 Accepted. The error tab shows a 400 Bad Request when the JSON body is malformed:

{
  "runId": "01a0c45f-ae40-7e5f-8a9b-0c1d2e3f4a5b",
  "recordsAccepted": 1,
  "integrationKey": "custom-phishing-sim",
  "streamName": "events"
}

{
  "statusCode": 400,
  "timestamp": "2026-09-22T14:30:00.000Z",
  "path": "/api/v1/push-ingest/custom-phishing-sim/events",
  "message": "Request body is not valid JSON. Send a JSON array of objects, or set Content-Type: text/csv to push a CSV.",
  "error": "Bad Request"
}

Acceptance means the batch was stored for asynchronous processing. It does not mean every record has already been interpreted into activity. For the 400 example, correct the JSON or send CSV with Content-Type: text/csv, then retry.

string

required

The run ID for this accepted batch. Keep it to check processing status.

number

required

The number of records accepted and stored.

string

required

The source name used for this push.

string

required

The stream name used for this push.

Send CSV instead

Set Content-Type: text/csv and send the file bytes, as shown in the CSV file request example above. The first row supplies field names. Boolean text becomes a boolean and ordinary numeric text becomes a number. Leading-zero values, unsafe large integers, dates, and other text remain strings. Empty cells omit that field. Malformed rows, unbalanced quotes, and UTF-16 files are rejected.

Request limits and retries

Contract	Current value
Maximum records	10,000 per request
Maximum request body	10 MB
Per-organization request rate	600 requests per 60 seconds

Split larger exports into batches that satisfy both limits. Wait for each response and retain the returned runId in sender logs.

Response	Meaning	Sender action
`202`	Batch accepted	Record the `runId`; do not immediately resend
`400`	Invalid name, JSON, CSV, record count, or body	Correct the request; do not retry unchanged
`401`	Missing, expired, revoked, or invalid key	Replace the key and use the Bearer header
`403`	Key lacks the required scope	Create a key with Push Ingest scope
`404`	Source or stream is not registered	Register the exact pair or correct the URL
`413`	Request body exceeds 10 MB	Split the batch into smaller requests
`429`	Temporary IP-level throttling	Honor `Retry-After` when present and back off
`503`	Organization rate bucket or limiter unavailable	Wait for `Retry-After`, then resend the same batch

The normal authenticated organization limit returns 503, not 429, so webhook senders treat it as retriable. A 503 is returned before the batch is stored; resending that same batch after the stated interval does not duplicate an accepted run.

Verify the data flow

Open the Custom Push Source and review Push History. Confirm the stream, record count, key attribution, and processing status. Data with a maintained interpreter can then become people and normalized activity. Data without an interpreter remains stored but does not produce activity.

Use exact field names and payload shape from the provider-specific guide when one exists. A successful 202 proves delivery, not that an arbitrary schema maps to Living Security activity.

Troubleshooting checklist

Copy the endpoint from the correct source and replace the stream placeholder.
Send the access key as Authorization: Bearer …; x-api-key is not accepted.
Confirm the body is a top-level JSON array, not a single object or an envelope around the records.
Confirm the source and stream spelling, including hyphens, underscores, and case.
Review Push History before resending a batch whose response was lost.
When contacting Living Security Support, include the organization, source, stream, request time, runId when available, and response status. Do not include the access key or event payload.

Zscaler ZIA Cloud NSS

Configure a supported Zscaler web-log feed with the exact source, stream, headers, and JSON shape.

API Access Keys

Create, rotate, and revoke scoped credentials.

Signal Data Sources

Learn how interpreted integration activity supports signals.

Integrations

Integration setup

Catalog

Outbound Channels

Before you begin

1. Register the source and streams

2. Create a push-ingest key

3. Choose the regional endpoint

Request body

4. Send a JSON batch

Send CSV instead

Request limits and retries

Verify the data flow

Troubleshooting checklist

Zscaler ZIA Cloud NSS

API Access Keys

Signal Data Sources

Integrations

Integration setup

Catalog

Outbound Channels

​Before you begin

​1. Register the source and streams

​2. Create a push-ingest key

​3. Choose the regional endpoint

​Request body

​4. Send a JSON batch

​Send CSV instead

​Request limits and retries

​Verify the data flow

​Troubleshooting checklist

​Related

Zscaler ZIA Cloud NSS

API Access Keys

Signal Data Sources

Before you begin

1. Register the source and streams

2. Create a push-ingest key

3. Choose the regional endpoint

Request body

4. Send a JSON batch

Send CSV instead

Request limits and retries

Verify the data flow

Troubleshooting checklist

Related