Contacts

Contacts represent individuals who interact with your workspace. They can be visitors, leads, or users, and contain profile information, activity history, and relationships to companies and deals.

The Contact Object

Name
id
Type
uuid
Description
Unique identifier for the contact.
Name
workspace_id
Type
uuid
Description
The workspace this contact belongs to.
Name
user_id
Type
string
Description
External user identifier from your system.
Name
type
Type
string
Description
Contact type: visitor, lead, or user.
Name
name
Type
string
Description
Contact's full name.
Name
email
Type
string
Description
Contact's email address.
Name
phone
Type
string
Description
Contact's phone number.
Name
notes
Type
string
Description
Internal notes about the contact.
Name
is_online
Type
boolean
Description
Whether the contact is currently online.
Name
is_blocked
Type
boolean
Description
Whether the contact is blocked from interacting.
Name
is_subscribed
Type
boolean
Description
Whether the contact is subscribed to communications.
Name
last_seen
Type
datetime
Description
Last time the contact was active.
Name
first_seen
Type
datetime
Description
First time the contact was seen.
Name
sign_up
Type
datetime
Description
When the contact signed up.
Name
web_sessions
Type
integer
Description
Number of web sessions recorded.
Name
last_page
Type
object
Description
Last page visited by the contact.
Name
last_ip
Type
string
Description
Last IP address used.
Name
locale
Type
string
Description
Contact's locale/language preference.
Name
timezone
Type
string
Description
Contact's timezone.
Name
country
Type
string
Description
Contact's country.
Name
state
Type
string
Description
Contact's state/region.
Name
city
Type
string
Description
Contact's city.
Name
browser
Type
string
Description
Browser used by the contact.
Name
browser_version
Type
string
Description
Browser version.
Name
os
Type
string
Description
Operating system.
Name
device
Type
string
Description
Device type (desktop, mobile, tablet).
Name
utm_source
Type
string
Description
UTM source parameter.
Name
utm_medium
Type
string
Description
UTM medium parameter.
Name
utm_campaign
Type
string
Description
UTM campaign parameter.
Name
utm_term
Type
string
Description
UTM term parameter.
Name
utm_content
Type
string
Description
UTM content parameter.
Name
attributes
Type
object
Description
Custom attributes stored as key-value pairs.
Name
photo_url
Type
string
Description
Auto-generated avatar URL.
Name
name_formatted
Type
string
Description
Formatted display name (falls back to email if name is empty).
Name
created_at
Type
datetime
Description
Timestamp when the contact was created.
Name
updated_at
Type
datetime
Description
Timestamp when the contact was last updated.

GET/app/contacts

List Contacts

Retrieve a paginated list of contacts in your workspace. Results can be filtered by segment and searched by name or email.

Query Parameters

Name
segment
Type
uuid
Required
*
Description
Segment ID to filter contacts. Must be a valid segment of type contact.
Name
q
Type
string
Description
Search query to filter contacts by name or email (uses full-text search).
Name
page
Type
integer
Description
Page number for pagination (default: 1).

Request

GET

/app/contacts

curl "https://api.pipeback.com/app/contacts?segment=9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"

Response

{
  "data": [
    {
      "id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
      "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
      "user_id": "usr_1234567890",
      "type": "user",
      "name": "John Doe",
      "email": "john@example.com",
      "phone": null,
      "notes": null,
      "is_online": false,
      "is_blocked": false,
      "is_subscribed": true,
      "last_seen": "2025-10-26T15:30:00.000000Z",
      "first_seen": "2025-01-15T10:20:00.000000Z",
      "sign_up": "2025-01-15T10:20:00.000000Z",
      "web_sessions": 45,
      "last_page": {
        "url": "https://example.com/dashboard",
        "title": "Dashboard"
      },
      "last_ip": "192.168.1.1",
      "locale": "en",
      "timezone": "America/New_York",
      "country": "United States",
      "state": "New York",
      "city": "New York",
      "browser": "Chrome",
      "browser_version": "120.0",
      "os": "macOS",
      "device": "desktop",
      "utm_source": "google",
      "utm_medium": "cpc",
      "utm_campaign": "spring_sale",
      "utm_term": null,
      "utm_content": null,
      "attributes": {
        "plan": "pro",
        "mrr": 99
      },
      "photo_url": "https://ui-avatars.com/api/?name=John+Doe&color=1D2674&background=EAF0FB&length=1",
      "name_formatted": "John Doe",
      "created_at": "2025-01-15T10:20:00.000000Z",
      "updated_at": "2025-10-26T15:30:00.000000Z",
      "companies": [
        {
          "id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7a",
          "name": "Acme Corporation"
        }
      ]
    }
  ],
  "links": {
    "first": "https://api.pipeback.com/app/contacts?page=1",
    "last": "https://api.pipeback.com/app/contacts?page=10",
    "prev": null,
    "next": "https://api.pipeback.com/app/contacts?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 10,
    "per_page": 25,
    "to": 25,
    "total": 250
  }
}

POST/app/contacts

Create a Contact

Create a new contact in your workspace.

Required Attributes

Name
type
Type
string
Required
*
Description
Contact type: visitor, lead, or user.
Name
email
Type
string
Required
*
Description
Contact's email address. Must be unique per workspace and type combination.

Optional Attributes

Name
name
Type
string
Description
Contact's full name (max 255 characters).
Name
user_id
Type
string
Description
External user identifier from your system (max 255 characters).

Request

POST

/app/contacts

curl -X POST https://api.pipeback.com/app/contacts \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "user",
    "email": "jane@example.com",
    "name": "Jane Doe"
  }'

Response

{
  "id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6c",
  "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
  "user_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6c",
  "type": "user",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": null,
  "notes": null,
  "is_online": false,
  "is_blocked": false,
  "is_subscribed": true,
  "last_seen": null,
  "first_seen": null,
  "sign_up": null,
  "web_sessions": 0,
  "last_page": null,
  "last_ip": null,
  "locale": null,
  "timezone": null,
  "country": null,
  "state": null,
  "city": null,
  "browser": null,
  "browser_version": null,
  "os": null,
  "device": null,
  "utm_source": null,
  "utm_medium": null,
  "utm_campaign": null,
  "utm_term": null,
  "utm_content": null,
  "attributes": null,
  "photo_url": "https://ui-avatars.com/api/?name=Jane+Doe&color=1D2674&background=EAF0FB&length=1",
  "name_formatted": "Jane Doe",
  "created_at": "2025-10-26T16:00:00.000000Z",
  "updated_at": "2025-10-26T16:00:00.000000Z"
}

GET/app/contacts/{id}

Retrieve a Contact

Retrieve detailed information about a specific contact, including related companies, conversations, tags, events, and deals.

Request

GET

/app/contacts/{id}

curl https://api.pipeback.com/app/contacts/9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"

Response

{
  "id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
  "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
  "user_id": "usr_1234567890",
  "type": "user",
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "notes": "Important customer",
  "is_online": false,
  "is_blocked": false,
  "is_subscribed": true,
  "last_seen": "2025-10-26T15:30:00.000000Z",
  "first_seen": "2025-01-15T10:20:00.000000Z",
  "sign_up": "2025-01-15T10:20:00.000000Z",
  "web_sessions": 45,
  "last_page": {
    "url": "https://example.com/dashboard",
    "title": "Dashboard"
  },
  "last_ip": "192.168.1.1",
  "locale": "en",
  "timezone": "America/New_York",
  "country": "United States",
  "state": "New York",
  "city": "New York",
  "browser": "Chrome",
  "browser_version": "120.0",
  "os": "macOS",
  "device": "desktop",
  "utm_source": "google",
  "utm_medium": "cpc",
  "utm_campaign": "spring_sale",
  "utm_term": null,
  "utm_content": null,
  "attributes": {
    "plan": "pro",
    "mrr": 99
  },
  "photo_url": "https://ui-avatars.com/api/?name=John+Doe&color=1D2674&background=EAF0FB&length=1",
  "name_formatted": "John Doe",
  "created_at": "2025-01-15T10:20:00.000000Z",
  "updated_at": "2025-10-26T15:30:00.000000Z",
  "companies": [
    {
      "id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7a",
      "name": "Acme Corporation",
      "contacts_count": 5
    }
  ],
  "tags": [
    {
      "id": "9d5f3d04-4d81-6f3c-0c5g-3d4e5f6g7h8a",
      "name": "VIP",
      "color": "blue"
    }
  ],
  "conversations": [],
  "contact_page_views": [],
  "events": [],
  "recent_events": [],
  "deals": []
}

PUT/app/contacts/{id}

Update a Contact

Update an existing contact's information.

Attributes

Name
name
Type
string
Description
Contact's full name (max 255 characters).
Name
email
Type
string
Description
Contact's email address (max 255 characters). Must be unique in the workspace.
Name
notes
Type
string
Description
Internal notes about the contact.
Name
tags
Type
array
Description
Array of tag IDs to associate with the contact. This will replace existing tags.

Request

PUT

/app/contacts/{id}

curl -X PUT https://api.pipeback.com/app/contacts/9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe Updated",
    "email": "john.updated@example.com",
    "notes": "Updated important customer notes",
    "tags": ["9d5f3d04-4d81-6f3c-0c5g-3d4e5f6g7h8a"]
  }'

Response

{
  "id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
  "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
  "user_id": "usr_1234567890",
  "type": "user",
  "name": "John Doe Updated",
  "email": "john.updated@example.com",
  "phone": "+1234567890",
  "notes": "Updated important customer notes",
  "is_online": false,
  "is_blocked": false,
  "is_subscribed": true,
  "last_seen": "2025-10-26T15:30:00.000000Z",
  "first_seen": "2025-01-15T10:20:00.000000Z",
  "sign_up": "2025-01-15T10:20:00.000000Z",
  "web_sessions": 45,
  "attributes": {
    "plan": "pro",
    "mrr": 99
  },
  "photo_url": "https://ui-avatars.com/api/?name=John+Doe+Updated&color=1D2674&background=EAF0FB&length=1",
  "name_formatted": "John Doe Updated",
  "created_at": "2025-01-15T10:20:00.000000Z",
  "updated_at": "2025-10-26T16:15:00.000000Z"
}

DELETE/app/contacts/{id}

Delete a Contact

Delete a contact from your workspace. This action cannot be undone.

Request

DELETE

/app/contacts/{id}

curl -X DELETE https://api.pipeback.com/app/contacts/9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"

Response

{
  "id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
  "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
  "user_id": "usr_1234567890",
  "type": "user",
  "name": "John Doe",
  "email": "john@example.com",
  "deleted_at": "2025-10-26T16:20:00.000000Z"
}