Submit Feedback via REST API

Submit customer feedback directly to Lexsis AI using our REST API. This endpoint allows you to programmatically send feedback from any source, with full control over metadata and processing.

Overview

The feedback submission API endpoint allows you to:

• Submit individual feedback items programmatically

• Include rich metadata for better classification

• Trigger automatic processing pipeline

• Integrate Lexsis AI into your existing workflows

Endpoint

POST https://api.trylexsis.com/v1/submissions

Authentication

Requires an API key with write permission. Include it in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Request Format

Headers

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Request Body Schema

{
  "source_id": "uuid",
  "source_identifier": "string",
  "raw_content": "string",
  "submitted_at": "ISO 8601 datetime",
  "related_metadata": {
    // Optional metadata fields
  }
}

Required Fields

Field	Type	Description
source_id	UUID	The UUID of the source integration where this feedback originates
source_identifier	string	Unique identifier from your system (e.g., review ID, ticket ID). Must be unique per source
raw_content	string	The raw feedback text content (minimum 1 character)
submitted_at	ISO datetime	Timestamp when the feedback was submitted in the source system (ISO 8601 format)

Optional Fields - Related Metadata

The related_metadata object accepts any fields from the standard metadata schema. All fields are optional:

Customer/User Information

• customer_id (string): Unique identifier for the customer/user

• customer_name (string): Customer/user name

• customer_email (string): Customer email address

• customer_segment (string): Customer segment - one of: Enterprise, SMB, Free, Trial

• customer_value (float): Monetary value of customer (MRR, LTV, etc.) - used for priority calculation

Business/Organization Information

• business_name (string): Business/organization name

• business_id (string): Unique identifier for business/organization

Platform/Product Information

• platform (string): Platform where feedback was submitted - one of: iOS, Android, Web, Desktop, Mobile, Tablet

• app_version (string): Application version (e.g., 4.94.0)

• product_version (string): Product version

• review_created_version (string): App version when review was created

Customer Journey Information

• account_age_days (integer): Number of days since account creation (used for journey stage inference)

• usage_frequency (string): Frequency of product usage - one of: Daily, Weekly, Monthly, Rarely, Never

• subscription_status (string): Subscription status - one of: Active, Trial, Expired, Cancelled

Rating/Score Information

• score (integer): Rating score (1-5 stars)

• thumbs_up_count (integer): Number of thumbs up/helpful votes

Location/Geography

• location (string): Geographic location (country, region, etc.)

• country (string): Country code (ISO 3166-1 alpha-2, e.g., us, gb)

• language (string): Language code (ISO 639-1, e.g., en, es)

Response/Reply Information

• reply_content (string): Response/reply content from business

• replied_at (ISO datetime): Timestamp when reply was posted

Additional Metadata

• user_image (string): User avatar/image URL

• source_review_id (string): Original review ID from source system

Custom Fields

Any additional fields in related_metadata will be preserved in the source_specific dictionary for reference.

Request Examples

Minimal Example (Required Fields Only)

{
  "source_id": "123e4567-e89b-12d3-a456-426614174000",
  "source_identifier": "review-12345",
  "raw_content": "The app crashes when I try to upload photos. Very frustrating!",
  "submitted_at": "2024-01-15T10:30:00Z"
}

Example with Customer Metadata

{
  "source_id": "123e4567-e89b-12d3-a456-426614174000",
  "source_identifier": "review-12346",
  "raw_content": "Love the new dashboard design! Much easier to navigate.",
  "submitted_at": "2024-01-15T11:00:00Z",
  "related_metadata": {
    "customer_id": "user-789",
    "customer_name": "John Doe",
    "customer_email": "[e-mail]",
    "customer_segment": "Enterprise",
    "customer_value": 5000.00,
    "platform": "Web",
    "app_version": "2.1.0",
    "score": 5
  }
}

Example with Platform and Journey Information

{
  "source_id": "123e4567-e89b-12d3-a456-426614174000",
  "source_identifier": "ticket-456",
  "raw_content": "Having trouble logging in on iOS. The password reset isn't working.",
  "submitted_at": "2024-01-15T14:20:00Z",
  "related_metadata": {
    "customer_id": "user-123",
    "customer_name": "Jane Smith",
    "platform": "iOS",
    "app_version": "3.2.1",
    "account_age_days": 45,
    "usage_frequency": "Daily",
    "subscription_status": "Active",
    "country": "us",
    "language": "en"
  }
}

Example with Rating and Response

{
  "source_id": "123e4567-e89b-12d3-a456-426614174000",
  "source_identifier": "review-12347",
  "raw_content": "Great customer support! They resolved my issue quickly.",
  "submitted_at": "2024-01-15T09:15:00Z",
  "related_metadata": {
    "customer_name": "Bob Wilson",
    "score": 5,
    "thumbs_up_count": 12,
    "reply_content": "Thank you for your feedback! We're glad we could help.",
    "replied_at": "2024-01-15T10:00:00Z"
  }
}

Response Format

Success Response (201 Created)

{
  "status": "success",
  "message": "Submission created successfully",
  "data": {
    "id": "789e4567-e89b-12d3-a456-426614174000",
    "tenant_id": "456e4567-e89b-12d3-a456-426614174000",
    "source_id": "123e4567-e89b-12d3-a456-426614174000",
    "source_identifier": "review-12345",
    "raw_content": "The app crashes when I try to upload photos...",
    "submitted_at": "2024-01-15T10:30:00Z",
    "ingested_at": "2024-01-15T10:30:05Z",
    "related_metadata": {
      // Your submitted metadata
    },
    "is_segmented": false,
    "segmentation_metadata": {},
    "created_at": "2024-01-15T10:30:05Z",
    "updated_at": "2024-01-15T10:30:05Z"
  }
}

Error Responses

400 Bad Request - Invalid Source

{
  "status": "error",
  "message": "Source validation failed",
  "detail": "Source with ID {source_id} does not belong to tenant {tenant_id}"
}

400 Bad Request - Duplicate Source Identifier

{
  "status": "error",
  "message": "Submission already exists",
  "detail": "Submission with source_identifier 'review-12345' already exists for this source"
}

401 Unauthorized

{
  "status": "error",
  "message": "Unauthorized",
  "detail": "Invalid or missing API key"
}

404 Not Found - Source Not Found

{
  "status": "error",
  "message": "Source not found",
  "detail": "Source with ID {source_id} not found"
}

Processing Behavior

Automatic Processing

If your tenant has auto_process_submissions enabled, submissions are automatically processed through the pipeline:

1. Segmentation: Feedback is broken into individual segments

2. Classification: Each segment is classified by intent, priority, sentiment, etc.

3. Bucketing: Similar segments are grouped into buckets

Processing typically completes within a few seconds to minutes, depending on submission volume.

Manual Processing

If automatic processing is disabled, submissions are stored but not processed. You can trigger processing manually via the pipeline API endpoints.

Best Practices

Unique Source Identifiers

Ensure source_identifier is unique per source. Duplicate identifiers will result in an error. Use a combination of your system's ID and timestamp if needed:

{
  "source_identifier": "ticket-12345-20240115"
}

Accurate Timestamps

Use the actual timestamp when feedback was submitted, not when you're sending it to the API. This ensures accurate trend analysis:

{
  "submitted_at": "2024-01-15T10:30:00Z"  // When customer submitted, not now
}

Metadata Enrichment

Include as much metadata as possible to improve classification accuracy:

• Customer value: Helps prioritize high-value customer feedback

• Platform information: Enables platform-specific analysis

• Journey stage: Improves journey stage classification

• Ratings: Enables sentiment and satisfaction analysis

Batch Submissions

For multiple submissions, send them sequentially or use the CSV upload endpoint for bulk uploads.

Code Examples

cURL

curl -X POST https://api.trylexsis.com/v1/submissions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "source_id": "123e4567-e89b-12d3-a456-426614174000",
    "source_identifier": "review-12345",
    "raw_content": "The app crashes when I try to upload photos.",
    "submitted_at": "2024-01-15T10:30:00Z"
  }'

Python

import requests
from datetime import datetime

url = "https://api.trylexsis.com/v1/submissions"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
data = {
    "source_id": "123e4567-e89b-12d3-a456-426614174000",
    "source_identifier": "review-12345",
    "raw_content": "The app crashes when I try to upload photos.",
    "submitted_at": datetime.now().isoformat() + "Z",
    "related_metadata": {
        "customer_name": "John Doe",
        "platform": "iOS",
        "score": 2
    }
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

JavaScript

const response = await fetch('https://api.trylexsis.com/v1/submissions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    source_id: '123e4567-e89b-12d3-a456-426614174000',
    source_identifier: 'review-12345',
    raw_content: 'The app crashes when I try to upload photos.',
    submitted_at: new Date().toISOString(),
    related_metadata: {
      customer_name: 'John Doe',
      platform: 'iOS',
      score: 2
    }
  })
});

const data = await response.json();
console.log(data);

Next Steps

• CSV Upload Guide - Upload feedback in bulk via CSV

• API Overview - Explore other API endpoints

• Getting Started Guide - Set up your account