How to create Custom Event Definition & Events | Swipe One Pte Ltd Help Center

Swipe One Event API

The SwipeOne Event API allows you to :

1. Create Event Definitions : Define the structure (properties/fields) of a particular event type.

(e.g., user_signup_event , cart_abandoned ).

2. Create Events : Send actual event data (for the previously defined event types) into the Swipe One system, including details about the contact and any additional properties.

Authentication

API Key : Required via the x-api-key parameter in your query string.

Example :

?x-api-key=YOUR_API_KEY

1. Create Event Definition

Endpoint

POST /api/workspaces/{workspaceId}/event-definitions?x-api-key=YOUR_API_KEY

Description

Creates a new event definition in the specified workspace. This defines how an event (e.g., sign-up, cart abandonment) is structured—i.e., what fields ( properties ) are required or optional, and what data types those fields should have ('text', 'email', 'phone', 'select', 'multiselect', 'country', 'url', 'address', 'person', 'date', 'number').

Request Body Fields

name ( string , required) A short, internal name that uniquely identifies this event definition.
label ( string , required) A human-readable title for this event definition.
properties ( array , required) - An array of objects describing each field (e.g., 'text', 'email', 'phone', 'select', 'multiselect', 'country', 'url', 'address', 'person', 'date', 'number') for this event type.
- label: The field's display label/title
- name: An optional internal/programmatic name for the field.
- fieldType: Specifies the type of data this field holds (e.g., text, email, date)
- numberFormat: For numeric fields, defines how the number should be formatted (e.g., comma, percentage).
- currency: If numberFormat is "currency," indicates the currency type
  (e.g., USD, EUR).
- dateFormat: If fieldType is "date," specifies how the date is formatted
  (e.g., MMM dd, yyyy).
- includeTime: If fieldType is "date," determines whether a time component is included.
- addressFields: If fieldType is "address," defines which address sub-fields
  (line1, city, etc.) are present.
- options: For select/multiselect fields, an array of objects defining selectable options (label, color, etc.).
- optionsName: For select/multiselect fields, an optional name/identifier for the options set.

Below is a table containing all possible fields for each property object, along with their types, requirements, conditions, and descriptions.

Field	Type	Required	Condition
label	`string`	Yes	-
name	`string`	No (optional)	-
fieldType	`string`	Yes	Must be one of : `text` , `email` , `phone` , `select` , `multiselect` , `country`, `url`, `address`, `person`, `date`, `number`
numberFormat	`string`	Optional ( Only if `fieldType = number` )	Valid values: `number` , `comma` , `percentage` , `currency`
currency	`string`	Optional ( Only if `numberFormat =` `currency` )	-
dateFormat	`string`	Yes ( Only if `fieldType = date` )	Valid values: `MMM`, `dd`, `yyyy`, `dd/MM/yyyy` , `MM/dd/yyyy`
includeTime	`boolean`	Yes ( Only if `fieldType = date` )	-
addressFields	`object`	Yes ( Only if `fieldType = address` )	Must contain: `line1`, `line2`, `city`, `country` , `state` , `zipcode`
options	`array`	Yes ( Only if `fieldType` is `select` or `multiselect` )	Items are objects of the form: `{ label, name?, color }`
optionsName	`string`	Optional ( Only if `fieldType` is `select` or `multiselect` )	-

createdBy ( object , optional) Metadata about who created the event definition
(e.g., user ID, name).
recordSummary ( boolean , required) Whether this event definition includes a record summary.

2. Create Event

Endpoint

POST /api/workspaces/{workspaceId}/events?x-api-key=YOUR_API_KEY

Description

Creates (or "fires") an event instance in the specified workspace. This is typically done after you have defined the event type in Create Event Definition. You specify the type of the event, the contact information, and any additional fields under properties.

Request Body Fields

type ( string , required) The event type, matching the name of the event definition
(e.g., user_signup_event , cart_abandoned ).
contact ( object , required) An object describing the contact associated with this event (e.g., email , firstName , user_id ).
properties ( object , optional) Additional key-value data that aligns with the properties defined in the event definition (e.g. : subscription plan, location).
createdBy ( object , optional) Information about who created/triggered this event (e.g., admin ID).

Usage Examples

Given below are updated two scenarios showing how to define and then create events using two endpoints :

POST /event-definitions
POST /events

In these updated examples, instead of using an Authorization header, an API key is passed as a query parameter ( ?x-apikey=YOUR_API_KEY ).

Examples

1. User Sign-up Event

1.1 Define the event ( `POST /event-definitions` )

JSON Body Example

{
  "name": "user_signup_event",
  "label": "User Sign-up Event",
  "properties": [
    {
      "name": "referral_code",
      "label": "Referral Code",
      "fieldType": "text"
    }
  ],
  "recordSummary": true
}

cURL Example

curl - X POST "https://your-domain.com/event-definitions?x-api-key=YOUR_API_KEY"\ -
	H "Content-Type: application/json"\ -
	d '{
"name": "user_signup_event",
"label": "User Sign-up Event",
"properties": [{
	"name": "referral_code",
	"label": "Referral Code",
	"fieldType": "text"
}],
"recordSummary": true
}'

JavaScript (Fetch) Example

fetch('https://your-domain.com/event-definitions?x-api-key=YOUR_API_KEY', {
		method: 'POST',
		headers: {
			'Content-Type': 'application/json',
		},
		body: JSON.stringify({
			name: 'user_signup_event',
			label: 'User Sign-up Event',
			properties: [{
				name: 'referral_code',
				label: 'Referral Code',
				fieldType: 'text',
			}, ],
			recordSummary: true,
		}),
	})
	.then(response => response.json())
	.then(data => console.log(data))
	.catch(error => console.error(error));

Python (Requests) Example

import requests
url = "https://your-domain.com/event-definitions?x-api-key=YOUR_API_KEY"
headers = {
	"Content-Type": "application/json"
}
data = {
	"name": "user_signup_event",
	"label": "User Sign-up Event",
	"properties": [{
		"name": "referral_code",
		"label": "Referral Code",
		"fieldType": "text"
	}],
	"recordSummary": True
}
response = requests.post(url, headers = headers, json = data)
print(response.json())

1.2 Create/Send the event ( `POST /events` )

JSON Body Example

{
  "type": "user_signup_event",
  "contact": {
    "email": "[email protected]"
  },
  "properties": {
    "referral_code": "ABCD123"
  }
}

cURL Example

curl - X POST "https://your-domain.com/events?x-api-key=YOUR_API_KEY"\ -
	H "Content-Type: application/json"\ -
	d '{
"type": "user_signup_event",
"contact": {
	"email": "[email protected]"
},
"properties": {
	"referral_code": "ABCD123"
}
}'

JavaScript (Fetch) Example

fetch('https://your-domain.com/events?x-api-key=YOUR_API_KEY', {
		method: 'POST',
		headers: {
			'Content-Type': 'application/json',
		},
		body: JSON.stringify({
			type: 'user_signup_event',
			contact: {
				email: '[email protected]',
			},
			properties: {
				referral_code: 'ABCD123',
			},
		}),
	})
	.then(response => response.json())
	.then(data => console.log(data))
	.catch(error => console.error(error));

Python (Requests) Example

import requests
url = "https://your-domain.com/events?x-api-key=YOUR_API_KEY"
headers = {
	"Content-Type": "application/json"
}
data = {
	"type": "user_signup_event",
	"contact": {
		"email": "[email protected]"
	},
	"properties": {
		"referral_code": "ABCD123"
	}
}
response = requests.post(url, headers = headers, json = data)
print(response.json())

2. Cart Abandoned

2.1 Define the event ( `POST /event-definitions` )

JSON Body Example

{
	"name": "cart_abandoned",
	"label": "Cart Abandoned Event",
	"properties": [{
		"name": "plan",
		"label": "Plan",
		"fieldType": "text"
	}]
}

cURL Example

curl - X POST "https://your-domain.com/event-definitions?x-api-key=YOUR_API_KEY"\ -
	H "Content-Type: application/json"\ -
	d '{
"name": "cart_abandoned",
"label": "Cart Abandoned Event",
"properties": [{
	"name": "plan",
	"label": "Plan",
	"fieldType": "text"
}]
}'

JavaScript (Fetch) Example

fetch('https://your-domain.com/event-definitions?x-api-key=YOUR_API_KEY', {
		method: 'POST',
		headers: {
			'Content-Type': 'application/json',
		},
		body: JSON.stringify({
			name: 'cart_abandoned',
			label: 'Cart Abandoned Event',
			properties: [{
				name: 'plan',
				label: 'Plan',
				fieldType: 'text',
			}, ],
		}),
	})
	.then(response => response.json())
	.then(data => console.log(data))
	.catch(error => console.error(error));

Python (Requests) Example

import requests
url = "https://your-domain.com/event-definitions?x-api-key=YOUR_API_KEY"
headers = {
	"Content-Type": "application/json"
}
data = {
	"name": "cart_abandoned",
	"label": "Cart Abandoned Event",
	"properties": [{
		"name": "plan",
		"label": "Plan",
		"fieldType": "text"
	}]
}
response = requests.post(url, headers = headers, json = data)
print(response.json())

2.2 Create/Send the event ( `POST /events` )

JSON Body Example

{
	"type": "cart_abandoned",
	"contact": {
		"email": "[email protected]"
	},
	"properties": {
		"plan": "agency_yearly"
	}
}

cURL Example

curl - X POST "https://your-domain.com/events?x-api-key=YOUR_API_KEY"\ -
	H "Content-Type: application/json"\ -
	d '{
"type": "cart_abandoned",
"contact": {
	"email": "[email protected]"
},
"properties": {
	"plan": "agency_yearly"
}
}'

JavaScript (Fetch) Example

fetch('https://your-domain.com/events?x-api-key=YOUR_API_KEY', {
		method: 'POST',
		headers: {
			'Content-Type': 'application/json',
		},
		body: JSON.stringify({
			type: 'cart_abandoned',
			contact: {
				email: '[email protected]',
			},
			properties: {
				plan: 'agency_yearly',
			},
		}),
	})
	.then(response => response.json())
	.then(data => console.log(data))
	.catch(error => console.error(error));

Python (Requests) Example

import requests
url = "https://your-domain.com/events?x-api-key=YOUR_API_KEY"
headers = {
	"Content-Type": "application/json"
}
data = {
	"type": "cart_abandoned",
	"contact": {
		"email": "[email protected]"
	},
	"properties": {
		"plan": "agency_yearly"
	}
}
response = requests.post(url, headers = headers, json = data)
print(response.json())

Important Note

To trigger an event for a contact, always ensure you include the email address in the event request body. Keep in mind that any data passed in the event properties will only be linked to the specific Event Definition. If you need to store data that persists with the contact, first create a contact property and then send the data through the contact object where the email is specified.

Best Practices

Create Definitions First
Define your event types before sending event data to avoid validation errors.
Consistent Field Usage
Use the same properties (names and data types) in your events that you've specified in your event definition.
Error Handling
Always handle 4XX or 5XX errors by checking the response body for details on what went wrong.
Security
Safeguard your x-api-key and rotate it regularly

Authentication

1. Create Event Definition

Field

Type

Required

Condition

2. Create Event

Usage Examples

Examples

1. User Sign-up Event

1.1 Define the event ( POST /event-definitions )

1.2 Create/Send the event ( POST /events )

2. Cart Abandoned

2.1 Define the event ( POST /event-definitions )

2.2 Create/Send the event ( POST /events )

Important Note

Best Practices

1.1 Define the event ( `POST /event-definitions` )

1.2 Create/Send the event ( `POST /events` )

2.1 Define the event ( `POST /event-definitions` )

2.2 Create/Send the event ( `POST /events` )