API reference · v1

Records

Keep stored contact and object data current, inspect consent history, and track deletion to completion.

List records

GET/v1/schemas/{schema}/records

Lists stored contact or object records, ordered by createdAt ascending then id ascending. Custom values are flattened at the top level alongside platform fields. Evaluated and aggregate attributes are not expanded. This endpoint accepts limit/offset only; it has no ad-hoc search, time filter, include, or trait-expansion query. Traversal is capped; pagination.hasMore can be false when totalCount exceeds the reachable window.

Path parameters

Name
schema
Type
string
Requirement
Required
Description
A schema id or slug.

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/schemas/students/records' \
  -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 records.
400The request was malformed or failed validation. Also covers malformed_json (body is not valid JSON) and, on list endpoints, offset_too_large.
401The credential is missing or invalid: invalid_api_key for an API key, invalid_access_token for an expired or revoked OAuth access token. The WWW-Authenticate header names the resource metadata, from which an OAuth client finds the authorization server.
403The key lacks permission, or the space is out of scope. An OAuth connection whose user holds the permission but did not grant it answers insufficient_scope.
404The referenced resource was not found.
429A request rate or capacity limit was reached. Follow the error code and Retry-After; a capacity refusal can follow durable preparation.
500The API failed to process a valid request.

Create a record

POST/v1/schemas/{schema}/records

Bearer API key required

Strictly creates one contact or object record (never updates an existing one). Any id in the body is ignored. source is forced to api. Missing AI auto-fill values require a timed Idempotency-Key in the format rpi1.<13-digit Unix milliseconds>.<UUIDv4>. Generate it once and retain it with the input. A completed paid preparation is reused; only a new model call needs new credit admission. Supports Idempotency-Key. Errors: schema_not_found, identifier_conflict (409), insufficient_credits (402).

Path parameters

Name
schema
Type
string
Requirement
Required
Description
A schema id or slug.

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. Failed record create/upsert requests retain status and stable error code with a constant message; detailed validation information is only in the first authorized response. Follow the code's retry policy, rather than creating a new key from the HTTP status alone. Changed input returns 422 idempotency_key_reused; active work returns 409 idempotency_conflict; unresolved work returns idempotency_outcome_unknown. Ordinary opaque keys keep their existing 24-hour completed-response retention. For record create/upsert that needs missing AI auto-fill, use rpi1.<13-digit Unix milliseconds>.<UUIDv4>. The rpi1. prefix is reserved for timed record keys and is checked before cached-response replay. Its retry window ends 24 hours after the issue time rounded up to the next minute. A clock more than five minutes ahead is refused. Expired keys are permanently refused, including after receipt cleanup. An expired or unknown result must be reconciled; do not automatically mint a new key. Unresolved financial/provider work remains retained. Erased record responses return 410 instead of replaying private data. Other idempotent operations keep their own key rules.

Request body

Send JSON with Content-Type: application/json. A body is required.

Input for creating, upserting, or updating a record. All fields are optional. For a contact schema the contact fields apply; for an object schema the object fields apply. Custom attribute keys are passed at the top level.

Name
id
Type
string
Description
See the request example and OpenAPI schema for this field.
Name
fullName
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
firstName
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
lastName
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
avatarUrl
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
userId
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
email
Type
string (email) | null
Description
See the request example and OpenAPI schema for this field.
Name
phone
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
subscriptions
Type
string[]
Description
See the request example and OpenAPI schema for this field.
Name
topicIds
Type
string[]
Description
See the request example and OpenAPI schema for this field.
Name
externalId
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
notes
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
tags
Type
string[]
Description
See the request example and OpenAPI schema for this field.

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/schemas/students/records' \
  -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 '{
  "email": "[email protected]",
  "firstName": "Sarah"
}'

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"
  },
  "warnings": []
}

Status codes

201The created record.
400The request was malformed or failed validation. Also covers malformed_json (body is not valid JSON) and, on list endpoints, offset_too_large.
401The credential is missing or invalid: invalid_api_key for an API key, invalid_access_token for an expired or revoked OAuth access token. The WWW-Authenticate header names the resource metadata, from which an OAuth client finds the authorization server.
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. An OAuth connection whose user holds the permission but did not grant it answers insufficient_scope.
404The referenced resource was not found.
409The write conflicts with an existing resource or the resource's current state.
410The record operation expired or its stored response was erased. Reconcile the original operation before starting a new one.
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).
429A request rate or capacity limit was reached. Follow the error code and Retry-After; a capacity refusal can follow durable preparation.
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.

Upsert a record

POST/v1/schemas/{schema}/records/upsert

Bearer API key required

Creates or updates a contact or object. An explicit id selects that exact record or returns record_not_found. Otherwise contact matching uses userId first; email can match only a contact without userId; phone can match only a contact without userId or email. Objects match by externalId. Per-field identifier collisions may be skipped and reported in warnings; inspect the returned record. Returns 201 for creation or 200 for update. Any missing AI auto-fill value on a new record requires a timed Idempotency-Key in the format rpi1.<13-digit Unix milliseconds>.<UUIDv4>. Generate it once and retain it with the input. Paid prepared values can complete a retry without new credits; new model calls still require credit admission. Required writable fields without a value/default can fail with required_attribute_missing (400, issues names the key).

Path parameters

Name
schema
Type
string
Requirement
Required
Description
A schema id or slug.

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. Failed record create/upsert requests retain status and stable error code with a constant message; detailed validation information is only in the first authorized response. Follow the code's retry policy, rather than creating a new key from the HTTP status alone. Changed input returns 422 idempotency_key_reused; active work returns 409 idempotency_conflict; unresolved work returns idempotency_outcome_unknown. Ordinary opaque keys keep their existing 24-hour completed-response retention. For record create/upsert that needs missing AI auto-fill, use rpi1.<13-digit Unix milliseconds>.<UUIDv4>. The rpi1. prefix is reserved for timed record keys and is checked before cached-response replay. Its retry window ends 24 hours after the issue time rounded up to the next minute. A clock more than five minutes ahead is refused. Expired keys are permanently refused, including after receipt cleanup. An expired or unknown result must be reconciled; do not automatically mint a new key. Unresolved financial/provider work remains retained. Erased record responses return 410 instead of replaying private data. Other idempotent operations keep their own key rules.

Request body

Send JSON with Content-Type: application/json. A body is required.

Name
id
Type
string
Description
See the request example and OpenAPI schema for this field.
Name
fullName
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
firstName
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
lastName
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
avatarUrl
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
userId
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
email
Type
string (email) | null
Description
See the request example and OpenAPI schema for this field.
Name
phone
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
subscriptions
Type
string[]
Description
See the request example and OpenAPI schema for this field.
Name
topicIds
Type
string[]
Description
See the request example and OpenAPI schema for this field.
Name
externalId
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
notes
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
tags
Type
string[]
Description
See the request example and OpenAPI schema for this field.

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/schemas/students/records/upsert' \
  -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 '{
  "userId": "customer_1042",
  "email": "[email protected]",
  "firstName": "Sarah"
}'

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"
  },
  "warnings": []
}

Status codes

200The updated record.
201The created record.
400The request was malformed or failed validation. Also covers malformed_json (body is not valid JSON) and, on list endpoints, offset_too_large.
401The credential is missing or invalid: invalid_api_key for an API key, invalid_access_token for an expired or revoked OAuth access token. The WWW-Authenticate header names the resource metadata, from which an OAuth client finds the authorization server.
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. An OAuth connection whose user holds the permission but did not grant it answers insufficient_scope.
404The referenced resource was not found.
409The write conflicts with an existing resource or the resource's current state.
410The record operation expired or its stored response was erased. Reconcile the original operation before starting a new one.
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).
429A request rate or capacity limit was reached. Follow the error code and Retry-After; a capacity refusal can follow durable preparation.
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 record

GET/v1/schemas/{schema}/records/{id}

Bearer API key required

Reads one contact or object in this schema. Stored custom values and platform fields are flattened; evaluated and aggregate attributes are not expanded. There is no include/expand query. Missing schema or record returns 404.

Path parameters

Name
schema
Type
string
Requirement
Required
Description
A schema id or slug.
Name
id
Type
string
Requirement
Required
Description
The record's platform id.

Request

curl --fail-with-body 'https://api.maxclicks.ai/v1/schemas/students/records/con_BcwDvBUeSaSDILA5tHgpmU7I' \
  -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"
  },
  "warnings": []
}

Status codes

200The record.
401The credential is missing or invalid: invalid_api_key for an API key, invalid_access_token for an expired or revoked OAuth access token. The WWW-Authenticate header names the resource metadata, from which an OAuth client finds the authorization server.
403The key lacks permission, or the space is out of scope. An OAuth connection whose user holds the permission but did not grant it answers insufficient_scope.
404The referenced resource was not found.
429A request rate or capacity limit was reached. Follow the error code and Retry-After; a capacity refusal can follow durable preparation.
500The API failed to process a valid request.

Update a record

PATCH/v1/schemas/{schema}/records/{id}

Bearer API key required

Partially updates a record. The path id overrides any body id. Explicit null clears a nullable field; omit a field to preserve it. Non-writable evaluated/aggregate keys are not accepted as stored inputs. Normalization and skipped per-field identity updates can produce warnings. The endpoint does not use Idempotency-Key. Errors: schema_not_found, record_not_found, identifier_conflict, or required_attribute_missing (400, issues names the missing key).

Path parameters

Name
schema
Type
string
Requirement
Required
Description
A schema id or slug.
Name
id
Type
string
Requirement
Required
Description
The record's platform id.

Request body

Send JSON with Content-Type: application/json. A body is required.

Name
id
Type
string
Description
See the request example and OpenAPI schema for this field.
Name
fullName
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
firstName
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
lastName
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
avatarUrl
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
userId
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
email
Type
string (email) | null
Description
See the request example and OpenAPI schema for this field.
Name
phone
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
subscriptions
Type
string[]
Description
See the request example and OpenAPI schema for this field.
Name
topicIds
Type
string[]
Description
See the request example and OpenAPI schema for this field.
Name
externalId
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
notes
Type
string | null
Description
See the request example and OpenAPI schema for this field.
Name
tags
Type
string[]
Description
See the request example and OpenAPI schema for this field.

Request

curl --fail-with-body 'https://api.maxclicks.ai/v1/schemas/students/records/con_BcwDvBUeSaSDILA5tHgpmU7I' \
  -X PATCH \
  -H "Authorization: Bearer $MAXCLICKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "firstName": "Sarah"
}'

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"
  },
  "warnings": []
}

Status codes

200The updated record.
400The request was malformed or failed validation. Also covers malformed_json (body is not valid JSON) and, on list endpoints, offset_too_large.
401The credential is missing or invalid: invalid_api_key for an API key, invalid_access_token for an expired or revoked OAuth access token. The WWW-Authenticate header names the resource metadata, from which an OAuth client finds the authorization server.
403The key lacks permission, or the space is out of scope. An OAuth connection whose user holds the permission but did not grant it answers insufficient_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.
429A request rate or capacity limit was reached. Follow the error code and Retry-After; a capacity refusal can follow durable preparation.
500The API failed to process a valid request.

Delete a record

DELETE/v1/schemas/{schema}/records/{id}

Bearer API key required

Requests durable deletion of a contact or object. Requires an Idempotency-Key identifying this explicit attempt: 1..128 characters, beginning with an alphanumeric character and containing only alphanumeric characters, underscore, period, colon or hyphen. Preserve it when recovering a lost response. The key identifies the operation; it does not use generic response-cache replay headers. The response carries operationId/status/canCancel/message. New admissions pause while accepted Events and deliveries drain; no records have been removed at that stage. Once removal begins, conflicting workspace work remains closed during cleanup. Poll GET /record-deletions/{operationId}; pending is unfinished, blocked needs reconciliation, and completed confirms erasure. Cancellation is available to the original requester with current write permission only before removal begins. This handler returns HTTP 202 for non-completed states and HTTP 200 for completed. A cancelled attempt must not be reused as a new deletion. An unknown record returns 404 record_not_found; after completion, retrying DELETE can therefore return 404, so retain the operationId for status inspection.

Path parameters

Name
schema
Type
string
Requirement
Required
Description
A schema id or slug.
Name
id
Type
string
Requirement
Required
Description
The record's platform id.

Headers

Name
Idempotency-Key
Type
string
Requirement
Required
Description
Stable identity for this explicit deletion attempt. Keep the same key to recover its operation status. This does not use generic response caching or replay headers. A new attempt after cancellation requires a new key; inspect the original operation first.

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/schemas/students/records/con_BcwDvBUeSaSDILA5tHgpmU7I' \
  -X DELETE \
  -H "Authorization: Bearer $MAXCLICKS_API_KEY" \
  -H "Idempotency-Key: ${MAXCLICKS_OPERATION_KEY:?Set MAXCLICKS_OPERATION_KEY first}"

Response

{
  "data": {
    "operationId": "delete:records:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "status": "completed",
    "canCancel": false,
    "message": "Record deletion is completed."
  }
}

Status codes

200Record deletion is completed.
202Deletion is unfinished. Poll the operation until status is completed.
400The request was malformed or failed validation. Also covers malformed_json (body is not valid JSON) and, on list endpoints, offset_too_large.
401The credential is missing or invalid: invalid_api_key for an API key, invalid_access_token for an expired or revoked OAuth access token. The WWW-Authenticate header names the resource metadata, from which an OAuth client finds the authorization server.
403The key lacks permission, or the space is out of scope. An OAuth connection whose user holds the permission but did not grant it answers insufficient_scope.
404The referenced resource was not found.
409The write conflicts with an existing resource or the resource's current state.
429A request rate or capacity limit was reached. Follow the error code and Retry-After; a capacity refusal can follow durable preparation.
500The API failed to process a valid request.

List a contact's audit trail

GET/v1/schemas/{schema}/records/{id}/audit-trail

Bearer API key required

Lists the consent and communication audit trail for a contact, newest first. Contact schemas only. Errors: schema_not_found, record_not_found.

Path parameters

Name
schema
Type
string
Requirement
Required
Description
A schema id or slug.
Name
id
Type
string
Requirement
Required
Description
The record's platform id.

Query parameters

Name
channel
Type
string
Description
Filter by communication channel.
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/schemas/students/records/con_BcwDvBUeSaSDILA5tHgpmU7I/audit-trail' \
  -H "Authorization: Bearer $MAXCLICKS_API_KEY"

Response

{
  "data": [
    {
      "id": "cat_BcwDvBUeSaSDILA5tHgpmU7I",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "communicationChannel": "email",
      "communicationTopicIds": [
        "ct_BcwDvBUeSaSDILA5tHgpmU7I"
      ],
      "eventType": "email_verification_sent",
      "state": "subscribed",
      "optInLevel": "single",
      "actorType": "contact",
      "actorIdentifier": "string",
      "context": null
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0,
    "totalCount": 0,
    "hasMore": false
  },
  "warnings": []
}

Status codes

200A page of audit-trail entries.
401The credential is missing or invalid: invalid_api_key for an API key, invalid_access_token for an expired or revoked OAuth access token. The WWW-Authenticate header names the resource metadata, from which an OAuth client finds the authorization server.
403The key lacks permission, or the space is out of scope. An OAuth connection whose user holds the permission but did not grant it answers insufficient_scope.
404The referenced resource was not found.
429A request rate or capacity limit was reached. Follow the error code and Retry-After; a capacity refusal can follow durable preparation.
500The API failed to process a valid request.

Get record deletion status

GET/v1/record-deletions/{operationId}

Bearer API key required

Poll a record-deletion operation in the caller's space. pending means drain, cancellation or cleanup is unfinished; inspect message for the current phase. blocked needs reconciliation; completed confirms deletion, and cancelled confirms cancellation before record removal. A missing or out-of-scope operation returns 404. Preserve operationId from records.delete. This read-only response reports canCancel=false; cancellation eligibility is enforced separately by records.cancelDeletion against the current requester and operation phase.

Path parameters

Name
operationId
Type
string
Requirement
Required
Description
The full operationId returned by records.delete.

Request

curl --fail-with-body 'https://api.maxclicks.ai/v1/record-deletions/delete%3Arecords%3A0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef' \
  -H "Authorization: Bearer $MAXCLICKS_API_KEY"

Response

{
  "data": {
    "operationId": "delete:records:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "status": "pending",
    "canCancel": false,
    "message": "Record deletion is in progress."
  },
  "warnings": []
}

Status codes

200Current deletion status.
401The credential is missing or invalid: invalid_api_key for an API key, invalid_access_token for an expired or revoked OAuth access token. The WWW-Authenticate header names the resource metadata, from which an OAuth client finds the authorization server.
403The key lacks permission, or the space is out of scope. An OAuth connection whose user holds the permission but did not grant it answers insufficient_scope.
404The referenced resource was not found.
429A request rate or capacity limit was reached. Follow the error code and Retry-After; a capacity refusal can follow durable preparation.
500The API failed to process a valid request.

Cancel a record deletion before removal

POST/v1/record-deletions/{operationId}/cancel

Bearer API key required

Requests cancellation during the initial admission-drain phase, before data removal begins. Requires the original requesting user and current Write permission in the workspace. Returns 202 while collection intake retirement is acknowledged, then 200 for an already cancelled operation. Poll records.getDeletion until status=cancelled. Repeating cancellation during cancellation or after it completes returns the current operation status. There is no separate Idempotency-Key for this route: operationId identifies the existing operation. A different requester or out-of-scope operation returns 404. Removal already begun returns 409; a currently leased admission check also returns 409 and requires waiting before retrying. Cancellation cannot restore data after removal begins.

Path parameters

Name
operationId
Type
string
Requirement
Required
Description
The full operationId returned by records.delete.

Request

curl --fail-with-body 'https://api.maxclicks.ai/v1/record-deletions/con_BcwDvBUeSaSDILA5tHgpmU7I/cancel' \
  -X POST \
  -H "Authorization: Bearer $MAXCLICKS_API_KEY"

Response

{
  "data": {
    "operationId": "delete:records:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "status": "pending",
    "canCancel": false,
    "message": "Record deletion is in progress."
  }
}

Status codes

200The operation was already cancelled.
202Cancellation is pending; poll the deletion operation.
400The request was malformed or failed validation. Also covers malformed_json (body is not valid JSON) and, on list endpoints, offset_too_large.
401The credential is missing or invalid: invalid_api_key for an API key, invalid_access_token for an expired or revoked OAuth access token. The WWW-Authenticate header names the resource metadata, from which an OAuth client finds the authorization server.
403The key lacks permission, or the space is out of scope. An OAuth connection whose user holds the permission but did not grant it answers insufficient_scope.
404The referenced resource was not found.
409The write conflicts with an existing resource or the resource's current state.
429A request rate or capacity limit was reached. Follow the error code and Retry-After; a capacity refusal can follow durable preparation.
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.