Skip to main content
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

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

​
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