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": "+97155987654",
        "contact_email": "[email protected]",
        "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": "+97155987654",
        "contact_email": "[email protected]",
        "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": "+97155987654",
        "contact_email": "[email protected]",
        "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": []
}
PreviousWhat are collections?NextImporting a collection via a Twise XML Feed

Last updated