Create a Tag

Endpoint

POST /workspaces/:workspaceId/tags

Description

This endpoint creates a new tag 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 tag should be created.

Request Body

A JSON object containing the tag details.

Body Parameters

Parameter	Type	Required	Description
`label`	`string`	Yes	The label of the tag.
`color`	`string`	Yes	The color associated with the tag.

Colors : gray, tomato, red, ruby, crimson, pink, plum, purple, violet, iris, indigo, cyan, blue, teal, jade, green, grass, bronze, gold, brown, orange, amber, yellow, lime, mint, sky

Example Request

curl -X POST "https://api.swipeone.com/api/workspaces/6660175570fbd8a9c22bedfb/tags" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "label": "VIP",
           "color": "#FF5733"
         }'

Response

Success Response (201)

When the tag is successfully created:

{
  "status": "success",
  "data": {
    "tag": {
      "_id": "6682840d9286aa59ee3d4181",
      "label": "VIP",
      "name": "vip",
      "workspaceId": "6660175570fbd8a9c22bedfb",
      "color": "#FF5733"
    }
  }
}

Error Responses

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

Retrieve All Tags

Endpoint

GET /workspaces/:workspaceId/tags

Description

This endpoint retrieves a list of all tags in the specified workspace.

Example Request

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

Response

{
  "status": "success",
  "data": {
    "count": 10,
    "tags": [
      {
        "_id": "6682840d9286aa59ee3d4181",
        "label": "VIP",
        "name": "vip",
        "workspaceId": "6660175570fbd8a9c22bedfb",
        "color": "#FF5733"
      }
    ]
  }
}

Retrieve Tag by ID

Endpoint

GET /tags/:tagId

Description

This endpoint retrieves details of a specific tag using its ID.

Example Request

curl -X GET "https://api.swipeone.com/api/tags/6682840d9286aa59ee3d4181" \
     -H "x-api-key: YOUR_API_KEY"

Response

{
  "status": "success",
  "data": {
    "tag": {
      "_id": "6682840d9286aa59ee3d4181",
      "label": "VIP",
      "name": "vip",
      "workspaceId": "6660175570fbd8a9c22bedfb",
      "color": "#FF5733"
    }
  }
}

Retrieve Contacts for a Tag

Endpoint

GET /tags/:tagId/contacts

Description

This endpoint retrieves all contacts associated with a specific tag.

Request Parameters

Parameter	Type	Location	Required	Description
`tagId`	`string`	`path`	Yes	The unique ID of the tag.
`searchAfter`	`string`	`query`	No	Pagination token for fetching the next set of results.
`searchBefore`	`string`	`query`	No	Pagination token for fetching the previous set of results.
`limit`	`integer`	`query`	No	Maximum number of contacts to return (default: `10`).

Example Request

curl -X GET "https://api.swipeone.com/api/tags/6682840d9286aa59ee3d4181/contacts?limit=10&searchAfter=someToken" \
     -H "x-api-key: YOUR_API_KEY"

Response

Success Response (200)

When contacts are successfully retrieved:

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

Error Responses

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

Example Error Response (404)

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

Notes

This endpoint supports cursor-based pagination using searchAfter and searchBefore tokens.
Ensure the tagId provided exists in the system

Update a Tag

Endpoint

PATCH /tags/:tagId

Description

This endpoint updates an existing tag in the system.

Request Body

A JSON object containing the updated tag details.

Body Parameters

Parameter	Type	Required	Description
`label`	`string`	No	Updated label of the tag.
`color`	`string`	No	Updated color of the tag.

Example Request

curl -X PATCH "https://api.swipeone.com/api/tags/6682840d9286aa59ee3d4181" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "label": "Updated VIP",
           "color": "#FF0000"
         }'

Response

{
  "status": "success",
  "data": {
    "tag": {
      "_id": "6682840d9286aa59ee3d4181",
      "label": "Updated VIP",
      "name": "vip",
      "workspaceId": "6660175570fbd8a9c22bedfb",
      "color": "#FF0000"
    }
  }
}

Error Responses

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

Update Contact Tags

Endpoint

POST /contacts/:contactId/tags

Description

This endpoint allows adding tags to a specific contact.

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
`contactId`	`string`	`path`	Yes	The unique ID of the contact to which tags should be added.

Request Body

A JSON object containing the list of tags.

Body Parameters

Parameter	Type	Required	Description
`tags`	`array of string/object`	Yes	Array of tag names to be set as tags to the contact.
tags.label	string	required if creating a tag	A label for the new tag
tag.color	string	required if creating a tag	A color for the new tag

Colors : gray, tomato, red, ruby, crimson, pink, plum, purple, violet, iris, indigo, cyan, blue, teal, jade, green, grass, bronze, gold, brown, orange, amber, yellow, lime, mint, sky

Example Request

curl -X POST "https://api.swipeone.com/api/contacts/6682840d9286aa59ee3d4181/tags" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "tags": [
               "vip", 
               "subscriber", 
               {
                   "label": "lead",
                   "color": "#FF5733"
               }
           ]
         }'

Response

Success Response (200)

When the tags are successfully added:

{
  "status": "success",
  "message": "Tags added to contact"
}

Error Responses

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

Example Error Response (404)

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

Notes

The provided tags will be created if passed as object before adding them to the contact.
The request will set just the provided tags. Existing tags will be removed
Events will be emitted for newly added tags to track changes