Create or Update a Contact

Endpoint

POST /workspaces/:workspaceId/contacts

Description

This endpoint allows you to create a new contact within a specified workspace.

Base URL

https://api.swipeone.com/api

Authentication

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

Request Parameters

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

Request Body

A JSON object containing the contact details.

Body Parameters

Parameter	Type	Required	Description
`firstName`	`string`	(Optional if `email` or `fullName` is present)	First name of the contact.
`lastName`	`string`	No	Last name of the contact.
`fullName`	`string`	(Optional if `email` or `firstName` is present)	Full Name of the contact
`email`	`string`	(Optional if `firstName` or `fullName` is present)	Email address of the contact.
`phone`	`string`	No	Phone number of the contact.
`address.line1`	`string`	No	Address line 1.
`address.line2`	`string`	No	Address line 2.
`address.city`	`string`	No	City of the contact.
`address.state`	`string`	No	State of the contact.
`address.country`	`string`	No	Country of the contact.
`address.zipcode`	`string`	No	ZIP code of the contact.
`birthday`	`string`	No	Contact's date of birth (ISO 8601 format).
`occupation`	`string`	No	Occupation of the contact.
`gender`	`string`	No	Gender of the contact.
`timezone`	`string`	No	Timezone of the contact.
`socialMediaUrls.facebook`	`string`	No	Facebook profile URL.
`socialMediaUrls.twitter`	`string`	No	Twitter profile URL.
`socialMediaUrls.linkedin`	`string`	No	LinkedIn profile URL.
`department`	`string`	No	Department in which the contact works.
`industry`	`string`	No	Industry type.
`teamSize`	`number`	No	Size of the team the contact works with.
`annualRevenue`	`number`	No	Contact's company annual revenue.
`website`	`string`	No	Contact's website URL.

Example Request

curl -X POST "https://api.swipeone.com/api/workspaces/6660175570fbd8a9c22bedfb/contacts" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "firstName": "John",
           "lastName": "Doe",
           "email": "[email protected]",
           "phone": "123-456-7890",
           "address": {
             "line1": "123 Main St",
             "line2": "Apt 4B",
             "city": "Springfield",
             "state": "IL",
             "country": "USA",
             "zipcode": "62704"
           },
           "birthday": "1980-01-01T00:00:00.000Z",
           "occupation": "Software Engineer",
           "gender": "Male",
           "timezone": "America/Chicago",
           "department": "Engineering",
           "teamSize": 100,
           "annualRevenue": 1000000,
           "website": "https://techcorp.com"
         }'

Response

Success Response (201)

When a contact is successfully created:

{
  "status": "success",
  "data": {
    "contact": {
      "_id": "6682840d9286aa59ee3d4181",
      "firstName": "John",
      "lastName": "Doe",
      "fullName": "John Doe",
      "email": "[email protected]",
      "phone": "123-456-7890",
      "createdAt": "2024-07-01T10:25:17.813Z",
      "updatedAt": "2024-07-01T10:25:17.813Z"
    }
  }
}

Error Responses

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

Example Error Response (400)

{
  "status": "fail",
  "message": "Invalid input data"
}

Headers

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

Notes

At least one of email, fullName, or firstName must be provided to create a contact.
Contacts are associated with a specific workspace.
The API validates input data before creating the contact.

Retrieve All Contacts

Endpoint

GET /workspaces/:workspaceId/contacts

Description

This endpoint retrieves a paginated list of contacts within a specified workspace.

Base URL

https://api.swipeone.com/api

Authentication

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

Request Parameters

Parameter	Type	Location	Required	Description
`workspaceId`	`string`	`path`	Yes	The unique ID of the workspace from which to retrieve contacts.
`searchText`	`string`	`query`	No	Text to search in contacts (Name or Email).
`sort`	`string`	`query`	No	Field to sort by (e.g., `CreatedAt`).
`order`	`integer`	`query`	No	Sort order: `1` for ascending, `-1` for descending (default is `1`).
`searchAfter`	`string`	`query`	No	Token to fetch the next set of results.
`searchBefore`	`string`	`query`	No	Token to fetch the previous set of results.
`limit`	`integer`	`query`	No	Number of contacts to return (default: `20`).

Pagination

The API uses cursor-based pagination with searchAfter and searchBefore tokens.
If searchAfter is provided, results after the specified token will be retrieved.
If searchBefore is provided, results before the specified token will be retrieved.
limit specifies the number of results per request (default is 20).

Example Request

curl -X GET "https://api.swipeone.com/api/workspaces/6660175570fbd8a9c22bedfb/contacts?limit=10&sort=createdAt&order=1" \
     -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": [
      {
        "_id": "6682840d9286aa59ee3d4181",
        "firstName": "John",
        "lastName": "Doe",
        "fullName": "John Doe",
        "email": "[email protected]",
        "phone": "123-456-7890",
        "createdAt": "2024-07-01T10:25:17.813Z",
        "updatedAt": "2024-07-01T10:25:17.813Z"
      }
    ]
  }
}

Error Responses

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

Example Error Response (404)

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

Headers

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

Notes

This endpoint supports searching by name and email.
Results can be sorted and paginated using the searchAfter and searchBefore tokensswipeone-backend.
Ensure the workspaceId provided exists and is valid.

Search Contacts

Endpoint

POST /workspaces/:workspaceId/contacts/search

Description

This endpoint retrieves a filtered, paginated list of contacts from a specified workspace based on the provided search criteria.

Base URL

https://api.swipeone.com/api

Authentication

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

Request Parameters

Parameter	Type	Location	Required	Description
`workspaceId`	`string`	`path`	Yes	The unique ID of the workspace to search contacts in.

Request Body

A JSON object containing the search filters and pagination details.

Body Parameters

Parameter	Type	Required	Description
`filter`	`object`	Yes	Filtering criteria using logical conditions (`and` / `or`).
`sort`	`array`	No	Sorting criteria with fields and order.
`searchAfter`	`string`	No	Token to fetch the next set of results.
`searchBefore`	`string`	No	Token to fetch the previous set of results.
`limit`	`number`	No	Number of contacts to return (default: `10`).
`searchText`	`string`	No	Text to search in contact attributes like name or email.

Example Request

curl -X POST "https://api.swipeone.com/api/workspaces/6660175570fbd8a9c22bedfb/contacts/search" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "filter": {
             "type": "and",
             "predicates": [
               {
                 "property": "customProperties.subscriptionStatus",
                 "operator": "is",
                 "value": "in_trial",
                 "dataType": "string"
               },
               {
                 "property": "gender",
                 "operator": "is",
                 "value": "Female",
                 "dataType": "string"
               }
             ]
           },
           "limit": 10,
           "sort": [
             {
               "property": "fullName",
               "order": "asc"
             },
             {
               "property": "teamSize",
               "order": "dsc"
             }
           ],
           "searchAfter": "someToken",
           "searchBefore": "someToken"
         }'

Response

Success Response (200)

When contacts matching the search criteria are found:

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

Error Responses

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

Example Error Response (400)

{
  "status": "fail",
  "message": "Invalid input data"
}

Headers

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

Pagination

This API uses cursor-based pagination with searchAfter and searchBefore tokens.
Use searchAfter to get the next set of results.
Use searchBefore to get the previous set of results.
limit specifies the number of records per request (default: 10).

Notes

Filtering is applied using logical conditions (and, or).
Supports sorting results based on multiple properties.
Ensure workspaceId is valid for successful results

Retrieve Contact by ID

Endpoint

GET /contacts/:contactId

Description

This endpoint retrieves details of a specific contact using the provided contact ID.

Base URL

https://api.swipeone.com/api

Authentication

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

Request Parameters

Parameter	Type	Location	Required	Description
`contactId`	`string`	`path`	Yes	The unique ID of the contact to retrieve.

Headers

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

Example Request

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

Response

Success Response (200)

When the contact is successfully retrieved:

{
  "status": "success",
  "data": {
    "contact": {
      "_id": "6682840d9286aa59ee3d4181",
      "firstName": "John",
      "lastName": "Doe",
      "fullName": "John Doe",
      "email": "[email protected]",
      "phone": "123-456-7890",
      "address": {
        "line1": "123 Main St",
        "line2": "Apt 4B",
        "city": "Springfield",
        "state": "IL",
        "country": "USA",
        "zipcode": "62704"
      },
      "birthday": "1980-01-01T00:00:00.000Z",
      "occupation": "Software Engineer",
      "gender": "Male",
      "timezone": "America/Chicago",
      "company": {
        "id": "5f8f8c44b54764421b7156b1",
        "name": "Tech Corp"
      },
      "socialMediaUrls": {
        "facebook": "https://facebook.com/johndoe",
        "twitter": "https://twitter.com/johndoe",
        "linkedin": "https://linkedin.com/in/johndoe"
      },
      "department": "Engineering",
      "industry": "Technology",
      "teamSize": 100,
      "annualRevenue": 1000000,
      "website": "https://techcorp.com",
      "tags": ["important", "vip"],
      "workspaceId": "6660175570fbd8a9c22bedfb",
      "createdAt": "2024-07-01T10:25:17.813Z",
      "updatedAt": "2024-07-01T10:25:17.813Z"
    }
  }
}

Error Responses

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

Example Error Response (404)

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

Notes

Ensure the contactId provided exists in the system.
The response includes detailed information about the contact, including personal details, company, and engagement summary