Collections API - Events

You’ll need to first obtain an API key using instructions here.

Authentication

For all endpoints, when making API requests, add the following auth headers:

Twise-Auth-Provider: cli
Twise-Auth-Payload: {“token”:”<your_api_key>”}

Uploading events

Endpoint

POST https://api3.twise.ai/personalities/{twise_id}/twin/vector_documents

(tip: you can find the twise_id in Integrations -> Zapier -> Twise ID)

Request payload fields

This endpoint consumes application/json.

Field	Type	Required	Description
document_type	boolean	Yes	Should be ‘event’
document	Event object	Yes	‘Event’ object documented below

Event model

Field	Type	Required	Description
id	string	No	If not provided, will automatically generate one.
title	string	Yes	Event title
description	string	Yes	Event description
venue	string	No	Venue name
url	string	No	URL for event details page
phone_number	string (in E.164 format)	No	Contact phone number (in E.164 format)
contact_email	string	No	Contact email
address	string	No	Address
city	string	No	City (e.g. “Dubai”)
category	string	No	Category
date_start	ISO date string	No	When the event happens/starts.
date_end	ISO date string	No	When the event ends. date_end cannot be defined if date_start is not defined
price	string (decimal)	No	Event ticket price (e.g. “100.50”). Has to be provided together with currency.
currency	string (ISO 4217, 3-letter currency code)	No	ISO 4217, 3-letter currency code (e.g. “AED”). Has to be provided together with price.
media	List[string]	No	List of URLs pointing to event images
price_range	PriceRange	No	A price range for tickets an event. If provided, product cards will show a price range instead of the price provided in priceand currencyfields.

Request body example

{
    "document_type": "event",
    "document": {
        "id": "event-id-2458",
        "title": "Desert Safari Adventure with Dinner",
        "description": "Experience the thrill of dune bashing in a 4x4 vehicle across the golden sands of the Arabian desert. This 6-hour adventure includes camel riding, sandboarding, and a traditional BBQ dinner under the stars with live entertainment featuring belly dancing and tanoura shows. Capture stunning sunset photos and get a henna tattoo as a souvenir of your desert experience.",
        "venue": "Arabian Desert Adventures",
        "url": "https://desertsafari.ae/evening-adventure",
        "phone_number": "[phone]",
        "contact_email": "[e-mail]",
        "address": "Pickup from any hotel in Dubai",
        "city": "Dubai",
        "category": "Outdoor Adventures",
        "date_start": "2024-06-15T00:00:00",
        "date_end": "2025-09-30T00:00:00",
        "price": "199.0",
        "currency": "AED",
        "price_range": {
            "min_variant_price": {
                "amount": "199.0",
                "currency_code": "AED"
            },
            "max_variant_price": {
                "amount": "349.0",
                "currency_code": "AED"
            }
        },
        "media": [
            "https://example.com/images/desert-safari-sunset.jpg",
            "https://example.com/images/desert-safari-dinner.jpg"
        ]
    }
}

Response Example

{
    "_id": "67bc6c89e02d505067148ad5",
    "type": "event",
    "document_id": "event-id-2458",
    "document": {
        "id": "event-id-2458",
        "title": "Desert Safari Adventure with Dinner",
        "description": "Experience the thrill of dune bashing in a 4x4 vehicle across the golden sands of the Arabian desert. This 6-hour adventure includes camel riding, sandboarding, and a traditional BBQ dinner under the stars with live entertainment featuring belly dancing and tanoura shows. Capture stunning sunset photos and get a henna tattoo as a souvenir of your desert experience.",
        "venue": "Arabian Desert Adventures",
        "url": "https://desertsafari.ae/evening-adventure",
        "phone_number": "[phone]",
        "contact_email": "[e-mail]",
        "address": "Pickup from any hotel in Dubai",
        "city": "Dubai",
        "category": "Outdoor Adventures",
        "date_start": "2024-06-15T00:00:00",
        "date_end": "2025-09-30T00:00:00",
        "price": "199.0",
        "currency": "AED",
        "price_range": {
            "min_variant_price": {
                "amount": "199.0",
                "currency_code": "AED"
            },
            "max_variant_price": {
                "amount": "349.0",
                "currency_code": "AED"
            }
        },
        "media": [
            "https://example.com/images/desert-safari-sunset.jpg",
            "https://example.com/images/desert-safari-dinner.jpg"
        ],
        "display_price": "199.0 AED",
        "price_float": 199.0
    },
    "personality_id": "67ab4c6df78156bf40dc813e",
    "id_suffix": "148ad5",
    "updated_at": "2025-02-24T12:56:41.028000Z",
    "uploaded_at": "2025-02-24T12:56:41.028000Z",
    "twin_feed_sync_id": null
}

Get events

Endpoint

GET https://api3.twise.ai/personalities/{twise_id}/twin/vector_documents

(tip: you can find the twise_id in Integrations -> Zapier -> Twise ID)

Request URL params fields

Field	Type	Required	Description
document_type	string	Yes	‘event’
per_page	int	No	number of events to return per page
is_featured	boolean	No	gets only ‘featured’ events
sort	string	No	key to sort by: ‘updated_at’

Response Example

{
    "total_count": 114,
    "next_page": 2,
    "prev_page": null,
    "results": [
        {
          ...
        },
    ]
}

Update events

Endpoint

PUT https://api3.twise.ai/personalities/{twise_id}/twin/vector_documents/{_id}

(tip: you can find the twise_id in Integrations -> Zapier -> Twise ID)

Request payload fields

This endpoint consumes application/json.

Field	Type	Required	Description
document	Event object	Yes	‘Event’ object documented below

Field	Type	Required	Description
title	string	No	Event title
description	string	No	Event description
venue	string	No	Venue name
url	string	No	URL for event details page
phone_number	string (in E.164 format)	No	Contact phone number (in E.164 format)
contact_email	string	No	Contact email
address	string	No	Address
city	string	No	City (e.g. “Dubai”)
category	string	No	Category
date_start	ISO date string	No	When the event happens/starts.
date_end	ISO date string	No	When the event ends. date_end cannot be defined if date_start is not defined
price	string (decimal)	No	Event ticket price (e.g. “100.50”). Has to be provided together with currency.
currency	string (ISO 4217, 3-letter currency code)	No	ISO 4217, 3-letter currency code (e.g. “AED”). Has to be provided together with price.
media	List[string]	No	List of URLs pointing to event images

Request body example

{
    "document": {
        "city": "Abu Dhabi",
        "address": "Pickup from any hotel in Abu Dhabi"
    }
}

Response example

{
    "_id": "67bc6c89e02d505067148ad5",
    "type": "event",
    "document_id": "event-id-2458",
    "document": {
        "id": "event-id-2458",
        "title": "Desert Safari Adventure with Dinner",
        "description": "Experience the thrill of dune bashing in a 4x4 vehicle across the golden sands of the Arabian desert. This 6-hour adventure includes camel riding, sandboarding, and a traditional BBQ dinner under the stars with live entertainment featuring belly dancing and tanoura shows. Capture stunning sunset photos and get a henna tattoo as a souvenir of your desert experience.",
        "venue": "Arabian Desert Adventures",
        "url": "https://desertsafari.ae/evening-adventure",
        "phone_number": "[phone]",
        "contact_email": "[e-mail]",
        "address": "Pickup from any hotel in Abu Dhabi",
        "city": "Abu Dhabi",
        "category": "Outdoor Adventures",
        "date_start": "2024-06-15T00:00:00",
        "date_end": "2025-09-30T00:00:00",
        "price": "199.0",
        "currency": "AED",
        "price_range": {
            "min_variant_price": {
                "amount": "199.0",
                "currency_code": "AED"
            },
            "max_variant_price": {
                "amount": "349.0",
                "currency_code": "AED"
            }
        },
        "media": [
            "https://example.com/images/desert-safari-sunset.jpg",
            "https://example.com/images/desert-safari-dinner.jpg"
        ],
        "display_price": "199.0 AED",
        "price_float": 199.0
    },
    "personality_id": "67ab4c6df78156bf40dc813e",
    "id_suffix": "148ad5",
    "updated_at": "2025-02-24T13:32:40.081000Z",
    "uploaded_at": "2025-02-24T12:56:41.028000Z",
    "twin_feed_sync_id": null
}

Delete events

Endpoint

DELETE https://api3.twise.ai/personalities/{twise_id}/twin/vector_documents/{_id}

(tip: you can find the twise_id in Integrations -> Zapier -> Twise ID)

Returns 204 No Content on a successful deletion.

Delete events (batch)

You are also able to batch delete documents using:

DELETE https://api3.twise.ai/personalities/{twise_id}/twin/vector_documents

Usage example

curl --location --request DELETE 'https://api3.twise.ai/personalities/{twise_id}/twin/documents' \
--header 'Twise-Auth-Provider: cli' \
--header 'Twise-Auth-Payload: {"token":"sk_xxx"}' \
--header 'Content-Type: application/json' \
--data '{
    "ids": ["67ab248f6ec29515563aec51"]
}'

Response example

{
  "success": true,
  "num_deleted": 1,
  "errors": []
}