> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stora.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Record integration activity

> Create a Timeline Event that shows an action from your integration on a contact's timeline.

Record actions from your integration as Timeline Events so operators can see what happened in Stora. This guide records an outbound call against a contact.

## Before you start

You need:

* An access token with `public.timeline_event:write`. You do not need source or template read scopes to create events with known IDs.
* The source and template IDs for your integration. Follow the setup below for either a partner app or a custom operator integration.

For the outbound-call example in this guide, you also need the ID of a contact in the connected operator's account. Other event types use the references required by their template.

To run this guide's `curl` examples, set `STORA_ACCESS_TOKEN` in your shell to your access token. `STORA_ACCESS_TOKEN` is an example variable name, not an API requirement.

## Choose your integration's setup

A Timeline Source identifies your integration on the operator's timeline. A Timeline Template defines the event's message and variables. Source setup differs between partner apps and custom integrations built for one operator.

**Partner app**

Ask Stora to create a global source for your integration before you release it. Stora provides a source ID that you can hardcode in your integration. The source is available to all operators, so use the same ID across all operator connections. You do not need to create or discover a source for each operator.

Agree with Stora on the templates that fit the actions your integration records. If no existing template fits your use case, request one in advance.

Hardcode the agreed template IDs in your integration. Map each supported action to its intended template. Do not accept arbitrary source or template IDs from operators or incoming requests, and do not discover templates at runtime.

> [!WARNING]
>
> Do not include template-related scopes in your partner application's requested scopes, including `public.timeline_template:read`. Use hardcoded template IDs to limit the integration to its intended events and prevent template misuse.

**Operator integration**

For an operator's own integration, create a custom source in that operator's Backoffice. You do not need Stora to provision a global source.

1. In **Settings**, open **Developers**, then **Timeline events**.
2. Under **Sources**, click **Edit**.
3. Click **Add Source**.
4. Enter the integration's **Name**. Optionally add an **Icon** and **Website URL**.
5. Click **Create Source**.

The custom source is available only to the operator where you created it. Save its ID in that operator's integration configuration. Do not reuse the ID for another operator.

To retrieve the source ID during setup, use [List all Sources](https://docs.stora.co/2025-09/api-reference/timeline-sources/list-all-sources.md) with a credential that has `public.timeline_source:read`.

For templates, return to **Timeline events** and click **View** under **Templates** to browse the shared template library. Creating a custom source does not create an operator-specific template. If no template fits your use case, ask Stora for one.

To retrieve a template ID during setup, use [List all Templates](https://docs.stora.co/2025-09/api-reference/timeline-templates/list-all-templates.md) with `public.timeline_template:read`. Save the chosen ID in the integration's configuration. Source and template read scopes are not required for event creation once you have the IDs.

## Prepare the example's event data

For the **Outbound call** template used below, provide the `contact` reference. You can also supply a `duration` string in `variables`.

Other templates can require references such as a unit, subscription, or invoice. Check the references and variables for your chosen template. For a partner app, confirm these requirements with Stora during setup.

Creating an event with a missing required reference fails. Custom variables can be incomplete on creation, but omitted values can leave the rendered message incomplete. Supply the values needed to describe the action.

## Create the event

Generate an idempotency key once for this action:

```bash theme={null}
EVENT_KEY="$(uuidgen)"
```

Replace `tsrc_REPLACE` with the source ID for your integration's setup and `aetpl_REPLACE` with the **Outbound call** template ID. For a partner app, use the hardcoded IDs agreed with Stora. For a custom operator integration, use the IDs saved in its configuration.

Replace `con_REPLACE` with the contact ID for this example and the external record details with your own record ID and URL.

```bash theme={null}
curl --request POST \
	'https://public-api.stora.co/2025-09/timeline/events' \
	--header "Authorization: Bearer $STORA_ACCESS_TOKEN" \
	--header 'Content-Type: application/json' \
	--header "Idempotency-Key: $EVENT_KEY" \
	--data '{
		"source": {"id": "tsrc_REPLACE"},
		"template": {"id": "aetpl_REPLACE"},
		"contact": {"id": "con_REPLACE"},
		"description": "Discussed the requested move-in date.",
		"variables": {"duration": "2 minutes"},
		"external": {
			"id": "call_123",
			"url": "https://example.com/calls/call_123"
		}
	}'
```

A successful request returns `201` with an `event` object. Save `event.id` beside your originating record. Open the contact in Stora Backoffice and confirm that the call appears on its timeline with your source and external link.

`description` adds a note alongside the template message. It does not replace the message. `external.id` identifies the record in your system, and `external.url` links to that record.

## Handle retries and corrections

If the create request times out, retry with the same body and `EVENT_KEY`. Do not generate a new key for a retry. Use a different key for a different action. An external record ID is not a substitute for an [idempotency key](https://docs.stora.co/2025-09/guides/requests.md#idempotent-requests).

If you need to correct an event, use its saved ID with [Update an Event](https://docs.stora.co/2025-09/api-reference/timeline-events/update-an-event.md). Updates validate required custom variables too, so preserve the values needed by the template.

Only update or [delete](https://docs.stora.co/2025-09/api-reference/timeline-events/delete-an-event.md) events that your integration is responsible for. For failed requests, inspect the [error response](https://docs.stora.co/2025-09/guides/errors.md) before retrying.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.