Customers
Private previewCustomer resources anchor the public platform. They give downstream systems a stable identity model for accounts, service locations, communication preferences, and lifecycle activity.
Base path
/api/public/v1/customers
read:customerswrite:customersdelete:customers
Schemas
Customer
Canonical public representation of a customer record in Asteri.
| Field | Type | Required | Description |
|---|---|---|---|
| id | uuid | Yes | Stable customer identifier. |
| organization_id | uuid | Yes | Organization that owns the record. |
| account_type | "individual" | "business" | Yes | High-level account classification. |
| display_name | string | Yes | Primary display name shown across the platform. |
| string | null | Yes | Primary contact email. | |
| phone | string | null | Yes | Primary contact phone number. |
| created_at | datetime | Yes | ISO-8601 timestamp for record creation. |
Generated example
{
"id": "8af2ca8e-8f31-4e6e-a46c-0703b61f7ca3",
"organization_id": "dce3853d-4f94-4bc8-a816-4d0d74c11a9d",
"account_type": "business",
"display_name": "North Harbor Facilities",
"email": "ops@northerborfacilities.com",
"phone": "+1-404-555-0128",
"created_at": "2026-03-18T15:40:12.000Z"
}CreateCustomerRequest
Payload for creating a customer in the public API.
| Field | Type | Required | Description |
|---|---|---|---|
| account_type | "individual" | "business" | Yes | Account classification used when creating the customer. |
| display_name | string | No | Customer display name or company name. Useful when you do not want to provide explicit name fields. |
| company_name | string | No | Explicit company name for business accounts. |
| first_name | string | No | Primary contact first name. |
| last_name | string | No | Primary contact last name. |
| string | Yes | Primary contact email. | |
| phone | string | Yes | Primary contact phone number. |
Generated example
{
"account_type": "business",
"display_name": "North Harbor Facilities",
"company_name": "North Harbor Facilities",
"first_name": "Nora",
"last_name": "Harbor",
"email": "ops@northerborfacilities.com",
"phone": "+1-404-555-0128"
}CustomerListResponse
Response body for customer list endpoints.
| Field | Type | Required | Description |
|---|---|---|---|
| data | Customer[] | Yes | Collection of customers matching the current filter set. |
| pagination | Pagination | Yes | List metadata for page traversal. |
Generated example
{
"data": [
{
"id": "8af2ca8e-8f31-4e6e-a46c-0703b61f7ca3",
"organization_id": "dce3853d-4f94-4bc8-a816-4d0d74c11a9d",
"account_type": "business",
"display_name": "North Harbor Facilities",
"email": "ops@northerborfacilities.com",
"phone": "+1-404-555-0128",
"created_at": "2026-03-18T15:40:12.000Z"
}
],
"pagination": {
"count": 2,
"limit": 25,
"next_cursor": null
}
}Endpoints
GET
Private preview/api/public/v1/customersList customers in the active organization with filtering and pagination.
read:customers
Common errors: 400 Bad request · 401 Unauthorized · 403 Forbidden · 429 Rate limited · 500 Internal error
No request body contract for this endpoint.
Response body
CustomerListResponse
{
"data": [
{
"id": "8af2ca8e-8f31-4e6e-a46c-0703b61f7ca3",
"organization_id": "dce3853d-4f94-4bc8-a816-4d0d74c11a9d",
"account_type": "business",
"display_name": "North Harbor Facilities",
"email": "ops@northerborfacilities.com",
"phone": "+1-404-555-0128",
"created_at": "2026-03-18T15:40:12.000Z"
}
],
"pagination": {
"count": 2,
"limit": 25,
"next_cursor": null
}
}Error responses
400
Bad request
Missing or invalid organization context.
Usually happens when: The request omits `x-organization-id` or sends malformed query/body data.
What to do: Send the active organization id and validate request fields against the contract examples before retrying.
{
"error": "Missing organization context. Provide x-organization-id.",
"issues": [
{
"path": "email",
"message": "Invalid email address"
}
]
}401
Unauthorized
Missing, invalid, or expired API credentials.
Usually happens when: The API key is invalid, expired, or no valid authenticated session is attached to the request.
What to do: Verify the key value, key status, expiration, and whether you are sending `x-api-key` or bearer auth correctly.
{
"error": "Invalid API key"
}403
Forbidden
Missing scopes or organization access for this request.
Usually happens when: The caller is authenticated but lacks the required scope or organization membership for the target resource.
What to do: Grant the missing scope in Security settings or switch to an org/key with access to the requested resource.
{
"error": "API key missing required scopes",
"missingScopes": [
"write:customers"
]
}429
Rate limited
Configured API key rate limit exceeded.
Usually happens when: The current key has exceeded its per-minute or per-day preview limit.
What to do: Throttle request volume and avoid immediate fan-out retries from parallel workers.
Retry guidance: Honor the `Retry-After` header for minute-level limits and back off longer if the `window` is `day`.
{
"error": "API key minute rate limit exceeded",
"limit": 60,
"window": "minute"
}500
Internal error
Unexpected preview API failure.
Usually happens when: The preview API hit an unexpected internal failure while reading or serializing the resource.
What to do: Log the contract version and response body, then retry once before escalating to Asteri support.
{
"error": "Failed to fetch customers"
}Usage
cURL
curl -X GET \
http://localhost:3000/api/public/v1/customers \
-H "x-api-key: ast_live_your_key" \
-H "x-organization-id: ${ORG_ID}"TypeScript SDK
import { AsteriPublicApiClient } from '@asteri/public-api-sdk';
const client = new AsteriPublicApiClient({
baseUrl: 'http://localhost:3000',
organizationId: process.env.ASTERI_ORG_ID!,
apiKey: process.env.ASTERI_API_KEY!,
});
const response = await client.customers.list();POST
Private preview/api/public/v1/customersCreate a customer with organization-scoped identity and contact data.
write:customers
Common errors: 400 Bad request · 401 Unauthorized · 403 Forbidden · 409 Conflict · 429 Rate limited · 500 Internal error
Request body
CreateCustomerRequest
{
"account_type": "business",
"display_name": "North Harbor Facilities",
"company_name": "North Harbor Facilities",
"first_name": "Nora",
"last_name": "Harbor",
"email": "ops@northerborfacilities.com",
"phone": "+1-404-555-0128"
}Response body
CreateCustomerResponse
{
"data": {
"id": "8af2ca8e-8f31-4e6e-a46c-0703b61f7ca3",
"organization_id": "dce3853d-4f94-4bc8-a816-4d0d74c11a9d",
"account_type": "business",
"display_name": "North Harbor Facilities",
"email": "ops@northerborfacilities.com",
"phone": "+1-404-555-0128",
"created_at": "2026-03-18T15:40:12.000Z"
}
}Error responses
400
Bad request
Missing organization context or invalid request payload.
Usually happens when: The request body is missing required fields, includes invalid field values, or omits org context.
What to do: Validate the payload against the generated request schema and fix any `issues` entries before retrying.
{
"error": "Missing organization context. Provide x-organization-id.",
"issues": [
{
"path": "email",
"message": "Invalid email address"
}
]
}401
Unauthorized
Missing, invalid, or expired API credentials.
Usually happens when: The API key is invalid, expired, or no valid authenticated session is attached to the request.
What to do: Verify the key value, key status, expiration, and whether you are sending `x-api-key` or bearer auth correctly.
{
"error": "Invalid API key"
}403
Forbidden
Missing scopes or organization access for this request.
Usually happens when: The caller is authenticated but lacks write scope or organization access for the mutation target.
What to do: Grant the missing write scope or use a key/session from the correct organization.
{
"error": "API key missing required scopes",
"missingScopes": [
"write:customers"
]
}409
Conflict
Duplicate customer email or conflicting customer state.
Usually happens when: A create request reuses a primary email that already belongs to another active customer in the same organization.
What to do: Fetch the existing customer first or update your upstream dedupe logic before retrying the create.
{
"error": "Customer email already exists in this organization",
"field": "email"
}429
Rate limited
Configured API key rate limit exceeded.
Usually happens when: The current key has exceeded its per-minute or per-day preview limit.
What to do: Throttle mutation throughput and avoid blind retries from queues or worker pools.
Retry guidance: Honor the `Retry-After` header and replay writes only after the relevant limit window resets.
{
"error": "API key minute rate limit exceeded",
"limit": 60,
"window": "minute"
}500
Internal error
Unexpected preview API failure.
Usually happens when: The preview API hit an unexpected internal failure while validating or persisting the mutation.
What to do: Capture the response payload and contract version, then retry once before escalating.
{
"error": "Failed to fetch customers"
}Usage
cURL
curl -X POST \
http://localhost:3000/api/public/v1/customers \
-H "x-api-key: ast_live_your_key" \
-H "x-organization-id: ${ORG_ID}" \
-H "Content-Type: application/json" \
-d '{
"account_type": "business",
"display_name": "North Harbor Facilities",
"company_name": "North Harbor Facilities",
"first_name": "Nora",
"last_name": "Harbor",
"email": "ops@northerborfacilities.com",
"phone": "+1-404-555-0128"
}'TypeScript SDK
import { AsteriPublicApiClient } from '@asteri/public-api-sdk';
const client = new AsteriPublicApiClient({
baseUrl: 'http://localhost:3000',
organizationId: process.env.ASTERI_ORG_ID!,
apiKey: process.env.ASTERI_API_KEY!,
});
const response = await client.customers.create({
"account_type": "business",
"display_name": "North Harbor Facilities",
"company_name": "North Harbor Facilities",
"first_name": "Nora",
"last_name": "Harbor",
"email": "ops@northerborfacilities.com",
"phone": "+1-404-555-0128"
});GET
Private preview/api/public/v1/customers/{customerId}Retrieve one customer and related profile metadata.
read:customers
Common errors: 400 Bad request · 401 Unauthorized · 403 Forbidden · 404 Not found · 429 Rate limited · 500 Internal error
No request body contract for this endpoint.
Response body
CustomerResponse
{
"data": {
"id": "8af2ca8e-8f31-4e6e-a46c-0703b61f7ca3",
"organization_id": "dce3853d-4f94-4bc8-a816-4d0d74c11a9d",
"account_type": "business",
"display_name": "North Harbor Facilities",
"email": "ops@northerborfacilities.com",
"phone": "+1-404-555-0128",
"created_at": "2026-03-18T15:40:12.000Z"
}
}Error responses
400
Bad request
Missing or invalid organization context.
Usually happens when: The request omits `x-organization-id` or sends malformed query/body data.
What to do: Send the active organization id and validate request fields against the contract examples before retrying.
{
"error": "Missing organization context. Provide x-organization-id.",
"issues": [
{
"path": "email",
"message": "Invalid email address"
}
]
}401
Unauthorized
Missing, invalid, or expired API credentials.
Usually happens when: The API key is invalid, expired, or no valid authenticated session is attached to the request.
What to do: Verify the key value, key status, expiration, and whether you are sending `x-api-key` or bearer auth correctly.
{
"error": "Invalid API key"
}403
Forbidden
Missing scopes or organization access for this request.
Usually happens when: The caller is authenticated but lacks the required scope or organization membership for the target resource.
What to do: Grant the missing scope in Security settings or switch to an org/key with access to the requested resource.
{
"error": "API key missing required scopes",
"missingScopes": [
"write:customers"
]
}404
Not found
Requested customer record was not found.
Usually happens when: The requested `customerId` does not exist in the active organization or has been removed from the public view.
What to do: Refresh your local record cache and confirm the customer belongs to the organization id you sent.
{
"error": "Customer not found"
}429
Rate limited
Configured API key rate limit exceeded.
Usually happens when: The current key has exceeded its per-minute or per-day preview limit.
What to do: Throttle request volume and avoid immediate fan-out retries from parallel workers.
Retry guidance: Honor the `Retry-After` header for minute-level limits and back off longer if the `window` is `day`.
{
"error": "API key minute rate limit exceeded",
"limit": 60,
"window": "minute"
}500
Internal error
Unexpected preview API failure.
Usually happens when: The preview API hit an unexpected internal failure while reading or serializing the resource.
What to do: Log the contract version and response body, then retry once before escalating to Asteri support.
{
"error": "Failed to fetch customers"
}Usage
cURL
curl -X GET \
http://localhost:3000/api/public/v1/customers/8af2ca8e-8f31-4e6e-a46c-0703b61f7ca3 \
-H "x-api-key: ast_live_your_key" \
-H "x-organization-id: ${ORG_ID}"TypeScript SDK
import { AsteriPublicApiClient } from '@asteri/public-api-sdk';
const client = new AsteriPublicApiClient({
baseUrl: 'http://localhost:3000',
organizationId: process.env.ASTERI_ORG_ID!,
apiKey: process.env.ASTERI_API_KEY!,
});
const response = await client.customers.get({ customerId: '8af2ca8e-8f31-4e6e-a46c-0703b61f7ca3' });