# Contacts

Contacts are the customers and leads in your Featurebase organization. Use this endpoint to list and retrieve contact information.

## List contacts

 - [GET /v2/contacts](https://docs.featurebase.app/rest-api/contacts/listcontacts.md): Returns a list of contacts (customers and leads) in your organization using cursor-based pagination.

### Query Parameters

- limit - Number of contacts to return (1-100, default 10)
- cursor - Cursor from previous response for pagination
- contactType - Filter by contact type: "customer" (default), "lead", or "all"

### Response Format

Returns a list object with:
- object - Always "list"
- data - Array of contact objects
- nextCursor - Cursor for the next page, or null if no more results

### Contact Object

Each contact includes:
- id - Unique contact identifier
- userId - External user ID from SSO (if set)
- email - Contact email address
- name - Contact display name
- profilePicture - Profile picture URL
- type - Contact type ("customer" or "lead")
- companies - Array of companies the contact belongs to
- customFields - Custom field values
- postsCreated - Number of posts created
- commentsCreated - Number of comments created
- lastActivity - Last activity timestamp

### Example

json
{
  "object": "list",
  "data": [
    {
      "object": "contact",
      "id": "676f0f6765bdaa7d7d760f88",
      "email": "john@example.com",
      "name": "John Doe",
      "type": "customer",
      ...
    }
  ],
  "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
}


### Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

## Create or update a contact

 - [POST /v2/contacts](https://docs.featurebase.app/rest-api/contacts/upsertcontact.md): Creates a new contact or updates an existing one.

If a contact with the given email or userId already exists, it will be updated.
Otherwise, a new contact will be created.

At least one of email or userId must be provided for identification.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | One of email/userId | Contact email address |
| userId | string | One of email/userId | External user ID from your system |
| name | string | No | Contact display name |
| profilePicture | string | No | Profile picture URL |
| companies | array | No | Companies the contact belongs to |
| customFields | object | No | Custom field values |
| subscribedToChangelog | boolean | No | Whether subscribed to changelog |
| locale | string | No | Contact locale/language |
| phone | string | No | Contact phone number |
| roles | array | No | Role IDs to assign |
| userHash | string | No | HMAC hash for identity verification |
| createdAt | string | No | When the contact was created (ISO 8601) |

### Company Object

Each company in the companies array can have:
- id (required) - External company ID from your system
- name (required) - Company name
- monthlySpend - Monthly spend/revenue
- customFields - Custom field values
- industry - Industry
- website - Company website URL
- plan - Current plan/subscription
- companySize - Number of employees
- createdAt - When the company was created

### Response

Returns the created or updated contact object.

- 201 Created - A new contact was created
- 200 OK - An existing contact was updated

### Example Request

json
{
  "email": "john@example.com",
  "name": "John Doe",
  "userId": "usr_12345",
  "companies": [
    {
      "id": "company_123",
      "name": "Acme Inc",
      "monthlySpend": 500,
      "plan": "enterprise"
    }
  ],
  "customFields": {
    "plan": "pro",
    "signupSource": "website"
  },
  "subscribedToChangelog": true
}


### Example Response

json
{
  "object": "contact",
  "id": "676f0f6765bdaa7d7d760f88",
  "email": "john@example.com",
  "name": "John Doe",
  "userId": "usr_12345",
  "type": "customer",
  "companies": [...],
  "customFields": {...},
  ...
}


### Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

## Get contact by ID

 - [GET /v2/contacts/{id}](https://docs.featurebase.app/rest-api/contacts/getcontactbyid.md): Retrieves a single contact by their Featurebase ID.

Returns both customers and leads.

### Path Parameters

- id - The Featurebase contact ID (24-character ObjectId)

### Response Format

Returns a single contact object with:
- object - Always "contact"
- id - Unique contact identifier
- userId - External user ID from SSO (if set)
- email - Contact email address
- name - Contact display name
- profilePicture - Profile picture URL
- type - Contact type ("customer" or "lead")
- companies - Array of companies the contact belongs to
- customFields - Custom field values
- postsCreated - Number of posts created
- commentsCreated - Number of comments created
- lastActivity - Last activity timestamp

### Example

json
{
  "object": "contact",
  "id": "676f0f6765bdaa7d7d760f88",
  "email": "john@example.com",
  "name": "John Doe",
  "type": "customer",
  ...
}


### Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

## Delete contact by ID

 - [DELETE /v2/contacts/{id}](https://docs.featurebase.app/rest-api/contacts/deletecontactbyid.md): Permanently deletes a contact by their Featurebase ID.

Supports deleting both customers and leads.

### Path Parameters

- id - The Featurebase contact ID (24-character ObjectId)

### Deletion Behavior

When a contact is deleted:
- The contact record is permanently removed
- Associated data cleanup is triggered asynchronously
- Comments and posts created by the contact are handled according to retention policies

### Response

Returns a deletion confirmation object:
- id - The ID of the deleted contact
- object - Always "contact"
- deleted - Always true

### Example Response

json
{
  "id": "676f0f6765bdaa7d7d760f88",
  "object": "contact",
  "deleted": true
}


### Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

## Get contact by external user ID

 - [GET /v2/contacts/by-user-id/{userId}](https://docs.featurebase.app/rest-api/contacts/getcontactbyuserid.md): Retrieves a single contact by their external user ID (from your system via SSO).

Important: This endpoint only returns customers (type: "customer"). Leads are not returned.

### Path Parameters

- userId - The external user ID from your system (matched via SSO integration)

### Response Format

Returns a single contact object with:
- object - Always "contact"
- id - Unique contact identifier
- userId - External user ID from SSO
- email - Contact email address
- name - Contact display name
- profilePicture - Profile picture URL
- type - Always "customer" for this endpoint
- companies - Array of companies the contact belongs to
- customFields - Custom field values
- postsCreated - Number of posts created
- commentsCreated - Number of comments created
- lastActivity - Last activity timestamp

### Example

json
{
  "object": "contact",
  "id": "676f0f6765bdaa7d7d760f88",
  "userId": "usr_12345",
  "email": "john@example.com",
  "name": "John Doe",
  "type": "customer",
  ...
}


### Use Case

This endpoint is useful when you need to look up a contact using your own system's user identifier, 
such as when displaying Featurebase data alongside your user's information in your own application.

### Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

## Delete contact by external user ID

 - [DELETE /v2/contacts/by-user-id/{userId}](https://docs.featurebase.app/rest-api/contacts/deletecontactbyuserid.md): Permanently deletes a contact by their external user ID.

Important: This endpoint only deletes customers (type: "customer"). Leads cannot be deleted using this endpoint.

### Path Parameters

- userId - The external user ID from your system

### Deletion Behavior

When a contact is deleted:
- The contact record is permanently removed
- Associated data cleanup is triggered asynchronously
- Comments and posts created by the contact are handled according to retention policies

### Response

Returns a deletion confirmation object:
- id - The ID of the deleted contact
- object - Always "contact"
- deleted - Always true

### Example Response

json
{
  "id": "676f0f6765bdaa7d7d760f88",
  "object": "contact",
  "deleted": true
}


### Use Case

Use this endpoint when you need to delete a contact using your own system's user identifier,
such as when a user deletes their account in your application.

### Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

## Block a contact

 - [POST /v2/contacts/{id}/block](https://docs.featurebase.app/rest-api/contacts/blockcontactbyid.md): Blocks a contact by their Featurebase ID from the messenger/inbox.

### Path Parameters

- id - The Featurebase internal ID of the contact (MongoDB ObjectId)

### Supported Contact Types

This endpoint blocks both:
- Customers - Users with registered accounts
- Leads - Anonymous or unregistered visitors

### Blocking Behavior

When a contact is blocked:
- The contact cannot send new messages via messenger
- Existing conversations are not deleted but no new messages can be added by the blocked user
- The block can be removed by unblocking the contact

### Response

Returns a block confirmation object:
- id - The ID of the blocked contact
- object - Always "contact"
- blocked - Always true

### Example Response

json
{
  "id": "507f1f77bcf86cd799439011",
  "object": "contact",
  "blocked": true
}


### Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

## Unblock a contact

 - [POST /v2/contacts/{id}/unblock](https://docs.featurebase.app/rest-api/contacts/unblockcontactbyid.md): Unblocks a contact by their Featurebase ID from the messenger/inbox.

### Path Parameters

- id - The Featurebase internal ID of the contact (MongoDB ObjectId)

### Supported Contact Types

This endpoint unblocks both:
- Customers - Users with registered accounts
- Leads - Anonymous or unregistered visitors

### Unblocking Behavior

When a contact is unblocked:
- The contact can resume sending messages via messenger
- Previously blocked conversations remain intact
- The contact regains full messenger functionality

### Response

Returns an unblock confirmation object:
- id - The ID of the unblocked contact
- object - Always "contact"
- unblocked - Always true

### Example Response

json
{
  "id": "507f1f77bcf86cd799439011",
  "object": "contact",
  "unblocked": true
}


### Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.