​
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.