Display API

Track when surveys are displayed to users

The Display API allows you to track when surveys are shown to users. This data is used for analytics and to prevent over-surveying.

Create a Display

Record that a survey was displayed to a user.

POST /api/v1/client/{environmentId}/displays

cURL

curl -X POST https://app.formbricks.com/api/v1/client/{environmentId}/displays \
  -H "Content-Type: application/json" \
  -d '{
    "surveyId": "srv_...",
    "userId": "user_123"
  }'

Path Parameters

environmentId · string · required

Your Formbricks environment ID

Body Parameters

surveyId · string · required

The ID of the survey that was displayed

userId · string

The user identifier (Enterprise only - for contact tracking)

Response

{
  "id": "dsp_...",
  "createdAt": "2021-01-01T00:00:00.000Z",
  "updatedAt": "2021-01-01T00:00:00.000Z",
  "surveyId": "srv_...",
  "contactId": "con_..."
}

id · string

The unique identifier for this display event

createdAt · string

ISO 8601 timestamp of when the display was recorded

updatedAt · string

ISO 8601 timestamp of when the display was last updated

surveyId · string

The ID of the displayed survey

contactId · string | null

The contact ID if user tracking is enabled

Use Cases

Track Survey Impressions

Know how many times a survey was shown, even if users didn’t respond:

// When showing a survey to a user
await fetch('https://app.formbricks.com/api/v1/client/env_123/displays', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    surveyId: 'srv_456'
  })
});

// Calculate response rate: responses / displays

Prevent Survey Fatigue

Use display data to limit how often users see surveys:

// Check recent displays for a user
const recentDisplays = await getRecentDisplays(userId);

if (recentDisplays.length < 3) {
  // User hasn't seen many surveys recently
  await trackDisplay({ surveyId, userId });
  showSurvey();
} else {
  // Don't over-survey this user
  console.log('User has seen too many surveys recently');
}

Link Displays to Responses

When a user responds to a survey, you can link it to the display:

// Track display
const display = await fetch(
  'https://app.formbricks.com/api/v1/client/env_123/displays',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ surveyId: 'srv_456' })
  }
).then(r => r.json());

// When user responds, include displayId
await fetch('https://app.formbricks.com/api/v1/client/env_123/responses', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    surveyId: 'srv_456',
    displayId: display.id,
    finished: true,
    data: { qst_1: 'answer' }
  })
});

Enterprise Features

User identification in displays requires an Enterprise plan. Free and Pro plans can track displays but cannot associate them with specific users.

User Tracking

For Enterprise customers, provide a userId to track which users saw which surveys:

await fetch('https://app.formbricks.com/api/v1/client/env_123/displays', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    surveyId: 'srv_456',
    userId: 'user_123' // Enterprise only
  })
});

Non-Enterprise attempts to use userId will receive:

{
  "message": "User identification is only available for enterprise users."
}

CORS Support

The Display API supports CORS for browser-based applications:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type

Preflight OPTIONS requests are cached for 1 hour.

Error Responses

Survey Not Found

{
  "message": "Survey not found"
}

Invalid Environment

{
  "message": "Fields are missing or incorrectly formatted",
  "details": {
    "environmentId": "Invalid environment ID"
  }
}

Enterprise Feature Required

{
  "message": "User identification is only available for enterprise users."
}

Best Practices

1. Track Before Showing: Record the display before actually showing the survey to the user
2. Handle Failures Gracefully: Don’t block the survey from showing if display tracking fails
3. Debounce: Avoid recording multiple displays if the user refreshes the page
4. Privacy: Respect user privacy and data regulations when tracking displays

Integration with Formbricks SDK

If you’re using the Formbricks JavaScript SDK, display tracking is handled automatically:

import formbricks from '@formbricks/js';

formbricks.init({
  environmentId: 'env_123',
  apiHost: 'https://app.formbricks.com'
});

// Displays are tracked automatically when surveys are shown

The SDK manages display tracking, response correlation, and display frequency logic for you.