Create a call request

curl --request POST \
  --url https://voice.growdental.ai/api/partner/v1/practices/{practiceId}/call-requests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contacts": [
    {
      "phone": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "email": "jsmith@example.com",
      "external_ref": "<string>"
    }
  ],
  "purpose": "<string>",
  "context": "<string>",
  "window": {
    "start": "2023-11-07T05:31:56Z",
    "end": "2023-11-07T05:31:56Z",
    "daily_start": "<string>",
    "daily_end": "<string>",
    "days": [
      3
    ]
  }
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "practice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "purpose": "<string>",
  "counts": {
    "total": 123,
    "pending": 123,
    "calling": 123,
    "completed": 123,
    "failed": 123,
    "skipped": 123
  },
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "context": "<string>",
  "window": {
    "start": "2023-11-07T05:31:56Z",
    "end": "2023-11-07T05:31:56Z",
    "daily_start": "<string>",
    "daily_end": "<string>",
    "days": [
      3
    ]
  },
  "contacts": [
    {
      "phone": "<string>",
      "name": "<string>",
      "external_ref": "<string>",
      "outcome": "<string>",
      "call_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ]
}

Call Requests

Create a call request

Queues outbound voice-AI calls to 1–50 contacts at a granted practice. Requires call-requests:write. Counts against the bulk rate bucket (60 requests/minute).

Calls are placed by the platform dialer inside the practice’s calling window (or the narrower window you provide), with retries and concurrency caps applied automatically. Track progress by polling GET /call-requests/{callRequestId} or by subscribing to the call_request.completed webhook event.

Always send an Idempotency-Key — a network retry without one can dial patients twice.

Consent: by submitting contacts you attest, per your partner agreement, that each contact has given prior express consent to be called at the supplied number (TCPA and applicable state law).

Quotas (enforced before anything is dialed):

Per-partner daily contact cap → 429 daily_cap_exceeded
Per-practice pending-contact cap → 409 queue_full
Practice minute-balance circuit breaker → 409 insufficient_minute_balance

POST

practices

{practiceId}

call-requests

Create a call request

curl --request POST \
  --url https://voice.growdental.ai/api/partner/v1/practices/{practiceId}/call-requests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contacts": [
    {
      "phone": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "email": "jsmith@example.com",
      "external_ref": "<string>"
    }
  ],
  "purpose": "<string>",
  "context": "<string>",
  "window": {
    "start": "2023-11-07T05:31:56Z",
    "end": "2023-11-07T05:31:56Z",
    "daily_start": "<string>",
    "daily_end": "<string>",
    "days": [
      3
    ]
  }
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "practice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "purpose": "<string>",
  "counts": {
    "total": 123,
    "pending": 123,
    "calling": 123,
    "completed": 123,
    "failed": 123,
    "skipped": 123
  },
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "context": "<string>",
  "window": {
    "start": "2023-11-07T05:31:56Z",
    "end": "2023-11-07T05:31:56Z",
    "daily_start": "<string>",
    "daily_end": "<string>",
    "days": [
      3
    ]
  },
  "contacts": [
    {
      "phone": "<string>",
      "name": "<string>",
      "external_ref": "<string>",
      "outcome": "<string>",
      "call_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ]
}

Authorizations

Authorization

string

header

required

Partner API key sent as a Bearer token:

Authorization: Bearer gd_live_...

Keys are issued by the GrowDental team (invite-only), shown once at creation, and stored server-side only as a SHA-256 hash. Key format: gd_live_ (or gd_test_) followed by a 43-character base62 secret (~256 bits of entropy). To rotate, request a new key, deploy it, then ask us to revoke the old one — both keys work during the overlap.

Headers

Idempotency-Key

string

Client-generated unique key (e.g. a UUID) making the POST safely retryable for 24 hours: retries with the same key and payload replay the original response; the same key with a different payload is rejected with 409 idempotency_conflict. Strongly recommended on every POST — required in practice for call-request creation, where a blind retry can dial patients twice.

Maximum string length: 255

Path Parameters

practiceId

string<uuid>

required

Practice ID (must be granted to your app — ungranted IDs return 404).

Body

application/json

contacts

object[]

required

Contacts to dial (1–50). Duplicate phone numbers (after E.164 normalization) are rejected with 400 duplicate_contacts.

Required array length: 1 - 50 elements

Show child attributes

purpose

string

required

Why these contacts are being called — shapes the agent's framing of the conversation. Free-form slug; common values: recall_reminder, treatment_follow_up, appointment_confirmation, reactivation.

Required string length: 1 - 100

Example:

"recall_reminder"

context

string

Free-text context for the voice agent, applied to every contact. Structured context is the only way partners influence call content — prompts and agent internals are not exposed.

Maximum string length: 5000

window

object

Optional scheduling constraints. Calls are always confined to the practice's configured calling hours and days; a window can only narrow them further. daily_start/daily_end are practice-local times.

Show child attributes

Response

Call request accepted and queued.

A call request with its window, context, and per-contact progress.

string<uuid>

required

status

enum<string>

required

queued until dialing begins, in_progress while contacts are being worked, completed when every contact is terminal.

Available options:

queued,

in_progress,

completed,

paused,

cancelled

practice_id

string<uuid>

required

purpose

string | null

required

counts

object

required

Aggregate contact-status counts for a call request. Keys beyond the listed ones may appear if new contact statuses are introduced.

Show child attributes

created_at

string<date-time>

required

updated_at

string<date-time>

required

context

string | null

required

The free-text context supplied at creation.

window

object

required

Show child attributes

contacts

object[]

required

Show child attributes

List call requests for a practice Get a call request

⌘I