Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.buildbetter.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

1

Create a Feedback Source

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

Create or Update People

Ensure the person exists in your system
3

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

​
Categories

  • content - The actual feedback (comments, descriptions, messages)
  • created_at - Timestamp fields
  • identifier - External identifiers and references
  • identity - User or entity identification fields
  • metadata - Additional context (priority, tags, channel, etc.)

​
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

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"
      }
    ]
  }'

​
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:
Invalid request format or missing required fieldsCheck that:
  • All required fields are present
  • JSON is properly formatted
  • Field types match expected values
Invalid or missing API keyEnsure:
  • API key is included in X-BuildBetter-Api-Key header
  • Key format is correct
  • API key has necessary permissions
Feedback source or person not foundVerify:
  • Feedback source ID exists
  • Person ID is valid (if provided)
  • You have access to the resource
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

View the GraphQL API

Learn how to query your ingested feedback data

Explore Webhooks

Set up real-time notifications for feedback events