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

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. If the schema has an AI auto-fill attribute, credits are checked first. 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, 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.

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

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 writable AI auto-fill attribute on the schema triggers the up-front credit check. Supports Idempotency-Key. 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, 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
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 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 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 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.

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 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.
413The request body exceeds the 10 MB limit.
415The request used an unsupported content type, charset, or content encoding.
429The rate limit was exceeded.
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. The response is an operationId/status/message object, not {id,deleted}. The workspace is closed for conflicting work while data and external resources are removed. Poll GET /record-deletions/{operationId} until status=completed; blocked requires reconciliation of unresolved work. The current handler returns HTTP 200 even when status=pending, so do not use HTTP status alone as proof of erasure. An unknown record returns 404 record_not_found. This endpoint does not use Idempotency-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

curl --fail-with-body 'https://api.maxclicks.ai/v1/schemas/students/records/con_BcwDvBUeSaSDILA5tHgpmU7I' \
  -X DELETE \
  -H "Authorization: Bearer $MAXCLICKS_API_KEY"

Response

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

Status codes

200Deletion operation status; pending is not completed erasure.
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.
429The rate limit was exceeded.
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 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.

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 cleanup is still in progress; blocked means unresolved work needs reconciliation and the workspace remains closed; completed confirms the deletion operation finished. A missing or out-of-scope operation returns 404. Preserve the operationId from records.delete.

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",
    "message": "Record deletion is in progress."
  },
  "warnings": []
}

Status codes

200Current deletion status.
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.