Feedback Ingestion API

Ingest external feedback data into BuildBetter to analyze alongside your calls and documents. This includes support tickets, NPS surveys, Slack messages, and more.

Quick Start

Create a Feedback Source

Define where your feedback comes from (e.g., “Support Tickets”, “NPS Survey”)

Create or Update People

Ensure the person exists in your system

Send Feedback Records

Ingest structured feedback with content and metadata

Authentication

All requests require authentication:

X-BuildBetter-Api-Key: ORGANIZATION_API_KEY

Endpoints

Create Feedback Source

POST /v3/rest/feedback-sources

Creates a new feedback source to categorize your data.

POST https://api.buildbetter.app/v3/rest/feedback-sources
Content-Type: application/json
X-BuildBetter-Api-Key: ORGANIZATION_API_KEY

{
  "name": "Customer Support Tickets",
  "type": "api"
}

Response:

{
  "id": 123,
  "name": "Customer Support Tickets",
  "type": "api",
  "created_at": "2025-01-01T12:00:00Z"
}

Create or Update Person

PUT /v3/rest/people

Ensures a person exists before ingesting their feedback.

PUT https://api.buildbetter.app/v3/rest/people
Content-Type: application/json
X-BuildBetter-Api-Key: ORGANIZATION_API_KEY

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "boundary": "external",
  "company": {
    "name": "Example Corp",
    "domain": "example.com"
  }
}

Response:

{
  "id": 456,
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "company_id": 789,
  "created_at": "2025-01-01T12:00:00Z"
}

Ingest Feedback Record

POST /v3/rest/feedback-sources/{id}/records

Sends structured feedback data to a feedback source.

POST https://api.buildbetter.app/v3/rest/feedback-sources/123/records
Content-Type: application/json
X-BuildBetter-Api-Key: ORGANIZATION_API_KEY

{
  "person_id": 456,
  "display_ts": "2025-01-01T10:30:00Z",
  "external_id": "unique-id-123",
  "fields": [
    {
      "category": "content",
      "type": "string",
      "name": "feedback",
      "value": "Your actual feedback text here"
    },
    {
      "category": "metadata",
      "type": "string",
      "name": "priority",
      "value": "high"
    }
  ]
}

Response:

{
  "id": 789,
  "person_id": 456,
  "feedback_source_id": 123,
  "display_ts": "2025-01-01T10:30:00Z",
  "external_id": "unique-id-123",
  "created_at": "2025-01-01T10:30:00Z"
}

Field Structure

Types

boolean - True/false values
date - Date only values
datetime - Date and time values
float - Decimal numeric values
integer - Whole number values
json - Structured JSON data
string - Text content

Example Field

{
  "category": "content",
  "type": "string",
  "name": "customer_comment",
  "value": "The new dashboard is fantastic!"
}

Implementation Examples

Support Tickets
NPS Survey
Slack Feedback

curl -X POST https://api.buildbetter.app/v3/rest/feedback-sources/123/records \
  -H "X-BuildBetter-Api-Key: ORGANIZATION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "person_id": 456,
    "display_ts": "2025-01-01T10:30:00Z",
    "external_id": "ticket-789",
    "fields": [
      {
        "category": "content",
        "type": "string",
        "name": "subject",
        "value": "Cannot log into mobile app"
      },
      {
        "category": "content",
        "type": "string",
        "name": "description",
        "value": "Face ID authentication is failing on iOS"
      },
      {
        "category": "metadata",
        "type": "string",
        "name": "priority",
        "value": "high"
      },
      {
        "category": "metadata",
        "type": "string",
        "name": "product_area",
        "value": "mobile_auth"
      }
    ]
  }'

curl -X POST https://api.buildbetter.app/v3/rest/feedback-sources/124/records \
  -H "X-BuildBetter-Api-Key: ORGANIZATION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "person_id": 456,
    "display_ts": "2025-01-01T14:00:00Z",
    "external_id": "nps-2025-q1-456",
    "fields": [
      {
        "category": "content",
        "type": "integer",
        "name": "nps_score",
        "value": 9
      },
      {
        "category": "content",
        "type": "string",
        "name": "feedback",
        "value": "Love the new features!"
      },
      {
        "category": "metadata",
        "type": "string",
        "name": "survey_type",
        "value": "quarterly_nps"
      }
    ]
  }'

curl -X POST https://api.buildbetter.app/v3/rest/feedback-sources/125/records \
  -H "X-BuildBetter-Api-Key: ORGANIZATION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "person_id": 789,
    "display_ts": "2025-01-01T16:45:00Z",
    "external_id": "slack-msg-abc123",
    "fields": [
      {
        "category": "content",
        "type": "string",
        "name": "message",
        "value": "The API is really slow today"
      },
      {
        "category": "metadata",
        "type": "string",
        "name": "channel",
        "value": "#product-feedback"
      },
      {
        "category": "metadata",
        "type": "string",
        "name": "urgency",
        "value": "medium"
      }
    ]
  }'

Best Practices

Use external_id to prevent duplicate records
Set display_ts to the original timestamp when the feedback was created
Validate data before sending to avoid errors
Use snake_case and descriptive field names for consistency
Include relevant metadata for better filtering and analysis

Error Handling

Common error responses and how to handle them:

400 Bad Request

Invalid request format or missing required fieldsCheck that:

All required fields are present
JSON is properly formatted
Field types match expected values

401 Unauthorized

Invalid or missing API keyEnsure:

API key is included in X-BuildBetter-Api-Key header
Key format is correct
API key has necessary permissions

404 Not Found

Feedback source or person not foundVerify:

Feedback source ID exists
Person ID is valid (if provided)
You have access to the resource

409 Conflict

Duplicate external_id detectedResolution:

Use a unique external_id
Check if record already exists
Update existing record if needed

Rate Limits

Requests per minute: 100
Records per request: 1
Field size limit: 10KB per field value

Next Steps

Legacy GraphQL Reference

Reference legacy GraphQL queries during migration

Explore Webhooks

Set up real-time notifications for feedback events

Getting Started

Legacy GraphQL API

REST API

Webhooks

Reference

Feedback Ingestion API

Quick Start

Authentication

Endpoints

Create Feedback Source

POST /v3/rest/feedback-sources

Create or Update Person

PUT /v3/rest/people

Ingest Feedback Record

POST /v3/rest/feedback-sources/{id}/records

Field Structure

Categories

Types

Example Field

Implementation Examples

Best Practices

Error Handling

Rate Limits

Next Steps

Legacy GraphQL Reference

Explore Webhooks

​Quick Start

​Authentication

​Endpoints

​Create Feedback Source

POST /v3/rest/feedback-sources

​Create or Update Person

PUT /v3/rest/people

​Ingest Feedback Record

POST /v3/rest/feedback-sources/{id}/records

​Field Structure

​Categories

​Types

​Example Field

​Implementation Examples

​Best Practices

​Error Handling

​Rate Limits

​Next Steps

Legacy GraphQL Reference

Explore Webhooks

Quick Start

Authentication

Endpoints

Create Feedback Source

Create or Update Person

Ingest Feedback Record

Field Structure

Categories

Types

Example Field

Implementation Examples

Best Practices

Error Handling

Rate Limits

Next Steps