Consent and calling hours

Calling people comes with rules. CallView applies these on every call, whatever a request asks for.

Consent

Send what the lead agreed to with the lead. We store it and return it with the lead:

"consent": {
  "source": "web_form",
  "agreed_at": "2026-10-06T16:58:02Z",
  "url": "https://example.com/quote",
  "text": "I agree to be called about solar quotes at the number above.",
  "ip": "203.0.113.9"
}

Field	Required	What to put
source	yes	Where they agreed: web_form, crm, purchased_list or your own word.
agreed_at	yes	When, with a time zone (Z for UTC).
text or url	one of them	The words they agreed to, or the page they agreed on.
ip	no	Their IP address at the time, if you have it.

Campaigns ask for consent on every API lead unless someone turns that off for the campaign in CallView. A lead without it then gets 422 consent_required. Send consent whenever you have it, even when it’s not required.

Calling hours

A lead is only called during its campaign’s calling hours, and never before 8 AM or after 9 PM in the lead’s own time zone. We work out the time zone from the phone number’s area code.

If you send a lead outside those hours, it isn’t refused. You get "status": "scheduled" with "scheduled_reason": "outside_calling_hours", and scheduled_for is the first minute it can be called (in UTC). It’s called then.

A campaign can be set in CallView to call at any hour, for leads who asked to be called right away. That’s a choice made in the app; the API can’t switch it on.

Not calling the same person twice

If another of your campaigns (or an inbound call) reached the same number in the last 24 hours, the lead waits until that 24 hours is up: "status": "scheduled", "scheduled_reason": "recent_contact_cooldown". The person doesn’t hear from you twice in a day.

The Do Not Call list

Your organization has one Do Not Call list, shared by every campaign. A number on it is never called:

• POST /leads with that number gets 422 on_dnc_list, and POST /calls does too.
• The list is checked again just before each call, so a number added after the lead was queued is still skipped.

To manage the list: GET /dnc/check?phone=..., POST /dnc, POST /dnc/batch and DELETE /dnc/{id}. See DNC.

Opt-outs

A number goes on the list when:

• you call POST /leads/{id}/opt_out (or POST /dnc),
• the lead asks not to be called again during a call, and the AI or your team takes them off,
• someone marks it in the app, or the call’s outcome is dnc,
• the lead replies STOP to a text.

Each time, lead.opted_out is sent for every lead of yours with that number. opt_out.source says how it happened: api, ai, outcome, manual, bulk or sms. Mirror it in your CRM, so no other system calls them either.

POST /leads/{id}/opt_out never cuts a call that’s in progress. The reply says "call_in_progress": true when one is, and the number is never dialed again after it.