---
title: "Create a new event"
method: POST
path: "/events"
tags: ["Events"]
---

# Create a new event

`POST /events`

Create a marketing-automation event on a customer account. An event records an activity (for example a customer interaction, a transaction, or an external trigger) that may launch a marketing-automation scenario configured for the corresponding event type.

**What happens when an event is created**

- An event record is created and its server-generated `event_id` is returned.
- If the corresponding event type is wired to a marketing-automation scenario, that scenario is launched and the event's data is passed to it.
- Property records supplied alongside the event are stored as the event's properties; their values are available to the marketing-automation scenario.

**Related operations**

- [GET /event-types](https://carecloud.readme.io/reference/geteventtypes) - the catalogue of event types configured for the project.
- [GET /event-properties](https://carecloud.readme.io/reference/geteventproperties) - the catalogue of event properties.
- [GET /events/{event_id}/property-records](https://carecloud.readme.io/reference/getsubeventproperties) - read the property records of an existing event.

## Headers

- `Accept-Language` string

## Request body

- object
  - `event` EventPost, required — Event resource.
    - `event_id` string — The unique ID of the event.
    - `event_type_id` string, required — The unique ID of the event type. [GET /event-types](https://carecloud.readme.io/reference/geteventtypes)
    - `customer_id` string — The unique platform customer ID. [GET /customers](https://carecloud.readme.io/reference/getcustomers) If this field is provided, it will always be used and any alternative identifier parameters (`customer_identifier_type` and `customer_identifier_value`) **must not** be included. If both are present, the request will be rejected.
    - `customer_identifier_type` 'email' | 'phone' | 'external_id' — Alternative identifier type to use when `customer_id` is not provided. If `customer_id` is missing, both `customer_identifier_type` and `customer_identifier_value` are required. Accepted values: - `email` – identify customer by e-mail address - `phone` – identify customer by phone number - `external_id` – identify customer by an external system ID (e-shop, POS, portal, etc.) If `customer_id` and an alternative identifier are both provided, the request will be rejected.
    - `customer_identifier_value` union — Alternative identifier value to use when `customer_id` is not provided. The value must match the format expected for the selected `customer_identifier_type`. - For `email` or `phone`, provide a string. - For `external_id`, provide an object with the following structure: ```json { "customer_source_id": "8795d942b31990e944c2ab1254", "external_id": "7ACFY3R" } ``` These parameters follow the same conventions as customer search by external ID in [GET /customer-source-records](https://carecloud.readme.io/reference/getcustomersourcerecords). If both `customer_id` and an alternative identifier are included, the request will be rejected.
      - string — String value when type is `email` or `phone`.
      - object — Object value when type is `external_id`.
        - `customer_source_id` string, required — The ID of the customer source (e.g., e-shop, POS). [GET /customer-sources](https://carecloud.readme.io/reference/getcustomersources)
        - `external_id` string, required — The identifier of the customer in that customer source.
    - `external_id` string, required — The unique external ID of the event. It may be ID from other system.
    - `data` union — Additional data of the event. Serialized data in JSON.
      - string
      - string[]
      - object
    - `created_at` string — Timestamp of the event. Accepts the format `YYYY-MM-DD HH:MM:SS` or ISO-8601 format (`YYYY-MM-DDTHH:MM:SS`). All times must be in the local timezone.
    - `secondary_external_id` string — Additional external ID of the event. Used when differentiation of external_id is needed.
    - `state` 0 | 1 | 2 — State of the event. *Possible values are: 0 - deleted / 1 - active / 2 - non active*
  - `property_records` PropertyRecord[] — Additional properties of the event. This parameter contain values in GET response only if query parameter `include_property_records` is set to true.
    - `property_record_id` string — The unique ID of the property record.
    - `property_id` string, required — The unique ID of the property.
    - `property_name` string — Name of the property.
    - `property_value` union — Value of the property record. The format depends on the data type of the property. - **string** – a plain text value: ```json { "property_id": "p1_note", "property_value": "VIP customer" } ``` - **date** – a date string in `YYYY-MM-DD` format: ```json { "property_id": "p1_birth_date", "property_value": "1985-06-15" } ``` - **integer** – a whole number: ```json { "property_id": "p1_visit_count", "property_value": 42 } ``` - **float** – a decimal number: ```json { "property_id": "p1_average_spend", "property_value": 149.90 } ``` - **enum** – a single-item array containing a PropertyItem object: ```json { "property_id": "p1_favourite_color", "property_value": [ { "id": "86e05affc7a7abefcd513ab400", "name": "Blue", "resource_record_id": null, "state": 1 } ] } ``` - **multiselect** – a multi-item array of PropertyItem objects: ```json { "property_id": "p1_favourite_color", "property_value": [ { "id": "86e05affc7a7abefcd513ab400", "name": "Blue", "resource_record_id": null, "state": 1 }, { "id": "81eaeea13b8984a169c490a325", "name": "Green", "resource_record_id": null, "state": 1 } ] } ``` - **custom data type** – the format depends on the specific data type configuration. For example, a serialized JSON object: ```json { "property_id": "p1_address", "property_value": "{\"street\":\"Main St\",\"city\":\"Prague\"}" } ```
      - string
      - number
      - integer
      - boolean
      - unknown[]
        - unknown
      - object
    - `last_change` string — Date and time of the last change. *(YYYY-MM-DD HH:MM:SS)*

## Response `201`

Created

- object
  - `data` object
    - `event_id` string — The unique ID of the event.

## Other responses

- `400` — Bad input parameter. The response body's `error.error_data.invalid_params[]` array lists the parameters that caused the failure, each carrying a `reason` code. See the `BadRequestErrorBody` schema for the generic reason taxonomy. Operations with domain-specific business rules document additional reasons at the operation level.
- `401` — The client has invalid credentials or auth token.
- `403` — The client does not exist or the client tried to access an unauthorized property or resource.
- `404` — The resource was not found.
- `405` — The resource does not support the specified HTTP method.
- `429` — Too many requests - more than the resource limit.
- `500` — Server is not working as expected.
- `503` — Temporary state when the service is temporarily unavailable, overloaded or there is a maintenance window.

---

[API](https://skmtc.net/crmcarecloud/apis/rest-api-reference.md) · [All operations](https://skmtc.net/crmcarecloud/apis/rest-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/crmcarecloud/rest-api-reference/versions/329c06dbf8d9/schema)