Required fields for a compliant call request

The schema validates shape and the preflight evaluates product policy. Passing both does not establish that a campaign is lawful in every jurisdiction. Keep the underlying evidence and obtain review appropriate to the call.

Top-level fields

Field	Required	Rules
to	Yes	Destination in E.164 form; preflight rejects invalid numbers.
objective	Yes	A non-empty, truthful description used to guide the call and disclosure.
onBehalfOf	No	Overrides compliance.caller.onBehalfOf when supplied.
voiceTier	No	standard or premium; defaults to standard.
webhookUrl	No	A valid URL associated with the request. Account webhook subscriptions are managed separately.
metadata	No	String-keyed JSON values for your correlation data; do not put secrets here.
compliance	Yes	The complete policy context described below.

Purpose and consent

compliance.purpose must be one of telemarketing, transactional, survey, political, charity, or internal_test. Choose the real purpose; the value changes preflight requirements.

The optional consent object becomes functionally required for approved AI voice calls:

{
  "basis": "prior_express_consent",
  "capturedAt": "2026-07-10T16:20:00Z",
  "evidenceRef": "crm-consent-record-4831"
}

Supported basis values are prior_express_written_consent, prior_express_consent, established_business_relationship, personal_relationship, nonprofit_exemption, and manual_internal_test. Current product preflight approves telemarketing only with prior_express_written_consent; non-telemarketing purposes require prior express or prior express written consent; internal tests accept manual_internal_test or prior express written consent.

The timestamp must parse, include an offset, and not be in the future. evidenceRef must identify an auditable record.

National DNC context

For telemarketing, include:

{
  "scrubbedAt": "2026-07-12T10:00:00Z",
  "subscriptionAccountNumber": "optional-account-reference"
}

The current product check requires a valid scrub timestamp no more than 31 days old. CallOnline also checks its account-specific do-not-call store for non-internal-test calls.

Called-party context

calledParty.timeZone is required and should be an IANA time-zone identifier. Product quiet-hour checks block non-internal-test calls before 8:00 a.m. and at or after 9:00 p.m. in that time zone. state is optional and exactly two characters. type can be wireless, residential, business, or unknown and defaults to unknown.

Caller identity and disclosure

The caller object requires:

• legalName: the responsible caller’s legal name;
• onBehalfOf: the organization represented in the call;
• callbackNumber: an E.164 callback number;
• aiDisclosureAcknowledged: true;
• dncPolicyAcknowledged: true.

These acknowledgements are literal true values, not strings. The product generates an AI disclosure script from the organization, objective, purpose, and recording choice.

Recording

recording.enabled defaults to false. twoPartyConsentRequired is optional context. Turning recording on can add obligations that vary by location and call circumstances; do not enable it by default without an approved recording policy.

Not legal advice: CallOnline validates documented product requirements and fails closed for specific conditions. Your organization remains responsible for legal basis, suppression sources, disclosure content, recording consent, retention, and campaign review.