​

Customer Endpoints

These endpoints let you manage customers within your organization. Some routes also provide access to additional data such as feedback, highlights, insights, and issues related to specific customers.

​

List Customers

GET /api/v1/organizations/{org_uuid}/customers

Returns a paginated list of customers in the specified organization.

​

Path Parameters

• org_uuid (string) – The UUID of the organization.

​

Query Parameters (optional)

• uuids (comma-separated string) – Filter by specific customer UUIDs.
• page_size (integer, default: 25)
• page_number (integer, default: 1)
• sort_by (string, default: last_interacted_date)
• sort_direction (string, default: desc)
• Other optional filters like company_uuids, personas, search, etc.

​

Example Request

GET /api/v1/organizations/abc123/customers?page_size=10

​

Example Response

{
  "customers": [
    {
      "uuid": "cust-0001",
      "organization_uuid": "abc123",
      "full_name": "Alice Johnson",
      "email": "[email protected]",
      "persona_uuid": null,
      "customer_company_uuid": null
      // ...
    }
  ],
  "total_customer_count": 100
}

​

Create Customer

POST /api/v1/organizations/{org_uuid}/customers

Creates a new customer within the specified organization.

​

Path Parameters

• org_uuid (string)

​

Request Body

{
  "full_name": "Alice Johnson",
  "email": "[email protected]",
  "role": "Marketing Manager",
  "persona_uuid": "persona-1234",       // optional
  "customer_company_uuid": "comp-0001"  // optional
}

​

Example Request

curl -X POST "https://your-domain.com/api/v1/organizations/abc123/customers" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -d '{
    "full_name": "Alice Johnson",
    "email": "[email protected]"
  }'

​

Example Response

{
  "customers": [
    {
      "uuid": "cust-9999",
      "organization_uuid": "abc123",
      "full_name": "Alice Johnson",
      "email": "[email protected]",
      "role": "Marketing Manager",
      "persona_uuid": null,
      "customer_company_uuid": null
      // ...
    }
  ]
}

​

Get Single Customer

GET /api/v1/organizations/{org_uuid}/customers/{customer_uuid}

Retrieves the details of a single customer.

​

Path Parameters

• org_uuid (string)
• customer_uuid (string)

​

Example Request

GET /api/v1/organizations/abc123/customers/cust-9999

​

Example Response

{
  "customers": [
    {
      "uuid": "cust-9999",
      "organization_uuid": "abc123",
      "full_name": "Alice Johnson",
      "email": "[email protected]"
      // ...
    }
  ],
  "total_customer_count": 1
}

​

Update Customer

PUT /api/v1/organizations/{org_uuid}/customers/{customer_uuid}

Updates the details of an existing customer.

​

Path Parameters

• org_uuid (string)
• customer_uuid (string)

​

Request Body

{
  "full_name": "Alice J.",
  "email": "[email protected]",
  "persona_uuid": "persona-5678",
  "customer_company_uuid": "comp-3333"
}

​

Example Request

curl -X PUT "https://your-domain.com/api/v1/organizations/abc123/customers/cust-9999" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -d '{
    "full_name": "Alice J.",
    "email": "[email protected]",
    "persona_uuid": "persona-5678",
    "customer_company_uuid": "comp-3333"
  }'

​

Example Response

{
  "customers": [
    {
      "uuid": "cust-9999",
      "full_name": "Alice J.",
      "email": "[email protected]",
      "persona_uuid": "persona-5678",
      "customer_company_uuid": "comp-3333"
      // ...
    }
  ]
}

​

Get Customer Feedback

GET /api/v1/organizations/{org_uuid}/customers/{customer_uuid}/feedbacks

Returns all feedback associated with the specified customer.

​

Path Parameters

• org_uuid (string)
• customer_uuid (string)

​

Query Parameters

• sort_by, sort_direction (default: feedback_date, desc)
• page_size (integer, default: 25)
• page_number (integer, default: 1)

​

Example Response

{
  "feedbacks": [
    {
      "uuid": "fdbk-1111",
      "organization_uuid": "abc123",
      "feedback_contents": "The product is great!",
      "feedback_date": "2025-03-01T10:00:00"
      // ...
    }
  ]
}

​

Get Customer Feedback Highlights

GET /api/v1/organizations/{org_uuid}/customers/{customer_uuid}/feedback_highlights

Lists highlights from the feedback associated with a specific customer.

​

Path Parameters

• org_uuid (string)
• customer_uuid (string)

​

Query Parameters

• page_size (integer, default: 25)
• page_number (integer, default: 1)

​

Example Response

{
  "highlights": [
    {
      "uuid": "high-0001",
      "quote": "This feature really helped me...",
      "sentiment_score": 0.9
      // ...
    }
  ],
  "total_highlight_count": 10
}

​

Get Customer Insights

GET /api/v1/organizations/{org_uuid}/customers/{customer_uuid}/insights

Lists insights derived from a specific customer’s feedback data.

​

Path Parameters

• org_uuid (string)
• customer_uuid (string)

​

Query Parameters

• page_size (integer, default: 25)
• page_number (integer, default: 1)

​

Example Response

{
  "insights": [
    {
      "uuid": "insg-0001",
      "title": "Feature X usage spike",
      "description": "Customer frequently mentions Feature X.",
      // ...
    }
  ]
}

​

Get Customer Issues

GET /api/v1/organizations/{org_uuid}/customers/{customer_uuid}/issues

Lists issues associated with the specified customer.

​

Path Parameters

• org_uuid (string)
• customer_uuid (string)

​

Query Parameters

• page_size (integer, default: 25)
• page_number (integer, default: 1)

​

Example Response

{
  "issues": [
    {
      "uuid": "issue-1111",
      "title": "Bug in checkout flow",
      "average_sentiment": -0.7
      // ...
    }
  ]
}

​

Additional Notes

• Pagination: All list endpoints support page_size and page_number to manage the volume of results returned.
• Error Handling:
  • 400: Bad or missing parameters.
  • 401: Unauthorized request (missing/invalid token).
  • 404: Customer (or organization) not found.
  • 500: An unexpected internal server error occurred.
• Filtering: Additional filter params may be available (e.g., by persona, feedback count, sentiment, etc.). Refer to the code for a full list of filters.