Perly

API Reference

The Perly REST API lets you programmatically manage customers, query health scores, ingest events, and configure integrations. All endpoints return JSON and use standard HTTP status codes.

Base URL
https://api.perly.ai
Authentication
Bearer <YOUR_API_KEY>

Quick example

curl -X GET "https://api.perly.ai/v1/customers?limit=10" \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json"

Customers

Create, retrieve, update, and manage customer profiles and metadata.

GET
/v1/customers

List all customers with optional filters and pagination

GET
/v1/customers/:id

Retrieve a single customer by ID

POST
/v1/customers

Create a new customer profile

PATCH
/v1/customers/:id

Update customer attributes and metadata

DELETE
/v1/customers/:id

Delete a customer and associated data

Health Scores

Query computed health scores, trends, and risk assessments for customers.

GET
/v1/customers/:id/health

Get the current health score and contributing signals for a customer

GET
/v1/customers/:id/health/history

Retrieve historical health score data with daily or weekly granularity

GET
/v1/health/summary

Aggregate health score distribution across all customers

GET
/v1/health/at-risk

List customers whose health score dropped below a threshold

Events & Signals

Ingest custom events and retrieve signal data that feeds into health scores.

POST
/v1/events

Ingest a batch of custom events (up to 1,000 per call)

GET
/v1/events

Query events with filters for customer, type, and date range

GET
/v1/signals/:customerId

List computed signals (usage, engagement, billing) for a customer

Integrations

Manage connected third-party integrations and sync status.

GET
/v1/integrations

List all configured integrations and their sync status

POST
/v1/integrations

Connect a new integration (Stripe, HubSpot, Salesforce, etc.)

GET
/v1/integrations/:id

Retrieve details and sync history for an integration

DELETE
/v1/integrations/:id

Disconnect an integration and stop syncing

POST
/v1/integrations/:id/sync

Trigger an immediate sync for a specific integration

Webhooks

Configure webhook endpoints to receive real-time notifications.

GET
/v1/webhooks

List all registered webhook endpoints

POST
/v1/webhooks

Register a new webhook endpoint with event subscriptions

PATCH
/v1/webhooks/:id

Update webhook URL, events, or active status

DELETE
/v1/webhooks/:id

Delete a webhook endpoint

Rate Limits

All API endpoints are rate-limited per API key. Default limits:

  • Read endpoints (GET): 1,000 requests/minute
  • Write endpoints (POST/PATCH/DELETE): 200 requests/minute
  • Event ingestion: 10,000 events/minute

Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response.

Error Codes

400Bad RequestInvalid parameters or request body
401UnauthorizedMissing or invalid API key
403ForbiddenInsufficient permissions for this action
404Not FoundResource does not exist
429Too Many RequestsRate limit exceeded
500Internal Server ErrorSomething went wrong on our end