API reference · v1
Segments
Generate and manage AI-defined contact filters.
List segments
GET
/v1/segmentsQuery parameters
- Name
limit- Type
- integer
- Description
- Page size. Clamped to 1..200 with a warning if out of range.
- Name
offset- Type
- integer
- Description
- Rows to skip. Negative values clamp to 0 with a warning; above 10000 returns 400 offset_too_large. pagination.hasMore becomes false when the next offset reaches the cap even if totalCount is larger. Records list has no ad-hoc filter; this is not an unlimited export contract.
Request
curl --fail-with-body 'https://api.maxclicks.ai/v1/segments' \
-H "Authorization: Bearer $MAXCLICKS_API_KEY"Response
{
"data": [
{
"id": "seg_BcwDvBUeSaSDILA5tHgpmU7I",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:00.000Z",
"name": "string",
"description": "string",
"contactSchemaId": "sch_BcwDvBUeSaSDILA5tHgpmU7I",
"contactSchemaSlug": "string",
"requirements": "string",
"conditionDescriptionMarkdown": "string",
"integrationVendorName": "string",
"matchingCount": 0
}
],
"pagination": {
"limit": 0,
"offset": 0,
"totalCount": 0,
"hasMore": false
},
"warnings": []
}Status codes
- 200A page of segments.
- 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 429The rate limit was exceeded.
- 500The API failed to process a valid request.
Create a segment
POST
/v1/segmentsGenerates a contact filter from a natural-language requirements prompt (every create is an AI call, in the ai rate bucket; credits are checked first) and persists it in one call. The response includes a live matchingCount. The generated expression is never returned. Errors: schema_not_found, invalid_segment, segment_generation_failed (422), segment_name_conflict (409), insufficient_credits (402).
Headers
- Name
Idempotency-Key- Type
- string
- Description
- Stable key for one logical write, maximum 256 characters. Scoped to calling API key, method, and resolved path, with a canonical request-body fingerprint. Replays recorded status/body with Idempotent-Replay=true, including recorded errors. Changed input returns 422 idempotency_key_reused; active work returns 409 idempotency_conflict; unresolved work returns idempotency_outcome_unknown. Completed records expire after 24 hours; unresolved records remain for reconciliation.
Request body
Send JSON with Content-Type: application/json. A body is required.
- Name
name- Type
- string
- Requirement
- Required
- Description
- See the request example and OpenAPI schema for this field.
- Name
description- Type
- string | null
- Description
- See the request example and OpenAPI schema for this field.
- Name
contactSchema- Type
- string
- Requirement
- Required
- Description
- A contact schema id or slug.
- Name
requirements- Type
- string
- Requirement
- Required
- Description
- Natural-language description of the filter criteria.
Request
# Set MAXCLICKS_OPERATION_KEY once per logical write; reuse it and the body on retries.
curl --fail-with-body 'https://api.maxclicks.ai/v1/segments' \
-X POST \
-H "Authorization: Bearer $MAXCLICKS_API_KEY" \
-H "Idempotency-Key: ${MAXCLICKS_OPERATION_KEY:?Set MAXCLICKS_OPERATION_KEY first}" \
-H "Content-Type: application/json" \
-d '{
"name": "Engaged customers",
"contactSchema": "customers",
"requirements": "Contacts who have opened an email in the last 30 days."
}'Response
{
"data": {
"id": "seg_BcwDvBUeSaSDILA5tHgpmU7I",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:00.000Z",
"name": "string",
"description": "string",
"contactSchemaId": "sch_BcwDvBUeSaSDILA5tHgpmU7I",
"contactSchemaSlug": "string",
"requirements": "string",
"conditionDescriptionMarkdown": "string",
"integrationVendorName": "string",
"matchingCount": 0
},
"warnings": []
}Status codes
- 201The created segment.
- 400The request was malformed or failed validation. Also covers
malformed_json(body is not valid JSON) and, on list endpoints,offset_too_large. - 401The API key is missing or invalid.
- 402Insufficient credits (
insufficient_credits) for an AI-generation call or a schema with AI auto-fill, or the space's email allowance is exhausted (email_limit_reached). - 403The key lacks permission, or the space is out of scope.
- 404The referenced resource was not found.
- 409The write conflicts with an existing resource or the resource's current state.
- 413The request body exceeds the 10 MB limit.
- 415The request used an unsupported content type, charset, or content encoding.
- 422The request was well-formed but could not be processed, typically a failed AI-generation call or a readiness gate (which may carry
error.issues). - 429The rate limit was exceeded.
- 500The API failed to process a valid request.
- 503The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.
Get a segment
GET
/v1/segments/{id}Error: segment_not_found.
Path parameters
- Name
id- Type
- string
- Requirement
- Required
- Description
- The segment id.
Request
curl --fail-with-body 'https://api.maxclicks.ai/v1/segments/seg_BcwDvBUeSaSDILA5tHgpmU7I' \
-H "Authorization: Bearer $MAXCLICKS_API_KEY"Response
{
"data": {
"id": "seg_BcwDvBUeSaSDILA5tHgpmU7I",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:00.000Z",
"name": "string",
"description": "string",
"contactSchemaId": "sch_BcwDvBUeSaSDILA5tHgpmU7I",
"contactSchemaSlug": "string",
"requirements": "string",
"conditionDescriptionMarkdown": "string",
"integrationVendorName": "string",
"matchingCount": 0
},
"warnings": []
}Status codes
- 200The segment.
- 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 404The referenced resource was not found.
- 429The rate limit was exceeded.
- 500The API failed to process a valid request.
Delete a segment
DELETE
/v1/segments/{id}Errors: segment_not_found, segment_integration_owned (403), segment_in_use (409, used as a broadcast audience, workflow trigger, or webhook condition, or referenced by other entities).
Path parameters
- Name
id- Type
- string
- Requirement
- Required
- Description
- The segment id.
Headers
- Name
Idempotency-Key- Type
- string
- Description
- Stable key for one logical write, maximum 256 characters. Scoped to calling API key, method, and resolved path, with a canonical request-body fingerprint. Replays recorded status/body with Idempotent-Replay=true, including recorded errors. Changed input returns 422 idempotency_key_reused; active work returns 409 idempotency_conflict; unresolved work returns idempotency_outcome_unknown. Completed records expire after 24 hours; unresolved records remain for reconciliation.
Request
# Set MAXCLICKS_OPERATION_KEY once per logical write; reuse it and the body on retries.
curl --fail-with-body 'https://api.maxclicks.ai/v1/segments/seg_BcwDvBUeSaSDILA5tHgpmU7I' \
-X DELETE \
-H "Authorization: Bearer $MAXCLICKS_API_KEY" \
-H "Idempotency-Key: ${MAXCLICKS_OPERATION_KEY:?Set MAXCLICKS_OPERATION_KEY first}"Response
{
"data": {
"id": "seg_BcwDvBUeSaSDILA5tHgpmU7I",
"deleted": true
},
"warnings": []
}Status codes
- 200The segment was deleted.
- 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 404The referenced resource was not found.
- 409The write conflicts with an existing resource or the resource's current state.
- 422The request was well-formed but could not be processed, typically a failed AI-generation call or a readiness gate (which may carry
error.issues). - 429The rate limit was exceeded.
- 500The API failed to process a valid request.
- 503The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.
Count a segment's matching contacts
GET
/v1/segments/{id}/countError: segment_not_found.
Path parameters
- Name
id- Type
- string
- Requirement
- Required
- Description
- The segment id.
Request
curl --fail-with-body 'https://api.maxclicks.ai/v1/segments/seg_BcwDvBUeSaSDILA5tHgpmU7I/count' \
-H "Authorization: Bearer $MAXCLICKS_API_KEY"Response
{
"data": {
"count": 0,
"total": 0
},
"warnings": []
}Status codes
- 200The live matching count and the schema's total contact count.
- 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 404The referenced resource was not found.
- 429The rate limit was exceeded.
- 500The API failed to process a valid request.
List a segment's matching contacts
GET
/v1/segments/{id}/contactsPaginated contact records currently matching the segment. limit is additionally hard-capped at config.segment.maximumContactsPageSize (100) regardless of the requested value. Error: segment_not_found.
Path parameters
- Name
id- Type
- string
- Requirement
- Required
- Description
- The segment id.
Query parameters
- Name
limit- Type
- integer
- Description
- Page size. Clamped to 1..200 with a warning if out of range.
- Name
offset- Type
- integer
- Description
- Rows to skip. Negative values clamp to 0 with a warning; above 10000 returns 400 offset_too_large. pagination.hasMore becomes false when the next offset reaches the cap even if totalCount is larger. Records list has no ad-hoc filter; this is not an unlimited export contract.
Request
curl --fail-with-body 'https://api.maxclicks.ai/v1/segments/seg_BcwDvBUeSaSDILA5tHgpmU7I/contacts' \
-H "Authorization: Bearer $MAXCLICKS_API_KEY"Response
{
"data": [
{
"id": "con_BcwDvBUeSaSDILA5tHgpmU7I",
"schemaId": "sch_BcwDvBUeSaSDILA5tHgpmU7I",
"schemaSlug": "string",
"source": "import",
"fullName": "string",
"firstName": "string",
"lastName": "string",
"avatarUrl": "string",
"userId": "user_8412",
"email": "[email protected]",
"phone": "string",
"subscriptions": [
"email"
],
"topicIds": [
"ct_BcwDvBUeSaSDILA5tHgpmU7I"
],
"notes": "string",
"tags": [
"string"
],
"emailStatistics": {
"sent": 0,
"delivered": 0,
"bounced": 0,
"complained": 0,
"unsubscribed": 0,
"uniqueOpens": 0,
"uniqueClicks": 0
},
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:00.000Z"
}
],
"pagination": {
"limit": 0,
"offset": 0,
"totalCount": 0,
"hasMore": false
},
"warnings": []
}Status codes
- 200A page of matching contacts.
- 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 404The referenced resource was not found.
- 429The rate limit was exceeded.
- 500The API failed to process a valid request.
Working with these endpoints? See error handling, safe retries, client library guides, and the complete OpenAPI schema.