Skip to main content
Contacts

Get contact by external user ID

Retrieves a single contact by their external user ID (from your system via SSO).

GET
/v2/contacts/by-user-id/{userId}

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

{
  "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.

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Path Parameters

userIdstringrequired

External user ID from your system

Maximum string length: 255
Example: usr_12345

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover
Example: 2026-08-19.orbit

Response

application/json

Success

commentsCreatednumber

Number of comments created

Example: 0
companiesobject[]

Companies the contact belongs to

customFieldsobject

Custom field values on the contact

descriptionstring

Contact description/bio

Example:
emailstring | null

Contact email

Example: john@example.com
idstringrequired

Unique identifier

Example: 676f0f6765bdaa7d7d760f88
lastActivitystring

Last activity ISO timestamp

Example: 2025-01-03T21:42:30.181Z
localestring

Contact locale

Example: en
manuallyOptedOutFromChangelogboolean

Whether manually opted out from changelog

Example: false
namestringrequired

Contact display name

Example: John Steezy
objectenum<string>required

Object type identifier

Available options: contact
Example: contact
organizationIdstring

Organization ID the contact belongs to

Example: 5febde12dc56d60012d47db6
postsCreatednumber

Number of posts created

Example: 0
profilePicturestring | null

Profile picture URL

Example: https://fb-usercontent.fra1.cdn.digitaloceanspaces.com/anon_23.png
rolesstring[]

Contact roles

subscribedToChangelogboolean

Whether subscribed to changelog

Example: true
typeenum<string>required

Type of contact

Available options: customer, lead
Example: customer
userIdstring

External user ID from SSO

Example: 676f0f673dbb299c8a4f3057
verifiedboolean

Whether email is verified

Example: true

Still need help? Ask the team