Create a Segment

Endpoint

POST /workspaces/:workspaceId/segments

Description

This endpoint creates a new segment in the specified workspace.

Base URL

https://api.swipeone.com/api

Authentication

Method: API Key Authentication
Header: x-api-key: {your_api_key}

Headers

Header	Type	Required	Description
`x-api-key`	`string`	Yes	Your API key for authentication.

Request Parameters

Parameter	Type	Location	Required	Description
`workspaceId`	`string`	`path`	Yes	The unique ID of the workspace where the segment should be created.

Request Body

A JSON object containing the segment details.

Body Parameters

Parameter	Type	Required	Description
`name`	`string`	Yes	Name of the segment.
`criteria`	`object`	Yes	Criteria to define the segment.
`criteria.type`	`string`	Yes	The type of the criteria, either `"and"` or `"or"`.
`criteria.predicates`	`array`	Yes	Array of conditions used for filtering.

Properties (Inside `criteria.predicates` array)

Parameter	Type	Required	Description
`property`	`string`	Yes	The property to evaluate.
`operator`	`string`	Yes	The operator to use for evaluation.
`value`	`string`	Yes	The value to compare against.
`dataType`	`string`	Yes	The type of the property (`string`, `number`, `boolean`, etc.).

Example Request

curl -X POST "https://api.swipeone.com/api/workspaces/6660175570fbd8a9c22bedfb/segments" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "Subscription Status in trial and Gender is Female",
           "criteria": {
             "type": "and",
             "predicates": [
               {
                 "property": "customProperties.subscriptionStatus",
                 "operator": "is",
                 "value": "in_trial",
                 "dataType": "string"
               },
               {
                 "property": "gender",
                 "operator": "is",
                 "value": "Female",
                 "dataType": "string"
               }
             ]
           }
         }'

Response

Success Response (201)

When the segment is successfully created:

{
  "status": "success",
  "data": {
    "segment": {
      "workspaceId": "6660175570fbd8a9c22bedfb",
      "name": "Subscription Status in trial and Gender is Female",
      "criteria": {
        "type": "and",
        "predicates": [
          {
            "property": "customProperties.subscriptionStatus",
            "operator": "is",
            "value": "in_trial",
            "dataType": "string"
          },
          {
            "property": "gender",
            "operator": "is",
            "value": "Female",
            "dataType": "string"
          }
        ]
      },
      "_id": "6684f0911504d49e7c00312e",
      "createdAt": "2024-07-03T06:32:49.145Z",
      "updatedAt": "2024-07-03T06:32:49.145Z"
    }
  }
}

Error Responses

Status Code	Description
`400`	Invalid input.
`401`	Unauthorized – API key is missing or invalid.
`500`	Internal server error.

Example Error Response (400)

{
  "status": "error",
  "message": "Invalid input"
}

Notes

The name field must be unique within the workspace.
The criteria.predicates array defines the filtering rules for segment members.
Allowed operators depend on the data type of the property

Retrieve All Segments

Endpoint

GET /workspaces/:workspaceId/segments

Description

This endpoint retrieves a list of all segments within a specified workspace.

Base URL

https://api.swipeone.com/api

Authentication

Method: API Key Authentication
Header: x-api-key: {your_api_key}

Headers

Header	Type	Required	Description
`x-api-key`	`string`	Yes	Your API key for authentication.

Request Parameters

Parameter	Type	Location	Required	Description
`workspaceId`	`string`	`path`	Yes	The unique ID of the workspace from which to retrieve segments.

Example Request

curl -X GET "https://api.swipeone.com/api/workspaces/6660175570fbd8a9c22bedfb/segments" \
     -H "x-api-key: YOUR_API_KEY"

Response

Success Response (200)

When segments are successfully retrieved:

{
  "status": "success",
  "data": {
    "count": 10,
    "segments": [
      {
        "name": "Subscribed Users",
        "criteria": {
          "type": "and",
          "predicates": [
            {
              "property": "customProperties.subscriptionStatus",
              "operator": "is",
              "value": "active",
              "dataType": "string"
            }
          ]
        }
      },
      {
        "name": "New Leads",
        "criteria": {
          "type": "or",
          "predicates": [
            {
              "property": "createdAt",
              "operator": "greater_than",
              "value": "2024-06-01T00:00:00Z",
              "dataType": "date"
            }
          ]
        }
      }
    ]
  }
}

Error Responses

Status Code	Description
`404`	Workspace not found.
`401`	Unauthorized – API key is missing or invalid.
`500`	Internal server error.

Example Error Response (404)

{
  "status": "fail",
  "message": "Workspace not found"
}

Notes

This endpoint retrieves all segments for a workspace.
Ensure that the workspaceId provided is valid

Retrieve Segment by ID

Endpoint

GET /segments/:segmentId

Description

This endpoint retrieves the details of a specific segment.

Base URL

https://api.swipeone.com/api

Authentication

Method: API Key Authentication
Header: x-api-key: {your_api_key}

Headers

Header	Type	Required	Description
`x-api-key`	`string`	Yes	Your API key for authentication.

Request Parameters

Parameter	Type	Location	Required	Description
`segmentId`	`string`	`path`	Yes	The unique ID of the segment.

Example Request

curl -X GET "https://api.swipeone.com/api/segments/6684f0911504d49e7c00312e" \
     -H "x-api-key: YOUR_API_KEY"

Response

Success Response (200)

When the segment is successfully retrieved:

{
  "status": "success",
  "data": {
    "segment": {
      "_id": "6684f0911504d49e7c00312e",
      "name": "Subscribed Users",
      "criteria": {
        "type": "and",
        "predicates": [
          {
            "property": "customProperties.subscriptionStatus",
            "operator": "is",
            "value": "active",
            "dataType": "string"
          }
        ]
      },
      "createdAt": "2024-07-01T10:25:17.813Z",
      "updatedAt": "2024-07-01T10:25:17.813Z"
    }
  }
}

Error Responses

Status Code	Description
`404`	Segment not found.
`401`	Unauthorized – API key is missing or invalid.
`500`	Internal server error.

Example Error Response (404)

{
  "status": "fail",
  "message": "Segment not found"
}

Notes

Ensure the segmentId provided exists in the systemswipeone-backend.

Retrieve Contacts for a Segment

Endpoint

GET /segments/:segmentId/contacts

Description

This endpoint retrieves all contacts associated with a specific segment.

Base URL

https://api.swipeone.com/api

Authentication

Method: API Key Authentication
Header: x-api-key: {your_api_key}

Headers

Header	Type	Required	Description
`x-api-key`	`string`	Yes	Your API key for authentication.

Request Parameters

Parameter	Type	Location	Required	Description
`segmentId`	`string`	`path`	Yes	The unique ID of the segment.
`searchAfter`	`string`	`query`	No	Cursor for pagination, indicating the ID after which to search.
`searchBefore`	`string`	`query`	No	Cursor for pagination, indicating the ID before which to search.
`limit`	`integer`	`query`	No	Maximum number of contacts to return (default: `10`).

Example Request

curl -X GET "https://api.swipeone.com/api/segments/6684f0911504d49e7c00312e/contacts?limit=10" \
     -H "x-api-key: YOUR_API_KEY"

Response

Success Response (200)

When contacts are successfully retrieved:

{
  "status": "success",
  "data": {
    "contacts": [
      {
        "name": "John Doe",
        "email": "[email protected]"
      }
    ],
    "count": 20,
    "searchAfter": "someToken",
    "searchBefore": "someToken"
  }
}

Error Responses

Status Code	Description
`404`	Segment not found.
`401`	Unauthorized – API key is missing or invalid.
`500`	Internal server error.

Example Error Response (404)

{
  "status": "fail",
  "message": "Segment not found"
}

Notes

Supports pagination with searchAfter and searchBefore parameters.
Ensure the segmentId provided exists in the systemswipeone-backend.

Update Segment

Endpoint

PATCH /segments/:segmentId

Description

This endpoint updates an existing segment in the system.

Base URL

https://api.swipeone.com/api

Authentication

Method: API Key Authentication
Header: x-api-key: {your_api_key}

Headers

Header	Type	Required	Description
`x-api-key`	`string`	Yes	Your API key for authentication.

Request Parameters

Parameter	Type	Location	Required	Description
`segmentId`	`string`	`path`	Yes	The unique ID of the segment.

Request Body

A JSON object containing the updated segment details.

Body Parameters

Parameter	Type	Required	Description
`name`	`string`	No	Updated name of the segment.
`criteria`	`object`	No	Updated criteria for filtering contacts.

Example Request

curl -X PATCH "https://api.swipeone.com/api/segments/6684f0911504d49e7c00312e" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "Updated Segment Name",
           "criteria": {
             "type": "and",
             "predicates": [
               {
                 "property": "customProperties.subscriptionStatus",
                 "operator": "is",
                 "value": "active",
                 "dataType": "string"
               }
             ]
           }
         }'

Response

Success Response (200)

When the segment is successfully updated:

{
  "status": "success",
  "data": {
    "segment": {
      "_id": "6684ecf950be6195ef46e7d3",
      "workspaceId": "6660175570fbd8a9c22bedfb",
      "name": "Updated Segment Name",
      "criteria": {
        "type": "and",
        "predicates": [
          {
            "property": "customProperties.subscriptionStatus",
            "operator": "is",
            "value": "active",
            "dataType": "string"
          }
        ]
      },
      "createdAt": "2024-07-03T06:17:29.050Z",
      "updatedAt": "2024-07-03T06:27:44.421Z"
    }
  }
}

Error Responses

Status Code	Description
`404`	Segment not found.
`400`	Invalid input.
`401`	Unauthorized – API key is missing or invalid.
`500`	Internal server error.

Notes

Partial updates are supported; only include fields that need modification.
Ensure that the segmentId exists

Segments

Create a Segment

Endpoint

Description

Base URL

Authentication

Headers

Request Parameters

Request Body

Body Parameters

Properties (Inside criteria.predicates array)

Example Request

Response

Success Response (201)

Error Responses

Notes

Retrieve All Segments

Endpoint

Description

Base URL

Authentication

Headers

Request Parameters

Example Request

Response

Success Response (200)

Error Responses

Notes

Retrieve Segment by ID

Endpoint

Description

Base URL

Authentication

Headers

Request Parameters

Example Request

Response

Success Response (200)

Error Responses

Notes

Retrieve Contacts for a Segment

Endpoint

Description

Base URL

Authentication

Headers

Request Parameters

Example Request

Response

Success Response (200)

Error Responses

Notes

Update Segment

Endpoint

Description

Base URL

Authentication

Headers

Request Parameters

Request Body

Body Parameters

Example Request

Response

Success Response (200)

Error Responses

Notes

Properties (Inside `criteria.predicates` array)